PlaceKit API Reference (1.0.0)

PlaceKit is a worldwide geocoding API providing fast and accurate address autocomplete, store locator, and two-way geocoding for your app.

PlaceKit OpenAPI Specifications (repository)

PlaceKit API

PlaceKit API endpoints is composed of two similar endpoints /search and /reverse.
API clients are simple wrappers on top of this API.

Search for addresses

Performs a forward geocoding search.

It will return results around coordinates (if provided) and the best matching textual relevance.

It is highly recommended to set the countries parameter with the country you need results from for the best accuracy and revelance possible.

Authorizations:
api_key
Request Body schema: application/json

Request parameters

query
string
Default: ""
Example: "42 avenue Champs Elysees Paris"

Search query terms.

countries
Array of strings
Example: ["fr"]

Array of two-letter ISO 3166-1 alpha-2 country codes.
Limit the results to given countries.
Select only one country for the best results.

language
string
Enum: "en" "fr"
Example: "fr"

Two-letter ISO 639-1 language code.
Default results are in their original language.
By setting this parameter, you can change the language of the results, if the translation is available.
Contact us if you need other languages.

types
Array of strings (types)
Items Enum: "airport" "-airport" "bus" "-bus" "city" "-city" "country" "-country" "street" "-street" "tourism" "-tourism" "townhall" "-townhall" "train" "-train"

Select the types of record to return.
Prepend with - to omit a type.
Returns all types by default.

maxResults
integer [ 1 .. 20 ]
Default: 5

Maximum number of results to return.

coordinates
string
Example: "48.873662, 2.295063"

GPS coordinates latitude and longitude.
Used to improve relevancy of results around the given area.

countryByIP
boolean
Default: false

Automatically select the country to search in via the user IP's detected location.
Returned results will be coming from the user's country's IP.
If set to true, the parameter countries acts as a fallback.

Responses

Response Headers
RateLimit-Limit
integer
Example: 5

Request limit per minute.

RateLimit-Remaining
integer
Example: 2

The number of requests left for the time window.

RateLimit-Reset
integer
Example: 34

Indicates how many seconds are left to wait before making a follow-up request.

Retry-After
integer
Example: 60

Indicates how many seconds to wait before making a follow-up request.

Response Schema: application/json
Array of objects (entity)
resultsCount
integer
Example: 2

Number of items results found.

maxResults
integer
Example: 5

Maximum number of results items returned.

query
string
Example: "42 avenue Champs Elysees Paris"

Search text query used for this response.

Request samples

Content type
application/json
{
  • "query": "42 avenue Champs Elysees Paris",
  • "countries": [
    ],
  • "language": "fr",
  • "types": [
    ],
  • "maxResults": 5,
  • "coordinates": "48.873662, 2.295063",
  • "countryByIP": false
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "resultsCount": 2,
  • "maxResults": 5,
  • "query": "42 avenue Champs Elysees Paris"
}

Reverse geocoding

Performs a reverse geocoding search.

It will return the closest results around coordinates.
If coordinates are not set, it will use the user's IP to approximate its coordinates but results will be less accurate (city level accuracy instead of street level accuracy).

Authorizations:
api_key
Request Body schema: application/json

Request parameters

countries
Array of strings
Example: ["fr"]

Array of two-letter ISO 3166-1 alpha-2 country codes.
Limit the results to given countries.
Select only one country for the best results.

language
string
Enum: "en" "fr"
Example: "fr"

Two-letter ISO 639-1 language code.
Default results are in their original language.
By setting this parameter, you can change the language of the results, if the translation is available.
Contact us if you need other languages.

types
Array of strings (types)
Items Enum: "airport" "-airport" "bus" "-bus" "city" "-city" "country" "-country" "street" "-street" "tourism" "-tourism" "townhall" "-townhall" "train" "-train"

Select the types of record to return.
Prepend with - to omit a type.
Returns all types by default.

maxResults
integer [ 1 .. 20 ]
Default: 5

Maximum number of results to return.

coordinates
string
Example: "48.873662, 2.295063"

GPS coordinates latitude and longitude.
Used to improve relevancy of results around the given area.

countryByIP
boolean
Default: true

Automatically select the country to search in via the user IP's detected location.
Returned results will be coming from the user's country's IP.
If set to true, the parameter countries acts as a fallback.

Responses

Response Headers
RateLimit-Limit
integer
Example: 5

Request limit per minute.

RateLimit-Remaining
integer
Example: 2

The number of requests left for the time window.

RateLimit-Reset
integer
Example: 34

Indicates how many seconds are left to wait before making a follow-up request.

Retry-After
integer
Example: 60

Indicates how many seconds to wait before making a follow-up request.

Response Schema: application/json
Array of objects (entity)
resultsCount
integer
Example: 2

Number of items results found.

maxResults
integer
Example: 5

Maximum number of results items returned.

query
string
Example: "42 avenue Champs Elysees Paris"

Search text query used for this response.

Request samples

Content type
application/json
{
  • "countries": [
    ],
  • "language": "fr",
  • "types": [
    ],
  • "maxResults": 5,
  • "coordinates": "48.873662, 2.295063",
  • "countryByIP": true
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "resultsCount": 2,
  • "maxResults": 5,
  • "query": "42 avenue Champs Elysees Paris"
}