linking | sitemap | api | about RESTful API

The API opens all of the place name search, geometry aggregating, and fuzzy matching features of to your application. Places are returned as robust polygon and polyline geometries, in GIS standards compliant GeoJSON format. All data are returned with source citation and coordinate system reference.

The current version of the API is v1

 API Key 

Access to the API is granted via an API Key. Rate-limited general access key is available for testing and demonstration purposes.

UseKey NameKey ValueLimit

Contact Tom Liebert for a full-access key:

 Return Format 

Available data formats that can be returned (if format is not specified json is returned):

xmlalmost any programming language can read XML
jsonuseful for JavaScript and increasingly PHP apps
csvopen with spreadsheet programs
htmla simple HTML table
phpRepresentation of PHP code that can be eval()’ed
serializeSerialized data that can be unserialized in PHP

 Request Format 

Requests may be made using the HTTP methods GET and POST. The API Key must be sent in the HTTP header, the resource is specified in the url and resource parameters are sent as POST data or in a URI string for GET methods.

server urlresource[parameter/value][parameter/value][format/value]

Example using cURL:

curl -X POST -H "X-API-KEY:[key]" --data "format=xml"
curl -X GET -H "X-API-KEY:[key]"

 Resources Available 


The general discovery methods take no parameters, and return an array of places. For each place, the following is returned: placename, shortname (shortened or simplified place name), place type, geographic scope, centroid latitude and longitude, geographic extents (bounding box format).

trending::Returns the 8 most-requested placenames to date. No parameters are required.

server urlresource[format/value]

random::Returns 12 randomly selected placenames, sorted by geographic scope. No parameters are required.

server urlresource[format/value]

placetypes::Returns an array of all available place types, sorted alphabetically. No parameters are required.

server urlresource[format/value]


Methods to discover places that relate to a known place; that is relative to a ! place_id.

similar::Returns up to 8 places with similar-sounding placenames, sorted by name similarity then most-requested (trending places). Requires a place_id.

server urlresourceparameter/[integer][format/value]

nearby::Returns up to 24 places determined to be nearby, sorted by place type then placename. Requires a place_id.

server urlresourceparameter/[integer][format/value]


Methods to discover places by name. These methods are not case-sensitive, and care should be taken to strip punctuation and non-standard characters.

suggest::Returns up to 16 places with a similar-sounding names, sorted by place type then placename. Requires a searchterm length of at least 3 characters. Case-insensitive.

server urlresourceparameter/[text][format/value]

match::Returns an array of places with matching placenames, sorted by place type then placename. Requires a placename. Case-insensitive.

server urlresourceparameter/[text][format/value]


Retrieves the geometry (full coodinates of the place polygon or polyline) and metadata of a place.

place::Returns the geometry coordinates in GeoJSON format, source metadata of a specific place. Requires a place_id. Geometry simplification may be requested to reduce the data payload and ease browser rendering of the geometry. Format should be json, as other data formats may return unexpected or inconsistent formatting.

server urlresourceparameter/[integer]parameter/[true or false][format/value]