![Page 1: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/1.jpg)
1© 2013 by Intellectual Reserve, Inc. All rights reserved.
Family SearchPlace 2.0 API26 September 2014
Dan Shellman([email protected])
Troy Wilde([email protected])
![Page 2: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/2.jpg)
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
![Page 3: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/3.jpg)
3
Where is the Place API?
Currently Available via Sandbox and ProductionDocumentation: https://familysearch.org/developers/docs/guides/places
![Page 4: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/4.jpg)
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
![Page 5: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/5.jpg)
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
![Page 6: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/6.jpg)
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
![Page 7: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/7.jpg)
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.)
![Page 8: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/8.jpg)
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
![Page 9: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/9.jpg)
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.
![Page 10: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/10.jpg)
10
Sample API SearchesSearch 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
![Page 11: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/11.jpg)
11
Product IdeasIdea 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?
![Page 12: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/12.jpg)
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)
![Page 13: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/13.jpg)
13
What Features Do You Need?
Where should we focus our efforts to help you?
![Page 14: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/14.jpg)
14
Contact Information
Dan ShellmanSoftware Development Manager
Troy WildeProduct Manager
![Page 15: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/15.jpg)
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.
![Page 16: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/16.jpg)
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 Algorithm1. Parse the place name2. Identify candidate
interpretations3. Filter/score
candidates4. Assemble resulting
interpretations
![Page 17: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/17.jpg)
17
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)
Place Name InterpretationContextAssociated constraints with an interpretation request, such as years, types, jurisdictions, etc.
![Page 18: 2014 Family Search Developer Conference Place 2.0 API](https://reader035.vdocument.in/reader035/viewer/2022062617/54c34cc34a795960188b45fa/html5/thumbnails/18.jpg)
18
Place Versus Place Description
13375781849 - Present
Three distinct Place Descriptions for the same Place.
United States1 Republic
Utah Territory344458 Territory
Utah393436 CountyFort Utah
5314383 City1849-1850
United States1 Republic
Utah Territory344458 Territory
Utah393436 CountyProvo
5314384 City1850 - 1896
United States1 Republic
Utah342 State
Utah393437 CountyProvo
5314385 City1896 - Present