The FamilySearch Places resource is used to read and search for places within the FamilySearch Place Authority. This provides partners the ability to incorporate authoritative places (both modern and historic) and create interactive experiences with users in identifying, researching, displaying and using places. For example, partners can interpret user-entered place names and associate a standardized place with the name, retrieve certain types of places within a particular jurisdiction, or search for places within a radius of a specified latitude/longitude point.
There are two primary resource types within the place authority: Places and Place Descriptions. A Place resource represents a logical or conceptual place and is uniquely identified by a numeric identifier. The Place Description resource is a representation of the logical place in a given time period, within a specific jurisdiction, with a specific official name, etc. Place Descriptions also have a unique numeric identifier. Note that the identifiers for the Place resource and the Place Description resource are in different namespaces; for example, Place identifier 123 is not the same as Place Description identifier 123. These unique identifiers can be used by partners to associate places with their own data, providing a powerful way to link data together. For example, a photo can be tagged as being taken at a particular place by associating the Place Description identifier with the photo. If another piece of data, such as an event in a person's life, is also associated with the same Place Description identifier, then those two pieces of data can be linked together because they happened at the same place.
A Place resource will have one or more Place Descriptions associated with it. For example, the city of Provo exists in the county of Utah, in the state of Utah, in the United States. However, when Provo was first established, the state of Utah did not exist. At the time, Utah County existed in Utah Territory. Because of this, Provo has two Place Descriptions (but only one Place resource), which can be represented like this:
Provo, Utah, Utah Territory, United States (1850-1896)
Provo, Utah, Utah, United States (1896-present)
The Place API does not require an authenticated session to retrieve data. Click here for more information on unauthenticated access.
Try It Out
Click here to see a sample app that uses the Place API.
Sample API Searches
Using the Places Search endpoint, you can match (interpret) a place name with a standardized Place Description (in this case, the "standard" is the unique identifier of the Place Description). You can also find places that exist within a particular jurisdiction or that existed at a certain time. These searches allow you to build more interactive user experiences, such as creating drop-down menus that allow users to see a list of possible places or creating maps with pins representing the places, etc.
|Search Description||API Search|
|Find All Cemeteries in Utah||
|Find Cemeteries Within 5 Miles Radius of Salt Lake City||
|Find All Counties in California in 1912||
|Interpret the Place Name "Orem, Utah" as it existed in 1872||
- To search for Place Descriptions, see the Places Search resource.
- To read a place, see the Place resource.
- To read a place description, see the Place Description resource.
- To read the jurisdictional children of a place description, see the Place Description Children resource.
- To read a specific place type as a controlled vocabulary element, see the Place Type resource.
- To read a list of all place types as a controlled vocabulary list, see the Place Types resource.
- To read a group of places as a controlled vocabulary list, see the Place Group resource.
- To read a group of related place types as a controlled vocabulary list, see the Place Type Group resource.
- To read a list of all place type groups as a controlled vocabulary list, see the Place Type Groups resource.
Places are also described in other languages. Information about places may have translations in other languages. If the
accept-language header is used to specify a requested language, the system will do its best to provide the closest translation for all information associated with the place. For example, if there's a translation of the official name in the requested language, it will be provided. The type may also be translated, etc. For more information, see the Internationalization guide.