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 compatibility requirements 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.

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.

To create the Tree, send a POST request to the Genealogies Tree resource. The documentation provides an example request for creating the tree.

Example Requests - Create a Genealogies Tree

Create 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 Genealogies system uses a GEDCOM X data model consisting of Person, Relationship, and SourceDescription records.

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 http://gedcomx.org/ParentChild and http://gedcomx.org/Couple. The 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 person1 and 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.

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.

Example Requests - Adding persons and relationships

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.

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 gx1.
POST this person to the Genealogies API. You will receive back the ID for this person.
GET the person from the Genealogies API. Let's call this gx1'.
Compare gx1 to 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.