Places

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.

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	/platform/places/search?q=+parentId:342~ +typeId:20
Where `parentId` defines the parent jurisdiction with an `id` of 342 (Utah), the `+` indicates that a parentId is required, the `~` indicates that it's any child (at any jurisdictional depth), and the `typeId` defines the type of placeDescription. In this example, 20 is a placeDescription of type "cemetery."
Find Cemeteries Within 5 Miles Radius of Salt Lake City	/platform/places/search?q=+typeId:20 latitude:40.76083 longitude:-111.89028 distance:5M
Where the `typeId` of 20 is a type of "cemetery" and the latitude and longitude are for Salt Lake City, with the distance being 5 miles.
Find All Counties in California in 1912	/platform/places/search?q=+parentId:327 +typeId:209 +date:+1912
Where the `parentId` defines the parent jurisdiction with an `id` of 327 (California), the `+` indicates that a parentId is required, the `typeId` defines the "county" type, and the `date`, which is required because of the leading `+`, is 1912 AD. The AD is indicated by the leading `+`.
Interpret the Place Name "Orem, Utah" as it existed in 1872	/platform/places/search?q=name:"Orem,UT" +date:+1872
Where the `name` represents the name of the place and the `date` (required) is 1872 AD. (The double quotes around the name are necessary if there are embedded spaces.) This is a special search called an "interpretation" because it attempts to interpret the text of the place name and find the best answer. The algorithm that performs the interpretation uses a complex parser and scoring algorithm to calculate the best match.

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.