FamilySearch has introduced a new Place RESTful Web Service API for finding and accessing a database of millions of places, both modern and historic. This presentation will introduce the data model, the capabilities of the API, and future directions. This presentation was given by Dan Shellman and Troy Wilde at the 2015 RootsTech Innovator Summit held at the Salt Palace Convention Center in Salt Lake City, Utah, USA on February 11, 2015.

1. FamilySearch Place API
February 2015

2. What is the FamilySearch Place API?
RESTful Web Service for places
Backed by a database of millions of places
Type: City
Unique Id: 5413607
Jurisdiction: Salt Lake, Utah, United States
Official Name: Salt Lake City
Location: 40.76083, -111.89028
Start/End Years: 1896 – Present

3. Key Features

4. Historical Places
Database has about a million historical places
Place Dates
Allen’s Camp, Yavapai, Arizona Territory, United States 1876 – 1878
St. Joseph, Yavapai, Arizona Territory, United States 1878 – 1879
St. Joseph, Apache, Arizona Territory, United States 1879 – 1895
St. Joseph, Navajo, Arizona Territory, United States 1896 – 1912
St. Joseph, Navajo, Arizona, United States 1912 – 1923
Joseph City, Navajo, Arizona, United States 1923 – Present

5. Permanent, Unique Identifiers
For places and their historical representations
Type: City
Jurisdiction: Salt Lake, Utah, United States
Official Name: Salt Lake City
Location: 40.76083, -111.89028
Start/End Years: 1896 – Present
5413607

6. Search
Primary search types
Name (aka “Interpretation”)
Jurisdiction
Spatial (location)
Additional parameters
Year
Type

7. Resource Model
Map data produced via Google Maps API.

8. Place and Place Description Resources
Place Name Dates Id
Fraknó, Sopron, Hungary Unknown – 1921 1743233
Forchtenau, Mattersburg,
Burgenland, Austria
1921 – 1972 6748259
Forchtenstein,
Mattersburg, Burgenland,
Austria
1972 – Present 6748260
Place
(3798317)

9. Place Resource
Logical or conceptual place
 Unique identifier
 Variant names
 Start/End years
Acts as a container of historical
representations
5061618
/platform/places/{id}

10. Place Description Resource
Historical representation of a place
 Unique identifier
 Jurisdiction
 Start/End years within jurisdiction
 Location
 Type
 Official localized names
5061618
Cairo, Cairo Governorate, Egypt
(2241928)
/platform/places/description/{id}

11. Search Resource
/platform/places/search?q=<param1> <param2>…
Parameter Example
name:<place name> name:“Notts,Eng”
[+]date:<date or date range> +date:1900/1943
[+/-]parentId:<id>[~],<id>[~]… +parentId:1~
[+/-]typeId:<id>,<id>… +typeId:20
latitude:<latitude> latitude:40.1234
longitude:<longitude> longitude:111.2345
distance:<distance>[M/K] distance:5M

12. Places with Name “Notts,Eng”
(Example: Name Search or “Interpretation”)
Place Name of “Notts,Eng”
name:“Notts,Eng”
/platform/places/search?q=name:”Notts,Eng”
Nottinghamshire, England (County)
Nottingham, Nottinghamshire, England (Borough)

13. Place Name of “日本”
name:“日本”
/platform/places/search?q=name:”%E6%97%A5%E6%9C%AC”
Places with Name “日本”
(Example: Name Search with non-Latin Name)
Japan

14. Counties in California in 1860
(Example: Jurisdiction Search with Type and Date)
Type: County
+typeId:209
Jurisdiction: CA
+parentId:327
Date: 1860
+date:1860
/platform/places/search?q=+typeId:209 +parentId:327 +date:1860
Counties in 1860 Counties in 2015

15. Cemeteries Near Portland, Oregon
(Example: Location Search with Type and Jurisdiction)
Type: Cemetery
 +typeId:20
Jurisdiction: Oregon
 +parentId:375~
Location
 latitude:45.52361 longitude:-122.675 distance:10M
/platform/places/search?q=+typeId:20 +parentId:375~
latitude:45.52361 longitude:-122.675 distance:10M
With Jurisdiction Without Jurisdiction

16. Communes in France
(Example: Jurisdiction Versus Location Search)
 Jurisdiction: Bas-Rhin, Alsace, France (Department)
 +parentId:442056~
 Type: Commune and Populated Place
 +typeId:140,201
 Location
 49.00064, 7.893335
 Distance: 16K
/platform/places/search?q=+typeId:140,201 +parentId:442056~
latitude:49.00064 longitude:7.893335 distance:16K
Jurisdiction-Only
Location-Only
Jurisdiction and Location

17. Use Cases

18. Data Quality
Identifiers add meaning to your data
Name, location, etc. are not sufficient
Meaningful data improves the user
experience
Data Record Data Record

19. Data Quality – Example Issues
 Non-Unique place names
 Altrincham, Cheshire, England
 Parish, Civil Registry, or Populated Place?
 Salt Lake City, Salt Lake, Utah, United States
 Should that be Utah or Utah Territory (before or after 1896)?
 Place names with multiple meanings
 Daniel Smith
 Gerald Forrest
 Susan Mathews
 Eustace Henderson
 Zachary Lou
 Location (latitude, longitude) not unique (represents centroid)
Which of these is NOT a valid place name?

20. Display Places
San Ángel
Mexico
↓
Federal District of Mexico
↓
Alvaro Obregón
↓
San Ángel

21. Compare Data with Associated Places
Record A Record B
Record C Record D
3052984
São Paulo, São Paulo, Brazil
3052675, 5727, 141
Campinas, São Paulo, Brazil
3052984
São Paulo, São Paulo, Brazil
3052984, 5727, 141
São Paulo, São Paulo, Brazil
Exact Match:
Same Place
Description
Identifiers
Different Place,
Same Jurisdiction:
Same Place
Description
Identifiers of
Parent Jurisdiction

22. Compare Data with Associated Places
Comparison Type What To Use? Notes
Exact Match Place Description Id Simple Id Comparison
Same Place,
Different History
Place Id Simple Id Comparison
Jurisdiction
Commonality
Place Description Id
of Jurisdictions
Simple Id Comparison
Distance Location (latitude,
longitude)
Haversine formula
Similarity Type Id Compare Type Ids

23. Partner Examples

24. Use Place API to select:
• City
• County
• State
Use Place API:
• Use longitude and
latitude to put pins on
a map

25. Use Place API to provide a
person timeline:
• Identify City, County and State
• Use longitude and latitude to
put pins on a map
• Display official place names

26. Use Place API to provide a
migration map:
• Identify City, County and
State
• Use longitude and latitude
to put pins on a map

27. Other Product Ideas
Idea Description / Example
Travel Alerts Smartphone alert: “You’re 3.7 miles away from your great-
grandfather’s cemetery. Would you like directions?”
Place Research What was this place known as at a particular time? What was
its jurisdiction?
Find Books/Journals What books or journals were written about this place during
the time my grandparents lived there? Where can I buy them?
Find Stories Find stories about people that lived at the same time and near
my ancestor.
Data Research Clustering of surnames across census records for a particular
area.
DNA Map DNA data against locations. Cross-reference with census
and record data.

28. Future Plans

29. Feature Plans
 Additional attributes on place descriptions
 Notes
 Wikipedia links
 Population
 Sources/citations
 External references
 Examples: NGA, GeoNames
 Auto-transliteration
 Place Boundaries

30. Sample Application

31. Sample Application
GitHub Project
https://github.com/dshellman/FSPlaceSampleApp
AngularJS-Based Application
Performs Simple Searches
By name, date, jurisdiction, type, and location
Displays results in a table and on a map

32. Questions?

33. Contact Info
 Troy Wilde, Product Manager
 twilde@familysearch.org
 Dan Shellman, Software Development Manager
 dshellman@familysearch.org
 Documentation Link
 https://familysearch.org/developers/docs/guides/places
 Sample App (AngularJS-based)
 https://github.com/dshellman/FSPlaceSampleApp

34. Additional Materials

35. Place Resource – Example
{
"places" : [ { "id" : "5061618",
"links" : {
"place" : {
"href" : "https://.../platform/places/5061618"
}
},
"names" : [ {
"lang" : "en",
"value" : "Cairo"
}, {
"lang" : "fr",
"value" : "Le Caire"
},
...
Place Identifier
Place URL
Language of Variant Name
Variant Name

36. Place Description Resource – Example
{
"places" : [ { "id" : "2241928",
"links" : {
"description" : {
"href" : "https://.../platform/places/description/2241928"
},
"children" : {
"href" : "https://.../platform/places/description/2241928/children"
},
"place" : {
"href" : "https://.../platform/places/5061618"
}
},
"lang" : "en",
...
Place Description Identifier
Place URL
Place Description Children URL
Place Description URL

37. Place Description Resource – Example
...
"identifiers" : {
"http://gedcomx.org/Primary" : [
"https://.../platform/places/5061618" ] },
"names" : [ {
"lang" : "en",
"value" : "Cairo"
}, ... ],
"type" : "https://.../platform/places/types/140",
"latitude" : 30.05,
"longitude" : 31.25,
"jurisdiction" : {
"resource" : "#5968"
},
...
Place Type URL
Language of Official Name
Official Name
Location
Internal Link to Parent Jurisdiction

38. Place Description Resource – Example
...
"display" : {
"name" : "Cairo",
"fullName" : "Cairo, Cairo Governorate, Egypt",
"type" : "Populated Place"
}
}, {
"id" : "5968“,
...
Displayable Information
Parent Jurisdiction Id (Internally Linked)

39. Place Types
List of all place types: /platform/places/types
{
"@id" : "https://.../platform/places/types",
"title" : "Place Types",
"description" : "List of available place types.",
"elements" : [ { "id" : "186",
"@id" : "https://.../platform/places/types/186",
"labels" : [{ "@language" : "en", "@value" : "City" }],
"descriptions" : [ {
"@language" : "en",
"@value" : "..."
} ]
},
...
Language
Localized Value
Type Identifier
Type URL

40. Place Type Groups
List of all place types: /platform/places/type-groups
{
"@id" : "https://.../platform/places/type-groups",
"title" : "Place Type Groups",
"description" : "List of available place type groups.",
"elements" : [ { "id" : "26",
"@id" : "https://.../platform/places/type-groups/26",
"labels" : [ { "@language" : "en", "@value" : "Country-Like" } ],
"descriptions" : [ {
"@language" : "en",
"@value" : "..."
} ]
},
...
Language
Localized Value
Type Group Identifier
Type Group URL

41. Place Description Groups
List of all place types: /platform/places/groups/{id}
{
"sourceDescriptions" : [ {
"id" : "19",
"links" : {
"place-group" : {
"href" : "https://.../platform/places/groups/19"
}
},
"titles" : [ {
"lang" : "en",
"value" : "Continental Europe" } ],
...
Language
Localized Value
Group Identifier
Group URL

42. Place Description Groups – Page 2
"descriptions" : [ {
"lang" : "en",
"value" : "Countries in Continental Europe"
} ],
"places" : [ {
"id" : "278",
"links" : {
"description" : {
"href" : "https://.../platform/places/description/278" }
},
"names" : [ {
"lang" : "en",
"value" : "Czechoslovakia" } ]
},
...
Array of Contained Place Descriptions
Localized Place
Description Name
Localized Description
of the Group
Place Description URL
Place Description Identifier

43. Search Results Example: Page 1
{
"subtitle" : "Results of searching for places.",
"title" : "Place Search Results",
"entries" : [ {
"content" : {
"gedcomx" : {
"places" : [ {
"id" : "8696757",
"links" : {
"description" : {
"href" :
"https://.../platform/places/description/8696757"
}
},
"lang" : "en",
Array of all search results
Array of jurisdictions
Place Description Identifier
URL to Place Description Resource

44. Search Results Example: Page 2
"identifiers" : {
"http://gedcomx.org/Primary" : [
"https://.../platform/places/1828212" ]
},
"type" : "https://.../platform/places/types/20",
"temporalDescription" : {
"formal" : "+1896/"
},
"latitude" : 40.51472,
"longitude" : -111.97667,
"jurisdiction" : {
"resource" : "#5346810"
},
URL to Place Resource
URL to Type Resource
Date (gedcomx format)
Place Description Identifier
for Parent Jurisdiction
(Note: internal link)

45. Search Results Example: Page 3
"display" : {
"name" : "Wasatch Lawn Memorial Park South",
"fullName" : "Wasatch Lawn Memorial Park South,
Riverton, Salt Lake, Utah, United States",
"type" : "Cemetery"
}
},
...
Localized Type Name for Display
Localized Official Name for Display
Parent Jurisdictions
(Note: from internal links)

46. Search Results Example: Page 4
{
"id" : "5346810",
"links" : { …same as search result… },
"lang" : "en",
"identifiers" : { …same as search result… },
"names" : [ {
"value" : "Riverton"
} ],
"jurisdiction" : {
"resource" : "#393453"
}
},
"score" : 75.0
Localized Official Name for Display
Place Description Identifier
for Parent Jurisdiction
(Note: internal link)
Place Description Identifier for this Jurisdiction
Relevance Score