Introduction

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.

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

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.

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.

📘

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.