Behavior
Methods
Any tool or programming language that has HTTP communication abilities, for example
cURL
or Postman or Python
requests
, can interact with our API by merely requesting the correct endpoint, for example
/routing
. All requests need to be made using the HTTPS protocol to ensure encryption and an extra layer of security. Additionally, most of our endpoints expect requests to be made in the standard JSON format. Our API's support the standard HTTP methods, e.g.,
GET
,
POST
, and so on.
Encoding
All API's require the contents of request objects be encoded using UTF-8. To represent special characters in strings, use the
%FF
hexadecimal representation. For example, in German, the word "airports" is "Flughäfen" and converts to "Flugh%C3%A4fen." If you are unsure of the conversion, there are numerous online encoder/decoder tools and automated encoding/decoding in language specific libraries.
For example (in Python 3.0+):
For a full-fledged URI request (in Python 3.0+):
Success
All success responses include standard HTTP statuses consistent with IETF standards. The API returns a JSON object when a request is successful. The JSON object contents are specific to the resource and described in the detailed documentation for each resource. The API backend handles requests in one of two ways:
- Synchronously : For smaller jobs (in terms of the number of unique locations), the request processes "quickly" (shorter than a connection timeout) and the response JSON body includes a result.
-
Asynchronously
: For larger jobs, the request does not process quickly, and the response JSON body includes a
jobidneeded to poll the endpoint and retrieve aurlto download the solution. Solutions are available at this URL for 24 hours from the timestamp included in the response header.
Failure
All failure responses include standard HTTP statuses consistent with IETF standards. In the event an error occurs, the response is a JSON with a top-level error code, error message, and other identifying information. All API errors return a JSON response with a human-readable comment describing the issue. Depending on the error returned, there may be additional objects to describe the error further. Note that if a client does not receive a response for a request within 29 seconds, the API returns an HTTP status code of
504
indicating a Gateway Timeout Error.
