Geocode / Reverse geocode

Find the Address or Coordinates for places

  1. Introduction
  2. Required Parameters
  3. Optional Parameters
  4. Responses
  5. Results
  6. 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

To restrict your results to specific areas. Currently, you can use components to filter over countries. Countries must be passed as three characters string (ISO 3166-1 Alpha 3).
Components should be passed as an array of different options which are separated by a |
components=country:FRA
or
components=country:CAN|country:BEL

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.

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 (default=20 for geocode request and default=1 for reverse geocode request)

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.

{
  "results": [
    {
      "address_components": [
        [
          "2 Grafton Street, Dublin, County Dublin, D02 Y527, Ireland",
          "Dublin"
        ],
        {
          "types": [
            "country"
          ],
          "long_name": "Ireland",
          "short_name": "IRL"
        },
        {
          "types": [
            "county"
          ],
          "long_name": "County Dublin",
          "short_name": "D"
        },
        {
          "long_name": "Dublin",
          "short_name": "Dublin",
          "types": [
            "locality"
          ]
        },
        {
          "long_name": "Dublin 2",
          "short_name": "Dublin 2",
          "types": [
            "district"
          ]
        },
        {
          "long_name": "Grafton Street",
          "short_name": "Grafton Street",
          "types": [
            "route"
          ]
        },
        {
          "long_name": "D02 Y527",
          "short_name": "D02 Y527",
          "types": [
            "postal_code"
          ]
        },
        {
          "long_name": "2",
          "short_name": "2",
          "types": [
            "street_number"
          ]
        }
      ],
      "formatted_address": "2 Grafton Street, Dublin, County Dublin, D02 Y527, Ireland",
      "geometry": {
        "location_type": "ROOFTOP",
        "location": {
          "lat": 53.34308,
          "lng": -6.25929
        },
        "viewport": {
          "northeast": {
            "lat": 53.34398,
            "lng": -6.25778
          },
          "southwest": {
            "lat": 53.34218,
            "lng": -6.2608
          }
        }
      },
      "types": [
        "house_number"
      ]
    }
  ],
  "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

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