Geocode
Convert addresses into geographic coordinates and coordinates into a human readable address
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.
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 suggestion to return. Several types are available, the list is the same as for autocomplete.
For the geocode enpoint, this field defaults to locality|postal_code|address.
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:
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.
{
"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:
"scores_per_components": {
"street_name": 0.6153846153846154,
"postal_code": 0.8,
"locality": 1.0
},
