Attention: This site does not support the current version of your web browser. To get the best possible experience using our website we recommend that you upgrade to a newer version or install another browser

Skip main navigation

Using Collections to Find FamilySearch Data

This guide will assist you in using the Collections Resources to locate FamilySearch data using the FamilySearch API.

The Discovery resources were originally used to discover FamilySearch data, but have been expanded and replaced by the Collections resources. For a historical perspective on the migration from Discovery to Collections resources, see the Discovery Resource Migration guide.

The collection that contains all of the FamilySearch data is described as the Root or Home collection. The Root Collection is divided into subcollections which are subsystems managed by FamilySearch, such as the FamilySearch Family Tree, FamilySearch Historical Records Archive, and FamilySearch Memories.

Finding FamilySearch Data

The collections are entry points into the FamilySearch data and allow discovery of what is being made available by the API. Any resource or link that is not listed is designed to be accessed through intermediate resources. For example, in the Family Tree Collection, there is no link to the Person Change History resource because you are expected to first get the person which contains the changes link. You should not have to plug in identifiers to a URI template to resolve resources (see the Hypermedia guide).

For example, if you want to read spouses connected to a person in the FamilySearch Family Tree, you would write code that does the following:

  1. Reads the FamilySearch Family Tree Collection to find the person-search link and follows the link to search for a person:

  2. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <gedcomx xmlns="http://gedcomx.org/v1/" xmlns:fs="http://familysearch.org/v1/" xmlns:atom="http://www.w3.org/2005/Atom" description="#SD-FSFT">
    <collection id="FSFT">
    ...
      <link rel="person-search" template="https://familysearch.org/platform/tree/search"/>
    ...
      <title>FamilySearch Family Tree</title>
    </collection>
    </gedcomx>
    

  3. Finds the person link in the search results and follows the link to read the person:

  4. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <gedcomx xmlns="http://gedcomx.org/v1/" xmlns:fs="http://familysearch.org/v1/" xmlns:atom="http://www.w3.org/2005/Atom" description="#SD-FSFT">
      <entry>
        <content type="application/x-gedcomx-v1+xml">
          <gx-gedcomx>
            <gx:person id="MMM3-K67">
              <link rel="person" href="https://familysearch.org/platform/tree/persons/MMM3-KG7"/>
              ...
            </gx:person>
        </content>
      </entry>
    </feed>
    

  5. Finds the spouses link and follows the link to read the spouses:

  6. <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <gedcomx xmlns="http://gedcomx.org/v1/" xmlns:fs="http://familysearch.org/v1/" xmlns:atom="http://www.w3.org/2005/Atom" description="#SD-PPPJ-MYZ">
      <person id="PPJ-MYZ">
      ...
        <link rel="spouses" href="https://familysearch.org/platform/tree/persons/PPPJ-MYZ/spouses"/>
      ...
      </person>
    </gedcomx>
    

If there's a resource that should be directly accessible and it isn't listed in the collection, contact Support at devsupport@familysearch.org. They may be able to add more entry points.

Data Access Paths

The following are the main types of data that are stored in the FamilySearch data collections.

  • Tree - People and their associated information and relationships.
  • Memories – Artifacts including documents, stories, and pictures.
  • Places – Locations by both current and historic names.
  • Sources – Documents and references used to verify tree conclusions.

Tree Person Data

When you read a person in the FamilySearch Family Tree, you have immediate access to certain facts, and links to other information about the person.

Facts

Simplified facts about a person are in the display section. These are intended for quick display purposes, but do not contain the richness of the data in the elements found on the person record. For example, you can find the birthday of a person in the display->birthdate. The facts are also stored in the Gedcom X fields such as fact type=”http://gedcomx.org/Birth”->date. For more information, see the Gedcom X guide and the FamilySearch Data Formats.

Links

  • Ancestors
  • Artifacts (memories, stories, and documents)
  • Change history
  • Children
  • Descendants
  • Discussions
  • Notes
  • Parents
  • Portraits
  • Sources
  • Spouses

Access to Tree Person Data

To access FamilySearch Family Tree data, begin by authenticating then access the “tree” collection directly or indirectly.

The following illustration is a high level diagram of the potential data access paths.

Direct Access

If you already have a person identification (PID) number, you can hard code URIs to go directly to FamilySearch API Resource endpoints to obtain specific information you are looking for. You can find person information directly using the following API Resources:

  • Person
  • Memories
  • Discussions
  • Children
  • Parents
  • Spouses
  • Ancestors
  • Descendants

For example, if you know that a person’s PID is MMMM-DDD, you can make a direct request for the memories that are attached to that person by inserting MMMM-DDD as designated into the Person Memories endpoint path and making a call to that path.

Indirect Access

You can follow a path of links to gain indirect access to the data you are looking for without hard coding URIs. These links are found in the response pages of certain API resource calls. To get started on a path go to the Family Tree collection by making one of the following API resource calls:

Note: Subsystems in the collections list such as memories, places, and sources might include information that is not yet associated or attached to people in the Family Tree.

From the Family Tree response, follow links to get the current user, get the current tree person, or use other links or URL templates to get the following information:

Links:
  • Memories
  • Discussions
  • Relationships
URL templates to resources:
  • Ancestry-query
  • Descendancy-query
  • Matches
  • Person-matches-query
  • Person-search
  • Person-with-relationships
  • Person
  • Preferred-parent-relationship
  • Preferred-spouse-relationship
  • Source-references-query

Sample Indirect Data Access Paths

Search for a person in the Family Tree

You can do one of the following:

Find Parents Information
  1. Get the person record
  2. Link to the "parents"
  3. Link to any of the following
    • Parent1
    • Parent2
    • Couple Relationship
    • ParentChild relationship (Parent1)
    • ParentChild relationship (Parent2)
    • ChildAndParentsRelationship
Find Children Information
  1. Get the person record
  2. Link to the "children"
  3. Link to any of the following
    • Any one of the children
    • ParentChild relationship (any of the children)
    • ChildAndParentsRelationship (any of the children)
Find Sources Information
  1. Get the person record
  2. Link to the "sources-description"
    • Read the title, text, or notes
    • Link to attributions
    • Link to the person attribution
  3. Link to source-references for descriptions and attributions
x

Select a language