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=
- &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.
- &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:
|
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>