FamilySearch Place API
-
Upload
familysearch -
Category
Technology
-
view
84 -
download
0
Transcript of FamilySearch Place API
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
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
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 – Present5413607
Search
Primary search typesName (aka “Interpretation”)
Jurisdiction
Spatial (location)
Additional parametersYear
Type
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)
Place Resource
Logical or conceptual place Unique identifier
Variant names
Start/End years
Acts as a container of historical representations
5061618
/platform/places/{id}
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}
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
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)
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
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
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
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
Data Quality
Identifiers add meaning to your data
Name, location, etc. are not sufficient
Meaningful data improves the user experience
Data Record Data Record
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?
Compare Data with Associated Places
Record A Record B
Record C Record D
3052984São Paulo, São Paulo, Brazil
3052675, 5727, 141Campinas, São Paulo, Brazil
3052984São Paulo, São Paulo, Brazil
3052984, 5727, 141São Paulo, São Paulo, Brazil
Exact Match: Same Place Description Identifiers
Different Place, Same Jurisdiction: Same Place Description Identifiers of Parent Jurisdiction
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
Use Place API to select:• City• County• State
Use Place API:• Use longitude and
latitude to put pins on a map
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
Use Place API to provide a migration map:• Identify City, County and
State• Use longitude and latitude
to put pins on a map
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.
Feature Plans
Additional attributes on place descriptions Notes
Wikipedia links
Population
Sources/citations
External references Examples: NGA, GeoNames
Auto-transliteration
Place Boundaries
Sample Application
GitHub Projecthttps://github.com/dshellman/FSPlaceSampleApp
AngularJS-Based Application
Performs Simple SearchesBy name, date, jurisdiction, type, and location
Displays results in a table and on a map
Contact Info
Troy Wilde, Product Manager
Dan Shellman, Software Development Manager
Documentation Link https://familysearch.org/developers/docs/guides/places
Sample App (AngularJS-based) https://github.com/dshellman/FSPlaceSampleApp
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
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
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
Place Description Resource – Example
...
"display" : {
"name" : "Cairo",
"fullName" : "Cairo, Cairo Governorate, Egypt",
"type" : "Populated Place"
}
}, {
"id" : "5968“,
...
Displayable Information
Parent Jurisdiction Id (Internally Linked)
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
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
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
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 URLPlace Description Identifier
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
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 Identifierfor Parent Jurisdiction(Note: internal link)
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)
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 Identifierfor Parent Jurisdiction(Note: internal link)
Place Description Identifier for this Jurisdiction
Relevance Score