--- title: "Search by name (forward)" method: GET path: "/geocoding/{query}.json" tags: ["Geocoding"] --- # Search by name (forward) `GET /geocoding/{query}.json` ## Request - Base URL: `https://api.maptiler.com` - URL: `https://api.maptiler.com/geocoding/{query}.json` - Auth: API key in query parameter `key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Forward geocoding (search by place name). ## Response `200` Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature - Result: Search result represented by FeatureCollection where every item is represented as a GeoJSON Feature - `type` 'FeatureCollection', required - `features` object[], required: Array of features found - `id` string, required: Unique feature ID - `text` string, required: Localized feature name - `language` string: Query's primary ISO 639-1 language code - `type` 'Feature', required - `properties` FeatureProperties, required - `ref` string, required: (experimental) External reference of the feature used for debugging purposes. The exact format of this field may change without notice, and should not be relied on at the moment. - `country_code` string, required: ISO 3166-1 alpha-2 country code of the feature - `kind` 'road' | 'road_relation' | 'admin_area' | 'place' | 'street' | 'virtual_street': (experimental) Kind of the feature - `categories` string[]: Array of [POI category](https://docs.maptiler.com/guides/location-services/geocoding-search/poi-category/). Only available for `poi` type. Category values may change in the near future. - `feature_tags` object: (experimental) Feature tags, only available for `poi` type. They can include e.g. working hours, type of amenity or wheelchair access. - `place_designation` 'allotments' | 'borough' | 'city' | 'city_block' | 'farm' | 'hamlet' | 'isolated_dwelling' | 'neighbourhood' | 'plot' | 'quarter' | 'suburb' | 'town' | 'village': (experimental) Additional information about the feature. The main use case is to determine if the administrative area represents an inhabited place (a town, a city or a village). This field is especially useful in cases, where a large city is a region, land or prefecture from administrative point of view (typical examples are Berlin and Tokyo). Please note that this field is not always filled. - `geometry` union, required - object - `type` 'Point', required - `coordinates` unknown[], required - unknown - object - `type` 'LineString', required - `coordinates` Coordinates[], required - unknown[] - unknown - object - `type` 'Polygon', required - `coordinates` array[], required - Coordinates[] - unknown[] - … - object - `type` 'MultiPoint', required - `coordinates` Coordinates[], required - unknown[] - unknown - object - `type` 'MultiLineString', required - `coordinates` array[], required - Coordinates[] - unknown[] - … - object - `type` 'MultiPolygon', required - `coordinates` array[], required - array[] - Coordinates[] - … - object - `type` 'GeometryCollection', required - `geometries` union[], required - union - object - … - object - … - object - … - object - … - object - … - object - … - `bbox` unknown[], required - unknown - `center` unknown[], required - unknown - `place_name` string, required: Formatted (including the hierarchy) and localized feature full name - `matching_place_name` string: A string analogous to the `place_name` field that matches the query. This field is only returned to help you understand how the response aligns with the submitted query. - `matching_text` string: A string analogous to the `text` field that matches the query. This field is only returned to help you understand how the response aligns with the submitted query. - `place_type` PlaceType[], required: An array of feature types describing the feature. Currently each feature has only single type but this may change in the future. - `place_type_name` string[], required: Localized type of the place name, matches `place_type` property. - `relevance` number, required: Indicates how well the returned feature matches the user's query on a scale from 0 to 1. 0 means the result does not match the query text at all, while 1 means the result fully matches the query text. You can use the relevance property to remove results that don't fully match the query. - `context` object[]: Feature hierarchy - `ref` string, required: (experimental) External reference of the feature used for debugging purposes. The exact format of this field may change without notice, and should not be relied on at the moment. - `country_code` string, required: ISO 3166-1 alpha-2 country code of the feature - `kind` 'road' | 'road_relation' | 'admin_area' | 'place' | 'street' | 'virtual_street': (experimental) Kind of the feature - `categories` string[]: Array of [POI category](https://docs.maptiler.com/guides/location-services/geocoding-search/poi-category/). Only available for `poi` type. Category values may change in the near future. - `feature_tags` object: (experimental) Feature tags, only available for `poi` type. They can include e.g. working hours, type of amenity or wheelchair access. - `place_designation` 'allotments' | 'borough' | 'city' | 'city_block' | 'farm' | 'hamlet' | 'isolated_dwelling' | 'neighbourhood' | 'plot' | 'quarter' | 'suburb' | 'town' | 'village': (experimental) Additional information about the feature. The main use case is to determine if the administrative area represents an inhabited place (a town, a city or a village). This field is especially useful in cases, where a large city is a region, land or prefecture from administrative point of view (typical examples are Berlin and Tokyo). Please note that this field is not always filled. - `id` string, required: Unique feature ID - `text` string, required: Localized feature name - `language` string: Query's primary ISO 639-1 language code - `address` string: Address number, if applicable - `query` string[], required: Tokenized search query - `attribution` string, required: Attribution of the result ## Other responses - `400`: Query too long / Invalid parameters - `403`: Key is missing, invalid or restricted --- [API](https://skmtc.dev/maptiler/apis/maptiler-api-reference.md) - [All operations](https://skmtc.dev/maptiler/apis/maptiler-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/maptiler/apis/maptiler-api-reference/revisions/68ce3046fc1a?raw)