Community Forum

Geocode (Early Access)

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. Samples
  7. 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.

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

fields

You can use this parameter to limit the fields returned in the response (by default, all fields are returned). This parameter accepts one value: geometry. 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.

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.

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":
    [
      {
        "types": ["route"],
        "formatted_address": "Place Jeanne D'Arc, 75013, Paris",
        "geometry":
          {
            "location": { "lat": 48.829405, "lng": 2.367944 },
            "location_type": "GEOMETRIC_CENTER",
          },
        "address_components":
          [
            {
              "short_name": "FR",
              "long_name": "France",
              "types": ["country", "administrative_area_level_0"],
            },
            {
              "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:

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

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.

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.

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