Places Search

Description

The Places Search query is used to match (interpret) a place name with a standardized place description. 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. Please note that all query parameters and URIs are expected to be properly encoded according to the HTTP specifications. The following query parameters apply:

variable description
start The index of the first search result for this page of results.
count The number of search results per page.
q

The query parameter that describes the search criteria. A parameter name and value is separated by a colon (:) and each name-value pair is separated by a white space ( ).

By default, values are exact. For nonexact matches, append a tilde (~) at the end of the value, such as name:Baden~.

name description
name The name of the place. This parameter causes an interpretation of the name to occur, with results ordered in "best guess first" order. Supports the '?' and the '*' wildcards, but the wildcard MUST NOT be at beginning of name. Escape wildcard character with backslash '\' for literal character search. Supports the '~' suffix for application-specific fuzzy search (incompatible with non-escaped wildcards). Wildcards and escaped wildcards on the same query are not supported. Example values:

  • name:"New York, New York"
  • name:england
  • name:"par*,france"
partialName The partial name of the place. This parameter is used to search for the "partial" name of a place. A partial name search is designed specifically for type-ahead use cases. The treatment of wildcards in a partial name is unspecified. If partialName is used, the name parameter will be ignored.
date The date (or date range). Supports the '+' operator to specify a required date (or date range). When there is no '-' operator, the date (or date range) is optional. Implied granularity is in years. See the GEDCOM X Date Format for more information.

  • +date:1800/1900
  • +date:1823
  • date:1723/2000
typeId The place type id. Supports the '+' operator to require the results to conform to the type. Supports the '-' operator to exclude places that conform to the type. Otherwise, the type is optional. For example, if '186' is the type id for cities, to include only cities in your results, enter +typeId:186. To exclude cities in your results, enter -typeId:186. Also supports multiple typeIds, such as +typeId:186 +typeId:209.
typeGroupId The place type group id. Supports the '+' operator to require the results to conform to the type group. Supports the '-' operator to exclude places that conform to the type group. Otherwise, the type group is optional. Supports multiple typeGroupIds in the form of +typeGroupId:123 +typeGroupId:456
parentId The parent jurisdiction (as a Place Description identifier) to limit the search results. Supports the '+' operator to require the results to have the parent jurisdiction. Supports the '-' operator to exclude places that are within the parent jurisdiction. Supports the '~' suffix for "any child", otherwise, implies direct parent. With no '+' or '-' specified, the parent is optional. For example, if the request is +parentId:1~ (US), all places within the US is returned. If the request is +parentId:1, only direct parents, like states, are returned. Supports multiple parentIds in the form of +parentId:1~ -parentId:32.
latitude The latitude of a centroid to search near.
longitude The longitude of a centroid to search near.
distance The distance from the centroid to search near. Units can be specified in Kilometers (K) or Miles (M) by appending the appropriate letter to the value. For example, distance:45K. Default unit is miles.

Operations

GET - Search for places matching criteria as query parameters.

Produces - Specify a returned data format using the Accept header.
Parameters
Name Type Description
count query The number of search results per page.
q query The search query.
start query The index of the first search result for this page of results.
Status Codes
  • 200  -  Upon a successful search.
  • 204  -  If no places were found.

Example Requests

Search For Places How to search for a place.
Search For Places Directly Under a Jurisdiction How to search for a place, requiring results to be limited to those directly under a specific jurisdiction.
Search For Places Under a Jurisdiction How to search for a place, requiring results to be limited to those directly or indirectly under a specific jurisdiction.

Change Language

Feedback

Sending...

Feedback was sent.

Can't send feedback. Retry in 5 seconds.