The FamilySearch Genealogies API provides a database that stores non-collaborative, user-submitted genealogies. The data submitted to FamilySearch Genealogies is separate from the data in FamilySearch Family Tree. With the exception of living persons, genealogies data will be publicly visible and searchable, and can be matched against the FamilySearch Historical Records. The Genealogies data is not subject to the same constraints and certification restrictions as is data that is submitted to the FamilySearch Family Tree.
The Genealogies API is provided with the intent that the data in the FamilySearch Genealogies database will inform the collaborative research of the Family Tree and contribute to its accuracy and quality.
Like the Family Tree API, the Genealogies API conforms to the GEDCOM X specification set, but the data validation rules are generally less restrictive than are the rules of the Family Tree. For example, the Genealogies API supports more fact types and can support multiple values for facts like birth, death, burial, etc. Clients that conform to the GEDCOM X specification set can be used to access both the Family Tree API and the Genealogies API.
The FamilySearch Genealogies database is separated into multiple "trees" that can contain persons. A user can create a tree and add/update/remove persons from the tree. Relationships can be created between two persons in a tree, but are not read outside the context of the person.
For more information about the Genealogies API, refer to the Genealogies section of the API documentation.
Syncing Data to Genealogies
In order to sync data to the Genealogies system, use the following process:
- Obtain access token for the user.
- Create a new Genealogies Tree.
- Add data to the Genealogies Tree.
- Update persons and relationships.
- Get the matches.
Step 1: Obtain access token for the user
This is accomplished by sending the user through the OAuth 2 authentication and authorization process. More information can be found here. To obtain a temporary access token for testing, you can go to the following pages:
Step 2: Create a Genealogies Tree
A Tree in the Genealogies system is the container which will hold all of the tree persons and information regarding the user's tree. This is roughly equivalent to the user's file containing tree information for a desktop genealogy application. A user can create and access multiple trees, so it is important to keep a mapping to the ID of the tree created. Only the authenticated user that created the tree has access to edit or delete that tree.
Example Requests - Create a Genealogies Tree
Step 3: Add Data to the Genealogies Tree
There are a few different methods for adding information to the user's tree.
Working with the Genealogies Data Model
The relationship model is different from the GEDCOM 5.x model consisting of Person and Family records. Two relationship types are used by GEDCOM X, namely
ParentChild relationship is a directional relationship, meaning that
person1 represents the parent and
person2 represents the child. The
Couple relationship is not a directional relationship, however
standard convention suggests that
person1 is generally a male while
person2 is generally female. The order of
person2 will be preserved. From these two relationship types, you represent
the relationships implied in the Family record individually.
For more information, see the GEDCOM X Conceptual Model documentation.
Strategies for Adding Data
You can either add persons and relationships one at a time, or add multiple persons and relationships in in bulk.
Adding persons and relationships
To add one or more persons, send a
POST request to the Genealogies Tree resource. The
Genealogies Tree resource will accept
a payload containing up to 100 persons represented in a GEDCOM X document. ((TODO: HOW TO MAP IDS))
To add one or more relationships or sources, send a
POST request to the Genealogies Tree resource. It is advised to add all persons to
the the tree prior to adding the relationships or sources, so that you have identifiers for all persons represented in the requests. --Relationship IDs are composed of the IDs of the persons involved in the relationships.-- Sources may be referenced
by multiple Persons records, so it is best to create the source description after the persons IDs are known. ((TODO: DOCUMENT RELATIONSHIP IDS))
Example Requests - Adding persons and relationships
- Add Persons to Tree
- Read Tree Persons
- Read Person
- Add Relationship to Tree
- Add Fact to Relationship
- Add Source to Tree
- Read Source
Step 4: Update Persons, Relationships, and Sources
As person data changes in your application, you will need to keep the user's data in sync with the tree found in the Genealogies system. The Genealogies API supports additions and deletions. If the same fact value is written twice, ((TODO: does it ignore the new one or update the timestamp?)). ((TODO: What happens to the old IDs when data is deleted with a dependency?))
TODO: Information on Relationship updates.
The strategy for keeping the data up to date depends upon the capabilities of your system.
Example Requests - Update Persons, Relationships, and Sources
- Update Person
- Delete Person
- Update Relationship
- Delete Relationship
- Update Relationship Fact
- Delete Relationship Fact
- Update Source Description
- Delete Source Description
Change Tracking Method
If your system is able to track individual changes in the form of a change log, then the process to keep the Genealogies Tree up to date is a matter of replaying the same changes on the remote tree.
- If a new person with new relationships was added to the local tree, your application would add the new person with the new relationships to the remote tree.
- If a new fact was added on the local tree, the new fact could be added to the person in the remote tree.
- If a fact was changed on the local tree, the previous fact would be deleted and the new fact added.
Compare and Modify Method
If your system does not keep track of changes, then the best way to keep in sync is to compare your data with what is in the Genealogies system and to calculate the difference.
One approach for doing this would be to create a GEDCOM X representation of the person and to compare that GEDCOM X representation to the GEDCOM X person read from the Genealogies system. As you develop this method, it may be helpful to test your comparison algorithms by following these steps:
- Create a GEDCOM X document representing your local person. Let's call this
POSTthis person to the Genealogies API. You will receive back the ID for this person.
GETthe person from the Genealogies API. Let's call this
gx1'. Your comparison algorithm should indicate that they are the same.
Step 5: Get Matches
The last step in this process is to get matches (or hints) from the Genealogies API. The match resource will support the ability to read matches for both Family Tree persons as well as historical records.