Ruby wrapper for all FamilySearch APIs.
Ruby JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This project aims to provide functionality for all of the API modules provided by FamilySearch.


Install the ruby-fs-stack gem

sudo gem install ruby-fs-stack

JSON gem

Ruby-fs-stack needs a json gem, but does not force it as a dependency.

sudo gem install json

or if you are using JRuby

sudo gem install json-jruby

or for the pure Ruby implementation

sudo gem install json_pure

Example Usage

Authenticating with FamilySearch

require 'rubygems'
require 'ruby-fs-stack'

# Optionally, you can pass a logger to the communicator
# the logger can be the standard Ruby Logger or any logger 
# that responds to :info or :debug like the Rails logger
require 'logger'
logger ='fs_stack.log')

communicator = :domain => '', # or ''
                                  :key => 'DEVELOPER-KEY',
                                  :user_agent => 'Ruby-Fs-Stack/v.1 (JimmyZimmerman) FsCommunicator/0.1 (Ruby)',
                                  :logger => logger

communicator.identity_v1.authenticate :username => 'USERNAME', :password => 'PASSWORD' #=> true
communicator.session #=> "USYSE4EF197..."

Reading Person Records

me = communicator.familytree_v2.person :me
puts "My name: " + me.full_name
puts "My birthdate: " +

# Read only the version number for a person
vperson = communicator.familytree_v2.person 'KW3B-NNM', :names => 'none', :genders => 'none', :events => 'none'
puts "Person's version: " + vperson.person

# read the person and the parent, family, and child information
person = communicator.familytree_v2.person 'KW3B-NNM', :parents => 'summary', :families => 'all', :children => 'all'

puts "Gender: " + person.gender
puts "First parent ID: " + person.parents[0].parents[0].id
puts "First child ID: " + person.families[0].children[0].id
puts "First spouse's gender: " + person.families[0].parents[1].gender
puts "First spouse's ID: " + person.families[0].parents[1].id

# Read multiple persons in one request.
# You can request as many person records as needed. The communicator will
# check the person.max.ids property from the /familytree/v2/properties call 
# and will automatically break the array into appropriate slices, then return the whole.
people = communicator.familytree_v2.person ['KW3B-NNM','KWQS-BBQ','KWQS-BBR'], :parents => 'all', :children => 'all', :families => 'all'
people.size #=> 3

# Ruby blocks:
# You can pass a block to the person read that will be executed for each person
# or set of persons immediately after they are read. This is useful if you want to
# create a progress indicator if you are requesting a very large array of persons.
# because we are passing 16 ids, this will require 2 person reads (10 persons each read)
# the block will be called twice with the persons in each batch passed
progress_count = 0
communicator.familytree_v2.person ids do |persons|
  progress_count += persons.size
  puts progress_count

# if a single ID is passed, then the block will receive a single person, not an array
# of persons
communicator.familytree_v2.person :me do |person|

Searching Records

search =  :givenName => "John", 
                                            :familyName => "Doe",
                                            :birthDate => "12 Jun 1812",
                                            :birthPlace => "Virginia, United States",
                                            :father => {:givenName => "Robert"},
                                            :maxResults => 10
search.count #=> 10
search.close #=> 2
search.partial #=> 16
search.results.each do |result|
  puts result.score #=> 4.0
  puts #=> "KW3B-JXV"
  puts result.person.full_name #=> "John Doe"
  puts #=> "abt 1812"
  puts result.father.full_name #=> "Robert Doe"
  puts result.mother.full_name #=> "Ruby Johnson"
  puts result.spouses.first.full_name #=> "Sarah Franklin"

Combining Records

# reads the latest version numbers for the people requested and POSTs a combine request.
new_person = communicator.familytree_v2.combine ['KWQS-BBQ','KWRS-BBZ','KWQS-BNR'] #=> 'KWQS-ZZZ'
new_person.version #=> '687799'

Selecting the Summary View

# assuming you know the value IDs that you want to set as summary
# grab a person with the ID and version set
person = communicator.familytree_v2.person 'KWQS-BBQ', :names => 'none', :events => 'none', :genders => 'none'
person.select_name_summary "100078"
person.select_birth_summary "1089498"
person.select_death_summary "7834987"
person.select_spouse_summary "KWQS-BBB"
# you must set both the mother and the father summary unless you want a single parent as the summary parents.
person.select_mother_summary "KWQS-MOM"
person.select_father_summary "KWQS-DAD"
communicator.familytree_v2.save_person person

Adding notes to an assertion

# assuming you know the assertion value ID that you want to create a note on
note = communicator.familytree_v2.write_note :personId => 'KWQS-BBQ', :assertionId => '60000021', :text => "This is my note text." #=> 'ZnMtZnQucC5LVzNCLU5NRzpwLjE0MDAwMDAwNDIyOjQwMDAwM29nMlpWOTgxOVpCWWs4RjAwMA=='

# As soon as this bug is fixed,, it you can write
# notes on relationship assertions
marriage_note = communicator.familytree_v2.write_note :spouseIds => ['KWQS-BBQ','KWQS-BBR'], :assertionId => '700000001', :text => "This is my note."

lineage_note = communicator.familytree_v2.write_note :parentIds => ['KWQS-BBQ'], :childId => 'KWQS-BBZ', :assertionId => '700000001', :text => "This is my note."

# To add a "Person Note" as seen in the new FamilySearch web application, attach the note to an exists assertion
# You find these by doing a person read with the :exists => 'all' option.


RDoc is hosted at


A Google Group has been set up for questions and discussion around the ruby-fs-stack project.


Copyright © 2009 Jimmy Zimmerman. See LICENSE for details.