Attention: This site does not support the current version of your web browser. To get the best possible experience using our website we recommend that you upgrade to a newer version or install another browser

Skip main navigation

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.

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 /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.

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.

x

Select a language