HyperTrack APIs allow you to manage devices and trips using an HTTP-based RESTful interface with JSON format. HyperTrack APIs are mainly used to integrate with the HyperTrack platform through your backend server. Using the APIs allows you to obtain the full state of all tracked devices and trips.
All error messages are in English, as indicated by the
Content-Language: en-US
header.
HyperTrack REST APIs can be consumed through HTTP requests. Please follow the guidelines below to ensure a working server setup.
Authentication
HTTP 401 - Unauthorized
{
"message": "Unauthorized"
}
API requests require Basic Authentication or an OAuth access token to succeed. Failing to set the Authorization header in the right format with correct credentials will result in errors.
A sample Authorization header for Basic Authentication looks like this:
Authorization: Basic V3AxTGdWTjNZSGFmOHVRcE9qalTNTMm5BaEF1RA==
Generating Basic Auth header
credentials="$(echo -n "{AccountId}:{SecretKey}" | base64)"
header="Authorization: Basic $credentials"
const auth =
"Basic " + new Buffer("{AccountId}" + ":" + "{SecretKey}").toString("base64");
const header = { Authorization: auth };
base64string = base64.encodestring('%s:%s' % ('{AccountId}', '{SecretKey}')).replace('\n', '')
header = ("Authorization: Basic %s" % base64string)
String authString = "Authorization: Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "{AccountId}","{SecretKey}")
.getBytes()
);
<?php
$header = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
?>
$header = 'Authorization: Basic ' + Base64.encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
let base64encoded = "{AccountId}:{AccountId}".data(using: .isoLatin1)?.base64EncodedString() ?? ""
urlRequest.addValue("Basic \(base64encoded)", forHTTPHeaderField: "Authorization")
The header should be constructed as follows:
- The AccountID and SecretKey from your account are combined with a single colon (":")
- The above sequence, considered a string, is encoded using Base64. You can do this manually here. Please ensure to choose the UTF-8 charset and LF (Unix) as the Newline separator
- The authorization method and a space ("Basic ") is prepended to the encoded string
A sample Authorization header using an OAuth access token looks like this:
Authorization: Bearer {access_token}
See the OAuth Token API to learn how to obtain an access token.
Tools like Postman or cURL allow you to set the Authorization Header without additional coding. You can use these features to test your auth implementation.With authentication in place, you should be able to make successful HTTP requests to HyperTrack APIs.
HTTPS Methods
Depending on the HyperTrack API and endpoint, your server should support the following HTTPS methods: GET, POST, and DELETE.
HTTP Response Codes
HyperTrack APIs implement appropriate HTTP response codes to indicate how the HTTP request was processed. In success cases, you will receive the expected JSON payload. However, API requests can fail due to client or server errors. We adopted the RFC 7807 standard for our error messages. Please ensure your implementation handles error messages for all HTTP requests.
The errors you will receive are human-readable. Please ensure you log the entire message to troubleshoot the cause of the error quickly.
JSON Payload
The payload you will receive with HTTPS requests is formatted in JSON. You need to implement the capability to parse JSON objects in order to leverage the HTTP response body content.
You should use a JSON parser that handles converting the escaped representation of control characters back to their ASCII character values (for example, converting \n to a newline character).
The HyperTrack APIs make use of GeoJSON and ISO 8601 timestamp formats, which you should handle appropriately as well.
Base URL and endpoints
All HyperTrack APIs have are available on the same base URL:
https://v3.api.hypertrack.com/
However, each API is reachable on a different endpoint:
- Devices API
devices
- Trips API:
trips
Path Parameters
Path parameters are used to accomplish querying, filtering, searching, sorting, and for pagination.
Query Trips API by trip_id
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}
const request = require("request");
const options = {
url: "https://v3.api.hypertrack.com/trips/{trip_id}",
auth: {
user: "{AccountId}",
password: "{SecretKey}"
}
};
request(options, (err, res, body) => {
console.dir(err, res, body);
});
import requests
response = requests.get("https://v3.api.hypertrack.com/trips/{trip_id}", auth=("{AccountId}", "{SecretKey}"))
print(response.text)
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "{AccountId}","{SecretKey}")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}")
.get()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/trips/{trip_id}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
require 'json'
url = URI("https://v3.api.hypertrack.com/trips/{trip_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Querying
HyperTrack APIs support querying to request a single resource using the respective identifier:
https://v3.api.hypertrack.com/devices/{device_id}
https://v3.api.hypertrack.com/trips/{trip_id}
Filtering
Filter Trips API sample URLs
# reduce result set size to 5 trips
GET https://v3.api.hypertrack.com/trips?limit=5
# find trips with status "completed"
GET https://v3.api.hypertrack.com/trips?status=completed
It is planned to provide filtering capabilities to ...
- Limit the items returned within a single API response
- Filter trips by trip status (active or completed)
Pagination
<%= partial("includes/snippets/trips-pagination-sample.md.erb") %>
The APIs utilize token-based pagination, which will allow to control how many items should be skipped in the returned result set.
The links section of the response provides a next
link to request the next page of results.
Postman Collection
We published a Postman Collection to make it easier and faster to experiment with the HyperTrack APIs. Postman Collections lists all available API endpoints, allow making API requests instantly (with Basic Auth), and can generate reusable code snippets to make API requests using the programming language of your choice.
Try it out yourself:
Payload and Headers
The responses will always include a set of headers. Please review them carefully when implementing the APIs.
Content-Type
The body payload sent by the server is in application/json
, which means that the JSON format is enforced for the payload by default. Please ensure you handle JSON appropriately before processing the data.
Pagination
The payload structure of responses is change as follows.
# get items 180-200 form entire result set
https://v3.api.hypertrack.com/trips?offset=180&limit=20
Name | Type | Description |
---|---|---|
links | reference object | Object with references to use for pagination |
links.next | URL | URL with pointer to the next page |
The links
object will include all pagination and filtering properties to navigate through result sets with the same query as initiated. You should use the links properties and prefix them with the API base URL to make consecutive API calls when scrolling through the result set.
The easiest way to identify the end of the pagination is to look for the existence of the links.next
property. If it doesn’t exist, you completed the pagination.
links
object provided in the response to scroll through all results.
Processing States
HTTP 202 - Trip completion processing payload
{
"message": "pending completion for trip '00112233-4455-6677-8899-AABBCCDDEEFF'"
}
In some scenarios, API requests cannot be fully processed before an API response has to be issued. An example of this is the completion of a trip. The request needs to be processed on the platform and trip completion needs to be confirmed on the mobile SDK of the device. To handle the processing, the API will respond with a processing state (e.g. processing_completion
for trips).
To handle the processing state, you should anticipate the response to be in a different format (see the message
property).
After processing the request on the HyperTrack platform, a webhook will be sent out and the requested resource will be available through the API. For trip completion, you will receive a completed
trip webhook. After the webhook arrival, you can also call the Trips API to retrieve the trip resource using the trip_id
.
Errors
HTTP 401 - Trip not found error payload
{
"status": 404,
"code": "trip_not_found",
"title": "Trip could not be found",
"type": "https://docs.hypertrack.com/#trips-api-trip-not-found",
"detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}
We are adopting the RFC 7807 standard for API error messages.
With compliance to the RFC standard, we are responding with
Content-Type: application/json
to reduce unexpected behavior when the API returns errors.
The standard requires at least the type
property. Everything else is optional. For HyperTrack, we always send title
, detail
, status
, and code
in addition. To detail out some errors (for instance multiple invalid fields), additional properties will be available.
Parameter | Type | Description |
---|---|---|
status | Number | HTTP status code |
code | String | Error class code |
title | String | Brief summary of the error class |
type | URL | URL to the respective error page (about:blank if none is provided) |
detail | String | Detailed description of the error instance |
invalid_params | Object | A list of invalid parameters to review (options) |
All error messages are in English, as indicated by the
Content-Language: en-US
header.
Please review the reference page to see all possible HTTP errors returned by the HyperTrack APIs.