The MiX Telematics REST API provides simple interfaces to the data made available by MiX Telematics systems.
This documentation describes how to access the API (see Getting Started) and provides comprehensive documentation of the resources available.
The API attempts to conform to the design principles of Representational State Transfer (REST).
Simply change the format extension of a request or set the HTTP Accept header to get results in the format of your choice. Most methods support the XML (HTTP content type application/xml), JSON (HTTP content type application/json). or CSV (HTTP content type text/csv) formats. The default response format is JSON.
All JSON responses can use the JSONP format simply by passing the callback function name in the optional callback query parameter.
The API is entirely HTTP based. Methods to retrieve data from the API require a GET request. Methods that submit, or change data require a POST. Methods that destroy data require a DELETE request. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one.
The API attempts to return appropriate HTTP status codes for every request. The following responses can be expected:
All API calls accept required and/or optional parameters. Parameter values should be converted to UTF-8 and URL encoded.
Most API calls require a valid authentication token to be passed either in the custom "X-auth" HTTP header, or in the "auth" query string parameter. An authentication token can be obtained by calling one of the Authentication APIs.
Note: The "auth" query string parameter is supported to facilitate making API calls from a web browser. Applications should make use of the "X-auth" HTTP header to avoid passing the authentication token in the query string.
API usage is limited to protect the MiX Telematics infrastructure from abuse. API calls are limited to 240 calls per user account per hour.
The rate limit status of the authenticated user is returned in the following HTTP headers with every response to an authenticated API call:
In addition, the rate limit status can be requested at any time by making a call to GET /account/rate_limit_status.
Note: Authentication requests, and requests to check the rate limit status and hit counts are not rate-limited.
It is important to note that rate limits are applied per user account. If multiple applications make use of the same user account, the rate limit of 240 calls per hour will be applied across calls from all of the applications using the same account.
The authenticated user's globalisation preferences are contained in the AccountProfile resource which can be obtained by calling GET account/profile. The server also sends the globalisation preferences in the custom "X-Globalisation" header in reponse to any authenticated call.
Applications can retrieve culture and time zone information by calling the Globalisation APIs.
For API calls which return dates and/or numeric values with measurement units, the server can convert such values to match the user's globalisation preferences automatically. If this is required, applications should pass the globalisation preferences back to the server with every call, either in the globalisation query string parameter, or in the custom "X-Globalisation" HTTP header. If globalisation preferences are not passed, the server will respond with resources containing UTC dates and metric numeric values.
The MiX Telematics REST API is easy to use. API calls which retrieve (GET) data can be tested in a web browser without writing any code. To try out the APIs in your browser:
