Community Forum

Geocode

Convert addresses into geographic coordinates and coordinates into a human readable address
  1. Overview
  2. Required Parameters
  3. Optional Parameters
  4. Localities Geocode example
  5. Response
  6. Usage limits
  7. Samples

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, as for the lack of a country code as parameter of the request.

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.

Reverse geocoding will return an empty array if no address is found within a 200-meter radius around the latlng coordinates.

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.

http
        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 checks 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

types

The types of suggestions to return. Below are the most commonly used types; the complete list is available here:

locality includes locality names (from city to village) and suburbs
postal_code publicly-used postal codes around the world
address addresses
admin_level most commonly used administrative areas
country countries as whole point of interest

For the geocode enpoint, this field defaults to locality|postal_code|address.

excluded_types

Specifies types of locations to exclude. Multiple types should be separated using the pipe character (|).

list_sub_buildings (reverse geocoding only)

allow to retrieve all addresses at the same location for a common street number or building. When list_sub_buildings=true and according to actual addresses at the provided location, results may contain an additional key sub_buildings as a list of address summaries. It will provide a public_id and a description for every address at the provided location (flats, organisations..).

fields

You can use this parameter to limit the fields returned in the response. This parameter can be any combination of geometry, address_components or shape (defaults to geometry|address_components). If set, it will limit the content of responses to the specified fields. For example, fields=geometry will limit the response to the geometry part and you won’t get the address_components, which can help with cost optimization in certain countries. fields=shape will include the shape for most provided types except addresses: country, admin_level, postal_code and locality.

Request cost may vary according to response completeness, please visit ou pricing page or get in touch with your Customer Care contact to learn how to estimate you license accordingly.

language

The language code, indicating in which language the results should be returned, if possible. If no language parameter is 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). Depending on requested language, only parts of the address components might be translated.

components

Even if not mandatory, it’s strongly recommend to use this parameter to ensure best relevant 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:es|country:it would restrict your results to results within the United Kingdom, France, Belgium, Spain and Italy.

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

data

This parameter accepts two values: standard (default) or advanced. The advanced value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. See details in the Localities API Coverage web page

Notice: 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.

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.

Localities Geocode example

A request for geocode containing the string Place Jeanne-d'Arc with components country:FR:

Localities Geocode call
        https://api.woosmap.com/localities/geocode
  ?address=Place%20Jeanne-d%27Arc
  &components=country%3AFR
  &key=YOUR_PUBLIC_API_KEY
    
        curl -L -X GET 'https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'\''Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    
        var 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.log('error', error));

    
        var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d\'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    
        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)


    
        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY")
  .method("GET", body)
  .addHeader("Referer", "http://localhost")
  .build();
Response response = client.newCall(request).execute();

    
        require "uri"
require "net/http"

url = URI("https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"

response = https.request(request)
puts response.read_body

Response

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

Localities Geocode Collection Response
JSON
        {
  "results":
    [
      {
        "public_id": "MCtGVFlkLzFNc2lCU3hMQUtxKy9GaXl5K3VNPV9f",
        "types": ["route"],
        "formatted_address": "Place Jeanne D'Arc, 75013, Paris",
        "geometry":
          {
            "location": { "lat": 48.829941, "lng": 2.369083 },
            "location_type": "GEOMETRIC_CENTER",
          },
        "address_components":
          [
            {
              "short_name": "FR",
              "long_name": "France",
              "types": ["country", "administrative_area_level_0"],
            },
            {
              "short_name": "Île-de-France",
              "long_name": "Île-de-France",
              "types": ["state"],
            },
            {
              "short_name": "Paris",
              "long_name": "Paris",
              "types": ["county"],
            },
            {
              "short_name": "Paris",
              "long_name": "Paris",
              "types": ["locality"],
            },
            {
              "short_name": "75013",
              "long_name": "75013",
              "types": ["postal_codes"],
            },
            {
              "short_name": "Place Jeanne D'Arc",
              "long_name": "Place Jeanne D'Arc",
              "types": ["route"],
            },
          ],
      },
    ],
}

Results

Each result contains the following fields:

public_id

Contains a unique ID for each result. Please use this ID to give feedbacks on results.

name

When the result is a postal code, locality, or administrative level, the name differs from the formatted address as it includes only the place name.

formatted_address

Contains the human-readable address.

geometry

Contains the longitude, latitude and viewport coordinates for the result, as well as its shape, when requested. 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)
POSTAL_CODE result is approximate. Address has inherited from the location of the postal code it is part of (for NYB addresses).
DISTRICT result is approximate. Address has inherited from the location of the district it is part of (for NYB addresses).

types

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

administrative_area_label

This field is only available for admin_level suggestions. It provides the local english name of the administration level (“department” for France or “federal_state” for Germany).

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 • • •     •              

status

This optional field is only specified for UK not yet built addresses.

Only one value yet, not_yet_built for addresses referenced as not yet built addresses by Royal Mail.

scores_per_components

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.0
           },

Usage limits

The following usage limits are in place for the Localities API on the geocode endpoint:

Samples

Localities Geocode

Localities Reverse Geocode

‹ Details Nearby ›
Was this article helpful?
Have more questions? Submit a request