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 Geocoding API endpoints is composed of two similar endpoints /search
and /reverse
.
API clients are simple wrappers on top of this API.
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.
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. |
language | string Example: "en" Two-letter ISO 639-1 language code. |
types | Array of strings (types) Items Enum: "administrative" "-administrative" "airport" "-airport" "bus" "-bus" "city" "-city" "country" "-country" "county" "-county" "street" "-street" "tourism" "-tourism" "townhall" "-townhall" "train" "-train" Select the types of record to return. |
maxResults | integer [ 1 .. 20 ] Default: 5 Maximum number of results to return. |
coordinates | string Example: "48.873662, 2.295063" GPS coordinates latitude and longitude. |
countryByIP | boolean Deprecated Default: false Automatically select the country to search in via the user IP's detected location. |
RateLimit | string Example: "limit=10, remaining=9, reset=1" Request limit information based on IETF draft 7 standard. |
RateLimit-Policy |
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. |
{- "query": "42 avenue Champs Elysees Paris",
- "countries": [
- "fr"
], - "language": "en",
- "types": [
- "administrative"
], - "maxResults": 5,
- "coordinates": "48.873662, 2.295063",
- "countryByIP": false
}
{- "results": [
- {
- "highlight": "<mark>42 Avenue</mark> des <mark>Champs Élysées</mark>",
- "name": "42 Avenue des Champs Élysées",
- "city": "Paris 8e Arrondissement",
- "county": "Paris",
- "administrative": "Île-de-France",
- "country": "France",
- "administrativecode": "CA",
- "citycode": "75108",
- "countrycode": "fr",
- "countycode": "75",
- "zipcode": [
- "75008"
], - "population": 2220445,
- "lat": 48.871086,
- "lng": 2.3036339,
- "coordinates": "48.871086, 2.3036339",
- "type": "street"
}
], - "resultsCount": 2,
- "maxResults": 5,
- "query": "42 avenue Champs Elysees Paris"
}
Performs a reverse geocoding search.
It will return the closest results around coordinates
.
If coordinates
are not provided, 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).
Request parameters
countries | Array of strings Example: "fr" Array of two-letter ISO 3166-1 alpha-2 country codes. |
language | string Example: "en" Two-letter ISO 639-1 language code. |
types | Array of strings (types) Items Enum: "administrative" "-administrative" "airport" "-airport" "bus" "-bus" "city" "-city" "country" "-country" "county" "-county" "street" "-street" "tourism" "-tourism" "townhall" "-townhall" "train" "-train" Select the types of record to return. |
maxResults | integer [ 1 .. 20 ] Default: 5 Maximum number of results to return. |
coordinates | string Example: "48.873662, 2.295063" GPS coordinates latitude and longitude. |
countryByIP | boolean Deprecated Default: true Automatically select the country to search in via the user IP's detected location. |
RateLimit | string Example: "limit=10, remaining=9, reset=1" Request limit information based on IETF draft 7 standard. |
RateLimit-Policy |
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. |
{- "countries": [
- "fr"
], - "language": "en",
- "types": [
- "administrative"
], - "maxResults": 5,
- "coordinates": "48.873662, 2.295063",
- "countryByIP": true
}
{- "results": [
- {
- "highlight": "<mark>42 Avenue</mark> des <mark>Champs Élysées</mark>",
- "name": "42 Avenue des Champs Élysées",
- "city": "Paris 8e Arrondissement",
- "county": "Paris",
- "administrative": "Île-de-France",
- "country": "France",
- "administrativecode": "CA",
- "citycode": "75108",
- "countrycode": "fr",
- "countycode": "75",
- "zipcode": [
- "75008"
], - "population": 2220445,
- "lat": 48.871086,
- "lng": 2.3036339,
- "coordinates": "48.871086, 2.3036339",
- "type": "street"
}
], - "resultsCount": 2,
- "maxResults": 5,
- "query": "42 avenue Champs Elysees Paris"
}
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.
Get all patch records associated to the user.
You can refine the results by using the same parameters as the regular /search
endpoint.
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. |
language | string Example: "en" Two-letter ISO 639-1 language code. |
types | Array of strings (types) Items Enum: "administrative" "-administrative" "airport" "-airport" "bus" "-bus" "city" "-city" "country" "-country" "county" "-county" "street" "-street" "tourism" "-tourism" "townhall" "-townhall" "train" "-train" Select the types of record to return. |
maxResults | integer [ 1 .. 20 ] Default: 5 Maximum number of results to return. |
coordinates | string Example: "48.873662, 2.295063" GPS coordinates latitude and longitude. |
countryByIP | boolean Deprecated Default: false Automatically select the country to search in via the user IP's detected location. |
offset | integer >= 0 Default: 0 Get paginated results starting from the offset. |
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. |
Select all pending
patch records
{- "status": "pending"
}
{- "results": [
- {
- "highlight": "<mark>42 Avenue</mark> des <mark>Champs Élysées</mark>",
- "name": "42 Avenue des Champs Élysées",
- "city": "Paris 8e Arrondissement",
- "county": "Paris",
- "administrative": "Île-de-France",
- "country": "France",
- "administrativecode": "CA",
- "citycode": "75108",
- "countrycode": "fr",
- "countycode": "75",
- "zipcode": [
- "75008"
], - "population": 2220445,
- "lat": 48.871086,
- "lng": 2.3036339,
- "coordinates": "48.871086, 2.3036339",
- "type": "street"
}
], - "resultsCount": 2,
- "maxResults": 5,
- "offset": 0,
- "totalResults": 2,
- "query": "42 avenue Champs Elysees Paris"
}
To create a new patch record, you must provide all the required properties.
Request parameters
required | object |
status | string Default: "pending" Enum: "pending" "approved" Example: "pending" Status of the current patch record. |
language | string Example: "en" Two-letter ISO 639-1 language code. |
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. |
administrativecode | |
citycode | string Example: "75108" INSEE city code (only available for France cities). |
countrycode | |
countycode | |
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 |
lng | number Deprecated Example: "2.3036339" Longitude value between |
coordinates | string Example: "48.871086, 2.3036339" GPS coordinates latitude and longitude of the current record. |
type | string Enum: "administrative" "airport" "bus" "city" "country" "county" "street" "tourism" "townhall" "train" Example: "street" Type of the record. |
Create a new patch record
{- "record": {
- "name": "Avenue New Road",
- "city": "Rome",
- "county": "Roma Capitale",
- "administrative": "Lazio",
- "country": "Italy",
- "countrycode": "it",
- "zipcode": [
- "00137"
], - "population": 2776362,
- "coordinates": "41.9518005, 12.5644911",
- "type": "street"
}, - "status": "pending"
}
{- "id": "c9ce0be25ff6a74405c8cfa040e5ba1f",
- "status": "pending",
- "name": "42 Avenue des Champs Élysées",
- "city": "Paris 8e Arrondissement",
- "county": "Paris",
- "administrative": "Île-de-France",
- "country": "France",
- "administrativecode": "CA",
- "citycode": "75108",
- "countrycode": "fr",
- "countycode": "75",
- "zipcode": [
- "75008"
], - "population": 2220445,
- "lat": 48.871086,
- "lng": 2.3036339,
- "coordinates": "48.871086, 2.3036339",
- "type": "street"
}
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.
Request parameters
required | object |
required | object (record) |
status | string Default: "pending" Enum: "pending" "approved" Example: "pending" Status of the current patch record. |
language | string Example: "en" Two-letter ISO 639-1 language code. |
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. |
administrativecode | |
citycode | string Example: "75108" INSEE city code (only available for France cities). |
countrycode | |
countycode | |
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 |
lng | number Deprecated Example: "2.3036339" Longitude value between |
coordinates | string Example: "48.871086, 2.3036339" GPS coordinates latitude and longitude of the current record. |
type | string Enum: "administrative" "airport" "bus" "city" "country" "county" "street" "tourism" "townhall" "train" Example: "street" Type of the record. |
Edit a record
{- "origin": {
- "name": "Avenue des Champs Élysées",
- "city": "Paris 8e Arrondissement",
- "county": "Paris",
- "administrative": "Île-de-France",
- "country": "France",
- "countrycode": "fr",
- "zipcode": [
- "75008"
], - "population": 2220445,
- "coordinates": "48.871086, 2.3036339",
- "type": "street"
}, - "update": {
- "name": "rue des Nouveaux Champs Élysées",
- "zipcode": [
- "75020"
]
}, - "status": "pending"
}
{- "id": "c9ce0be25ff6a74405c8cfa040e5ba1f",
- "status": "pending",
- "name": "42 Avenue des Champs Élysées",
- "city": "Paris 8e Arrondissement",
- "county": "Paris",
- "administrative": "Île-de-France",
- "country": "France",
- "administrativecode": "CA",
- "citycode": "75108",
- "countrycode": "fr",
- "countycode": "75",
- "zipcode": [
- "75008"
], - "population": 2220445,
- "lat": 48.871086,
- "lng": 2.3036339,
- "coordinates": "48.871086, 2.3036339",
- "type": "street"
}
id required | string <md5> Patch record unique identifier |
language | string <ISO-639-1> Two-letter ISO 639-1 language code. |
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. |
administrativecode | |
citycode | string Example: "75108" INSEE city code (only available for France cities). |
countrycode | |
countycode | |
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 |
lng | number Deprecated Example: "2.3036339" Longitude value between |
coordinates | string Example: "48.871086, 2.3036339" GPS coordinates latitude and longitude of the current record. |
type | string Enum: "administrative" "airport" "bus" "city" "country" "county" "street" "tourism" "townhall" "train" Example: "street" Type of the record. |
{- "id": "c9ce0be25ff6a74405c8cfa040e5ba1f",
- "status": "pending",
- "name": "42 Avenue des Champs Élysées",
- "city": "Paris 8e Arrondissement",
- "county": "Paris",
- "administrative": "Île-de-France",
- "country": "France",
- "administrativecode": "CA",
- "citycode": "75108",
- "countrycode": "fr",
- "countycode": "75",
- "zipcode": [
- "75008"
], - "population": 2220445,
- "lat": 48.871086,
- "lng": 2.3036339,
- "coordinates": "48.871086, 2.3036339",
- "type": "street"
}
id required | string <md5> Patch record unique identifier |
Request parameters
object (record) | |
status | string Enum: "pending" "approved" Example: "pending" Status of the current data fix. |
language | string Example: "en" Two-letter ISO 639-1 language code. |
{- "status": "approved"
}
{- "message": "Access denied authentication failed"
}
id required | string <md5> Patch record unique identifier |
language required | string <ISO-639-1> Two-letter ISO 639-1 language code. |
{- "message": "Access denied authentication failed"
}
Get all API keys associated to the current key's app.
id | string Example: "cln0clovg0001xpeh5oxv9tfs" Key identifier. |
token | string Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=" API Key used to perform operations on the API. |
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. Private API keys are read and write and are meant to be used for admin use. |
domains | Array of strings <FQDN | IPv4 | IPv6 | localhost> unique [ items <FQDN | IPv4 | IPv6 | localhost > ] Example: "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']" 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. |
[- {
- "id": "cln0clovg0001xpeh5oxv9tfs",
- "token": "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=",
- "appId": "ULIMBXTYDH",
- "role": "public",
- "domains": "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']",
- "createdAt": "2023-09-26T13:23:27.077Z",
- "updatedAt": "2023-09-26T13:24:37.862Z"
}
]
Get all API keys associated to the current key's app.
Request parameters
role | string Default: "public" Enum: "public" "private" Public API keys are read-only and are expected to be exposed to the browser. Private API keys are read and write and are meant to be used for admin use. |
domains | Array of strings <FQDN | IPv4 | IPv6 | localhost> unique [ items <FQDN | IPv4 | IPv6 | localhost > ] Example: "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']" Allow list of domains or IPs from which the requests to the API are allowed. |
id | string Example: "cln0clovg0001xpeh5oxv9tfs" Key identifier. |
token | string Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=" API Key used to perform operations on the API. |
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. Private API keys are read and write and are meant to be used for admin use. |
domains | Array of strings <FQDN | IPv4 | IPv6 | localhost> unique [ items <FQDN | IPv4 | IPv6 | localhost > ] Example: "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']" 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. |
{- "role": "public",
- "domains": "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']"
}
{- "id": "cln0clovg0001xpeh5oxv9tfs",
- "token": "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=",
- "appId": "ULIMBXTYDH",
- "role": "public",
- "domains": "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']",
- "createdAt": "2023-09-26T13:23:27.077Z",
- "updatedAt": "2023-09-26T13:24:37.862Z"
}
id required | string Example: cln0clovg0001xpeh5oxv9tfs Key unique identifier |
id | string Example: "cln0clovg0001xpeh5oxv9tfs" Key identifier. |
token | string Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=" API Key used to perform operations on the API. |
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. Private API keys are read and write and are meant to be used for admin use. |
domains | Array of strings <FQDN | IPv4 | IPv6 | localhost> unique [ items <FQDN | IPv4 | IPv6 | localhost > ] Example: "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']" 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. |
{- "id": "cln0clovg0001xpeh5oxv9tfs",
- "token": "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=",
- "appId": "ULIMBXTYDH",
- "role": "public",
- "domains": "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']",
- "createdAt": "2023-09-26T13:23:27.077Z",
- "updatedAt": "2023-09-26T13:24:37.862Z"
}
id required | string Example: cln0clovg0001xpeh5oxv9tfs Key unique identifier |
Request parameters
domains | Array of strings <FQDN | IPv4 | IPv6 | localhost> unique [ items <FQDN | IPv4 | IPv6 | localhost > ] Example: "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']" Allow list of domains or IPs from which the requests to the API are allowed. |
id | string Example: "cln0clovg0001xpeh5oxv9tfs" Key identifier. |
token | string Example: "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=" API Key used to perform operations on the API. |
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. Private API keys are read and write and are meant to be used for admin use. |
domains | Array of strings <FQDN | IPv4 | IPv6 | localhost> unique [ items <FQDN | IPv4 | IPv6 | localhost > ] Example: "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']" 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. |
{- "domains": "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']"
}
{- "id": "cln0clovg0001xpeh5oxv9tfs",
- "token": "pk_OGRVIUTnuxFEJUXNECjFrZ6sdVovGz1ojygkbzGXcbM=",
- "appId": "ULIMBXTYDH",
- "role": "public",
- "domains": "['dev.domain.com', '82.123.239.43', '*.domain.io', 'localhost']",
- "createdAt": "2023-09-26T13:23:27.077Z",
- "updatedAt": "2023-09-26T13:24:37.862Z"
}