Family Tree Search

June 29, 2023

The Tree Person Search resource provides a powerful interface for users of third-party clients to find persons in the FamilySearch Family Tree. This guide will describe the behavior of the system and how to properly form a query to find the desired person records.

Search Results

Search results do not return information on living persons and will only contain persons for which the authenticated user has permissions to see. For each search hit, information regarding related people will also be contained in the results. The information returned by the search system is intended to help a user identify a person in the tree, but may not contain the “canonical” representation of the person and relationships. For canonical person information, please use the Tree Person resource.

Search results are returned in a GEDCOM X Atom format application/x-gedcomx-atom+json or application/x-gedcomx-atom+xml. Your client must include this in the Accept header or an error will be returned.

Accept: application/x-gedcomx-atom+json;

Search Fields

The Tree Person Search resource uses query string parameters to express search fields in the following format:

category.term[.modifer][.cardinality]=value

Category

The category of the parameter. For search query terms, the category will be q.

Term

The first part of a field and is a single search term such as givenName, surname, birthLikePlace, birthLikeDate, fatherGivenName, motherSurname, and marriageLikeDate. For a more comprehensive list, see the Tree Person Search resource documentation.

Modifier

Used to modify the options of a specific term. They come after the term. The value for a modifier is "on". Only one modifier can be applied per term. Multiple modifiers to a term require a new field. For example: q.surname=Tippitt&q.surname.require=on&q.surname.exact=on

Supported modifiers include:

• exact - Names: do not attempt to interpret name. Places: find this place or a place within its jurisdiction.  Supported on names and places.
• require - Term must be present in search results.  Supported on all terms. (Automatically applied to surname field when surname is supplied but not excluded)
• from - Turn the term into a range term, supplying from value. Causes any non-range value to be ignored. For example, q.residenceDate=+2016&q.residenceDate.from=+2000 will result in an open ended range search [2000 TO *].
• to - Turn the term into a range term, supplying to value. Causes any non-range value to be ignored. For example, q.residenceDate=+2016&q.residenceDate.to=+2015 will result in an open ended range search [* TO 2015].

Cardinality

A repeated term occurs when multiple values for a term are desired. Repeated terms beyond the initial term will be terminated with a single digit number from 1 to 9 to differentiate the fields. The initial term does not require a digit suffix. For example: q.surname=tippitt&q.surname.1=conley

Multi-word values, containing spaces, should not use repeated terms. The value must be properly URL encoded. For example: q.givenname=Juan%20Diego&q.surname=Lopez%20Garcia

Field Value

Field values should be URL Percent Encoded values as required. For example: givenName=Juan%20Diego

Repeated Terms

Repeated terms are generally associated with distinct events, persons or names. A single person can have multiple marriage places and dates. They are the same type of event, but distinct occurrences. Distinct occurrences of like events, persons or names are searched for within a single query by repeating the terms.

Grouped Terms

Term grouping is kept unique by using the cardinality. To search for a person married in Colorado in 1920 and then again in Nevada in 1940 repeat the terms adding the cardinality on the terms. Use the cardinality on the duplicated terms to indicate the correct grouping of the repeated terms. For example, correctly grouping the terms allows the search to locate the marriage in Colorado in 1920 and not marriages in Colorado in 1940:

q.marriagePlace=Colorado&q.marriageDate.from=+1920&q.marriageDate.to=+1920&q.marriagePlace.1=Nevada&q.marriageDate.1=+1940

Certain terms, if present will be grouped by default. All terms for a grouping do not need to be present.

• Names: (givenName, surname)
• Dates and Places: (birthLikeDate, birthLikePlace) (residenceDate, residencePlace) (deathLikeDate, deathLikePlace) 
• Spouse: (spouseGivenName, spouseSurname, marriageLikeDate, marriageLikePlace)
• Parents: (motherGivenName, motherSurname, motherBirthLikePlace) (fatherGivenName, fatherSurname, fatherBirthLikePlace) (parentGivenName, parentSurname) 

Repeated Grouped Terms

When grouped terms are repeated, they will be grouped according to the cardinality specified when repeating the terms. Repeated grouped terms ending in the same cardinality will be grouped together. For example: givenName=Florence%20Lee&q.surname=tippitt&q.givenName.1=Florence&q.surname.1=conley

Exact Modifier Details

The following rules apply to using the exact modifier on names and places:

• Names - All spaces, capitalization and diacritics are removed from the value. It will then be used to search for names that have had the same treatment applied to them. For example, the givenName of "RENÉE Noëlle" with givenName.exact=on will be converted to reneenoelle. Records that contain that exact treated givenName will be considered correct. A givenName of Rene E No Elle is considered a match.
• Places - Only that specific place or places within that jurisdiction are returned. For example, searching for "Utah County, Utah" will return records in Utah County, including records in Lehi, Provo, American Fork, etc; but not records outside of Utah County that are still in Utah. 

Terms with default behaviors

The following terms have default behaviors applied:

• names (givenName, surname, etc.) - Unless the exact modifier is applied, all names are compared using algorithms to increase recall. If exact is applied, then the name supplied must exactly match the original name as indexed or corrected in the record.  (Names are fuzzy by default)
• places - place searches that are not specified as "exact" will search records within three jurisdiction levels of the place searched. For example, searching for "Lehi, Utah County, Utah, USA" will return records in Lehi, Utah County, and Utah; but not all of USA.  
• date - dates can be supplied with granularity down to the day. Currently only the year of the date is honored when searching terms. Supplied dates may also be manipulated or extended to increase recall. The exact modifier is not currently supported on dates.
• father - searches using father terms will include father and parent events.
• mother - searches using mother terms will include mother and parent events.

Wildcards for Names

The following rules apply to using wildcards for name query terms.

• Names values may include the * and ? wildcards.
• Wildcard values with exact works as follows:
  • Jo?n exact will find John, Joan, etc.
  • Jo?n J* will include those with a second given name beginning with J.
• Remember, values must be URL Percent encoded so * becomes %2A and ? becomes %3F

Date Formats

The following rules apply to date formats:

• Dates will be formatted as Simple Dates as defined in: Gedcomx Simple Date (±YYYY[-MM[-DD]]). Currently, information beyond year is discarded.
• Date ranges are inclusive. q.birthLikeDate.from=+1920&q.birthLikeDate.to=+1925 will include 1920 and 1925

Search Result Paging

Search results are returned in paged result sets according to the count and offset query string parameters. It is recommended that the client follows the links included in the body of the search results leading to the next or previous pages.

JSON:

"links" : {
  "next" : {
    "href" : "https://api.familysearch.org/platform/tree/search?...&count=20&start=40"
  },
  "prev" : {
    "href" : "https://api.familysearch.org/platform/tree/search?...&count=20& &start=0"
  },
  "first" : {
    "href" : "https://api.familysearch.org/platform/tree/search?...&count=20&start=0"
  }
}

XML:

XML:

<link rel="first" href="https://api.familysearch.org/platform/tree/search?...&amp;count=20&amp;start=0"/>
<link rel="next" href="https://api.familysearch.org/platform/tree/search?... &amp;count=20&amp;start=40"/>
<link rel="prev" href="https://api.familysearch.org/platform/tree/search?... &amp;count=20&amp;start=0"/>

Sample API Searches