--- title: "Search and geocoding API" description: "Forward and reverse geocoding API for global location search." --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # Search and geocoding API The MapTiler **Search and geocoding API** makes it possible to search for any place on Earth and get accurate location data in return. See the [intro to place search](https://docs.maptiler.com/guides/developer/location-services/geocoding-search/) to learn how it works and what you can use it for. ## How to use the API - Directly from your web or backend applications. - Via the [Geocoding API client](https://docs.maptiler.com/client-js/api/variables/services_geocoding.geocoding/) library, which wraps the API calls in ready-made functions for easier use in JavaScript. The client library is a good choice for JavaScript if you only need to use geocoding but not a map. - With our complete **MapTiler SDK JS** which provides a [geocoding control module](https://docs.maptiler.com/sdk-js/modules/geocoding/) to quickly integrate place search into your application. The SDK is best if you need the geocoding functionality plus a complete map dev kit, or if you want more favorable usage tracking [via **sessions** rather than API requests](https://docs.maptiler.com/guides/account/sessions-vs-requests/). - With other JavaScript libraries: [MapLibre GL JS](https://docs.maptiler.com/maplibre/examples/geocoding-control/) • [Leaflet](https://docs.maptiler.com/leaflet/examples/geocoding-control/) • [OpenLayers](https://docs.maptiler.com/openlayers/examples/geocoding-control/) - Without a map: [Vanilla JS](https://docs.maptiler.com/sdk-js/examples/geocoding-vanilla-js/) Key You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to secure it](https://docs.maptiler.com/guides/developer/credentials/api-key/#secure-key). ## Getting started For practical guidance on how to use this API, check out: - Check the [geocoding playground](https://www.maptiler.com/showcase/geocoding/) to see how to construct the API calls - Explanation and usage tips for the most used [search parameters](https://docs.maptiler.com/guides/developer/location-services/geocoding-search/parameters) ### Basic example ```js import { geocoding } from "@maptiler/client"; // in an async function, or as a 'thenable': const result = await geocoding.forward("paris"); ``` ## Geocoding API reference Scalar API Reference - [ Introduction ](#description/introduction) - [ Geocoding ](#tag/geocoding) Close Group - Geocoding - [ Search by name (forward) HTTP Method:  GET](#tag/geocoding/GET/geocoding/{query}.json) - [ Search by coordinates (reverse) HTTP Method:  GET](#tag/geocoding/GET/geocoding/{longitude},{latitude}.json) - [ Search by feature ID HTTP Method:  GET](#tag/geocoding/GET/geocoding/{id}.json) - [ Batch geocoding API HTTP Method:  GET](#tag/geocoding/GET/geocoding/{queries}.json) [Powered by Scalar](https://www.scalar.com) v1.0 OpenAPI 3.1.0 # MapTiler API [Support](mailto:support@maptiler.com) [](https://docs.maptiler.com/support/requests/) [Terms of Service](https://www.maptiler.com/terms/) Server Server:https://api.maptiler.com MapTiler API ## AuthenticationRequired Selected Auth Type: key Client Libraries Shell Ruby Node.js PHP Python MoreSelect from all clients Shell Curl ## Geocoding ​Copy link Geocoding Operations - get/geocoding/{query}.json - get/geocoding/{longitude},{latitude}.json - get/geocoding/{id}.json - get/geocoding/{queries}.json ### Search by name (forward) ​Copy link Auth Required Forward [geocoding (search by place name)](https://www.maptiler.com/cloud/geocoding/). Path Parameters - queryCopy link to query Type: string required Examples Zurichrestaurant mediterranean Place name to search. You can also use bare [POI category](https://docs.maptiler.com/guides/location-services/geocoding-search/poi-category/) or mix it with a name to search for POIs of desired category, unless `poi` index is excluded. Query Parameters - bboxCopy link to bbox Type: array · bbox Example \[5.9559, 45.818, 10.4921, 47.8084\] Example 5.9559,45.818,10.4921,47.8084 A `[w, s, e, n]` bounding box array to use for limiting search results. Only features inside the provided bounding box will be included. - proximityCopy link to proximity A `[lon, lat]` array to use for biasing search results or the string `ip` to do server-side IP based geolocation. Specify to prefer results close to a specific location - features closer to the proximity value will be given priority over those further from the proximity value. Any ofCoordinates - Type: array · Coordinates Example \[8.528509, 47.3774434\] Example 8.528509,47.3774434 - languageCopy link to language Type: array string\[\] …20 unique!enum Example de,en Example de,en Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made. values - aa - ab - ae - af - ak - Show all values - countryCopy link to country Type: array string\[\] unique! Example sk,cz Example sk,cz Limit search to specific country/countries. - limitCopy link to limit Type: integer min:   1 max:   10 Maximum number of results. Default: 5 for forward geocoding, 1 for reverse geocoding. For reverse geocoding, limit > 1 requires exactly one `types` value and switches to a nearest-neighbour search (N closest features of that type within 1 km). Without limit, reverse geocoding returns a single best match per layer at the queried point - typesCopy link to types Type: array string\[\] · PlaceType\[\] unique!enum Filter types of which features to return. If not specified, default configuration of API is used (see [PlaceTypeValues](https://docs.maptiler.com/cloud/api/geocoding/#PlaceTypeValues) for the list). In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single `type` can be returned, otherwise single feature for every specified type (or default types) can be returned - see also the [limit](#limit) parameter. - Type: string · PlaceTypeenum Check out the [descriptions and default values](https://docs.maptiler.com/guides/location-services/geocoding-search/place-types-values/) of each of the PlaceType values values - continental\_marine - country - major\_landform - region - subregion - Show all values - excludeTypesCopy link to excludeTypes Type: boolean Default false Set to `true` to use all available feature types except those specified in `types`. - fuzzyMatchCopy link to fuzzyMatch Type: boolean Default true Set to `false` to disable fuzzy search. - autocompleteCopy link to autocomplete Type: boolean Set to `true` to use autocomplete, `false` to disable autocomplete. - worldviewCopy link to worldview Type: string enum Example ch Example ch Some of the geographical boundaries and names are disputed. When `worldview` option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: `auto` - the worldview is determined by the location of the client, `default` - disputed areas are returned without country information, countries with disputed borders are returned without full geometry. values - default - auto - ae - ch - jp - kr - us Responses - 200 Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature application/json - 400 Query too long / Invalid parameters - 403 Key is missing, invalid or restricted Request Example for get/geocoding/_{query}_.json Shell Curl ```curl curl 'https://api.maptiler.com/geocoding/Zurich.json?key=YOUR_MAPTILER_API_KEY' ``` Copy Copy Test Request(get /geocoding/{query}.json) Status: 200Status: 400Status: 403 Show Schema ```json { "type": "FeatureCollection", "features": [ { "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string", "additionalProperty": "anything", "type": "Feature", "properties": { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything" }, "geometry": { "type": "Point", "coordinates": [ 8.528509, 47.3774434 ] }, "bbox": [ 5.9559, 45.818, 10.4921, 47.8084 ], "center": [ 8.528509, 47.3774434 ], "place_name": "string", "matching_place_name": "string", "matching_text": "string", "place_type": [ "continental_marine" ], "place_type_name": [ "string" ], "relevance": 1, "context": [ { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything", "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string" } ], "address": "string", "^place_name_(\\w\\w)": "string" } ], "query": [ "string" ], "attribution": "© MapTiler © OpenStreetMap contributors" } ``` JSONCopy JSONCopy Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature ### Search by coordinates (reverse) ​Copy link Auth Required Reverse geocoding (search by coordinates). Path Parameters - longitudeCopy link to longitude Type: number min:   \-180 max:   180 required Example 8.528509 - latitudeCopy link to latitude Type: number min:   \-90 max:   90 required Example 47.3774434 Query Parameters - languageCopy link to language Type: array string\[\] …20 unique!enum Example de,en Example de,en Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made. values - aa - ab - ae - af - ak - Show all values - limitCopy link to limit Type: integer min:   1 max:   10 Maximum number of results. Default: 5 for forward geocoding, 1 for reverse geocoding. For reverse geocoding, limit > 1 requires exactly one `types` value and switches to a nearest-neighbour search (N closest features of that type within 1 km). Without limit, reverse geocoding returns a single best match per layer at the queried point - typesCopy link to types Type: array string\[\] · PlaceType\[\] unique!enum Filter types of which features to return. If not specified, default configuration of API is used (see [PlaceTypeValues](https://docs.maptiler.com/cloud/api/geocoding/#PlaceTypeValues) for the list). In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single `type` can be returned, otherwise single feature for every specified type (or default types) can be returned - see also the [limit](#limit) parameter. - Type: string · PlaceTypeenum Check out the [descriptions and default values](https://docs.maptiler.com/guides/location-services/geocoding-search/place-types-values/) of each of the PlaceType values values - continental\_marine - country - major\_landform - region - subregion - Show all values - excludeTypesCopy link to excludeTypes Type: boolean Default false Set to `true` to use all available feature types except those specified in `types`. - worldviewCopy link to worldview Type: string enum Example ch Example ch Some of the geographical boundaries and names are disputed. When `worldview` option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: `auto` - the worldview is determined by the location of the client, `default` - disputed areas are returned without country information, countries with disputed borders are returned without full geometry. values - default - auto - ae - ch - jp - kr - us Responses - 200 Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature application/json - 400 Query too long / Invalid parameters - 403 Key is missing, invalid or restricted Request Example for get/geocoding/_{longitude}_,_{latitude}_.json Shell Curl ```curl curl 'https://api.maptiler.com/geocoding/8.528509,47.3774434.json?key=YOUR_MAPTILER_API_KEY' ``` Copy Copy Test Request(get /geocoding/{longitude},{latitude}.json) Status: 200Status: 400Status: 403 Show Schema ```json { "type": "FeatureCollection", "features": [ { "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string", "additionalProperty": "anything", "type": "Feature", "properties": { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything" }, "geometry": { "type": "Point", "coordinates": [ 8.528509, 47.3774434 ] }, "bbox": [ 5.9559, 45.818, 10.4921, 47.8084 ], "center": [ 8.528509, 47.3774434 ], "place_name": "string", "matching_place_name": "string", "matching_text": "string", "place_type": [ "continental_marine" ], "place_type_name": [ "string" ], "relevance": 1, "context": [ { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything", "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string" } ], "address": "string", "^place_name_(\\w\\w)": "string" } ], "query": [ "string" ], "attribution": "© MapTiler © OpenStreetMap contributors" } ``` JSONCopy JSONCopy Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature ### Search by feature ID ​Copy link Auth Required Search feature by its ID (`id`) as returned in forward or reverse geocoding response and return its full geometry. Note that the feature ID is not stable and it changes when the database is re-indexed. Path Parameters - idCopy link to id Type: string required Pattern `^(\S+)\.([0-9]+)$` Example country.26561650 Feature ID (found in response of forward or reverse geocoding) Query Parameters - languageCopy link to language Type: array string\[\] …20 unique!enum Example de,en Example de,en Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made. values - aa - ab - ae - af - ak - Show all values - worldviewCopy link to worldview Type: string enum Example ch Example ch Some of the geographical boundaries and names are disputed. When `worldview` option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: `auto` - the worldview is determined by the location of the client, `default` - disputed areas are returned without country information, countries with disputed borders are returned without full geometry. values - default - auto - ae - ch - jp - kr - us Responses - 200 Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature application/json - 400 Query too long / Invalid parameters - 403 Key is missing, invalid or restricted Request Example for get/geocoding/_{id}_.json Shell Curl ```curl curl 'https://api.maptiler.com/geocoding/country.26561650.json?key=YOUR_MAPTILER_API_KEY' ``` Copy Copy Test Request(get /geocoding/{id}.json) Status: 200Status: 400Status: 403 Show Schema ```json { "type": "FeatureCollection", "features": [ { "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string", "additionalProperty": "anything", "type": "Feature", "properties": { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything" }, "geometry": { "type": "Point", "coordinates": [ 8.528509, 47.3774434 ] }, "bbox": [ 5.9559, 45.818, 10.4921, 47.8084 ], "center": [ 8.528509, 47.3774434 ], "place_name": "string", "matching_place_name": "string", "matching_text": "string", "place_type": [ "continental_marine" ], "place_type_name": [ "string" ], "relevance": 1, "context": [ { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything", "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string" } ], "address": "string", "^place_name_(\\w\\w)": "string" } ], "query": [ "string" ], "attribution": "© MapTiler © OpenStreetMap contributors" } ``` JSONCopy JSONCopy Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature ### Batch geocoding API ​Copy link Auth Required Perform geocoding of more than one request in a single API call. Check out the [Batch Geocoding guide](https://docs.maptiler.com/guides/geocoding/batch-geocoding-api/) for an example. Path Parameters - queriesCopy link to queries Type: string required Example Paris;Berlin Semicolon-separated list of queries. Semicolon `;` must be provided verbatim and not be URL-encoded. Each query may be forward, reverse or by feature ID. Maximum of 50 queries are supported. Query Parameters - bboxCopy link to bbox Type: array · bbox Example \[5.9559, 45.818, 10.4921, 47.8084\] Example 5.9559,45.818,10.4921,47.8084 A `[w, s, e, n]` bounding box array to use for limiting search results. Only features inside the provided bounding box will be included. - proximityCopy link to proximity A `[lon, lat]` array to use for biasing search results or the string `ip` to do server-side IP based geolocation. Specify to prefer results close to a specific location - features closer to the proximity value will be given priority over those further from the proximity value. Any ofCoordinates - Type: array · Coordinates Example \[8.528509, 47.3774434\] Example 8.528509,47.3774434 - languageCopy link to language Type: array string\[\] …20 unique!enum Example de,en Example de,en Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made. values - aa - ab - ae - af - ak - Show all values - countryCopy link to country Type: array string\[\] unique! Example sk,cz Example sk,cz Limit search to specific country/countries. - limitCopy link to limit Type: integer min:   1 max:   10 Maximum number of results. Default: 5 for forward geocoding, 1 for reverse geocoding. For reverse geocoding, limit > 1 requires exactly one `types` value and switches to a nearest-neighbour search (N closest features of that type within 1 km). Without limit, reverse geocoding returns a single best match per layer at the queried point - typesCopy link to types Type: array string\[\] · PlaceType\[\] unique!enum Filter types of which features to return. If not specified, default configuration of API is used (see [PlaceTypeValues](https://docs.maptiler.com/cloud/api/geocoding/#PlaceTypeValues) for the list). In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single `type` can be returned, otherwise single feature for every specified type (or default types) can be returned - see also the [limit](#limit) parameter. - Type: string · PlaceTypeenum Check out the [descriptions and default values](https://docs.maptiler.com/guides/location-services/geocoding-search/place-types-values/) of each of the PlaceType values values - continental\_marine - country - major\_landform - region - subregion - Show all values - excludeTypesCopy link to excludeTypes Type: boolean Default false Set to `true` to use all available feature types except those specified in `types`. - fuzzyMatchCopy link to fuzzyMatch Type: boolean Default true Set to `false` to disable fuzzy search. - autocompleteCopy link to autocomplete Type: boolean Set to `true` to use autocomplete, `false` to disable autocomplete. - worldviewCopy link to worldview Type: string enum Example ch Example ch Some of the geographical boundaries and names are disputed. When `worldview` option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: `auto` - the worldview is determined by the location of the client, `default` - disputed areas are returned without country information, countries with disputed borders are returned without full geometry. values - default - auto - ae - ch - jp - kr - us Responses - 200 Array of geocoding results where items are matching order of queries in the request. Every result is represented as FeatureCollection where every item is represented as a GeoJSON Feature application/json - 400 Query too long / Invalid parameters - 403 Key is missing, invalid or restricted Request Example for get/geocoding/_{queries}_.json Shell Curl ```curl curl 'https://api.maptiler.com/geocoding/Paris;Berlin.json?key=YOUR_MAPTILER_API_KEY' ``` Copy Copy Test Request(get /geocoding/{queries}.json) Status: 200Status: 400Status: 403 Show Schema ```json [ { "type": "FeatureCollection", "features": [ { "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string", "additionalProperty": "anything", "type": "Feature", "properties": { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything" }, "geometry": { "type": "Point", "coordinates": [ 8.528509, 47.3774434 ] }, "bbox": [ 5.9559, 45.818, 10.4921, 47.8084 ], "center": [ 8.528509, 47.3774434 ], "place_name": "string", "matching_place_name": "string", "matching_text": "string", "place_type": [ "continental_marine" ], "place_type_name": [ "string" ], "relevance": 1, "context": [ { "ref": "osm:r71525", "country_code": "fr", "kind": "road", "categories": [ "restaurant" ], "feature_tags": { "additionalProperty": "string" }, "place_designation": "city", "additionalProperty": "anything", "id": "municipality.46425", "text": "Paris", "language": "en", "^text_(\\w\\w)": "string", "^language_(\\w\\w)": "string" } ], "address": "string", "^place_name_(\\w\\w)": "string" } ], "query": [ "string" ], "attribution": "© MapTiler © OpenStreetMap contributors" } ] ``` JSONCopy JSONCopy Array of geocoding results where items are matching order of queries in the request. Every result is represented as FeatureCollection where every item is represented as a GeoJSON Feature ![](https://docs.maptiler.com/assets/img/open-api.png) Using the OpenAPI Specification? Get the [openapi.yaml](https://docs.maptiler.com/_data/cloud/api/openapi.yml)