API docs by Redocly

PlaceKit API Reference (1.2.0)

API Support: support@placekit.io URL: https://api.placekit.co Terms of Service

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)

Geocoding

PlaceKit Geocoding 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.

If your use case allows your users to search in any country, then you should ommit countries parameter and let the API defines the user's country by its IP.

To have the best location accuracy, you should set coordinates based on your users' position.

Authorizations:
api_key
Request Body schema: application/json
optional

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.
If not set, the API automatically selects the user's country defined by its IP.

language
string
Example: "en"

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.

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
Deprecated
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
string
Example: "limit=10, remaining=9, reset=1"

Request limit information based on IETF draft 7 standard.

RateLimit-Policy
string
Example: "10;w=1"

Request limit policy based on IETF draft 7 standard.

Response Schema: application/json
Array of objects
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": "en",
  • "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
optional

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.
If not set, the API automatically selects the user's country defined by its IP.

language
string
Example: "en"

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.

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
Deprecated
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
string
Example: "limit=10, remaining=9, reset=1"

Request limit information based on IETF draft 7 standard.

RateLimit-Policy
string
Example: "10;w=1"

Request limit policy based on IETF draft 7 standard.

Response Schema: application/json
Array of objects
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": "en",
  • "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"
}

Live Patching

PlaceKit Live Patching feature enables users to create a data validation flow to fix data errors or add new addresses to their catalog, chose their validation flow and instantly publish it to their end-users.

A private API key is required to use Live Patching endpoints.

List patch records

Get all patch records associated to the user.

You can refine the results by using the same parameters as the regular /search endpoint.

Authorizations:
api_key
Request Body schema: application/json
optional

Request parameters (optional)

status
string
Enum: "pending" "approved"
Example: "approved"

Select patch records with the corresponding status.

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.
If not set, the API automatically selects the user's country defined by its IP.

language
string
Example: "en"

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.

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
Deprecated
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.

offset
integer >= 0
Default: 0

Get paginated results starting from the offset.

Responses

Response Schema: application/json
Array of objects
resultsCount
integer
Example: "2"

Number of items results found.

maxResults
integer
Example: "5"

Maximum number of results items returned.

offset
integer
Example: "0"

Offset used for this paginated response.

totalResults
integer
Example: "2"

The total number of available records.

query
string
Example: "42 avenue Champs Elysees Paris"

Search text query used for this response.

Request samples

Content type
application/json
Example

Select all pending patch records

{
  • "status": "pending"
}

Response samples

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

Create a new patch record

To create a new patch record, you must provide all the required properties.

Authorizations:
api_key
Request Body schema: application/json
required

Request parameters

required
object
status
string
Default: "pending"
Enum: "pending" "approved"
Example: "pending"

Status of the current patch record.
pending: the admin will need to validate the data. Once approved, the patch record will be avaiable to end-users.
approved: the patch record will be immediately available to end-users.

language
string
Example: "en"

Two-letter ISO 639-1 language code.
Specify the language in which the patch record is written.

Responses

Response Schema: application/json
id
string
Example: "c9ce0be25ff6a74405c8cfa040e5ba1f"

Data fix identifier.

status
string
Example: "pending"

Patch record status.

name
string
Example: "42 Avenue des Champs Élysées"

Name of the current record.

city
string
Example: "Paris 8e Arrondissement"

City name.

county
string
Example: "Paris"

County name (department).

administrative
string
Example: "Île-de-France"

Administrative name (region).

country
string
Example: "France"

Country name.

countrycode
zipcode
Array of strings
Example: "75008"

Postcodes associated with the record.

population
integer
Example: "2220445"

Population number of the record city.

lat
number
Deprecated
Example: "48.871086"

Latitude value between -90 and 90.
Use coordinates instead.

lng
number
Deprecated
Example: "2.3036339"

Longitude value between -180 and 180.
Use coordinates instead.

coordinates
string
Example: "48.871086, 2.3036339"

GPS coordinates latitude and longitude of the current record.

type
string
Enum: "airport" "bus" "city" "country" "street" "tourism" "townhall" "train"
Example: "street"

Type of the record.

Request samples

Content type
application/json

Create a new patch record

{
  • "record": {
    },
  • "status": "pending"
}

Response samples

Content type
application/json
{
  • "id": "c9ce0be25ff6a74405c8cfa040e5ba1f",
  • "status": "pending",
  • "name": "42 Avenue des Champs Élysées",
  • "city": "Paris 8e Arrondissement",
  • "county": "Paris",
  • "administrative": "Île-de-France",
  • "country": "France",
  • "countrycode": "fr",
  • "zipcode": [
    ],
  • "population": 2220445,
  • "lat": 48.871086,
  • "lng": 2.3036339,
  • "coordinates": "48.871086, 2.3036339",
  • "type": "street"
}

Fix an existing record

To fix an existing record, you must provide the exact record you want to fix as the origin object.
You must also provide at least one of the property you want to modify in update.

If you want your patch record to be immediately available to your end-users, set the property status to approved.
Otherwise, the patch record will be marked as pending and will require the app owner to validate it via the Dashboard or the API.

Authorizations:
api_key
Request Body schema: application/json
required

Request parameters

required
object
required
object (record)
status
string
Default: "pending"
Enum: "pending" "approved"
Example: "pending"

Status of the current patch record.
pending: the admin will need to validate the data. Once approved, the patch record will be avaiable to end-users.
approved: the patch record will be immediately available to end-users.

language
string
Example: "en"

Two-letter ISO 639-1 language code.
Specify the language in which the patch record is written.

Responses

Response Schema: application/json
id
string
Example: "c9ce0be25ff6a74405c8cfa040e5ba1f"

Data fix identifier.

status
string
Example: "pending"

Patch record status.

name
string
Example: "42 Avenue des Champs Élysées"

Name of the current record.

city
string
Example: "Paris 8e Arrondissement"

City name.

county
string
Example: "Paris"

County name (department).

administrative
string
Example: "Île-de-France"

Administrative name (region).

country
string
Example: "France"

Country name.

countrycode
zipcode
Array of strings
Example: "75008"

Postcodes associated with the record.

population
integer
Example: "2220445"

Population number of the record city.

lat
number
Deprecated
Example: "48.871086"

Latitude value between -90 and 90.
Use coordinates instead.

lng
number
Deprecated
Example: "2.3036339"

Longitude value between -180 and 180.
Use coordinates instead.

coordinates
string
Example: "48.871086, 2.3036339"

GPS coordinates latitude and longitude of the current record.

type
string
Enum: "airport" "bus" "city" "country" "street" "tourism" "townhall" "train"
Example: "street"

Type of the record.

Request samples

Content type
application/json

Edit a record

{
  • "origin": {
    },
  • "update": {
    },
  • "status": "pending"
}

Response samples

Content type
application/json
{
  • "id": "c9ce0be25ff6a74405c8cfa040e5ba1f",
  • "status": "pending",
  • "name": "42 Avenue des Champs Élysées",
  • "city": "Paris 8e Arrondissement",
  • "county": "Paris",
  • "administrative": "Île-de-France",
  • "country": "France",
  • "countrycode": "fr",
  • "zipcode": [
    ],
  • "population": 2220445,
  • "lat": 48.871086,
  • "lng": 2.3036339,
  • "coordinates": "48.871086, 2.3036339",
  • "type": "street"
}

Get a patch record

Authorizations:
api_key
path Parameters
id
required
string <md5>

Patch record unique identifier

query Parameters
language
string <ISO-639-1>

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 record, if the translation is available.

Responses

Response Schema: application/json
id
string
Example: "c9ce0be25ff6a74405c8cfa040e5ba1f"

Data fix identifier.

status
string
Example: "pending"

Patch record status.

name
string
Example: "42 Avenue des Champs Élysées"

Name of the current record.

city
string
Example: "Paris 8e Arrondissement"

City name.

county
string
Example: "Paris"

County name (department).

administrative
string
Example: "Île-de-France"

Administrative name (region).

country
string
Example: "France"

Country name.

countrycode
zipcode
Array of strings
Example: "75008"

Postcodes associated with the record.

population
integer
Example: "2220445"

Population number of the record city.

lat
number
Deprecated
Example: "48.871086"

Latitude value between -90 and 90.
Use coordinates instead.

lng
number
Deprecated
Example: "2.3036339"

Longitude value between -180 and 180.
Use coordinates instead.

coordinates
string
Example: "48.871086, 2.3036339"

GPS coordinates latitude and longitude of the current record.

type
string
Enum: "airport" "bus" "city" "country" "street" "tourism" "townhall" "train"
Example: "street"

Type of the record.

Response samples

Content type
application/json
{
  • "id": "c9ce0be25ff6a74405c8cfa040e5ba1f",
  • "status": "pending",
  • "name": "42 Avenue des Champs Élysées",
  • "city": "Paris 8e Arrondissement",
  • "county": "Paris",
  • "administrative": "Île-de-France",
  • "country": "France",
  • "countrycode": "fr",
  • "zipcode": [
    ],
  • "population": 2220445,
  • "lat": 48.871086,
  • "lng": 2.3036339,
  • "coordinates": "48.871086, 2.3036339",
  • "type": "street"
}

Edit a patch record

Authorizations:
api_key
path Parameters
id
required
string <md5>

Patch record unique identifier

Request Body schema: application/json
optional

Request parameters

object (record)
status
string
Enum: "pending" "approved"
Example: "pending"

Status of the current data fix.
pending: the admin will need to validate the data. Once approved, the patch record will be avaiable to end-users.
approved: the patch record will be immediately available to end-users.

language
string
Example: "en"

Two-letter ISO 639-1 language code.
Specify the language in which the patch record is written.

Responses

Request samples

Content type
application/json
Example
{
  • "status": "approved"
}

Response samples

Content type
application/json
{
  • "message": "Access denied authentication failed"
}

Delete a patch record

Authorizations:
api_key
path Parameters
id
required
string <md5>

Patch record unique identifier

Responses

Response samples

Content type
application/json
{
  • "message": "Access denied authentication failed"
}

Delete a patch record translation

Authorizations:
api_key
path Parameters
id
required
string <md5>

Patch record unique identifier

language
required
string <ISO-639-1>

Two-letter ISO 639-1 language code.
Delete patch record language translation. There must be at least another translation available.

Responses

Response samples

Content type
application/json
{
  • "message": "Access denied authentication failed"
}

Keys

Handle your API keys programmatically.

A private API key is required to use Keys endpoints.

List API keys

Get all API keys associated to the current key's app.

Authorizations:
api_key

Responses

Response Schema: application/json
Array
id
string
Example: "cln0clovg0001xpeh5oxv9tfs"

Key identifier.

token
string
Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM="

API Key used to perform operations on the API.
Set this key in the request header x-placekit-api-key.

appId
string
Example: "ULIMBXTYDH"

App ID associated with this API key.

role
string
Enum: "public" "private"

Public API keys are read-only and are expected to be exposed to the browser.
A public API key can only perform Geocoding operations.
It is highly recommended to set domains when a public API key is in use.

Private API keys are read and write and are meant to be used for admin use.
A private API key can perform all operations.

domains
Array of strings <FQDN | IPv4 | IPv6> unique
Example: "['dev.domain.com', '82.123.239.43', 'my.domain.io']"

Allow list of domains or IPs from which the requests to the API are allowed.

createdAt
string <timestamp>
Example: "2023-09-26T13:23:27.077Z"

Timestamp when the key was created.

updatedAt
string <timestamp>
Example: "2023-09-26T13:24:37.862Z"

Timestamp when the key was last modified.

Response samples

Content type
application/json
[
  • {
    }
]

Create an API key

Get all API keys associated to the current key's app.

Authorizations:
api_key
Request Body schema: application/json
optional

Request parameters

role
string
Default: "public"
Enum: "public" "private"

Public API keys are read-only and are expected to be exposed to the browser.
A public API key can only perform Geocoding operations.
It is highly recommended to set domains when a public API key is in use.

Private API keys are read and write and are meant to be used for admin use.
A private API key can perform all operations.

domains
Array of strings <FQDN | IPv4 | IPv6> unique
Example: "['dev.domain.com', '82.123.239.43', 'my.domain.io']"

Allow list of domains or IPs from which the requests to the API are allowed.

Responses

Response Schema: application/json
id
string
Example: "cln0clovg0001xpeh5oxv9tfs"

Key identifier.

token
string
Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM="

API Key used to perform operations on the API.
Set this key in the request header x-placekit-api-key.

appId
string
Example: "ULIMBXTYDH"

App ID associated with this API key.

role
string
Enum: "public" "private"

Public API keys are read-only and are expected to be exposed to the browser.
A public API key can only perform Geocoding operations.
It is highly recommended to set domains when a public API key is in use.

Private API keys are read and write and are meant to be used for admin use.
A private API key can perform all operations.

domains
Array of strings <FQDN | IPv4 | IPv6> unique
Example: "['dev.domain.com', '82.123.239.43', 'my.domain.io']"

Allow list of domains or IPs from which the requests to the API are allowed.

createdAt
string <timestamp>
Example: "2023-09-26T13:23:27.077Z"

Timestamp when the key was created.

updatedAt
string <timestamp>
Example: "2023-09-26T13:24:37.862Z"

Timestamp when the key was last modified.

Request samples

Content type
application/json
{
  • "role": "public",
  • "domains": "['dev.domain.com', '82.123.239.43', 'my.domain.io']"
}

Response samples

Content type
application/json
{
  • "id": "cln0clovg0001xpeh5oxv9tfs",
  • "token": "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=",
  • "appId": "ULIMBXTYDH",
  • "role": "public",
  • "domains": "['dev.domain.com', '82.123.239.43', 'my.domain.io']",
  • "createdAt": "2023-09-26T13:23:27.077Z",
  • "updatedAt": "2023-09-26T13:24:37.862Z"
}

Get an API key

Authorizations:
api_key
path Parameters
id
required
string
Example: cln0clovg0001xpeh5oxv9tfs

Key unique identifier

Responses

Response Schema: application/json
id
string
Example: "cln0clovg0001xpeh5oxv9tfs"

Key identifier.

token
string
Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM="

API Key used to perform operations on the API.
Set this key in the request header x-placekit-api-key.

appId
string
Example: "ULIMBXTYDH"

App ID associated with this API key.

role
string
Enum: "public" "private"

Public API keys are read-only and are expected to be exposed to the browser.
A public API key can only perform Geocoding operations.
It is highly recommended to set domains when a public API key is in use.

Private API keys are read and write and are meant to be used for admin use.
A private API key can perform all operations.

domains
Array of strings <FQDN | IPv4 | IPv6> unique
Example: "['dev.domain.com', '82.123.239.43', 'my.domain.io']"

Allow list of domains or IPs from which the requests to the API are allowed.

createdAt
string <timestamp>
Example: "2023-09-26T13:23:27.077Z"

Timestamp when the key was created.

updatedAt
string <timestamp>
Example: "2023-09-26T13:24:37.862Z"

Timestamp when the key was last modified.

Response samples

Content type
application/json
{
  • "id": "cln0clovg0001xpeh5oxv9tfs",
  • "token": "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=",
  • "appId": "ULIMBXTYDH",
  • "role": "public",
  • "domains": "['dev.domain.com', '82.123.239.43', 'my.domain.io']",
  • "createdAt": "2023-09-26T13:23:27.077Z",
  • "updatedAt": "2023-09-26T13:24:37.862Z"
}

Update API key domains

Authorizations:
api_key
path Parameters
id
required
string
Example: cln0clovg0001xpeh5oxv9tfs

Key unique identifier

Request Body schema: application/json
optional

Request parameters

domains
Array of strings <FQDN | IPv4 | IPv6> unique
Example: "['dev.domain.com', '82.123.239.43', 'my.domain.io']"

Allow list of domains or IPs from which the requests to the API are allowed.

Responses

Response Schema: application/json
id
string
Example: "cln0clovg0001xpeh5oxv9tfs"

Key identifier.

token
string
Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM="

API Key used to perform operations on the API.
Set this key in the request header x-placekit-api-key.

appId
string
Example: "ULIMBXTYDH"

App ID associated with this API key.

role
string
Enum: "public" "private"

Public API keys are read-only and are expected to be exposed to the browser.
A public API key can only perform Geocoding operations.
It is highly recommended to set domains when a public API key is in use.

Private API keys are read and write and are meant to be used for admin use.
A private API key can perform all operations.

domains
Array of strings <FQDN | IPv4 | IPv6> unique
Example: "['dev.domain.com', '82.123.239.43', 'my.domain.io']"

Allow list of domains or IPs from which the requests to the API are allowed.

createdAt
string <timestamp>
Example: "2023-09-26T13:23:27.077Z"

Timestamp when the key was created.

updatedAt
string <timestamp>
Example: "2023-09-26T13:24:37.862Z"

Timestamp when the key was last modified.

Request samples

Content type
application/json
{
  • "domains": "['dev.domain.com', '82.123.239.43', 'my.domain.io']"
}

Response samples

Content type
application/json
{
  • "id": "cln0clovg0001xpeh5oxv9tfs",
  • "token": "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=",
  • "appId": "ULIMBXTYDH",
  • "role": "public",
  • "domains": "['dev.domain.com', '82.123.239.43', 'my.domain.io']",
  • "createdAt": "2023-09-26T13:23:27.077Z",
  • "updatedAt": "2023-09-26T13:24:37.862Z"
}

Delete an API key

Authorizations:
api_key
path Parameters
id
required
string
Example: cln0clovg0001xpeh5oxv9tfs

Key unique identifier

Responses

Response samples

Content type
application/json
{
  • "message": "Access denied authentication failed"
}