The document discusses the FamilySearch Place API, which provides a database of millions of historical places with unique identifiers and associated information. It was built to improve genealogical search results and data quality by standardizing on place references rather than names. The API allows users to search for places by name, location, or other criteria. Future plans include adding place boundary and attribute data to provide more context about places over time.

1. 1
Family Search
Place 2.0 API
26 September 2014
Dan Shellman
(dshellman@familysearch.org)
Troy Wilde
(twilde@familysearch.org)
© 2013 by Intellectual Reserve, Inc. All rights reserved.

2. 2
What is the Place API?
RESTful Web Service supporting the search and
retrieval of places and place information
• Database of millions of places
• Examples of information associated with each place:
 Unique identifier
 Type
 Jurisdiction
 Official name
 Location (latitude/longitude of centroid)
 Years of existence

3. 3
Where is the Place API?
Currently Available via Sandbox and Production
Documentation: https://familysearch.org/developers/docs/guides/places

4. 4
Why Did Family Search Build a Place API?
Improve Search Results
• Convert place names into place references for
easy comparison
Data Quality
• Improve quality of data through standardizing
on place references, rather than place names
Mapping Features
• Show points on a map of places relating to
ancestors

5. 5
Many Data Sets/Services Already Exist
National Geospatial-Intelligence Agency (NGA)
• http://www.nga.mil
• Millions of places
GeoNames
• http://geonames.org
• Millions of places
• Web Service accessible (or direct database download)
• Commonly used by many genealogical applications
Twofishes
• http://twofishes.net
• Open Source library based upon GeoNames database

6. 6
Why Use FamilySearch Place API?
Primary Reason: Historical Place Information
• Most large data sets do not have much or any
historical information
• Family History is history, and places change all the
time
• Difficult to link historical places with their modern
counterparts
• Over a million historical places
• Provide superior service to ourselves and the
community to improve the patron experience

7. 7
Why Use FamilySearch Place API?
Additional Reasons
• More Comprehensive Jurisdictions
 Many data sets have few jurisdictional levels
• Genealogically-Relevant Places
 Ecclesiastical (Churches, Parishes, etc.)
 Census (Minor-Civil Divisions, Townships,
etc.)

8. 8
What Can You Do With It?
Improve Existing Products
• Data quality improvements
 Store identifiers, not place names
 Display more information about a place
 User selection/experience
• Better integration with other products
 Share identifiers, not place names
Build a New Product
• Mash-up with other services
• Value-added data integration

9. 9
What Does It Do?
Search for places
• By name (i.e. “Place Name Interpretation”)
• By location (radius from a central point)
• By criteria, such as jurisdiction, type, year,
etc.
Get place information
• Official/variant names, type, years of existence, location,
etc.

10. 10
Sample API Searches
Search Description API Search
Find All Cemeteries in
Utah
/platform/places/search?q=+parentId:342~ +typeId:20
Find Cemeteries Within
5 Miles Radius of Salt
Lake City
/platform/places/search?q=+typeId:20 latitude:40.76083
longitude:-111.89028 distance:5M
Find All Counties in
California in 1912
/platform/places/search?q=+typeId:209 +parentId:327
+date:+1912
Interpret the Place
Name ‘Orem,UT’ as it
existed in 1872
/platform/places/search?q=name:”Orem,UT” +date:+1872

11. 11
Product Ideas
Idea Description
Migration Map Movement of ancestors over time. Create a travel
log over the course of their migrations.
Travel Alerts Smartphone alert: “You’re 3.7 miles away from your
great-grandfather’s cemetery. Would you like
directions?”
Local/Contextual
History
When my great-grandfather was married in Fort
Utah in 1849…”there was a battle with …, and the
Saints were trying to become a state. It wouldn’t be
long before the Civil War would break out…”
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?

12. 12
Future Plans
Existing Features (not yet exposed)
• Attributes (arbitrary data associated with a place)
• Sources/Citations (where the data came from)
• External references (e.g. NGA identifiers)
Future Planned Features
• Boundaries
• More attribute data (e.g. Wikipedia links)
• Place name transliteration (auto-transliteration of place
names into other scripts)

13. 13
What Features Do You Need?
Where should we focus our efforts to help you?

14. 14
Contact Information
Dan Shellman
Software Development Manager
dshellman@familysearch.org
Troy Wilde
Product Manager
twilde@familysearch.org

15. 15
Why the New Service?
Better architecture/design to support new features
• More flexible interpretation algorithm
• Better model for data extensibility
Support faster data changes
• New/changed data is immediately available
Provide generalized search capabilities
• Spatial search
• Search by jurisdiction, type, etc.

16. 16
What’s New?
Place Name Interpretation
• More context options
• More sophisticated scoring
• More flexible and powerful parser
New Data Model
• Logical Place versus Place Description (a representation of a
place across time, jurisdiction, etc.)
• Extensibility: adding new data via Attributes (e.g. population
snapshot)
Place Search Capability
• Search by latitude/longitude
• Search by jurisdiction, type, year, etc.
Interpretation Algorithm
1. Parse the place name
2. Identify candidate
interpretations
3. Filter/score
candidates
4. Assemble resulting
interpretations

17. Context
Associated constraints
with an interpretation
request, such as years,
types, jurisdictions,
etc.
17
Place Name Interpretation
Special type of search that
converts a Place Name into one or
more Place Description references
Parser
• Potentially multiple paths of name tokens
 Hood River Oregon -> [Hood] [River] [Oregon], [Hood River] [Oregon], [Hood] [River Oregon]
• Identification of alternative name tokens
 Ft Dallas -> Fort Dallas, N Carolina -> North Carolina
Name Token Lookup (Candidate Identification)
• Uses a Solr/Lucene backend to find candidates from a name token
• Supports “fuzzy” search (edit distance)
Scoring (and Filtering)
• Each candidate is analyzed by many scorers
• Scoring is configurable (used to improve results as we perform P&R studies)
• Filters remove incorrect or invalid candidates
Assembly
• Sort by score
• Additional processing as needed (e.g. limit result count)

18. 18
Place Versus Place Description
1337578
1849 - Present
Three distinct
Place Descriptions
for the same Place.
United States
1 Republic Utah Territory
344458 Territory
Utah
393436 County Fort Utah
5314383 City
1849-1850
United States
1 Republic Utah Territory
344458 Territory
Utah
393436 County Provo
5314384 City
1850 - 1896
United States
1 Republic Utah
342 State
Utah
393437 County Provo
5314385 City
1896 - Present