Geocoding API

Introduction

Open Street is a route optimization service which enables you to calculate a route in the right order to minimize the distance traveled.
Our online web application uses Open Street APIs, including the one that allows geocoding, that is the transformation between a postal address and a latitude and longitude coordinate.

Running the Geocoding API

Protocol used

This API uses the GET method implemented in the HTTP 1.1 protocol. It can therefore be used from a standard web browser or any other library to download data from a web server. Caution, this geocoding API is capable of receiving special or accented characters, which must be correctly encoded in sequences beginning with a percentage (%). Spaces should be replaced by plus (+). Recent browsers automatically encode URLs but this is not always the case with HTTP libraries.

All of our APIs support gzip compression, so it is strongly recommended to enable this feature in your HTTP client. To verify that compression is active, the client request header must have Accept-Encoding: "gzip, deflate"  and the response header of the server must have Content-Encoding: "gzip" . This reduces the data download time by almost 50%.

The response time of this API is less than 500ms. Thanks to our internal cache, the answers can be returned faster if the information has already been requested, approximately of a few milliseconds.

Input Data

To work, this API needs data that is provided as URL parameters. In the table below, asterisks * indicate the parameters that are required to start a calculation.

Parameter	Value	Explanations
address*	1 Rue de la Paix, Paris, France	The most accurate postal address, with fields separated by commas or semicolons. It must be encoded as a URL.
key*	chaine-de-caracteres	Every user’s Authentication key.

The URL that queries the geocoding API must be encoded correctly, that is, all special and accented characters are transformed by sequences beginning with the percentage sign (%). Spaces must be transformed to the plus sign (+).

Modern browsers automatically encode the addresses entered in the URL bar, but this is not always the case for HTTP libraries like curl.

A concrete example

Let us take the example of the prefecture of Bourg-en-Bresse whose address will be «Préfecture de l’Ain, Bourg-en-Bresse, France».
This is what the query for the geocoding API looks like. Note that a valid authentication key is required.

Using Geocoding data

Output Data

he output data format is a json object that can be downloaded and processed by an application, or viewed by a browser. HTTP-based compression is handled by the HTTP client transparently for the developer.

The resulting document is compatible with Google Geocoding API, while omitting superfluous details. If you have already developed an application that uses this API, you already know the operation. We use different databases for this service, so the results can sometimes vary from Google’s.

Below is a table of output parameters.

Parameter	Explanation
formatted_address	Corrected address as understood by the API.
lat	Latitude of the requested point..
lng	Longitude of the requested point.
status	Status code

The structure of the document has not been represented in this document, but the json object also contains the following strings: results, geometry, location

 

Usage tips

When you process this json object, you must retrieve the values by their associated string, not by their position in the document or their line number. Indeed, other data are likely to be inserted in the future and it is the only way to respect the compatibility. You can safely transform the json object into an array of your programming language with a specialized library, provided you keep the strings and values. For more information on json, visit json.org, which provides a complete list of decoding libraries in different languages.

You can use this API in conjunction with our Route Optimization API. In this case it is advisable to launch the geocoding as soon as possible, and not to wait for the user to launch an optimization calculation. This will improve the fluidity of your application.

If you know beforehand the list of addresses that you are likely to ask, you should start all your geocoding requests the first time with a script of your creation. Thus, all future queries will benefit from our integrated cache, and will be much faster.

Unlike our optimization API, our geocoding routines are not particularly more powerful than those available for free on the internet. For example, if your geocoding needs are particularly important, we recommend that you rely primarily on Google Geocoding API or an equivalent service, and only use our geocoding API if you fail to.

Error codes

The standard status code must be “OK”. For any other return value, the geocoding request will have failed. The table below describes the meaning of the various codes you may encounter using our API.

Code	Explanation
SYNTAX_ERROR	The request is incomplete or contains an error.
LIMIT_REACHED	You have exhausted your usage quotas. Learn More.
WRONG_KEY	Your authentication key is wrong. Contact us
ADDRESS_IS_INCONSISTENT	The requested address string is a too short, or too long.
REQUEST_DENIED	Unable to respond to this query.

 

Upcoming developments

• Other optional parameters are likely to emerge to refine the calculation.
• The GET method of the HTTP protocol limits the size of the requests to 8 KB.