The Tree Person Search resource defines the interface for performing a search for persons in the tree.

Each entry in the search results MAY contain content of the GEDCOM X media type that provides data about the results of the search, e.g., persons and relationships.

Due to the complexities of search operations, the query parameter names are broken up into parts. The parts consist of a mandatory category, a mandatory term, an optional modifier, and an optional cardinality.

The category serves as a namespace to avoid parameter name collision. The category q is defined to denote search query parameters which are documented in the Query Parameters table below. A category is required for all query parameter names except offset and count. Additional categories of f for filters and c for facets (or counts) are available. Filters are similar to query parameters, but do not allow any "fuzziness". The specified field value must match exactly or be filtered from the search results. Facets will count the terms and additional faceting information for the search term specified will be returned.

The term is the actual query parameter name such as givenName, birthLikePlace, parentSurname, etc. Again, the supported terms are documented in the Query Parameters table below.

The modifier modifies the way the search treats the specified term. The modifiers currently defined are exact, require,from and to.

The exact modifier is supported for Name and Place terms. By default, names are compared using algorithms to increase recall such as using spelling variants, nicknames, abbreviations, removal of diacritics and white space, etc. If exact is applied to a name, only results where the name exactly matches will be returned. Place searches that are not specified as exact will search records within three jurisdiction levels of the place searched (e.g. searching for "Lehi, Utah County, Utah, USA" will return records in Lehi, Utah County, and Utah; but not all of USA). The default value for all exact parameters unless otherwise noted is 'off'. To make a term exact, the value must be 'on'.

The require modifier is supported on all terms. When the require modifier is applied to a term, the term must be present for an entry to be included in the search results. The require modifier is automatically applied to the surname term.

The to and from modifiers are supported for Date terms and are used for date ranges. Date ranges can be open-ended and are inclusive.

The cardinality allows a term to be repeated and related terms to be associated correctly. For example, if the person being searched for was married two times, each spouse can be part of the query as shown below:

spouse #1 - q.spouseGivenName.1="Mary Ann"&q.spouseSurname.1=Smith

spouse #2 - q.spouseGivenName.2=Sally&q.spouseSurname.2=Brady.

This instructs the search engine to search for spouses named "Mary Ann Smith" and "Sally Brady", but not for spouses named "Mary Ann Brady" or "Sally Smith". Any other search query parameters associated with a specific spouse must have the same cardinality designator so the parameters are associated correctly. The cardinality designator is an integer with 1 <= cardinality <= 9.

General Guidelines

URLs should be properly encoded.

Values that contain white space must be surrounded by double quotes (i.e. q.givenName="Sally Mae").

Name values may include the '*' and '?' wildcard characters.

'BirthLike' dates and place values include dates and places of birth, christening, etc. The actual birthdate, if known, is preferred.

'DeathLike' dates and place values include dates and places of death, burial, cremation etc. The actual death date, if known, is preferred.

Date values are specified as Gedcomx Simple Date values ( ±YYYY[-MM[-DD]] ).

Place values are specified as either a string comparison or as a standardized place name, depending on the context of the search.

• A place query value expects a place string that consists of one or more jurisdictional levels which may include city, county, state, country, etc. Wildcards may be used for increased flexibility. (i.e. q.birthLikePlace = “Lehi, Utah County, Utah, USA”).
• A place filter or facet term often has a digit appended at the end of the term name. This helps specify multivalued terms. For example, f.birthLikePlace0 is the term to filter the country, f.birthLikePlace1 is the term to filter the state, and so on.
• A place filter or facet value expects a precise indication of place location identified in Places [https://www.familysearch.org/developers/docs/api/places/Place_resource]. These values are specified in standardized place name format as [parent_place_id],[place_name]. (i.e. f.birthLikePlace1=3,Alberta where the place_id of Canada is 3). Tip: The faceting information returned by queries with facet (count) terms enabled includes a “params” field, which specifies the parameters that could be used to filter a query by that facet’s value. For place terms, the parameter values are already in standardized form, making it easier to create a query filtered by that place, without having to look up the place id.

father/mother/parent terms - 'father' terms are parents with sex=Male; 'mother' terms are parents with sex=Female; 'parent' terms are parents with sex other than Male or Female.

Single term searches are not allowed unless the single term is surname.

Searches that do not include a surname will experience higher failure rates due to the fact that they are very resource intensive.

 

Query (category q) Parameters

Name	Description
q.givenName	The given name of the person being searched.
q.surname	The family name of the person being searched.
q.sex	The sex of the person being searched. Valid values are documented in Gedcomx Known Gender Types. 'http://gedcomx.org/' should not be included in the value. 'Male', 'Female', etc. is all that is required.
q.birthLikeDate	The birth like Gedcomx date of the person being searched.
q.birthLikePlace	The birth like place of the person being searched.
q.deathLikeDate	The death like Gedcomx date of the person being searched.
q.deathLikePlace	The death like place of the person being searched.
q.marriageLikeDate	The marriage like Gedcomx date of the person being searched.
q.marriageLikePlace	The marriage like place of the person being searched.
q.residenceDate	A Gedcomx date of residence of the person being searched.
q.residencePlace	A place of residence of the person being searched.
q.fatherGivenName	The given name of a father of the person being searched.
q.fatherSurname	The family name of a father of the person being searched.
q.fatherBirthLikePlace	The birth like place of a father of the person being searched.
q.motherGivenName	The given name of a mother of the person being searched.
q.motherSurname	The family name of a mother of the person being searched.
q.motherBirthLikePlace	The birth like place of a mother of the person being searched.
q.parentGivenName	The given name of a parent of the person being searched. If the sex is known to be 'Male' or 'Female', use 'mother' or 'father' rather than 'parent'.
q.parentSurname	The family name of a parent of the person being searched. If the sex is known to be 'Male' or 'Female', use 'mother' or 'father' rather than 'parent'.
q.parentBirthLikePlace	The birth like place of a parent of the person being searched.
q.spouseGivenName	The given name of the spouse of the person being searched.
q.spouseSurname	The family name of the spouse of the person being searched.

Other Parameters

Name	Description
offset	The 0 based index of the first result to be returned. Default = 0. 0 <= offset <= 4999
count	The maximum number of search results to return. Default = 20. 1 <= count <= 100.

The search will only return the first 5000 results. Therefore, if offset + count is >= 5000, the results will be truncated. If offset > 5000, a bad request status code will be returned.

 

Filter Guidelines

The f category is used to filter the search and is supported on all terms.

f.term's often have a digit appended at the end of the term name. This helps specify multivalued terms. For example f.birthLikePlace0 is the term to filter the country, f.birthLikePlace1 is the term to filter the state, and so on.

Note: Using an f.term with an empty value will require that the term be empty in search results.

Note: Using the f.treeId and the f.collectionId values requires turning on the Pending Modification for search.include.cet. See:

API Evolution Guide.

The f.collectionId is bounded by the collections FamilySearch makes available for searching. Right now the values are:

• tree or the uri https://familysearch.org/platform/collections/tree - FamilySearch Family Tree
• cet or the uri https://familysearch.org/platform/collections/cet - CET collections
• If no value is provided and the search.include.cet pending modification is enabled, results may include persons from both collections.

c category facets may be used to help determine valuable filters to be used on subsequent calls

Some example filter terms are:

f.birthPlace0 f.birthPlace1 f.birthPlace2 f.birthYear0
f.birthYear1 f.deathLikePlace0 f.deathLikePlace1 f.deathLikePlace2 f.deathYear0 f.deathYear1 f.eventPlaceLevel0 f.eventPlaceLevel1 f.eventPlaceLevel2 f.eventPlaceLevel3 f.eventPlaceLevel4 f.eventPlaceLevel5 f.place0 f.place1 f.place2 f.fatherGivennameStandard f.fatherSurnameStandard f.gender f.givenNameStandard f.maritalStatus f.marriagePlaceLevel0 f.marriagePlaceLevel1 f.marriagePlaceLevel2 f.marriageYear0 f.marriageYear1 f.motherGivennameStandard f.motherSurnameStandard f.spouseGivennameStandard f.spouseSurnameStandard f.surnameStandard f.treeId f.collectionId

 

Facet Guidelines

The c category is used to specify faceting or counted terms to be returned by the search. When set to "on", search will return faceting for the search term specified. e.g. c.gender=on

The returned Gedcomx object will have a facets object added to it. A facets object will be a list of facet objects.
A facet object will consist of the following:

• a displayName string containing the label that will be displayed to the user, this field cannot be null or empty
• a params string containing the query parameters that would be added to the request in order to filter and facet the next level, this field can be null or empty
• a count showing how many results match that face, this field can be null or empty
• a facets list of facet objects, this list can be null or empty

Some example facet terms are:

c.birthPlaceLevel0 c.birthPlaceLevel1 c.birthPlaceLevel2 c.birthYear0 c.birthYear1 c.deathPlaceLevel0 c.deathPlaceLevel1 c.deathPlaceLevel2 c.deathYear0 c.deathYear1 c.gender c.marriagePlaceLevel0 c.marriagePlaceLevel1 c.marriagePlaceLevel2 c.marriageYear0 c.marriageYear1 c.place0 c.place1 c.place2

 

The following is an example query using multiple filters and facets:
http://www.familysearch.org/platform/tree/search?q.surname=Smith&c.birthLikePlace2=on&f.birthLikePlace1=3%2CYukon&f.birthLikePlace1=3%2CAlberta&count=10