Community Forum

Geocode / Reverse geocode

Find the Address or Coordinates for places
  1. Introduction
  2. Required Parameters
  3. Optional Parameters
  4. Address Geocode example
  5. Responses
  6. Results
  7. Usage limits

Introduction

Woosmap Address Geocode endpoint provides you with the geographical locations of addresses, or the address of geographical locations in response to a HTTP request. For example if you need to know the coordinates of the 224 Rue de Rivoli, Paris or the address of 40.68, 74.04.

If looking for coordinates (geocoding) the request specifies a complete or partial address string. To get an address from coordinates (reverse geocoding) the request specifies a pair of coordinates.

The returned address/coordinates is more or less accurate depending on the data contained in the request. A partial address is less likely to return the proper coordinates than the complete address.

A Woosmap Address request is an HTTP URL of the following form:

        https://api.woosmap.com/address/geocode/json?parameters

Former method to call geocode endpoint to retrieve details for an autocomplete suggestion remains available but is now deprecated. Please use the dedicated details endpoint.

Required Parameters

Certain parameters are required to initiate an Address request. As is standard in URLs, all parameters are separated using the ampersand(&) character. Few parameters are mandatory. Either a field of address or latlng must be present in addition to a Woosmap API key.

        https://api.woosmap.com/address/geocode/json?latlng=40.689247,-74.044502&key={PUBLIC_API_KEY}

or

        https://api.woosmap.com/address/geocode/json?address=224%20Rue%20de%20Rivoli%2C%20Paris&key={PUBLIC_API_KEY}

address

The address string of which to find the coordinates for. The address must be URL encoded for example space is %20.

latlng

The Latitude coordinate and Longitude coordinate in a comma separated string to find an address for.

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 contain a referer.

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

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, no referer checking associated with those keys.

Optional Parameters

language

The language to return the address elements in. Must be a ISO 639-1 language code.

location

Bias for the results. Should be pass in lat,lng format (example : 5.2,-2.3)

components

Geographic places to which you would like to restrict your results. Currently, you can use components to filter over countries. Countries are identified by a two character, ISO 3166-1 Alpha-2 or a three character, ISO 3166-1 Alpha-3 compatible country code. Multiple countries must be passed as separates components, with the pipe character (|) as a separator.

If the request contains multiple countries (eg. components=country:FRA|country:ITA), the API looks for addresses where country=FRA OR country=ITA. If no address match one of those two values, a ZERO_RESULTS message is returned.

Example

components=country:fr or components=country:fra would restrict your results to places within France.

Multiple countries example

components=country:gb|country:fr|country:be|country:sp|country:it would restrict your results to the United Kingdom, France, Belgium, Spain and Italy.

cc_format

Default country code format in responses is Alpha3. However, format in responses can be changed by specifying components in alpha2 or by specifying the proper value for the cc_format parameter.

Available cc_format are (alpha2, alpha3)

limit

Maximum number of results to be returned (value from 1 to 100, default values for geocode request [20] and for reverse geocode request [1])

Address Geocode example

The following example shows a Geocode request for “Place de la Resistance Paris”, in country France, limiting the returned result to maximum 5 addresses:

Address Geocode call
        https://api.woosmap.com/address/geocode/json
  ?address=Place%20de%20la%20Resistance%20Paris
  &components=country%3AFR
  &limit=5
  &key=YOUR_PUBLIC_API_KEY
    
        curl -L -X GET 'https://api.woosmap.com/address/geocode/json?address=Place%20de%20la%20Resistance%20Paris&components=country%3AFR&limit=5&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    
        var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.woosmap.com/address/geocode/json?address=Place%20de%20la%20Resistance%20Paris&components=country%3AFR&limit=5&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/address/geocode/json?address=Place%20de%20la%20Resistance%20Paris&components=country%3AFR&limit=5&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/address/geocode/json?address=Place%20de%20la%20Resistance%20Paris&components=country%3AFR&limit=5&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/address/geocode/json?address=Place%20de%20la%20Resistance%20Paris&components=country%3AFR&limit=5&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/address/geocode/json?address=Place%20de%20la%20Resistance%20Paris&components=country%3AFR&limit=5&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

Responses

Address provides a JSON response containing one root element, results which contains an array of places. A more accurate request should return one place, whereas a less accurate request may return multiple.

Address Geocode Collection Response
JSON
        {
  "results":
    [
      {
        "formatted_address": "Place de la Résistance, 75007 Paris, France",
        "types": ["route"],
        "address_components":
          [
            {
              "types": ["country"],
              "long_name": "France",
              "short_name": "FRA",
            },
            {
              "types": ["state"],
              "long_name": "Ile-de-France",
              "short_name": "IDF",
            },
            {
              "types": ["county"],
              "long_name": "Paris",
              "short_name": "Paris",
            },
            {
              "long_name": "Paris",
              "short_name": "Paris",
              "types": ["locality"],
            },
            {
              "long_name": "7th Arrondissement",
              "short_name": "7th Arrondissement",
              "types": ["district"],
            },
            {
              "long_name": "Place de la Résistance",
              "short_name": "Place de la Résistance",
              "types": ["route"],
            },
            {
              "long_name": "75007",
              "short_name": "75007",
              "types": ["postal_code"],
            },
          ],
        "geometry":
          {
            "location_type": "GEOMETRIC_CENTER",
            "location": { "lat": 48.86228, "lng": 2.30345 },
            "viewport":
              {
                "northeast": { "lat": 48.86231, "lng": 2.30544 },
                "southwest": { "lat": 48.86191, "lng": 2.30147 },
              },
          },
      },
    ],
  "status": "OK",
}

Results

Each result contains the following fields:

address_components

Splits address components into dedicated fields that may be use for further processes.

formatted_address

Contains the human-readable address.

geometry

Contains the longitude, latitude and viewport coordinates for the result completed with additional data on 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 country eat_and_drink going_out_entertainment sights_and_museums natural_and_geographical transport accommodations leisure_and_outdoor shopping business_and_services facilities areas_and_buildings place

distance

Present when doing reverse geocode (latlng instead of address in the request). Distance in meters from the response address to the given spatial context (latlng).

status

Returns more info on if the request was successful or not, valid responses:

OK indicates the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
REQUEST_DENIED indicates that the service denied use of the Address API (e.g. wrong API Key, wrong/no referer, …).
UNKNOWN_ERROR indicates an Address API request could not be processed due to a server error. The request may succeed if you try again.

Usage limits

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

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