familysearch place api

46
FamilySearch Place API February 2015

Upload: familysearch

Post on 18-Jul-2015

84 views

Category:

Technology


0 download

TRANSCRIPT

FamilySearch Place API

February 2015

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

Key Features

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

Resource Model

Map data produced via Google Maps API.

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

Use Cases

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?

Display Places

San ÁngelMexico

Federal District of Mexico↓

Alvaro Obregón↓

San Ángel

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

Partner Examples

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.

Future Plans

Feature Plans

Additional attributes on place descriptions Notes

Wikipedia links

Population

Sources/citations

External references Examples: NGA, GeoNames

Auto-transliteration

Place Boundaries

Sample Application

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

Questions?

Contact Info

Troy Wilde, Product Manager

[email protected]

Dan Shellman, Software Development Manager

[email protected]

Documentation Link https://familysearch.org/developers/docs/guides/places

Sample App (AngularJS-based) https://github.com/dshellman/FSPlaceSampleApp

Additional Materials

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