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 # Autocomplete GET https://api.woosmap.com/localities/autocomplete Returns worldwide place suggestions for a text query, matching on whole words or substrings. Designed for as-you-type input: addresses, cities, postal codes, suburbs, and more. **Ratelimit:** 50/1s ### Authorization [`key`](#authorization-localities-publicapikey) apiKeyquery Public key of the project usually starts with `woos-` [`private_key`](#authorization-localities-privateapikey) apiKeyquery Private key with or without write permission. [`X-Api-Key`](#authorization-localities-privateapikeyheader) apiKeyheader Private key with or without write permission. ### Header Parameters [`accept-language`](#header-accept-language) string ### Query Parameters [`language`](#query-language) stringDefaults to `""` Language code (ISO 639-1, two letters) for the response. Resolution order: 1. `language` (this parameter) 2. The request's `Accept-Language` header 3. locale default 4. English (when neither is recognised) Only part of the address components are translated; not required for postal-code requests. Example:`en` [`data`](#query-data) stringDefaults to `standard` Selects the postal-code dataset. `advanced` extends the default Western-Europe coverage to worldwide postal codes. _ **Requires a dedicated license option subject to specific billing — please contact us.** _ Available options:`advanced`, `standard` Example:`advanced` [`components`](#query-components) string Restricts results to one or more countries. Pass each country as a `country:` filter. Use `|` to provide multiple values. Example:`country:gb` [`types`](#query-types) LocalitiesTypes | LocalitiesTypesPoi | LocalitiesTypesPoiAliasDefaults to `locality|postal_code` Restricts results to one or more types. Use `|` to provide multiple values. # Show 3 variants Hide 3 variants LocalitiesTypesstring Show 17 enum values Hide 17 enum values `country` `admin_level` `admin_level_1` `admin_level_2` `admin_level_3` `postal_code` `address` `route` `locality` `city` `town` `village` `hamlet` `borough` `suburb` `quarter` `neighbourhood` * * * LocalitiesTypesPoistring Show 80 enum values Hide 80 enum values `point_of_interest` `beach` `government` `park` `park.national` `place_of_worship` `police` `post_office` `sports` `sports.golf` `sports.winter` `transit` `transit.station` `transit.station.airport` `transit.station.rail` `transit.station.rail.subway` `transit.station.rail.train` `transit.station.rail.light_rail` `transit.station.rail.monorail` `transit.station.rail.funicular` `transit.station.rail.tram` `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.art_gallery` `tourism.attraction` `tourism.attraction.amusement_park` `tourism.attraction.zoo` `tourism.attraction.aquarium` `tourism.monument` `tourism.monument.castle` `tourism.museum` * * * LocalitiesTypesPoiAliasstring Show 9 enum values Hide 9 enum values `airport` `train_station` `metro_station` `shopping` `museum` `zoo` `amusement_park` `art_gallery` `tourist_attraction` Example:`address` [`excluded_types`](#query-excluded-types) LocalitiesTypes | LocalitiesTypesPoi | LocalitiesTypesPoiAlias Restricts results by excluding one or more types. Use `|` to provide multiple values. # Show 3 variants Hide 3 variants LocalitiesTypesstring Show 17 enum values Hide 17 enum values `country` `admin_level` `admin_level_1` `admin_level_2` `admin_level_3` `postal_code` `address` `route` `locality` `city` `town` `village` `hamlet` `borough` `suburb` `quarter` `neighbourhood` * * * LocalitiesTypesPoistring Show 80 enum values Hide 80 enum values `point_of_interest` `beach` `government` `park` `park.national` `place_of_worship` `police` `post_office` `sports` `sports.golf` `sports.winter` `transit` `transit.station` `transit.station.airport` `transit.station.rail` `transit.station.rail.subway` `transit.station.rail.train` `transit.station.rail.light_rail` `transit.station.rail.monorail` `transit.station.rail.funicular` `transit.station.rail.tram` `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.art_gallery` `tourism.attraction` `tourism.attraction.amusement_park` `tourism.attraction.zoo` `tourism.attraction.aquarium` `tourism.monument` `tourism.monument.castle` `tourism.museum` * * * LocalitiesTypesPoiAliasstring Show 9 enum values Hide 9 enum values `airport` `train_station` `metro_station` `shopping` `museum` `zoo` `amusement_park` `art_gallery` `tourist_attraction` Example:`suburb|quarter|neighbourhood` [`input`](#query-input) stringrequired Text to search for. Predictions are matched on this string and ordered by relevance. Only the first 20 tokens (within 150 characters) are processed. Example:`London` [`custom_description`](#query-custom-description) string Overrides the suggestion description format per type. Available fields depend on the type. Use `|` to provide multiple values. Example:`locality:"{name} - {administrative_area_level_0}"|postal_code:"{name} ({administrative_area_level_1})"` [`extended`](#query-extended) string Allows a refined search over locality names sharing the same leading postal\_code. Suggestion descriptions switch to `name (postal code), admin_1, admin_0`. Avoid combining with the `postal_code` type to prevent duplicate locations. Supported countries: France, Monaco, Italy, Spain, Belgium, Switzerland, Luxembourg. Example:`postal_code` [`location`](#query-location) string Biases results toward a point, specified as `latitude,longitude`. Pair with `radius`. Example:`52.479699,-1.902691` [`radius`](#query-radius) integerDefaults to `100000` Radius in meters around `location` to prioritise results. Results outside this radius may still appear. Example:`200000` ### Response 200application/json Successful Response [`localities`](#resp-200-localities) object[]required #Show 7 propertiesHide 7 properties localities.[`public_id`](#resp-200-localities-public-id) stringrequired Unique identifier for this place. Pass it to the `/details` endpoint to retrieve the full record. localities.[`type`](#resp-200-localities-type) stringrequireddeprecated This field might be removed in the future, please use the `types` field which is more exhaustive. localities.[`types`](#resp-200-localities-types) string[]required An array containing the types of the result localities.[`description`](#resp-200-localities-description) stringrequired 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. localities.[`matched_substrings`](#resp-200-localities-matched-substrings) object | null 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[]required Substrings of `description` that match the `input`, each given as an `offset` and `length`. Show 2 propertiesHide 2 properties localities.matched\_substrings.description.[`offset`](#resp-200-localities-matched-substrings-description-offset) integerrequired localities.matched\_substrings.description.[`length`](#resp-200-localities-matched-substrings-description-length) integerrequired localities.[`has_addresses`](#resp-200-localities-has-addresses) boolean | null Indicates whether a postal code has addresses you can drill into. Returned for postal codes in some territories (e.g. United Kingdom, Ireland). When `true`, call `/details` with this suggestion's `public_id` will list the addresses; each address carries its own `public_id` for a further `/details` lookup. localities.[`related`](#resp-200-localities-related) object | null 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[]required 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) stringrequired localities.related.postal\_codes.[`description`](#resp-200-localities-related-postal-codes-description) stringrequired ### Errors #401 Unable to locate credentials. `application/json` [`detail`](#err-401-detail) stringrequired #402 Out of free quota. `application/json` [`detail`](#err-402-detail) stringrequired #403 Credentials found, but not matching. `application/json` [`detail`](#err-403-detail) stringrequired #422 Validation Error `application/json` [`detail`](#err-422-detail) object[] Show 5 propertiesHide 5 properties detail.[`loc`](#err-422-detail-loc) any[]required detail.[`msg`](#err-422-detail-msg) stringrequired detail.[`type`](#err-422-detail-type) stringrequired detail.[`input`](#err-422-detail-input) any detail.[`ctx`](#err-422-detail-ctx) object #429 Rate limit reached `application/json` [`detail`](#err-429-detail) stringrequired ```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 } ] } } ] } ```