Geocode (Early Access)

Convert addresses into geographic coordinates and coordinates into a human readable address

  1. Overview
  2. Required Parameters
  3. Optional Parameters
  4. Response
  5. Samples
  6. Early Access

Localities Geocode is in Early Access stage. See more details on Early Access here.

Overview

Localities Geocode provides the geographical locations of addresses, postal codes or localities. For example geocoding 224 Rue de Rivoli, Paris returns the coordinates of this address and all its details. The request must include a complete or partial text string in order to retrieve geographic details about a location, such as coordinates or address components. The accuracy of the results depends on the input provided in the request. A partial address is less likely to return the proper coordinates.

Localities Reverse Geocode converts geographical coordinates into a human readable address. For example, reverse geocoding 48.879017,2.331382 returns the corresponding address 19 Rue Blanche, 75009, Paris.

Geocoding addresses and postal_code may be subject to specific product activation. Please see coverage page for more details.

Required Parameters

All parameters are separated using the ampersand (&) character. Only your Woosmap API key and the address field are mandatory to use the geocode endpoint.

https://api.woosmap.com/localities/geocode?key={PUBLIC_API_KEY}&address={TEXT_INPUT}

key

Your project’s API key. This key identifies your Woosmap Project for purposes of security and quota management. Public keys are designed to be used client-side, where every request contains a referer. Alternatively, you can use the private_key parameter for server-side requests.

Reminder: To use the Localities API, your Public API key (key parameter) has to be authorized for the domains and/or IPs (referer) from which you make the call. More on securing API keys here.

You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.

private_key

Your project’s private API key. This key identifies your Woosmap Project for purposes of security and quota management. Private keys are designed to be used server-side, where no referer checkings are performed.

You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.

address (geocoding only)

The input string to geocode. Can represent an address, a street, a locality or a postal code. The address parameter must be URL encoded.

OR

latlng (reverse geocoding only)

The latlng parameter is used for reverse geocoding, it’s required if the address parameter is missing.

Optional Parameters

language

The language code, indicating in which language the results should be returned, when available. If language is not specified, the Localities Geocode endpoint will use the default language of each country.

components

A grouping of places to which you would like to restrict your results. Components can be used to filter over countries. 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. 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 results within the United Kingdom, France, Belgium, Spain and Italy.

To restrict the search to metropolitain France, the components country:fr-fr can be used.

cc_format

To specify the country code format returned in the response. Possible values are alpha2 and alpha3. Default is the format used to specify components or alpha2 if no components are specified.

Response

Localities Geocode provides a JSON response containing one root element, results, an array containing the requested geocode result.

Results

Each result contains the following fields:

formatted_address

Contains the human-readable address.

geometry

Contains the longitude, latitude and viewport coordinates for the result, supplemented by additional data also related to the result in the location_type field.

geometry.location_type available values:

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)

types

Contains the type of result. Can be any value from following list:
house_number route locality postal_code

address_components

Detailed fields of the result (long and short). Available fields depend on the returned type.

Corresponding types/fields table:

  name administrative_area_level_0 administrative_area_level_1 administrative_area_level_2 postal_codes postal_town locality iata_code route street_number premise organisation post_box
address    
route          
locality              
postal_code                  

Result example

{
    "results": [
        {
            "formatted_address": "13 Baker Street, London, W1U 3AH",
            "types": [
                "address"
            ],
            "geometry": {
                "location": {
                    "lat": 51.5171245,
                    "lng": -0.1557667
                },
                "location_type": "ROOFTOP"
            },
            "address_components": [
                {
                    "types": [
                        "country",
                        "administrative_area_level_0"
                    ],
                    "long_name": "United Kingdom",
                    "short_name": "GBR"
                },
                {
                    "types": [
                        "administrative_area_level_1"
                    ],
                    "long_name": "City of London",
                    "short_name": "City of London"
                },
                {
                    "types": [
                        "locality"
                    ],
                    "long_name": "London",
                    "short_name": "London"
                },
                {
                    "types": [
                        "postal_codes"
                    ],
                    "long_name": "W1U 3AH",
                    "short_name": "W1U 3AH"
                },
                {
                    "types": [
                        "route"
                    ],
                    "long_name": "Baker Street",
                    "short_name": "Baker Street"
                },
                {
                    "types": [
                        "street_number"
                    ],
                    "long_name": "13",
                    "short_name": "13"
                }
            ]
        }
    ]
}

Samples

Localities Geocode

Localities Reverse Geocode

Early Access

Early Access products or features are ready for testing by customers. Publicly announced, Early Access features or products are feature-complete, covered by the Woosmap SLA and technical support, unless otherwise specified in product terms or the terms of a particular Early Access program. Early Access offerings are intended for feedbacks collection and to help Woosmap Teams finely tune product or feature based on those if necessary. The average Early Access stage lasts about six months. In some cases, accessing Early Access features or products may involve contacting our Support to get invitation or feature activation. If prices mentioned, they may be adjusted until the feature or product passes in General Availability stage.

Was this article helpful?
Have more questions? Submit a request