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

Tree Person Search

Description

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 an optional category, a mandatory term, an optional modifier, and an optional cardinality.

The category serves as a namespace to avoid query parameter name collision. Currently just one 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.

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, nick-names, 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

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 birth date, 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]] ).

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

Data Formats

Readable

If you make a GET request, specify the desired data format using the Accept header.

Writable

If you POST something, specify the data format using the Content-Type header.

Note: if you are expecting a BODY returned from a POST, you should also specify the format using the Accept header.

  • */*

Parameters

Name Type Description
Authorization header The authorization carrying the OAuth 2.0 access token. See OAuth 2.0 Bearer Tokens.
access_token query The ID of the OAuth 2 access token used for identification and authorization of the user (and agent) making the request.

Operations

GET - Read the results of a search.

Status Codes
200 Upon a successful read.
204 Upon a successful search with no results.
400 If the request was unable to be understood by the application. See response warning headers for details.
429 If the request was throttled.

Example Requests

Search for tree persons - first page How to get the first page of tree person search results.
Search for tree persons - next page How to get the next page (and by extension, subsequent pages) of tree person search results..
Search for tree persons with cardinality and modifier. How to search for tree persons using cardinality and modifiers.
Search for tree persons with wildcard characters How to search for tree persons using wildcard characters in the search parameter values.
x

Select a language