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
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.
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.
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.
|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
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.
|Corrected address as understood by the API.
|Latitude of the requested point..
|Longitude of the requested point.
The structure of the document has not been represented in this document, but the json object also contains the following strings: results, geometry, location
"Préfecture de l'Ain, 45 Avenue Alsace Lorraine, 01012 Bourg-en-Bresse, France"
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.
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.
|The request is incomplete or contains an error.
|You have exhausted your usage quotas. Learn More.
|Your authentication key is wrong. Contact us
|The requested address string is a too short, or too long.
|Unable to respond to this query.
- 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.