Source: https://developers.woosmap.com/api-reference/localities-api/get-localities-geocode/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Geocode a locality or Reverse Geocode a latlng # Geocode a locality or Reverse Geocode a latlng GET https://api.woosmap.com/localities/geocode Provides details for an address or a geographic position. Either parameter `address` **or** `latlng` is required. ### 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 [`address`](#query-address) string The input string to geocode. Can represent an address, a street, a locality or a postal code. The `address` parameter must be URL encoded. To protect against illegitimate requests, only the 20 first tokens found in the first 150 characters will be used. Example:`224%20Rue%20de%20Rivoli%2C%20Paris` [`latlng`](#query-latlng) string The latlng parameter is used for reverse geocoding, it’s required if the `address` parameter is missing. Example:`5.2,-2.3` [`types`](#query-types) stringDefaults to `locality|postal_code|address` When executing a geocode request with the `address` parameter, it 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. This parameter is ignored when used with the `latlng` parameter. # 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|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` [`list_sub_buildings`](#query-list-sub-buildings) boolean When latlng parameter is used for reverse geocoding, setting `list_sub_building=true` allows to retrieve all addresses at the same location for a common street number or building. Results may contain an additional key "sub\_buildings" with "public\_id" and "description" values for every addresses at the same location sharing the same address components. Example:`true` [`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` [`fields`](#query-fields) string If set, it will limit the content of responses to the specified fields. This parameter can be any combination of `geometry`, `address_components` or `shape` (defaults to `geometry|address_components`). Available options:`geometry` Example:`geometry` [`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` [`cc_format`](#query-cc-format) string To specify the format for the short [country code](https://en.wikipedia.org/wiki/ISO_3166-1) expected to be returned in the address\_components field. Default is the format used to specify `components` or `alpha2` if no components are specified. Available options:`alpha2`, `alpha3` Example:`alpha2` ### Response 200application/json Request Localities Geocode successful [`results`](#resp-200-results) object[] #Show 10 propertiesHide 10 properties results.[`formatted_address`](#resp-200-results-formatted-address) string Contains the readable text description of the result. Example:`London, England, United Kingdom` results.[`types`](#resp-200-results-types) string[] An array containing the types of the result results.[`administrative_area_label`](#resp-200-results-administrative-area-label) string Only available for `admin_level` suggestions, this contains the local english name of the administration level ("department" for France or "federal\_state" for Germany). Example:`district` results.[`public_id`](#resp-200-results-public-id) string Contains a unique ID for each suggestion. Please use this ID to give feedbacks on results. Example:`MkvnYy6K6oVGqeqfWJGO/6eCgqo=` results.[`geometry`](#resp-200-results-geometry) object The location of the result, in latitude and longitude. Accuracy is also provided. Example: ```json { "location": { "lat": 48.829405, "lng": 2.367944 }, "location_type": "GEOMETRIC_CENTER" } ``` Show 4 propertiesHide 4 properties results.geometry.[`location_type`](#resp-200-results-geometry-location-type) string Specifies additional data about the geocoded location. The following values are currently supported: - `ROOFTOP` result is a precise geocode for which we have location information accurate down to street address precision. - `RANGE_INTERPOLATED` result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address. - `GEOMETRIC_CENTER` result is the geometric center of a result such as a polyline (for example, a street) or polygon (city, region, …). - `APPROXIMATE` result is approximate (usually when no other above value applies) - `POSTAL_CODE` Address has inherited from the location of the postal code it is part of (for NYB addresses) - `DISTRICT` Address has inherited from the location of the district it is part of (for NYB addresses) Show 6 enum values Hide 6 enum values `ROOFTOP` `RANGE_INTERPOLATED` `GEOMETRIC_CENTER` `APPROXIMATE` `POSTAL_CODE` `DISTRICT` results.geometry.[`location`](#resp-200-results-geometry-location) object An object describing a specific location with Latitude and Longitude in decimal degrees. Example: ```json { "lat": 43.3, "lng": 3.46 } ``` Show 2 propertiesHide 2 properties results.geometry.location.[`lat`](#resp-200-results-geometry-location-lat) numberrequired Latitude in decimal degrees Example:`42.3` results.geometry.location.[`lng`](#resp-200-results-geometry-location-lng) numberrequired Longitude in decimal degrees Example:`3.46` results.geometry.[`viewport`](#resp-200-results-geometry-viewport) object A rectangle in geographical coordinates from points at the southwest and northeast corners. Example: ```json { "northeast": { "lat": 49.315678, "lng": 4.15292 }, "southwest": { "lat": 49.31073, "lng": 4.145162 } } ``` Show 2 propertiesHide 2 properties results.geometry.viewport.[`northeast`](#resp-200-results-geometry-viewport-northeast) object An object describing a specific location with Latitude and Longitude in decimal degrees. Example: ```json { "lat": 43.3, "lng": 3.46 } ``` Show 2 propertiesHide 2 properties results.geometry.viewport.northeast.[`lat`](#resp-200-results-geometry-viewport-northeast-lat) numberrequired Latitude in decimal degrees Example:`42.3` results.geometry.viewport.northeast.[`lng`](#resp-200-results-geometry-viewport-northeast-lng) numberrequired Longitude in decimal degrees Example:`3.46` results.geometry.viewport.[`southwest`](#resp-200-results-geometry-viewport-southwest) object An object describing a specific location with Latitude and Longitude in decimal degrees. Example: ```json { "lat": 43.3, "lng": 3.46 } ``` Show 2 propertiesHide 2 properties results.geometry.viewport.southwest.[`lat`](#resp-200-results-geometry-viewport-southwest-lat) numberrequired Latitude in decimal degrees Example:`42.3` results.geometry.viewport.southwest.[`lng`](#resp-200-results-geometry-viewport-southwest-lng) numberrequired Longitude in decimal degrees Example:`3.46` results.geometry.[`shape`](#resp-200-results-geometry-shape) object A GeoJSon Geometry representing the shape of the area, as specified in [RFC7946](https://datatracker.ietf.org/doc/html/rfc7946). To display on the map, simply wrap this object in a feature: ``` { "type": "Feature", "geometry": this_geojson_geometry } ``` Example: ```json { "type": "Polygon", "coordinates": [ [ [ 2.06984, 48.77919 ], [ 2.07984, 48.77919 ], [ 2.07984, 48.78919 ], [ 2.06984, 48.78919 ], [ 2.06984, 48.77919 ] ] ] } ``` Show 2 propertiesHide 2 properties results.geometry.shape.[`type`](#resp-200-results-geometry-shape-type) string the geometry type Available options:`Polygon`, `MultiPoligon` results.geometry.shape.[`coordinates`](#resp-200-results-geometry-shape-coordinates) array[] results.[`status`](#resp-200-results-status) string This optional field is only available for UK addresses referenced as not yey built by Royal Mail. Only one value yet. Available options:`not_yet_built` results.[`address_components`](#resp-200-results-address-components) object[] An array containing Address Components with additional information Example: ```json [ { "types": [ "country" ], "long_name": "United Kingdom", "short_name": "GBR" }, { "long_name": "London", "short_name": "London", "types": [ "locality" ] } ] ``` Show 3 propertiesHide 3 properties results.address\_components.[`long_name`](#resp-200-results-address-components-long-name) string | array The full text description or name of the address component, or a list of names (ie. list of postal codes). Example:`United Kingdom` results.address\_components.[`short_name`](#resp-200-results-address-components-short-name) string | array An abbreviated textual name for the address component, if available. For example, an address component for the state of United Kingdom may have a `long_name` of `United Kingdom` and a `short_name` of `UK` using the 2-letter postal abbreviation. Example:`UK` results.address\_components.[`types`](#resp-200-results-address-components-types) string[] An array indicating the type of the address component. Example: ```json [ "country", "administrative_area_level_0" ] ``` results.[`distance`](#resp-200-results-distance) number When reverse geocoding, this field represents the distance (in meter) to the requested latlng Example:`5.234` results.[`sub_buildings`](#resp-200-results-sub-buildings) object[] When reverse geocoding with `list_sub_buildings=true`, this field will contain a list of precise addresses that can be found at that location, i.e. all flats within a building. Show 2 propertiesHide 2 properties results.sub\_buildings.[`public_id`](#resp-200-results-sub-buildings-public-id) stringrequired The public\_id of the address can be used to gather details on that specific address Example:`Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9faitia1pNNURnOWYvQmRjMUdweXl5SjdLZUZnPQ==` results.sub\_buildings.[`description`](#resp-200-results-sub-buildings-description) stringrequired A human readable description of the address Example:`Flat 1, Radway House, Alfred Road, London, W2 5ER` results.[`scores_per_components`](#resp-200-results-scores-per-components) object For each component (street\_name, postal\_code, and locality), it indicates the degree of correspondence with the original query. This value ranges from 0 to 1, with 0 indicating no match with the original query, and enables you to assess the quality of the Geocode’s result. Example: ```json { "scores_per_components": { "street_name": 0.6153846153846154, "postal_code": 0.8, "locality": 1 } } ``` Show 3 propertiesHide 3 properties results.scores\_per\_components.[`street_name`](#resp-200-results-scores-per-components-street-name) number Street score results.scores\_per\_components.[`postal_code`](#resp-200-results-scores-per-components-postal-code) number Postal code score results.scores\_per\_components.[`locality`](#resp-200-results-scores-per-components-locality) number Postal code score ### 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/geocode?address=Place%20Jeanne-d%27Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY' \ -H 'Referer: http://localhost' ``` ```javascript const requestOptions = { method: "GET", redirect: "follow" }; fetch("https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&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/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY" payload = {} headers = { 'Referer': 'http://localhost' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ``` ```json-200-geocode { "results": [ { "public_id": "0+FTYd/1MsiBSxLAKq+/Fiyy+uM=", "types": [ "address", "route" ], "formatted_address": "Place Jeanne D'Arc, 75013, Paris", "address_components": [ { "types": [ "country", "administrative_area_level_0", "division_level_0" ], "long_name": "France", "short_name": "FR" }, { "types": [ "state", "division_level_1" ], "long_name": "Île-de-France", "short_name": "Île-de-France" }, { "types": [ "administrative_area_level_1", "county", "division_level_2" ], "long_name": "Paris", "short_name": "Paris" }, { "types": [ "locality" ], "long_name": "Paris", "short_name": "Paris" }, { "types": [ "postal_codes" ], "long_name": "75013", "short_name": "75013" }, { "types": [ "route" ], "long_name": "Place Jeanne D'Arc", "short_name": "Place Jeanne D'Arc" } ], "geometry": { "location": { "lat": 48.829405, "lng": 2.367944 }, "location_type": "GEOMETRIC_CENTER" }, "scores_per_components": { "street_name": 1 } } ] } ``` ```json-200-reverse { "results": [ { "public_id": "", "types": [ "address" ], "formatted_address": "Radway House, Alfred Road, London, W2 5ER", "address_components": [ { "types": [ "country", "administrative_area_level_0", "division_level_0" ], "long_name": "United Kingdom", "short_name": "GB" }, { "types": [ "state", "division_level_1" ], "long_name": "England", "short_name": "England" }, { "types": [ "administrative_area_level_1", "county", "division_level_2" ], "long_name": "City of London", "short_name": "City of London" }, { "types": [ "district", "division_level_3" ], "long_name": "Westminster", "short_name": "Westminster" }, { "types": [ "locality" ], "long_name": "London", "short_name": "London" }, { "types": [ "postal_codes" ], "long_name": "W2 5ER", "short_name": "W2 5ER" }, { "types": [ "route" ], "long_name": "Alfred Road", "short_name": "Alfred Road" }, { "types": [ "premise" ], "long_name": "Radway House", "short_name": "Radway House" } ], "geometry": { "location": { "lat": 51.5211258, "lng": -0.1956346 }, "location_type": "ROOFTOP" }, "distance": 28.62347934634507, "sub_buildings": [ { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9faitia1pNNURnOWYvQmRjMUdweXl5SjdLZUZnPQ==", "description": "Flat 1, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fbTRoZVpxYkhBYVVXSytqek04UGtGQ1VLTVI0PQ==", "description": "Flat 2, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fcmY1MHV6aE5kVytLWWZLV3JabzFzR2lnbThzPQ==", "description": "Flat 3, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fajlaWXJJUDFKSmI1Y0dpNElDanBQejF2YUg4PQ==", "description": "Flat 4, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fbkdEZTNOODZNL0VlWGtoR0pSa2tBS1NMYndVPQ==", "description": "Flat 5, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fTGxlWUlKN2NhU1JXcTBuSEs1RExiamliNlpNPQ==", "description": "Flat 6, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9feVZXa05ISjhzVGNHK2NQUHFpNlFIUWgvSnpJPQ==", "description": "Flat 7, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fTVc5NldSeWpuOENUS2xST21vZzdnNGxGQldrPQ==", "description": "Flat 8, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fN3RkdE9HeHBwT2M5R1hQMUFwNDJUc3NwRklZPQ==", "description": "Flat 9, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fR2RVRHpoYll4a2RlTldjLzF3NVNFTXNZYzlFPQ==", "description": "Flat 10, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fL3FXbnVZU2h4bjAwMDNKK3hJeU9OL3lnemFzPQ==", "description": "Flat 11, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fVVVCUWhpNVJQWWk2eTl1WFBTVTRmK3Zma3VBPQ==", "description": "Flat 12, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fV2hSUDNadnFMN3ZzaWJ6UFd2MWM3aW1qT3hBPQ==", "description": "Flat 13, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fcWxGbFRlcE1TVStZVElodzFSdVhiTGxZTXl3PQ==", "description": "Flat 14, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fYjR5VHRXMmZTQ0FOMGwwZHJNaFh5TFRnVHlnPQ==", "description": "Flat 15, Radway House, Alfred Road, London, W2 5ER" }, { "public_id": "Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9fNmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PQ==", "description": "Flat 16, Radway House, Alfred Road, London, W2 5ER" } ] } ] } ``` ```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" } ```