Source: https://developers.woosmap.com/api-reference/localities-api/get-localities-autocomplete/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Autocomplete for Localities # Autocomplete for Localities GET https://api.woosmap.com/localities/autocomplete Autocomplete on worldwide suggestions for a for text-based geographic searches. It can match on full words as well as substrings. You can therefore send queries as the user types, to provide on-the-fly addresses, city names, postal codes or suburb name suggestions. ### Authorization [`key`](#authorization-woosmap-platform-api-reference-publicapikeyauth) apiKeyquery A Public key generated specifically to authenticate API requests on the front side. See how to [register a Public API Key](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-public-api-key). [`Referer`](#authorization-woosmap-platform-api-reference-refererheader) apiKeyheader The Referer HTTP request header is mandatory when using PublicApiKeyAuth. In browser environment, the Referer is set by the browser itself and cannot be overridden. [`private_key`](#authorization-woosmap-platform-api-reference-privateapikeyauth) apiKeyquery A Private key generated specifically to authenticate API requests on server side. Required for Data management API. See how to [register a Private API Key](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-private-api-key). [`X-Api-Key`](#authorization-woosmap-platform-api-reference-privateapikeyheaderauth) apiKeyheader A Private key to authenticate API requests through the Header instead of Query parameter. Use either PrivateApiKeyHeaderAuth or PrivateApiKeyAuth. See how to [register a Private API Key](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-private-api-key). ### Query Parameters [`input`](#query-input) stringrequired The text string on which to search, for example: "london" or "123 Cross Road". The Woosmap Localities API will return predictions matches based on this string and order the results based on their perceived relevance. To protect against illegitimate requests, only the 20 first tokens found in the first 150 characters will be used. Example:`London` [`types`](#query-types) stringDefaults to `locality|postal_code` Specifies the types of suggestions to return in the query. Multiple types can be combined using the pipe character (`|`) as a separator. This parameter supports a wide range of locality classifications, including: - Standard locality types (e.g., cities, administrative areas, postal codes) - Points of Interest (POI) categories - POI aliases These classifications enable flexible geographic data representation and querying. # Show 3 variants Hide 3 variants LocalitiesTypesstring Common types unrelated to points of interest (POI). The `locality` type serves as an alias grouping various settlement types (see `enum` for details). This grouping enables flexible and efficient querying of related geographic data. Show 14 enum values Hide 14 enum values `country` `admin_level` `postal_code` `address` `route` `locality` `city` `town` `village` `hamlet` `borough` `suburb` `quarter` `neighbourhood` * * * LocalitiesTypesPoistring Categories of points of interest (POI) supported for detailed classification in geographic data queries. Show 72 enum values Hide 72 enum values `point_of_interest` `transit.station` `transit.station.airport` `transit.station.rail` `beach` `business` `business.car_repair` `business.car_rental` `business.cinema` `business.conference_centre` `business.exhibition_centre` `business.theatre` `business.nightclub` `business.finance` `business.finance.bank` `business.fuel` `business.parking` `business.mall` `business.food_and_drinks` `business.food_and_drinks.bar` `business.food_and_drinks.biergarten` `business.food_and_drinks.cafe` `business.food_and_drinks.fast_food` `business.food_and_drinks.pub` `business.food_and_drinks.restaurant` `business.food_and_drinks.food_court` `business.shop` `business.shop.mall` `business.shop.bakery` `business.shop.butcher` `business.shop.library` `business.shop.grocery` `business.shop.sports` `business.shop.toys` `business.shop.clothes` `business.shop.furniture` `business.shop.electronics` `business.shop.doityourself` `business.shop.craft` `education` `education.school` `education.kindergarten` `education.university` `education.college` `education.library` `hospitality` `hospitality.hotel` `hospitality.hostel` `hospitality.guest_house` `hospitality.bed_and_breakfast` `hospitality.motel` `medical` `medical.hospital` `medical.pharmacy` `medical.clinic` `tourism` `tourism.attraction` `tourism.attraction.amusement_park` `tourism.attraction.zoo` `tourism.attraction.aquarium` `tourism.monument` `tourism.monument.castle` `tourism.museum` `government` `park` `park.national` `place_of_worship` `police` `post_office` `sports` `sports.golf` `sports.winter` * * * LocalitiesTypesPoiAliasstring Aliases for some point\_of\_interest types. These aliases are deprecated and should be replaced with the corresponding types in `LocalitiesTypesPoi`. For example: - `airport` → `transit.station.airport` - `train_station` → `transit.station.rail.train` This ensures consistency and alignment with the updated schema. Show 9 enum values Hide 9 enum values `airport` `train_station` `metro_station` `shopping` `museum` `zoo` `amusement_park` `art_gallery` `tourist_attraction` Example:`locality|airport|admin_level` [`excluded_types`](#query-excluded-types) string The types of suggestion to exclude. Multiple types can be passed using the pipe character (`|`) as a separator. Example:`suburb|quarter|neighbourhood` [`components`](#query-components) string A grouping of places to which you would like to restrict your results. Components can and should be used when applicable to filter over countries and retrieve more accurate results. Countries must be passed as an ISO 3166-1 Alpha-2 or Alpha-3 compatible country code. For example: `components=country:fr` or `components=country:fra` would restrict your results to places within France and `components=country:fr-fr` returns locations only in Metropolitan France. Multiple countries must be passed as multiple `country:XX` filters, with the pipe character (`|`) as a separator. For example: `components=country:gb|country:fr|country:be|country:sp|country:it` would restrict your results to city names or postal codes within the United Kingdom, France, Belgium, Spain and Italy. Example:`country:fr|country:es` [`language`](#query-language) string The language code, using ISO 639-2 Alpha-2 country codes, indicating in which language the results should be returned, if possible. If language is not supplied, first `Accept-Language` of the browser will be used. If neither the provided `language` or the `Accept-Language` are known, the Localities service uses the international default language (English). No `language` is necessary for a postal\_code request. According to requested language, only parts of the address components might be translated. Example:`en` [`location`](#query-location) string This parameter is used to add a geographical bias to the query. The location defines the point around which to retrieve results in priority. It must be specified in the `latitude,longitude` string format. Example:`5.2,-2.3` [`radius`](#query-radius) integer This parameter may be used in addition to the `location` parameter to define the distance in meters within which the API will return results in priority. Results outside of the defined area may still be displayed. Default radius if this parameter is not set is 100 000. Example:`200000` [`data`](#query-data) string Two values for this parameter: `standard` or `advanced`. By default, if the parameter is not defined, value is set as `standard`. The `advanced` value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. _ **A dedicated option subject to specific billing on your license is needed to use this parameter. Please contact us if you are interested in using this parameter and you do not have subscribed the proper option yet.** _ Available options:`standard`, `advanced` Example:`advanced` [`extended`](#query-extended) string If set, this parameter allows a refined search over locality names that bears the same postal code. By triggering this parameter, integrators will benefit from a search spectrum on the `locality` type that _ **includes postal codes** _. To avoid confusion, it is recommended not to activate this parameter along with the `postal_code` type which could lead to duplicate locations. Also, the default description returned by the API changes to `name (postal code), admin_1, admin_0`. It is only available for France, Monaco, Italy, Spain, Belgium, Switzerland and Luxembourg. Available options:`postal_code` Example:`postal_code` [`custom_description`](#query-custom-description) string This parameter allows to choose the description format for all or some of the suggestion types selected. The custom formats are described as follows (available fields depend on the returned type): `custom_description=type_A:"{field_1}, {field_2}, [...]"|type_B:"{field_1}, {field_2}, [...]"` Example:`locality:"{name} - {administrative_area_level_0}"|postal_code:"{name} ({administrative_area_level_1})"` ### Response 200application/json Autocompletion Localities successfully retrieved [`localities`](#resp-200-localities) object[] #Show 7 propertiesHide 7 properties localities.[`public_id`](#resp-200-localities-public-id) string Contains a unique ID for each suggestion. Please use this ID if you need to give us feedbacks on results. This ID is also required to perform Localities Details request. Example:`MkvnYy6K6oVGqeqfWJGO/6eCgqo=` localities.[`types`](#resp-200-localities-types) string[] An array containing the types of the result localities.[`type`](#resp-200-localities-type) stringdeprecated this field might be removed in the future, please use the `types` field which is more exhaustive localities.[`description`](#resp-200-localities-description) string Concatenation of `name`, `admin_1`, `admin_0` to be used as suggestion in drop down list if needed. The description can vary depending on the type requested. Example:`20121, Milano, Italy` localities.[`matched_substrings`](#resp-200-localities-matched-substrings) object Contains a set of substrings in the `description` field that match elements in the `input`. It can be used to highlight those substrings. Each substring is identified by an `offset` and a `length`.` Show 1 propertiesHide 1 properties localities.matched\_substrings.[`description`](#resp-200-localities-matched-substrings-description) object[] match substrings for localities `description` Show 2 propertiesHide 2 properties localities.matched\_substrings.description.[`length`](#resp-200-localities-matched-substrings-description-length) number Length of the matched substring in the prediction result text. localities.matched\_substrings.description.[`offset`](#resp-200-localities-matched-substrings-description-offset) number Start location of the matched substring in the prediction result text. localities.[`related`](#resp-200-localities-related) object Contains a set of related elements to the locality suggestion. Show 1 propertiesHide 1 properties localities.related.[`postal_codes`](#resp-200-localities-related-postal-codes) object[] Postal codes related to the locality suggestion. Show 2 propertiesHide 2 properties localities.related.postal\_codes.[`public_id`](#resp-200-localities-related-postal-codes-public-id) string Public ID of a related Postal Code. localities.related.postal\_codes.[`description`](#resp-200-localities-related-postal-codes-description) string Formatted description for the related Postal Code. localities.[`has_addresses`](#resp-200-localities-has-addresses) boolean On the specific territory of United Kingdom, Localities autocomplete request can return the additional attribute `has_addresses` for a postal code, which indicates if a postal code bears addresses. When `has_addresses` is `true`, it is possible to display a list of the available addresses by requesting `details` with the Localities `public_id`. To get the details of an address you will need to request again `/details` endpoint passing in the dedicated address `public_id`. Example:`true` ### Errors #401 Unauthorized. Incorrect authentication credentials. `application/json` [`detail`](#err-401-detail) string Details for the credentials error Example:`Incorrect authentication credentials. Please check or use a valid API Key` #403 Forbidden. This Woosmap API is not enabled for this project. `application/json` [`detail`](#err-403-detail) string Details for the forbidden error message Example:`This Woosmap API is not enabled for this project.` #429 Too Many Requests. The rate limit for this endpoint has been exceeded. `application/json` [`detail`](#err-429-detail) string Details for the Over Query Limit error message Example:`The rate limit for this endpoint has been exceeded` ```shell curl -L 'https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY' \ -H 'Referer: http://localhost' ``` ```javascript const requestOptions = { method: "GET", redirect: "follow" }; fetch("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY", requestOptions) .then((response) => response.text()) .then((result) => console.log(result)) .catch((error) => console.error(error)); ``` ```python import requests url = "https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY" payload = {} headers = { 'Referer': 'http://localhost' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` ```json { "localities": [ { "public_id": "Ch6qA8cLmvyvEEoFy6nYeFcEdNU=", "type": "locality", "types": [ "locality", "city" ], "description": "London, City of London, United Kingdom", "matched_substrings": { "description": [ { "offset": 0, "length": 4 } ] } }, { "public_id": "m/T2C4YI2LgszkKXrELBC+9dfC8=", "type": "locality", "types": [ "locality", "city" ], "description": "Derry/Londonderry, Derry City and Strabane, United Kingdom", "matched_substrings": { "description": [ { "offset": 6, "length": 4 } ] } }, { "public_id": "J6eISGMjjvQwPkao8rsByB3aVwM=", "type": "locality", "types": [ "locality", "village" ], "description": "London Colney, Hertfordshire, United Kingdom", "matched_substrings": { "description": [ { "offset": 0, "length": 4 } ] } }, { "public_id": "52MnrbHVWH21CLWH8VY/YWKhqeM=", "type": "locality", "types": [ "locality", "village" ], "description": "London Apprentice, Cornwall, United Kingdom", "matched_substrings": { "description": [ { "offset": 0, "length": 4 } ] } }, { "public_id": "S/5AkUmMBhX35qVI2jR38+dALwk=", "type": "locality", "types": [ "locality", "city" ], "description": "City of London, United Kingdom", "matched_substrings": { "description": [ { "offset": 8, "length": 4 } ] } } ] } ``` ```json { "detail": "Incorrect authentication credentials. Please check or use a valid API Key" } ``` ```json { "detail": "This Woosmap API is not enabled for this project." } ``` ```json { "detail": "The rate limit for this endpoint has been exceeded" } ```