Place Authority

Use the Place Authority service to get representations of authoritative place information from FamilySearch.

URI

Use this URI to search for places based on a given place phrase as a query parameter:

https://api.familysearch.org/authorities/v1/place?

Use this URI to search for a place representation based on a place id:

https://api.familysearch.org/authorities/v1/place/[id]

You can request multiple places at once by adding multiple ids separated by commas following this pattern:

https://api.familysearch.org/authorities/v1/place/[id],[id],[id],...

Note: Use the place.max.places parameter of the Authorities Properties Authority service to obtain the maximum number of places that you can include in one request.

HTTP Method

GET

Parameters

&place=
The place, as entered by the user, to be normalized. (Required for the first example URI.)
&view=
  • simple: Returns only the official and normalized names of each place.
  • full: Returns all the place details from the place authority. (default)
&maxResults=
Specify the maximum number of place results to be returned with each place query. (optional)
&variants=
Specifies whether FamilySearch should return place variants (true or false). The default is false. The view must be set to full.
&children=
Returns a list of all the child places if set to "true". The default is false. The view must be set to full.
&filter=
Limits the number of results returned.
  • true: Returns only the closest matches from the place authority. It favors cities over counties where both the city and the county have the same name.
  • false: Returns all search results from the place authority. (default)
&locale=?
Specify the language in which normalized places should be returned. (optional) NOTE: Not all places have been localized. The supported values are:
ar (Arabic) fi (Finnish) lt (Lithuanian) sk (Slovak)
be (Belarusian) fr (French) lv (Latvian) sl (Slovenian)
bg (Bulgarian) ga (Irish) mk (Macedonian) sq (Albanian)
ca (Catalan) hr (Croatian) ms (Malay) sr (Serbian)
cs (Czech) hu (Hungarian) mt (Maltese) sv (Swedish)
da (Danish) in (Indonesian) nl (Dutch/Flemish) th (Thai)
de (German) is (Icelandic) no (Norwegian) tr (Turkish)
el (Modern Greek) it (Italian) pl (Polish) uk (Ukrainian)
en (English) iw (Hebrew) pt (Portuguese) vi (Vietnamese)
es (Spanish) ja (Japanese) ro (Romanian) zh (Chinese)
et (Estonian) ko (Korean) ru (Russian)  

Coordinates

The response provides latitude and longitude for many places.

Errors

Error Possible Causes Implemented
400 Bad Request: Generic client error or multiple client errors. Could be caused by:
  • Invalid parameter or parameter value
  • Requesting more places in one query than the API supports. Use the Authorities Properties service to see current limits.
 Yes
401 Unauthorized: The user has invalid credentials or the session ID is missing, invalid, or has expired. This error also appears if the query string contains multiple question marks or the the session parameter contains letters in an incorrect case. Yes
404 Not Found: This request contained an invalid ID or a bad URI. No
500 Server Error: A generic server error or multiple server errors occurred. If you get this error, please report it through devsupport@familysearch.org. You can also post it to the FamilySearch Developer Network (FSDN). Yes
503 Service Unavailable: FamilySearch or the service that you are using is not currently available. Or you are being throttled. Yes

Example: Using a Place Phrase

Request 

https://api.familysearch.org/authorities/v1/place?place=United%20States&locale=en&sessionId={sessionId}

Response 

<?xml version='1.0' encoding='utf-8'?>
<authorities xmlns="http://api.familysearch.org/authorities/v1" xmlns:fsapi-v1="http://api.familysearch.org/v1" version="1.4.20091022.4995" statusMessage="OK" statusCode="200">
    <places version="3.5.0" count="1">
        <place type="Country General" original="United States" iso="US" id="1" culture="1">
            <normalized>
                <form>United States</form>
            </normalized>
            <official>United States</official>
            <parents>
                <place ref="-1">World</place>
            </parents>
        </place>
    </places>
</authorities>

Example: Using a Place ID

Request 

https://api.familysearch.org/authorities/v1/place/353289?{sessionId=}

Response 

<?xml version="1.0" encoding="utf-8"?>
<authorities xmlns="http://api.familysearch.org/authorities/v1" xmlns:fsapi-v1="http://api.familysearch.org/v1" version="1.0.20080320.1495" statusMessage="OK" statusCode="200">
    <places version="3.0.8" count="1">
        <place type="Populated Place" iso="US-ID" id="353289" culture="1">
            <normalized>
                <form>Shelley, Bingham, Idaho, United States</form>
            </normalized>
            <official>Shelley</official>
            <location>
                <point>
                    <latitude>43.38139</latitude>
                    <longitude>-112.1225</longitude>
                </point>
            </location>
            <parents>
                <place ref="1349">Bingham</place>
            </parents>
        </place>
    </places>
</authorities>