Read Person Matches using query

This example request illustrates how to request matches for a person that does not exist in the database. The person is described using the match query. 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.

JSON

Request

GET /platform/tree/matches?q=spouseGivenName:Charlotte~+gender:Male~+givenName:Israel~+motherSurname:Hoyt~+birthDate:%2230+January+1880%22~+spouseSurname:Cox~+birthPlace:%22Orderville,+UT%22~+motherGivenName:Clarissa~+deathPlace:%22Kanab,+Kane,+UT%22~+surname:Heaton~+deathDate:%2229+August+1936%22~+fatherSurname:Heaton~+fatherGivenName:Jonathan~&count=10
Accept: application/x-gedcomx-atom+json
Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Response

HTTP/1.1 200 OK
Content-type: application/x-gedcomx-atom+json
X-processing-time: 3
Warning: The GET version of the '/tree/matches' API has been deprecated. Use the POST version.
Vary: Accept,Accept-Language,Accept-Encoding,Expect
Date: Sun, 03 Apr 1836 10:00:00 GMT-5
Cache-control: no-cache, no-store, no-transform, must-revalidate, max-age=0
Transfer-encoding: chunked{
  "id" : "uuid:random_uuid",
  "results" : 2,
  "index" : 1,
  "subtitle" : "Results for person matches.",
  "title" : "Person Match Results",
  "updated" : 1543677067759,
  "links" : {
    "self" : {
      "href" : "https://api.familysearch.org/platform/tree/matches?flag=fsh&count=10&q=spouseGivenName:Charlotte~+gender:Male~+givenName:Israel~+motherSurname:Hoyt~+birthDate:%2230+January+1880%22~+spouseSurname:Cox~+birthPlace:%22Orderville,+UT%22~+motherGivenName:Clarissa~+deathPlace:%22Kanab,+Kane,+UT%22~+surname:Heaton~+deathDate:%2229+August+1936%22~+fatherSurname:Heaton~+fatherGivenName:Jonathan~"
    }
  },
  "entries" : [ {
    "content" : {
      "gedcomx" : {
        "description" : "sd1",
        "persons" : [ {
          "id" : "MMM3-KG7",
          "gender" : {
            "type" : "http://gedcomx.org/Male"
          },
          "links" : {
            "person" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMM3-KG7?flag=fsh"
            },
            "portrait" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMM3-KG7/portrait?flag=fsh"
            }
          },
          "identifiers" : {
            "http://gedcomx.org/Persistent" : [ "https://familysearch.org/ark:/61903/4:1:MMM3-KG7" ]
          },
          "names" : [ {
            "type" : "http://gedcomx.org/BirthName",
            "nameForms" : [ {
              "fullText" : "Israel Heaton"
            } ]
          } ],
          "facts" : [ {
            "type" : "http://gedcomx.org/Birth",
            "date" : {
              "original" : "30 January 1880"
            },
            "place" : {
              "original" : "Orderville, UT"
            }
          }, {
            "type" : "http://gedcomx.org/Death",
            "date" : {
              "original" : "29 August 1936"
            },
            "place" : {
              "original" : "Kanab, Kane, UT"
            }
          } ],
          "display" : {
            "name" : "type=BirthName,nameForms[0]=Israel Heaton,pref=null",
            "gender" : "type=Male",
            "birthDate" : "30 January 1880",
            "deathDate" : "29 August 1936"
          }
        }, {
          "id" : "MMM3-485",
          "gender" : {
            "type" : "http://gedcomx.org/Male"
          },
          "links" : {
            "person" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMM3-485?flag=fsh"
            },
            "portrait" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMM3-485/portrait?flag=fsh"
            }
          },
          "identifiers" : {
            "http://gedcomx.org/Persistent" : [ "https://familysearch.org/ark:/61903/4:1:MMM3-485" ]
          },
          "names" : [ {
            "nameForms" : [ {
              "fullText" : "Jonathan Heaton"
            } ]
          } ],
          "display" : {
            "name" : "type=null,nameForms[0]=Jonathan Heaton,pref=null",
            "gender" : "type=Male"
          }
        }, {
          "id" : "MMMS-R96",
          "gender" : {
            "type" : "http://gedcomx.org/Female"
          },
          "links" : {
            "person" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMMS-R96?flag=fsh"
            },
            "portrait" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMMS-R96/portrait?flag=fsh"
            }
          },
          "identifiers" : {
            "http://gedcomx.org/Persistent" : [ "https://familysearch.org/ark:/61903/4:1:MMMS-R96" ]
          },
          "names" : [ {
            "nameForms" : [ {
              "fullText" : "Clarissa Hoyt"
            } ]
          } ],
          "display" : {
            "name" : "type=null,nameForms[0]=Clarissa Hoyt,pref=null",
            "gender" : "type=Female"
          }
        }, {
          "id" : "MMMS-DLS",
          "gender" : {
            "type" : "http://gedcomx.org/Female"
          },
          "links" : {
            "person" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMMS-DLS?flag=fsh"
            },
            "portrait" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMMS-DLS/portrait?flag=fsh"
            }
          },
          "identifiers" : {
            "http://gedcomx.org/Persistent" : [ "https://familysearch.org/ark:/61903/4:1:MMMS-DLS" ]
          },
          "names" : [ {
            "nameForms" : [ {
              "fullText" : "Charlotte Cox"
            } ]
          } ],
          "display" : {
            "name" : "type=null,nameForms[0]=Charlotte Cox,pref=null",
            "gender" : "type=Female"
          }
        }, {
          "id" : "MMMS-MZL",
          "gender" : {
            "type" : "http://gedcomx.org/Male"
          },
          "links" : {
            "person" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMMS-MZL?flag=fsh"
            },
            "portrait" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMMS-MZL/portrait?flag=fsh"
            }
          },
          "identifiers" : {
            "http://gedcomx.org/Persistent" : [ "https://familysearch.org/ark:/61903/4:1:MMMS-MZL" ]
          },
          "names" : [ {
            "nameForms" : [ {
              "fullText" : "Alma Heaton"
            } ]
          } ],
          "display" : {
            "name" : "type=null,nameForms[0]=Alma Heaton,pref=null",
            "gender" : "type=Male"
          }
        } ],
        "relationships" : [ {
          "type" : "http://gedcomx.org/ParentChild",
          "person1" : {
            "resource" : "#MMM3-485",
            "resourceId" : "MMM3-485"
          },
          "person2" : {
            "resource" : "#MMM3-KG7",
            "resourceId" : "MMM3-KG7"
          }
        }, {
          "type" : "http://gedcomx.org/ParentChild",
          "person1" : {
            "resource" : "#MMMS-R96",
            "resourceId" : "MMMS-R96"
          },
          "person2" : {
            "resource" : "#MMM3-KG7",
            "resourceId" : "MMM3-KG7"
          }
        }, {
          "type" : "http://gedcomx.org/Couple",
          "person1" : {
            "resource" : "#MMM3-KG7",
            "resourceId" : "MMM3-KG7"
          },
          "person2" : {
            "resource" : "#MMMS-DLS",
            "resourceId" : "MMMS-DLS"
          }
        }, {
          "type" : "http://gedcomx.org/ParentChild",
          "person1" : {
            "resource" : "#MMM3-KG7",
            "resourceId" : "MMM3-KG7"
          },
          "person2" : {
            "resource" : "#MMMS-MZL",
            "resourceId" : "MMMS-MZL"
          }
        } ]
      }
    },
    "id" : "MMM3-KG7",
    "score" : 0.95,
    "title" : "Person MMM3-KG7 (type=BirthName,nameForms[0]=Israel Heaton,pref=null)",
    "updated" : 1543677067759,
    "links" : {
      "person" : {
        "href" : "https://api.familysearch.org/platform/tree/persons/MMM3-KG7?flag=fsh"
      }
    }
  }, {
    "content" : {
      "gedcomx" : {
        "description" : "sd2",
        "persons" : [ {
          "id" : "MMM9-VMZ",
          "links" : {
            "person" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMM9-VMZ?flag=fsh"
            },
            "portrait" : {
              "href" : "https://api.familysearch.org/platform/tree/persons/MMM9-VMZ/portrait?flag=fsh"
            }
          },
          "identifiers" : {
            "http://gedcomx.org/Persistent" : [ "https://familysearch.org/ark:/61903/4:1:MMM9-VMZ" ]
          },
          "names" : [ {
            "type" : "http://gedcomx.org/BirthName",
            "nameForms" : [ {
              "fullText" : "Israel Hoyt Heaton"
            } ]
          } ],
          "display" : {
            "name" : "type=BirthName,nameForms[0]=Israel Hoyt Heaton,pref=null"
          }
        } ]
      }
    },
    "id" : "MMM9-VMZ",
    "score" : 0.85,
    "title" : "Person MMM9-VMZ (type=BirthName,nameForms[0]=Israel Hoyt Heaton,pref=null)",
    "updated" : 1543677067759,
    "links" : {
      "person" : {
        "href" : "https://api.familysearch.org/platform/tree/persons/MMM9-VMZ?flag=fsh"
      }
    }
  } ],
  "searchInfo" : [ {
    "totalHits" : 2,
    "closeHits" : 1
  } ]
}

XML

Request

GET /platform/tree/matches?q=spouseGivenName:Charlotte~+gender:Male~+givenName:Israel~+motherSurname:Hoyt~+birthDate:%2230+January+1880%22~+spouseSurname:Cox~+birthPlace:%22Orderville,+UT%22~+motherGivenName:Clarissa~+deathPlace:%22Kanab,+Kane,+UT%22~+surname:Heaton~+deathDate:%2229+August+1936%22~+fatherSurname:Heaton~+fatherGivenName:Jonathan~&count=10
Accept: application/atom+xml
Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Response

HTTP/1.1 200 OK
Content-type: application/atom+xml
X-processing-time: 3
Warning: The GET version of the '/tree/matches' API has been deprecated. Use the POST version.
Vary: Accept,Accept-Language,Accept-Encoding,Expect
Date: Sun, 03 Apr 1836 10:00:00 GMT-5
Cache-control: no-cache, no-store, no-transform, must-revalidate, max-age=0
Transfer-encoding: chunked<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<feed xmlns:fs="http://familysearch.org/v1/" xmlns:gx="http://gedcomx.org/v1/" xmlns="http://www.w3.org/2005/Atom">
    <fs:searchInfo>
        <fs:closeHits>1</fs:closeHits>
        <fs:totalHits>2</fs:totalHits>
    </fs:searchInfo>
    <id>uuid:random_uuid</id>
    <gx:results>2</gx:results>
    <gx:index>1</gx:index>
    <link rel="self" href="https://api.familysearch.org/platform/tree/matches?flag=fsh&amp;count=10&amp;q=spouseGivenName:Charlotte~+gender:Male~+givenName:Israel~+motherSurname:Hoyt~+birthDate:%2230+January+1880%22~+spouseSurname:Cox~+birthPlace:%22Orderville,+UT%22~+motherGivenName:Clarissa~+deathPlace:%22Kanab,+Kane,+UT%22~+surname:Heaton~+deathDate:%2229+August+1936%22~+fatherSurname:Heaton~+fatherGivenName:Jonathan~"/>
    <subtitle>Results for person matches.</subtitle>
    <title>Person Match Results</title>
    <updated>2018-12-01T08:11:07.759-07:00</updated>
    <entry>
        <content type="application/x-gedcomx-v1+xml">
            <gx:gedcomx description="sd1">
                <gx:person id="MMM3-KG7">
                    <gx:link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMM3-KG7?flag=fsh"/>
                    <gx:link rel="portrait" href="https://api.familysearch.org/platform/tree/persons/MMM3-KG7/portrait?flag=fsh"/>
                    <gx:identifier type="http://gedcomx.org/Persistent">https://familysearch.org/ark:/61903/4:1:MMM3-KG7</gx:identifier>
                    <gx:gender type="http://gedcomx.org/Male"/>
                    <gx:name type="http://gedcomx.org/BirthName">
                        <gx:nameForm>
                            <gx:fullText>Israel Heaton</gx:fullText>
                        </gx:nameForm>
                    </gx:name>
                    <gx:fact type="http://gedcomx.org/Birth">
                        <gx:date>
                            <gx:original>30 January 1880</gx:original>
                        </gx:date>
                        <gx:place>
                            <gx:original>Orderville, UT</gx:original>
                        </gx:place>
                    </gx:fact>
                    <gx:fact type="http://gedcomx.org/Death">
                        <gx:date>
                            <gx:original>29 August 1936</gx:original>
                        </gx:date>
                        <gx:place>
                            <gx:original>Kanab, Kane, UT</gx:original>
                        </gx:place>
                    </gx:fact>
                    <gx:display>
                        <gx:birthDate>30 January 1880</gx:birthDate>
                        <gx:deathDate>29 August 1936</gx:deathDate>
                        <gx:gender>type=Male</gx:gender>
                        <gx:name>type=BirthName,nameForms[0]=Israel Heaton,pref=null</gx:name>
                    </gx:display>
                </gx:person>
                <gx:person id="MMM3-485">
                    <gx:link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMM3-485?flag=fsh"/>
                    <gx:link rel="portrait" href="https://api.familysearch.org/platform/tree/persons/MMM3-485/portrait?flag=fsh"/>
                    <gx:identifier type="http://gedcomx.org/Persistent">https://familysearch.org/ark:/61903/4:1:MMM3-485</gx:identifier>
                    <gx:gender type="http://gedcomx.org/Male"/>
                    <gx:name>
                        <gx:nameForm>
                            <gx:fullText>Jonathan Heaton</gx:fullText>
                        </gx:nameForm>
                    </gx:name>
                    <gx:display>
                        <gx:gender>type=Male</gx:gender>
                        <gx:name>type=null,nameForms[0]=Jonathan Heaton,pref=null</gx:name>
                    </gx:display>
                </gx:person>
                <gx:person id="MMMS-R96">
                    <gx:link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMMS-R96?flag=fsh"/>
                    <gx:link rel="portrait" href="https://api.familysearch.org/platform/tree/persons/MMMS-R96/portrait?flag=fsh"/>
                    <gx:identifier type="http://gedcomx.org/Persistent">https://familysearch.org/ark:/61903/4:1:MMMS-R96</gx:identifier>
                    <gx:gender type="http://gedcomx.org/Female"/>
                    <gx:name>
                        <gx:nameForm>
                            <gx:fullText>Clarissa Hoyt</gx:fullText>
                        </gx:nameForm>
                    </gx:name>
                    <gx:display>
                        <gx:gender>type=Female</gx:gender>
                        <gx:name>type=null,nameForms[0]=Clarissa Hoyt,pref=null</gx:name>
                    </gx:display>
                </gx:person>
                <gx:person id="MMMS-DLS">
                    <gx:link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMMS-DLS?flag=fsh"/>
                    <gx:link rel="portrait" href="https://api.familysearch.org/platform/tree/persons/MMMS-DLS/portrait?flag=fsh"/>
                    <gx:identifier type="http://gedcomx.org/Persistent">https://familysearch.org/ark:/61903/4:1:MMMS-DLS</gx:identifier>
                    <gx:gender type="http://gedcomx.org/Female"/>
                    <gx:name>
                        <gx:nameForm>
                            <gx:fullText>Charlotte Cox</gx:fullText>
                        </gx:nameForm>
                    </gx:name>
                    <gx:display>
                        <gx:gender>type=Female</gx:gender>
                        <gx:name>type=null,nameForms[0]=Charlotte Cox,pref=null</gx:name>
                    </gx:display>
                </gx:person>
                <gx:person id="MMMS-MZL">
                    <gx:link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMMS-MZL?flag=fsh"/>
                    <gx:link rel="portrait" href="https://api.familysearch.org/platform/tree/persons/MMMS-MZL/portrait?flag=fsh"/>
                    <gx:identifier type="http://gedcomx.org/Persistent">https://familysearch.org/ark:/61903/4:1:MMMS-MZL</gx:identifier>
                    <gx:gender type="http://gedcomx.org/Male"/>
                    <gx:name>
                        <gx:nameForm>
                            <gx:fullText>Alma Heaton</gx:fullText>
                        </gx:nameForm>
                    </gx:name>
                    <gx:display>
                        <gx:gender>type=Male</gx:gender>
                        <gx:name>type=null,nameForms[0]=Alma Heaton,pref=null</gx:name>
                    </gx:display>
                </gx:person>
                <gx:relationship type="http://gedcomx.org/ParentChild">
                    <gx:person1 resource="#MMM3-485" resourceId="MMM3-485"/>
                    <gx:person2 resource="#MMM3-KG7" resourceId="MMM3-KG7"/>
                </gx:relationship>
                <gx:relationship type="http://gedcomx.org/ParentChild">
                    <gx:person1 resource="#MMMS-R96" resourceId="MMMS-R96"/>
                    <gx:person2 resource="#MMM3-KG7" resourceId="MMM3-KG7"/>
                </gx:relationship>
                <gx:relationship type="http://gedcomx.org/Couple">
                    <gx:person1 resource="#MMM3-KG7" resourceId="MMM3-KG7"/>
                    <gx:person2 resource="#MMMS-DLS" resourceId="MMMS-DLS"/>
                </gx:relationship>
                <gx:relationship type="http://gedcomx.org/ParentChild">
                    <gx:person1 resource="#MMM3-KG7" resourceId="MMM3-KG7"/>
                    <gx:person2 resource="#MMMS-MZL" resourceId="MMMS-MZL"/>
                </gx:relationship>
            </gx:gedcomx>
        </content>
        <id>MMM3-KG7</id>
        <link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMM3-KG7?flag=fsh"/>
        <gx:score>0.95</gx:score>
        <title>Person MMM3-KG7 (type=BirthName,nameForms[0]=Israel Heaton,pref=null)</title>
        <updated>2018-12-01T08:11:07.759-07:00</updated>
    </entry>
    <entry>
        <content type="application/x-gedcomx-v1+xml">
            <gx:gedcomx description="sd2">
                <gx:person id="MMM9-VMZ">
                    <gx:link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMM9-VMZ?flag=fsh"/>
                    <gx:link rel="portrait" href="https://api.familysearch.org/platform/tree/persons/MMM9-VMZ/portrait?flag=fsh"/>
                    <gx:identifier type="http://gedcomx.org/Persistent">https://familysearch.org/ark:/61903/4:1:MMM9-VMZ</gx:identifier>
                    <gx:name type="http://gedcomx.org/BirthName">
                        <gx:nameForm>
                            <gx:fullText>Israel Hoyt Heaton</gx:fullText>
                        </gx:nameForm>
                    </gx:name>
                    <gx:display>
                        <gx:name>type=BirthName,nameForms[0]=Israel Hoyt Heaton,pref=null</gx:name>
                    </gx:display>
                </gx:person>
            </gx:gedcomx>
        </content>
        <id>MMM9-VMZ</id>
        <link rel="person" href="https://api.familysearch.org/platform/tree/persons/MMM9-VMZ?flag=fsh"/>
        <gx:score>0.85</gx:score>
        <title>Person MMM9-VMZ (type=BirthName,nameForms[0]=Israel Hoyt Heaton,pref=null)</title>
        <updated>2018-12-01T08:11:07.759-07:00</updated>
    </entry>
</feed>