Tree Person Search
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.
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.
|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
If you make a
GET request, specify the desired data format using the
POST something, specify the data format using the
Note: if you are expecting a
BODY returned from a
POST, you should also specify the format using the
|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.|
GET - Read the results of a search.
|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.|