Getting Started with Placekey.io

Location data can be so much more than simply placing a pin on a map. Placekey, the universal standard identifier for any physical place, believes that such data can be combined so as to drive a greater good. Location data can reveal not just where you are in the world, but the whole world of possibilities around such information. With Placekey and our data and technology integration partners, we unlock new insights on location data. With this post, we will help you get started with implementing the Placekey API in your app.

Getting Started

To get started you'll need an API Key. To jump right to a request, try our examples on this page. This is a HTTP API secured by SSL so always use https://api.placekey.io. All request and response bodies will be JSON. Make sure to set your Content-Type header to application/json.

You can use this API to retrieve a Placekey for any location in the world – identifying it by its geographical coordinates or its address. Your Placekey will contain a unique identifier for the POI that's located there. (If you have any feedback or if you need help, please contact us: https://placekey.io/feedback.)

Placekey Developer Portal: The Placekey Developer Portal allows you to get access to the API, review your usage, and generate API keys.

Placekey Design: The Placekey design specification is available here. The details in Placekey encoding is here. 

Placekey Libraries: We have built libraries for Python and Javascript that allow you to perform geometric operations with Placekey. To work with Python, click here. To access the JavaScript library, click here.

Placekey Tutorials: We also offer various tutorials about how Placekey can benefit your data work.

Authentication

Authentication to the API is done via API Keys, which can be generated from your account dashboard. You can make as many as you like but remember that rate-limiting applies, so remember to revoke keys that aren't in use to ensure you aren’t using up your quota. All you have to do to be authenticated is to set the apikey header on your request to your API key.

Error Codes

Placekey uses standard HTTP status codes to communicate success or failure:

Rate Limiting: Our rate limit is currently 1000 requests per minute to the Placekey API and 100 requests per minute to the Placekey Bulk API. If you exceed this, you will receive a HTTP 429 response code.

Versioning: Currently, we support only v1 of our API. We version our API in the path, so if you're querying https://api.placekey.io/v1 you know you're in the right place. Your access to all versions will use the same credentials and rate-limits.

Placekey API

A general Placekey API request body is a JSON object with the following parameters:

The query field specifies the place to be matched and the options field specifies any modifications desired to the behaviour of the API.

Each query must have non-blank values for at least one of the following combinations to get a place key:

• query.latitude + query.longitude
• query.street_address + query.city + query.region + query.postal_code + query.iso_country_code

Of course, the more information you provide us with, the more precise our match can be, so include as much detail as possible in the query. If you don't have the information, try passing a null and we'll try our best to match.

Response

Your response will be a JSON object. When accessing the /placekey endpoint, your response will contain the following:

‍

When accessing the /placekeys endpoint, your response will be a list of the above.

In our next post, we’ll explore Placekey’s matching algorithm and establishing a Placekey for an exact address and a single location, as well as for a POI.