--- title: "Geocoding API" description: "Documentation for forward and reverse geocoding on MapTiler Server." --- > 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. # Geocoding API [On-prem geocoding](https://docs.maptiler.com/guides/on-prem/server/geocoding/) makes it possible to add place search to your self-hosted maps. It includes both forward geocoding (search by place name) and reverse geocoding (search by coordinates). ## 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) v4.9.0 OpenAPI 3.1.0 # MapTiler Server API [Support](mailto:support@maptiler.com) [](https://support.maptiler.com) [MapTiler Server License Agreement](https://www.maptiler.com/server/license/) [Terms of Service](https://www.maptiler.com/server/license/) Server Server:http://{host}/api host MapTiler Server API Client Libraries Shell Ruby Node.js PHP Python MoreSelect from all clients Shell Curl ## Geocoding ​Copy link Search for places by name, coordinates or feature ID. 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 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\] 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\] - languageCopy link to language Type: array string\[\] …20 unique!enum 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"\] Limit search to specific country/countries. - limitCopy link to limit Type: integer min:   1 max:   10 Default 5 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](#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 Default true Set to `true` to use autocomplete, `false` to disable autocomplete. - worldviewCopy link to worldview Type: string enum Default default 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 Request Example for get/geocoding/_{query}_.json Shell Curl ```curl curl http://localhost:3650/api/geocoding/Zurich.json ``` Copy Copy Status: 200Status: 400 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 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"\] 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 Default 5 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](#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 Default default 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 Request Example for get/geocoding/_{longitude}_,_{latitude}_.json Shell Curl ```curl curl http://localhost:3650/api/geocoding/8.528509,47.3774434.json ``` Copy Copy Status: 200Status: 400 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 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"\] 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 Default default 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 Request Example for get/geocoding/_{id}_.json Shell Curl ```curl curl http://localhost:3650/api/geocoding/country.26561650.json ``` Copy Copy Status: 200Status: 400 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 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\] 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\] - languageCopy link to language Type: array string\[\] …20 unique!enum 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"\] Limit search to specific country/countries. - limitCopy link to limit Type: integer min:   1 max:   10 Default 5 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](#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 Default true Set to `true` to use autocomplete, `false` to disable autocomplete. - worldviewCopy link to worldview Type: string enum Default default 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 Request Example for get/geocoding/_{queries}_.json Shell Curl ```curl curl 'http://localhost:3650/api/geocoding/Paris;Berlin.json' ``` Copy Copy Status: 200Status: 400 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/server/api/openapi.yml)