ruby-fs-stack

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

Installation

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 = Logger.new('fs_stack.log')

communicator = FsCommunicator.new :domain => 'http://www.dev.usys.org', # or 'https://api.familysearch.org'
                                  :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: " + me.birth.value.date.normalized

# 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.
ids = ['KWCZ-1WL','KWCH-DGY','KWZR-RPD','KWCH-DPM','KWCH-DP9',
      'KN1H-HBK','KLYL-KPZ','2794-46L','279W-NDV','KWJJ-5Y3','26KN-QTT',
      'KWCV-7F7','2NQ9-FGV','K2WM-SHZ','KCR4-MBW','KWZR-RPX']
# 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
end

# 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|
  puts person.id
end

Searching Records

search = communicator.familytree_v2.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 result.id #=> "KW3B-JXV"
  puts result.person.full_name #=> "John Doe"
  puts result.person.birth.date.original #=> "abt 1812"
  puts result.father.full_name #=> "Robert Doe"
  puts result.mother.full_name #=> "Ruby Johnson"
  puts result.spouses.first.full_name #=> "Sarah Franklin"
end

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']
new_person.id #=> '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."
note.id #=> 'ZnMtZnQucC5LVzNCLU5NRzpwLjE0MDAwMDAwNDIyOjQwMDAwM29nMlpWOTgxOVpCWWs4RjAwMA=='

# As soon as this bug is fixed, https://issues.devnet.familysearch.org/issues/show/149, 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

RDoc is hosted at rdoc.info:

rdoc.info/projects/jimmyz/ruby-fs-stack

Discussion

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

groups.google.com/group/ruby-fs-stack