Person Search

Description

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

variable description
start The index of the first search result desired by the search client.
count The number of search results per page desired by the search client.
q

The query parameter that describes the search criteria. A parameter name and value is separated by a colon ':' and each name-value pair is separated by a white space ' '.

q=givenName:John surname:Smith gender:male birthDate:"30 June 1900"

Notice the white space in the birthDate value. If white space is required in the value, then the value must be wrapped in double quotes.

By default, values are exact. For non-exact matches append a tilde '~' at the end of the value such as givenName:Bob~.

name description
name: The full name of the person being searched.
givenName: The given name of the person being searched.
surname: The family name of the person being searched.
gender: The gender of the person being searched. Valid values are "male" and "female".
birthDate: The birth date of the person being searched. Date ranges are supported by placing a "-" between two dates.
birthPlace: The birth place of the person being searched.
christeningDate: The christening date of the person being searched. Date ranges are supported by placing a "-" between two dates.
christeningPlace: The christening place of the person being searched.
birthLikeDate: The date of the birth-like event of the person being searched. Date ranges are supported by placing a "-" between two dates.
birthLikePlace: The place of the birth-like event of the person being searched.
deathDate: The death date of the person being searched. Date ranges are supported by placing a "-" between two dates.
deathPlace: The death place of the person being searched.
burialDate: The burial date of the person being searched. Date ranges are supported by placing a "-" between two dates.
burialPlace: The burial place of the person being searched.
deathLikeDate: The date of the death-like event of the person being searched. Date ranges are supported by placing a "-" between two dates.
deathLikePlace: The place of the death-like event of the person being searched.
marriageDate: The marriage date of the person being searched. Date ranges are supported by placing a "-" between two dates.
marriagePlace: The marriage place of the person being searched.

Relation Search Parameters

The following set of standard parameters is defined as the substitution of {relation} with any of the values father, mother, and spouse.

{relation}Name: The full name of the {relation} of the person being searched.
{relation}GivenName: The given name of the {relation} of the person being searched.
{relation}Surname: The family name of the {relation} of the person being searched.
{relation}BirthDate: The birth date of the {relation} of the person being searched. Date ranges are supported by placing a "-" between two dates.
{relation}BirthPlace: The birth place of the {relation} of the person being searched.
{relation}DeathDate: The death date of the {relation} of the person being searched. Date ranges are supported by placing a "-" between two dates.
{relation}DeathPlace: The death place of the {relation} of the person being searched.
{relation}MarriageDate: The marriage date of the {relation} of the person being searched. Date ranges are supported by placing a "-" between two dates.
{relation}MarriagePlace: The marriage place of the {relation} of the person being searched.

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.

  • */*

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.
context query The search context token, allowing requests for subsequent pages. The context is supplied in the query response with the "X-FS-Page-Context" header.
count query The number of search results per page.
q query The search query.
start query The index of the first search result for this page of results.

Operations

GET - Read the results of a search.

Status Codes
200 Upon a successful read.
204 Upon a successful query with no results.
400 If the query to be processed was unable to be understood by the application.
400 If the application declines to process the query because it would have resulted in too many results.
429 If the request was throttled.
Warnings
299 If the query to be processed was unable to be understood by the application.
414 If the application declines to process the query because it would have resulted in too many results.

Example Requests

Read Next Page of Search Results How to get the first two entries of the next page of search results.
Search Persons How to search for persons.
Search Persons With Warnings and Errors Example illustrating what happens when there are warnings and errors during a person search.
x

Select a language