2021 - Q1 Newsletter
This edition will cover the following topics:
- 2021 - Q1 Newsletter
Scheduled Maintenance
New Enumeration values for Ordinance Rollup Status
In the coming weeks, new values will be added to the enumeration for the Ordinance Rollup Status. Your application logic should ignore any of these new values that it doesn't know how to handle. See Ordinance Rollup Status resource for more information.
New Ordinances Completed endpoint
The Ordinances Completed endpoint is available in Beta for viewing the recent recorded ordinances completed by the current user and will be released to Production in the coming weeks. This information is helpful for those users that may want additional verification beyond what is currently available in Family Tree but may not necessarily prove that the ordinance was completed. Rather it provides assistance for a FamilySearch support person to determine the exact status of a missing ordinance. Users contacting FamilySearch Support should provide all information from the Ordinances Completed report related to their specific question about a person’s ordinances.
Please note: Additional details regarding this endpoint are available in the API documentation for Ordinances. See Church Related Services for more information regarding access to ordinance endpoints for authorized partners.
[UPDATE] Enumeration values for Relationship Types
As mentioned in December 2020, the enumeration for Relationship Types will include new values. However because of some critical dependencies, this update has been delayed until Q3 or Q4 2021. We will provide additional reminders in upcoming newsletters as we have additional information.
Change to Match results
FamilySearch data analysts have noted that some inexperienced users accept all Match suggestions rather than reviewing them for accuracy. To avoid merging records in error, a minor change will be made to the Person Matches By Example and Match By Tree Person Id endpoints results in coming weeks. The default confidence will be increased to 5 (high confidence) rather than 4 as it is now. No action is needed if you prefer following the same confidence logic as familysearch.org. The confidence parameter will continue to be accepted if expanded results are desired.
[UPDATE] OAuth 2.0 Changes for Desktop and Mobile
All integrated desktop and mobile applications using the OAuth 2.0 Password Flow will be affected by the delay mentioned in the 2020 Q4 Newsletter but will be available for release starting mid-2021. This new authentication method is available today in Integration, Beta, and Production for development and testing.
A new guide OAuth 2.0 for Native Apps has been released to assist in this transition. Sample code and detailed explanation of how this works is included.
We are working on an enhancement which will allow users of desktop and mobile apps to have long-lived authentication. The current implementation requires a user to check the "keep me signed in for 2 weeks" checkbox in order to receive a refresh token that is only valid for two weeks. The enhancement will always issues a refresh token with an expiration of 90 days.
Your application should provide your user an option to remember authentication on the device. If selected, your application should make use of the refresh token. If not selected, your application should ignore the refresh token and honor the user's selection.
We recommend that you do not release your application with updated OAuth 2.0 code until the Production environment includes the release of this enhancement, targeted for release mid-2021. Once released, the password flow will continue to be supported for a sufficient window of time to allow your customers to upgrade. More precise dates will be published in the Q2 Newsletter.
Please contact devsupport@familysearch.org if you have any questions or need help. We are happy to set up a time to walk you through the details and answer questions.
Change to Search Results
Subtle data changes have been made to search results to improve performance and increase compatibility with the GedcomX standard for international character sets. Please confirm that your application can correctly handle the following examples. These changes are already available for development and testing in the Integration environment. This experiment can be turned on in the Beta and Production environments using the following header. The final release to Production could be as early as June 2021.
search.return.enhanced.gedcomx
Please Note: The examples (below) may not be the "final" versions of this data. They are given as examples of GedcomX representations of this tree data.
1. Person Names
The primary person and the secondary people each contain all of their Names. Each Name preserves all of the NameForms and the attributes associated with each NameForm.
Example: Person Names
"persons": [
{
"living": false,
"gender": {
"type": "http://gedcomx.org/Male"
},
"names": [
{
"preferred": true,
"nameForms": [
{
"fullText": "王漢永",
"parts": [...],
"lang": "zh-Hani"
},
{
"fullText": "Cannon Jonathan",
"parts": [...],
"lang": "zh-Latn"
}
],
"type": "http://gedcomx.org/BirthName"
},
{
"preferred": false,
"nameForms": [
{
"fullText": "王磊",
"parts": [...],
"lang": "zh-Hani"
},
{
"fullText": "Cannon Jon",
"parts": [...],
"lang": "zh-Latn"
}
],
"type": "http://gedcomx.org/AlsoKnownAs"
}
],
"facts": [...],
"fields": [...],
"display": {...},
"id": "LR45-S6P",
"identifiers": {...},
"sortKey": "0000000000"
},
{
"living": false,
"gender": {
"type": "http://gedcomx.org/Male"
},
"names": [
{
"preferred": true,
"nameForms": [
{
"fullText": "Michael Cannon",
"parts": [...],
"lang": "en"
}
],
"type": "http://gedcomx.org/BirthName"
},
{
"preferred": false,
"nameForms": [
{
"fullText": "Mike Cannon",
"parts": [...],
"lang": "en"
}
],
"type": "http://gedcomx.org/AlsoKnownAs"
},
{
"preferred": false,
"nameForms": [
{
"fullText": "Mike the Psyche",
"parts": [...],
"lang": "en"
}
],
"type": "http://gedcomx.org/Nickname"
},
{
"preferred": false,
"nameForms": [
{
"fullText": "王한영",
"parts": [...],
"lang": "zh-Hani"
},
{
"fullText": "Cannon M",
"parts": [...],
"lang": "zh-Latn"
}
],
"type": "http://gedcomx.org/AlsoKnownAs"
}
],
"facts": [...],
"fields": [...],
"display": {...},
"id": "LRW2-7C6",
"identifiers": {...}
}
]
2. Person facts/fields/misc.
- The primary and secondary person(s) have facts, fields, and identifiers.
- The fact "place" attribute now has more information than just the original place name. It now includes the "normalized" attribute.
- Relationship facts will no longer be included with person facts. Relationship facts for couple relationships will now be included on the Relationship objects.
- Additional fact attributes and values are available. See GedcomX fields attributes
Example: Person facts/fields/misc.
"persons": [
{
"living": false,
"gender": {
"attribution": {...},
"id": "92fd4b89-8213-421b-8f14-a9fc0f00a3f8",
"type": "http://gedcomx.org/Male"
},
"names": [...],
"facts": [
{
"date": {...},
"place": {...},
"fields": [...],
"attribution": {...},
"id": "db3ddebb-c8ed-48dd-95e5-520a752324fd",
"type": "http://gedcomx.org/Birth"
},
{
"date": {...},
"place": {...},
"fields": [...],
"attribution": {...},
"id": "d10e0e6a-7ae2-4ab3-849e-2d0331294e2a",
"type": "http://gedcomx.org/Death"
},
{
"date": {...},
"place": {...},
"value": "graduated elementary school",
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "OTHER"
}
]
}
],
"attribution": {...},
"id": "e7954796-c542-4051-9fd2-3bdf7eef1c9e",
"type": "data:,Elementary+School+Graduation"
},
{
"date": {...},
"value": "Garbage Man",
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "OTHER"
}
]
}
],
"attribution": {...},
"id": "bcac0933-e07a-4f21-8704-7bc98ca3af32",
"type": "http://gedcomx.org/Occupation"
},
{
"date": {...},
"place": {...},
"value": "Testing affiliation",
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "OTHER"
}
]
}
],
"attribution": {...},
"id": "24ba578d-3a7e-45b9-87bb-a44179ae4e9d",
"type": "http://familysearch.org/v1/Affiliation"
},
{
"value": "The Cannons",
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "OTHER"
}
]
}
],
"attribution": {...},
"id": "543272d4-c608-4b4f-858b-cd84bdf8b3f8",
"type": "http://familysearch.org/v1/TribeName"
}
],
"fields": [...],
"display": {...},
"id": "LRWV-TFL",
"identifiers": {...},
"sortKey": "0000000000"
}
]
3. Person Display Information
- Primary person doesn't include relationship event info in Display section
- Additional fields added to primary person: ascendancyNumber, descendancyNumber, lifespan, familiesAsChild and familiesAsParent.
- Secondary person includes most of same display fields as primary person
- Place and date values for display fields are normalized
- Selected display name will most closely match query parameter
Example: Person Display
"persons": [
{
"living": false,
"gender": {...},
"names": [...],
"facts": [...],
"fields": [...],
"display": {
"ascendancyNumber": "1",
"birthDate": "1963",
"birthPlace": "Louisville, Jefferson, Kentucky, United States",
"deathDate": "2000",
"deathPlace": "Urbana, Champaign, Illinois, United States",
"descendancyNumber": "1",
"familiesAsChild": [
{
"parent1": {
"resource": "https://familysearch.org/ark:/61903/4:1:LRW2-7C6",
"resourceId": "LRW2-7C6"
},
"parent2": {
"resource": "https://familysearch.org/ark:/61903/4:1:LRW2-QTF",
"resourceId": "LRW2-QTF"
},
"children": [
{
"resource": "#LRWV-TFL",
"resourceId": "LRWV-TFL"
}
]
}
],
"familiesAsParent": [
{
"parent1": {
"resource": "#LRWV-TFL",
"resourceId": "LRWV-TFL"
},
"parent2": {
"resource": "https://familysearch.org/ark:/61903/4:1:LRWV-TTT",
"resourceId": "LRWV-TTT"
}
}
],
"gender": "Male",
"lifespan": "1963-2000",
"name": "John Cannon",
"role": "Other"
},
"id": "LRWV-TFL",
"identifiers": {...},
"sortKey": "0000000000"
},
{
"living": false,
"gender": {...},
"names": [...],
"facts": [...],
"fields": [...],
"display": {
"birthDate": "1966",
"birthPlace": "Houston, Harris, Texas, United States",
"deathDate": "2004",
"gender": "Female",
"lifespan": "1966-2004",
"name": "Elise Smith",
"role": "Other"
},
"id": "LRWV-TTT",
"identifiers": {...}
}
4. Relationships
- Couple relationship include all related relationships facts
- Parent-Child relationships include children of primary person and common children with selected spouse
- Relationship includes data for "attribution", "fields" on relationship event facts, "sortKey", "id", "identifiers".
- Relationships ordering based on how closely the relations match provided query params (such that the best match of a given relation type comes before the other relations of that same type). The relation types will not necessarily be grouped together.
Example: Person Relationships
"persons": [
{...Michael Cannon (LRW2-7C6) - mainPerson...},
{...Marjorie McDonald (LRW2-QTF) - wife1...},
{...Cannon Jonathan (LR45-S6P) - father...},
{...Margaret Johnson (LRW2-QTK) - wife2...},
{...Peter Cannon (LRW2-WJL) - childWithWife1...},
{...John Cannon (LRWV-TFL) - childWithWife2...}
],
"relationships": [
{
"person1": {
"resource": "#LRW2-7C6",
"resourceId": "LRW2-7C6"
},
"person2": {
"resource": "#LRW2-QTF",
"resourceId": "LRW2-QTF"
},
"facts": [
{
"date": {...},
"place": {...},
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "MARRIAGE"
}
]
}
],
"attribution": {
"contributor": {
"resource": "https://api.familysearch.org/platform/users/agents/9MSQ-YWL",
"resourceId": "9MSQ-YWL"
},
"modified": "2021-01-22T20:53:21.803+00:00"
},
"id": "92106359-b470-469a-ab92-de74be5012c7",
"type": "http://gedcomx.org/Marriage"
},
{
"date": {...},
"place": {...},
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "OTHER"
}
]
}
],
"attribution": {...},
"id": "c80ea7ea-e568-4653-9da7-01c91e37892c",
"type": "http://gedcomx.org/Divorce"
}
],
"id": "MJYS-57V",
"sortKey": "0000000001",
"type": "http://gedcomx.org/Couple"
},
{
"person1": {
"resource": "#LRW2-7C6",
"resourceId": "LRW2-7C6"
},
"person2": {
"resource": "#LRW2-QTK",
"resourceId": "LRW2-QTK"
},
"facts": [
{
"date": {...},
"place": {...},
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "MARRIAGE"
}
]
}
],
"attribution": {...},
"id": "3c804694-a8e7-4fac-8dd6-07980012fa75",
"type": "http://gedcomx.org/Marriage"
}
],
"id": "MJYS-PK5",
"sortKey": "0000000002",
"type": "http://gedcomx.org/Couple"
},
{
"person1": {
"resource": "#LR45-S6P",
"resourceId": "LR45-S6P"
},
"person2": {
"resource": "#LRW2-7C6",
"resourceId": "LRW2-7C6"
},
"id": "P1MYRS-63J",
"identifiers": {
"http://familysearch.org/v1/ChildAndParentsRelationship": [
"https://api.familysearch.org/platform/tree/child-and-parents-relationships/MYRS-63J"
]
},
"type": "http://gedcomx.org/ParentChild"
},
{
"person1": {
"resource": "#LRW2-7C6",
"resourceId": "LRW2-7C6"
},
"person2": {
"resource": "#LRWV-TFL",
"resourceId": "LRWV-TFL"
},
"id": "P1MY5L-SV5",
"identifiers": {
"http://familysearch.org/v1/ChildAndParentsRelationship": [
"https://api.familysearch.org/platform/tree/child-and-parents-relationships/MY5L-SV5"
]
},
"type": "http://gedcomx.org/ParentChild"
},
{
"person1": {
"resource": "#LRW2-QTF",
"resourceId": "LRW2-QTF"
},
"person2": {
"resource": "#LRWV-TFL",
"resourceId": "LRWV-TFL"
},
"id": "P2MY5L-SV5",
"identifiers": {
"http://familysearch.org/v1/ChildAndParentsRelationship": [
"https://api.familysearch.org/platform/tree/child-and-parents-relationships/MY5L-SV5"
]
},
"type": "http://gedcomx.org/ParentChild"
},
{
"person1": {
"resource": "#LRW2-7C6",
"resourceId": "LRW2-7C6"
},
"person2": {
"resource": "#LRW2-WJL",
"resourceId": "LRW2-WJL"
},
"id": "P1MY5L-34Q",
"identifiers": {
"http://familysearch.org/v1/ChildAndParentsRelationship": [
"https://api.familysearch.org/platform/tree/child-and-parents-relationships/MY5L-34Q"
]
},
"type": "http://gedcomx.org/ParentChild"
},
{
"person1": {
"resource": "#LRW2-QTK",
"resourceId": "LRW2-QTK"
},
"person2": {
"resource": "#LRW2-WJL",
"resourceId": "LRW2-WJL"
},
"id": "P2MY5L-34Q",
"identifiers": {
"http://familysearch.org/v1/ChildAndParentsRelationship": [
"https://api.familysearch.org/platform/tree/child-and-parents-relationships/MY5L-34Q"
]
},
"type": "http://gedcomx.org/ParentChild"
}
]
5. SourceDescriptions
- Additional attributes available in Person SourceDescription: "citations", "titles", "notes", and "modified".
Example: Person SourceDescriptions
"persons": [...],
"relationships": [...],
"sourceDescriptions": [
{
"citations": [
{
"lang": "en",
"value": "\"Family Tree,\" database, <i>FamilySearch</i> (http://familysearch.org), entry for Michael Cannon(PID https://familysearch.org/ark:/61903/4:1:LRW2-7C6); contributed by various users."
}
],
"componentOf": {
"description": "#sd_c_969",
"descriptionId": "sd_c_969"
},
"titles": [
{
"value": "Michael Cannon"
}
],
"notes": [
{
"subject": "LRW2-7C6",
"text": "1611349134685"
},
{
"subject": "LRW2-QTF",
"text": "1611349134685"
},
{
"subject": "LR45-S6P",
"text": "1611260272152"
},
{
"subject": "LRW2-QTK",
"text": "1611348315927"
},
{
"subject": "LRW2-WJL",
"text": "1605545471636"
},
{
"subject": "LRWV-TFL",
"text": "1611346919154"
}
],
"identifiers": {
"http://gedcomx.org/Persistent": [
"https://familysearch.org/ark:/61903/4:1:LRW2-7C6"
]
},
"modified": "2021-01-22T20:58:54.685+00:00",
"about": "https://familysearch.org/ark:/61903/4:1:LRW2-7C6",
"id": "sdp_LRW2-7C6",
"resourceType": "http://gedcomx.org/Person"
},
{
"titles": [
{
"value": "FamilySearch Family Tree",
"lang": "en"
}
],
"identifiers": {
"http://gedcomx.org/Persistent": [
"https://api.familysearch.org/platform/collections/tree/"
]
},
"about": "https://api.familysearch.org/platform/collections/tree/",
"id": "sd_c_969",
"resourceType": "http://gedcomx.org/Collection"
}
]
6. Places/Fields/Links
- Places includes latitude, longitude values
- Fields included
- Links may not be available
Example: Person Places/Fields/Links
"gedcomx": {
"persons": [...],
"relationships": [...],
"sourceDescriptions": [...],
"places": [
{
"names": [
{
"value": "Weehawken, Hudson, New Jersey, United States",
"lang": "en"
}
],
"latitude": 40.7689,
"longitude": -74.01543,
"id": "4590007"
},
{
"names": [
{
"value": "Buildwas, Shropshire, England, United Kingdom",
"lang": "en"
}
],
"latitude": 52.6375,
"longitude": -2.53119,
"id": "2978587"
},
{
"names": [
{
"value": "Mooers, Clinton, New York, United States",
"lang": "en"
}
],
"latitude": 44.96333,
"longitude": -73.58778,
"id": "4663618"
},
{
"names": [
{
"value": "Little Langford, Wiltshire, England, United Kingdom",
"lang": "en"
}
],
"latitude": 51.1213,
"longitude": -1.93852,
"id": "2970263"
}
],
"fields": [
{
"type": "searchRecordType",
"values": [
{
"text": "OTHER"
}
]
},
{
"type": "search_collection_metadata",
"values": [
{
"text": "969",
"type": "search_collection_id"
}
]
},
{
"type": "recordCountries",
"values": [
{
"text": "World (Miscellaneous)"
}
]
},
{
"type": "recordSubCountries",
"values": [
{
"text": "World (Miscellaneous),Other"
}
]
}
],
"description": "#SD-LR7Z-9YX"
}