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:
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
},