Integrate FamilySearch Tree Data and Features in your App

What is a User Tree?

User trees are a new FamilySearch product that allows users to create and maintain a family tree and to choose if other users can view and edit it. They offer most of the same features as the FamilySearch global family tree, including record hints, photo upload, and source documentation. For example, third-party products can sync with user trees and receive record hints, helping users make new discoveries in their research.

User Trees and Global Family Tree: Similarities and Differences

The user and developer experience in user trees will be familiar to those already using the FamilySearch global tree. The User Tree API also uses the same endpoints that are used for the global family tree, with a few extra endpoints to cover the differences. Detailed descriptions of the differences can be found in the guide Comparison of Family Tree and User Trees.

User Tree API Features

The FamilySearch API offers the following user tree features:

1. Tree Sync. The API enables data to be synced between trees . The API provides a change history, enabling a synced client to stay up to date with tree data changes made on FamilySearch.org. Clients can likewise update the tree on FamilySearch.org to reflect changes that were made in the user’s local tree copy.
2. Research Hints. The API enables access to historical record and family tree hints on FamilySearch that match information in your users’ trees. Users can view records on FamilySearch.org, attach a record as a source, add facts about their ancestors, and sync the changes back to their client.
3. Publication. The API enables a user to publish a tree on FamilySearch. By publishing the tree on FamilySearch, users can be assured that the data published will remain available and accessible for generations to come. It also enables a researcher to be discovered by other researchers who may have more information about a particular family line.

User Tree Key Concepts

User trees and the FamilySearch global tree share a common underlying FamilySearch tree system. Therefore, many of the same API endpoints are used for both types of trees. It is helpful when working with user trees to understand the following concepts:

1. FamilySearch Tree System. FamilySearch provides API access to user trees and the global family tree. Each of these functions differently. Refer to the FamilySearch Tree System document for details on data organization and functionality.
2. User Tree Access Model. User trees introduce the ability to specify different access privileges for different users in a family tree. Additionally, developers can configure which clients can have API access to the trees created by their client. See the User Tree Access Model document to learn more about these access controls.
3. User Tree Privacy Settings. Users can set the privacy of a family tree to be either private or public. See the User Tree Privacy Settings document to learn more about how privacy settings work in a family tree.
4. Tree Selection. The API enables users to select which tree to work with during their session. See the Current Tree Selection document to learn more about how family tree selection affects the behavior of the API.
5. Early Access to User Trees. During the time in which user trees are in invite-only beta testing, you will need to request access. Apply for access from the FamilySearch Labs page, and send a message to [email protected].

User Tree Integration Guides

There are guides available with information about integrating an application with user trees. Depending upon the type of integration desired, a developer may implement one or more of these into an application.

Uploading a Tree to a User Tree

Uploading a tree to a user tree via the FamilySearch API enables users to maintain connectivity between their trees and the application that performed the upload. The process of uploading a tree through the API involves several steps which are explained in the Uploading a Tree to a User Tree document.

Downloading a User Tree

For trees accessible through the FamilySearch API, users can download data to their chosen application while maintaining connectivity to the data online. To learn more about the process of downloading a tree through the API, see the document Downloading a User Tree.

Syncing Family Trees

Once a family tree on FamilySearch is connected to a third-party application, users may wish to keep that data in sync. This means changes in one tree are reflected on the other tree. See the guide Syncing Family Trees to learn more about strategies for keeping data in sync.

Integrating Research Hints

One of the primary benefits of integrating with user trees is the ability for users to receive research hints. Family trees in user trees are matched with other FamilySearch data, including family trees and historical records. Integrated applications can access these hints, providing valuable research opportunities for their users. To learn more about integrating research hints, see the guide Integrating Hints.

Deleting User Trees

There may be times where a user desires to delete a family tree from user trees. The guide Deleting User Trees describes this process.