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

Person Matches by Example

Description

The Person Matches by Example resource returns a list of possible FamilySearch tree persons that match a person described by either query parameters (GET) or a GEDCOM X document containing person details (POST). This resource is particularly useful for matching a person in an external tree to a person in the FamilySearch tree. The Match by Tree Person Id resource should be used to find matches (possible duplicates) for a specific person already in the FamilySearch tree.

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

Person Matches are non-exact. The match algorithm will take into account all of the information given about the person (and the person's parents, children and spouses, if included) and return matches, each having a likelihood of the match being the same person that was specified in the request. Because the match algorithm is non-exact, a returned match may have information that does not exactly match the information specified in the request. The likelihood is contained in the ResultConfidence field of each Entry (match result).

Dates can be specific (20 July 1946), partial (May 1836 or just 1836), approximate (about 1793) or a range (1898-1903).


The following is for using the GET version of this resource:

As of May 1, 2018 this resource is deprecated because the functionality available in the POST version of this call allows more flexibility and more accurate matching.


variable description
q

The query parameter that describes the match 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.

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

Relation Match 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 matched.
{relation}GivenName: The given name of the {relation} of the person being matched.
{relation}Surname: The family name of the {relation} of the person being matched.
{relation}BirthDate: The birth date of the {relation} of the person being matched. Date ranges are supported by placing a "-" between two dates.
{relation}BirthPlace: The birth place of the {relation} of the person being matched.
{relation}DeathDate: The death date of the {relation} of the person being matched. Date ranges are supported by placing a "-" between two dates.
{relation}DeathPlace: The death place of the {relation} of the person being matched.
{relation}MarriageDate: The marriage date of the {relation} of the person being matched. Date ranges are supported by placing a "-" between two dates.
{relation}MarriagePlace: The marriage place of the {relation} of the person being matched.
{relation}Id: The ID of the {relation} of the person being matched.

The following is for using the POST version of this resource:



The POST body must contain a valid GEDCOM X JSON or XML block. The following elements of the GEDCOM X are required:

Primary Person There must be a primary person and the primary person must have an id (such as "primaryPerson")
Main Source Description There must be a main source description in the GEDCOM X document that points to the primary person (see Main sourceDescription.about below)
Main sourceDescription.about The main source description's about attribute must point to the primary person via an anchor tag (i.e. about="#primaryPerson")

Note: For more accurate results, the GEDCOM X POST body may (and should whenever possible) contain the main person's parents, spouses, and children. All of the persons in the GEDCOM X must have ID's so that relationships can be defined between the persons. Persons not specified in a relationship (other than the primary person) will be ignored when matching. The person ID's can be of any format. ID's such as "primaryPerson", "mother1","child1" etc. are acceptable and more intuitive for human understanding.


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.
confidence query The level of confidence of the results, an integer from 1 to 5. The higher the number the higher the confidence desired. The default value is 3.
count query The number of results to provide, an integer from 1 to 100. The default value is 5.
q query The match by example query for the GET version of this resource.

Operations

GET - Read the results of a match by example (A query is a form of an example).

As of May 1, 2018 this resource is deprecated because the functionality available in the POST version of this call will allow more flexibility and more accurate matching.

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.
414 If the application declines to process the query because it would have resulted in too many results.
429 If the request was throttled.
Warnings
400 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.

POST - Use the provided Gedcomx document to perform a match.

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.
414 If the application declines to process the query because it would have resulted in too many results.
429 If the request was throttled.
Warnings
400 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 Person Matches using Gedcomx How to request matches for a person using a Gedcomx document.
Read Person Matches using query How to request matches for a person using query parameters.
x

Select a language