linking | sitemap | api | about

thePlacename.com RESTful API

The API opens all of the place name search, geometry aggregating, and fuzzy matching features of thePlacename.com 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
demoX-API-KEYNYHD3MKGB4QQYJF7DP3F3WT8KR5YY0IPKZYWMZU410/hr

Contact Tom Liebert for a full-access key: http://tomliebert.com/contact

 Return Format 

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

paramdescription
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]
http://theplacename.com/api/v1/trending/format/json

Example using cURL:

curl -X POST -H "X-API-KEY:[key]" http://theplacename.com/api/v1/trending --data "format=xml"
#or:
curl -X GET -H "X-API-KEY:[key]" http://theplacename.com/api/v1/trending/format/html

 Resources Available 

 General

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]
http://theplacename.com/api/v1/trending

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

server urlresource[format/value]
http://theplacename.com/api/v1/random

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

server urlresource[format/value]
http://theplacename.com/api/v1/placetypes


 Relative

Methods to discover places that relate to a known place; that is relative to a !thePlacename.com 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]
http://theplacename.com/api/v1/similar/place_id/51224

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]
http://theplacename.com/api/v1/nearby/place_id/51224


 Search

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]
http://theplacename.com/api/v1/suggest/searchterm/bost

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]
http://theplacename.com/api/v1/match/name/boston


 Place

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]
http://theplacename.com/api/v1/place/place_id/51224/simplify/trueformat/json