Customer Account API

Introduction

Open Street is a multipoint route optimization service that is accessible to developers who wish to include this technology in their own applications. The service can be consumed either in the form of a flat rate that gives the right to optimization quotas per day (eg 30 optimizations per day of 50 points each), or in user fees, Ie each optimization is counted from the user account until the user account is exhausted.

It is for this second scenario that there is a user account management API. This API allows you to create optimization accounts, and track their usage.

Description of the customer account API

Protocol used

Like all Open Street APIs, HTTP 1.1 is used, and two methods are required to cover all the functionalities of this API: POST and GET. There is always at least one URL parameter in the query, even in the case of POST methods.

This optimization API is not likely to receive special or accented characters, but URLs must still be properly encoded. Recent browsers automatically encode URLs but not always HTTP libraries. With PHP you can use urlencode() .

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" .

The query processing time is short at the scale of a user interface, generally less than 300 ms.

Catalog of input parameters

This API accepts several types of queries, which produce different results. Parental parameters which determine the type of request and the so-called «child» parameters which are necessary for the proper functioning of the request are distinguished. Parent parameters do not have a value assigned to them, only their precedence is sufficient. On the other hand, the child parameters must have an associated value, with a request of type either POST or GET.

An asterisk * indicates a required parameter to start a calculation.

On the Open Street infrastructure, there are two types of accounts: the customer account that contains the billing data (contact details, applicable tariff) and the calculation account that is assigned to a customer account. This calculation account allows you to perform route optimizations without having to authenticate with the customer account.

A customer account is defined by its email account and password, while a calculation account is defined by its key of 32 characters (key parameter hereafter).

Most of the time, a customer will have only one calculation account. But a customer can open several calculation accounts, which can be useful for statistics purposes. In this case, several calculation accounts will be able to debit the customer account.

Parent parameter	Child parameter	Explanation	Method
deposits	key*	List of credit deposits made by the customer who owns this calculation account.	GET
credit	key*	Value of the credit remaining on the customer account that owns this calculation account.	GET
tsp_requests	key*, date	List of queries made by the specified calculation account. The date parameter specifies a start date as YYYYMMDD	GET
tsp_rates	key*	Fee schedule for this calculation accountf	GET
tsp_quotas	key*	Quotas applicable to the customer who owns this calculation account.	GET
create_key	name*, description, email*	Creates a calculation account assigned to the specified customer account through the email.	GET
create_customer	address_company*, address_person*, address_street*, address_street2, address_pc*, address_city*, address_cedex, email*, password_hashed_db*	Creates a customer account with its contact information, its identifier (email) and the hash MD5 of its password.	POST
salt	null	Returns a value of 32 characters that changes every minute, and that is useful for the authentication process for the query_customer query.query_customer.	GET
query_customer	email*, password_hashed_js*	List of calculation accounts assigned to the customer account. This request is sensitive. The password_hashed_js parameter is calculated by md5(md5($ password_typed).$salt) (PHP syntax)..	POST

Authentication methods

For these different requests, different types of authentication can be distinguished according to the request.

• Most of the time, a calculation account key is sufficient to make a query. This key must be kept absolutely confidential. By its length of 32 characters, an ill-intentioned person would have a chance on 1,53 10⁵⁴ to discover your key what appears to be an acceptable risk.
• To create a customer account, an identifier (email address) and a password are required. The password must be hashed in md5 and not transmitted in plain text when creating the account.
• To request a customer account and list its calculation accounts, a more complicated authentication process is required. The password is never transmitted in clear or simply hashed. The password_hashed_js parameter must be md5(md5($password_typed).$salt) , or otherwise say, the md5 hash of: hash md5 of the entered password, concatenated to the salt value obtained from the query of the same name. This increased security is set to protect key values.

Data Usage

Exemples

or example, the credit request is of GET type, so we will pass all its parameters into URL parameters. The complete request will therefore be: https://maps.open-street.com/api/account/?credit&key=cle-compte-calcul .

The following result indicates that € 95.44 remains on the requested customer account.

The create_customer request is a POST type, so we’ll pass the parent parameter to a URL parameter, and all other parameters will be POST. The HTTP method used is POST. Here is a bash script that creates a query of this type. We can also use javascript to create such a query (jQuery recommended) or a simple synchronous HTML form.

The result will only be a successful status.

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.

The result of the query must be tested in particular with the status code. If it says something other than « OK » then the query will fail. The following error codes are subject to change.

Error codes

Here is the meaning of the error codes that can be encountered with this API.

Code	Explanation
SYNTAX_ERROR	The request is incomplete or contains an error.
REQUEST_TOO_LONG	GET and POST settings are far too long.
WRONG_KEY	Your authentication key is wrong.
TOO_MANY_PARENT_PARAMETERS	You tried two parent parameters in a single query while the parent parameter is unique and sets the query type.
MISSING_CHILD_PARAMETER	You did not enter all required parameters for this query.
MISSING_PARAMETER	You have not entered any parameters.
UNKNOWN_PARAMETER	One of the parameters is unknown.
WRONG_METHOD	You did not use the correct HTTP method between POST and GET.
WRONG_ADDRESS	One of the address fields is too long (limit to 255 characters per field except address_pc to 10 and address_cedex to 20).
WRONG_EMAIL	The email is invalid.
WRONG_PASSWORD	The password is invalid.