References
APIs
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.
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")
[request addRequestHeader:@"Authorization"
value:[NSString stringWithFormat:@"Basic %@",
[ASIHTTPRequest base64forData:
[[NSString stringWithFormat:@"%@:%@", "{AccountId}", "{SecretKey}"]
dataUsingEncoding:NSUTF8StringEncoding]]]];
The header should be constructed as followed:
- 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.
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 endoints
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
Coming soon: Trips API pagination parameters
# get items 180-200 form entire result set
https://v3.api.hypertrack.com/trips?offset=180&limit=20
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.
{
"data": [
// trip objects
],
"links": {
"next": "https://v3.api.hypertrack.com/trips?pagination_token=abc"
}
}
| 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.
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.
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) |
Please review the reference page to see all possible HTTP errors returned by the HyperTrack APIs.
OAuth
Obtain an OAuth access token. The token can be used to authorize API requests as an alternative to Basic Authentication.
In addition, you can use the same API to securely embed views in your own operations dashboards. Please this guide section to learn how to securely embed dashboard views leveraging access token and its scope.
Token
Obtain an OAuth access token example:
curl -X POST https://v3.api.hypertrack.com/oauth/token \
-d "{ "client_id": "{AccountId}", "client_secret": "{SecretKey}", "grant_type": "client_credentials" }"
Obtain an access_token.
POST /oauth/token
Authentication: Basic Auth
OAuth token request attributes
| Name | Type | Description |
|---|---|---|
| client_id | string | Your AccountId |
| client_secret | string | Your SecretKey |
| grant_type | string | As of now, only "client_credentials" is supported |
| scope | string | '*' by default |
HTTP 200 - Obtain an OAuth access token
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5oeXBlcnRyYWNrLmNvbSIsImV4cCI6MTY1MzE1MzI1NywiaWF0IjoxNjUzMDY2ODU3LCJzdWIiOiJmb28ifQ.wxkxWRV4Ilf9W1L_TGCj8wpJZhg8fVfm6Cdg1HGUoIw",
"token_type": "Bearer",
"expires_in": 86400
}
Use the access_token from the response to authorize subsequent API requests like so:
Authorization: Bearer {access_token}
Devices
Use the HyperTrack API to track and manage devices with installed app(s) built with the HyperTrack SDK.
Start tracking
Device start tracking example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}/start
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
// Use Node.js helper library method to start tracking
hypertrack.devices.startTracking(deviceId).then(() => {
// Tracking started
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.devices.start_tracking({device_id})
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/devices/{device_id}/start")
.post(null)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices/{device_id}/start';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"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/devices/{device_id}/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
HTTP 200 - Tracking command was sent (no content)
Start tracking a device with the API.
POST /devices/{device_id}/start
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of device, case sensitive
Stop tracking
Device stop tracking example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}/stop
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
// Use Node.js helper library method to stop tracking
hypertrack.devices.stopTracking(deviceId).then(() => {
// Tracking stopped
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.devices.stop_tracking({device_id})
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/devices/{device_id}/stop")
.post(null)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
url = 'https://v3.api.hypertrack.com/devices/{device_id}/stop';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"method" => "POST",
"http" => [
"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/devices/{device_id}/stop")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
HTTP 200 - Tracking command was sent (no content)
Stop tracking a device with the API.
POST /devices/{device_id}/stop
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of device, case sensitive
Set device name and metadata
Set device name and metadata example:
payload='{
"name": "Alex’s Phone",
"metadata": {
"customer_id": "ABC123"
}
}'
curl -X PATCH \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id} \
-H 'Content-Type: application/json' \
-d $payload
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
// Change device name
hypertrack.devices.changeName(deviceId, "Test Name").then(() => {
// Name changed
}).catch(error => {
// Error handling
})
// Change device metadata
let metadata = {
customer_id: "ABC123"
};
hypertrack.devices.patchMetadata(deviceId, metadata).then(() => {
// Metadata set
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
# Change device name
hypertrack.devices.change_name({device_id}, "Test name")
# Change metadata
metadata = {
"customer_id": "ABC123"
}
hypertrack.devices.patch_metadata({device_id}, metadata)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n "
+ "\"name\": \"Alex’s Phone\",\n "
+ " \"metadata\": {\n"
+ " \"customer_id\": \"ABC123\"\n"
+ " }\n"
+ "}");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/devices/{device_id}")
.patch(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices/{device_id}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"name": "Alex’s Phone",
"metadata": {
"customer_id": "ABC123"
}
}'
$context = stream_context_create([
"http" => [
"method" => "PATCH",
"header" => $basicAuth
],
'content' => $payload
]);
$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/devices/{device_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"name": "Alex’s Phone",
"metadata": {
"customer_id": "ABC123"
}
}.to_json
response = http.request(request)
puts response.read_body
HTTP 204 - Device updated (no content)
Update the name and/or metadata for a device.
PATCH /devices/{device_id}
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of a tracked device, case sensitive
Request Body
Request body must be a JSON formatted string. In order to patch name and/or metadata for the device, you must include name and/or metadata as keys inside this JSON object. Note that metadata needs to be a valid JSON object.
Get device list
Get device list example:
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.getAll().then(devices => {
// Process devices list
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
"""
Arguments:
- pagination: bool flag to enable or disable pagination. False by default
- pagination_token: string token received from previous call to request next page
"""
devices = hypertrack.devices.get_all()
print(devices)
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/devices")
.get()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices';
$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/devices")
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
HTTP 200 - Devices payload
"data":
[
{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"location": {
"speed": 4.20,
"accuracy": 14.09,
"bearing": 193.12,
"geometry": {
"type": "Point",
"coordinates": [
35.1016383,
47.8391314,
65.40
]
},
"recorded_at": "2019-07-18T18:01:59.064000Z",
},
"device_status": {
"data": {
"recorded_at": "2019-07-30T01:38:45.610000Z",
"activity": "stop"
},
"value": "active"
},
"battery": "normal",
"device_info": {
"timezone": "America/Los_Angeles",
"os_name": "iOS",
"device_brand": "Apple",
"sdk_version": "3.3.2",
"device_model": "iPhone X",
"network_operator": "T-Mobile",
"name": "Alex’s Phone",
"os_version": "12.4"
},
"registered_at": "2019-07-10T01:38:45.610000Z",
"metadata": { ... }
},
...
],
"pagination_token": "asdflwerewdia",
"links": {
"next": "https://v3.api.hypertrack.com/devices/?pagination_token=asdflwerewdia"
}
Get list of devices in your account (excludes deleted devices)
GET /devices
Query Parameters
metadata_filter(optional)- a URL encoded string for JSON metadata to search for matching keys and values for devices associated with your account.last_updated_since(optional) - an ISO 8601 date and time string to get devices since last update timestamp.name_filter(optional) - string of the name of the device to search fortracking_status(optional) - valid options areallto get all devices (default API behavior) in your account andall_trackedto get all devices that are intended to be tracked.
Authentication: Basic Auth or OAuth Token
Response Attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique device identifier, case sensitive |
| location | object | (optional) |
| location.speed | float | (optional) speed in m/s |
| location.accuracy | float | (optional) accuracy in m |
| location.bearing | float | (optional) bearing in degrees starting at due north and continuing clockwise around the compass |
| location.geometry | object | Location in GeoJSON format |
| location.geometry.type | string | As of right now, only Point is supported |
| location.geometry.coordinates | array | Array of longitude, latitude and optional altitude |
| location.recorded_at | string | ISO 8601 date when the location was recorded |
| device_status | object | Device status. |
| device_status.value | string | Can be one of active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status. |
| device_status.data | object | Extra information about device status |
| device_status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| device_status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| device_status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| battery | object | Battery data |
| battery.battery_percent | object | Battery percentage of the device at battery.recorded_at time |
| battery.recorded_at | object | Client timestamp when battery measurement was taken |
| device_info | object | Device information |
| device_info.timezone | string | The timezone on the device in TZ format |
| device_info.os_name | string | The operating system of the device, can be one of iOS or Android |
| device_info.device_brand | string | The brand of the device |
| device_info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| device_info.device_model | string | The device model |
| device_info.network_operator | string | The network operator for the device |
| device_info.os_version | string | The version of the operating system on the device |
| device_info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| metadata | object | Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API |
| registered_at | string | ISO 8601 date when the device was registered |
| name | object | The name of the device submitted via Mobile SDKs (Android, iOS) or Devices API |
Get device location and status
Get device location and status example:
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.get(deviceId).then(device => {
// Process device
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
device = hypertrack.devices.get({deviceId})
print(device)
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/devices/{device_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/devices/{device_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/devices/{device_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
HTTP 200 - Single device payload
{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"location": {
"speed": 4.20,
"accuracy": 14.09,
"bearing": 193.12,
"geometry": {
"type": "Point",
"coordinates": [
35.1016383,
47.8391314,
65.40
]
},
"recorded_at": "2019-07-18T18:01:59.064000Z",
},
"device_status": {
"data": {
"recorded_at": "2019-07-30T01:38:45.610000Z",
"activity": "stop"
},
"value": "active"
},
"battery": "normal",
"device_info": {
"timezone": "America/Los_Angeles",
"os_name": "iOS",
"device_brand": "Apple",
"sdk_version": "3.3.2",
"device_model": "iPhone X",
"network_operator": "T-Mobile",
"name": "Alex’s Phone",
"os_version": "12.4"
},
"registered_at": "2019-07-10T01:38:45.610000Z",
"metadata": { ... }
}
Get live location and status of a device in a single API call.
If you need to stream live location updates to your own server backend, please use webhooks instead of repeated calls to Device API as explained here.
If you would like to create compelling live tracking experiences for your devices in a real-time dashboard, please check out this guide. With custom tracking views, you create real-time views for your customers without having to either call Devices API or provision your own server infrastructure to stream location data to your backend.
GET /devices/{device_id}
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of a tracked device, case sensitive
Response Attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique device identifier, case sensitive |
| location | object | (optional) |
| location.speed | float | (optional) speed in m/s |
| location.accuracy | float | (optional) accuracy in m |
| location.bearing | float | (optional) bearing in degrees starting at due north and continuing clockwise around the compass |
| location.geometry | object | Location in GeoJSON format |
| location.geometry.type | string | As of right now, only Point is supported |
| location.geometry.coordinates | array | Array of longitude, latitude and optional altitude |
| location.recorded_at | string | ISO 8601 date when the location was recorded |
| device_status | object | Device status. |
| device_status.value | string | Can be one of active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status. |
| device_status.data | object | Extra information about device status |
| device_status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| device_status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| device_status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| battery | object | Battery data |
| battery.battery_percent | object | Battery percentage of the device at battery.recorded_at time |
| battery.recorded_at | object | Client timestamp when battery measurement was taken |
| device_info | object | Device information |
| device_info.timezone | string | The timezone on the device in TZ format |
| device_info.os_name | string | The operating system of the device, can be one of iOS or Android |
| device_info.device_brand | string | The brand of the device |
| device_info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| device_info.device_model | string | The device model |
| device_info.network_operator | string | The network operator for the device |
| device_info.os_version | string | The version of the operating system on the device |
| device_info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| metadata | object | Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API |
| registered_at | string | ISO 8601 date when the device was registered |
| name | object | The name of the device submitted via Mobile SDKs (Android, iOS) or Devices API |
Get device history
Get single device history example:
curl \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/devices/{device_id}/history/{date}?timezone=Europe%2FZaporozhye'
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.getHistory(deviceId, "2020-03-17").then(history => {
// Process device history
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
"""
Arguments:
- device_id: string
- history_date - may be string in format "YYYY-mm-dd or python date/datetime object"
"""
device_history = hypertrack.devices.get_history(device_id, "2020-03-17")
print(device_history)
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/devices/{device_id}/history/{date}")
.get()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices/{device_id}/history/{date}';
$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/devices/{device_id}/history/{date}")
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
HTTP 200 - Single device history response
{
"name": "Mary Poppins"
"device_id": "9B207303-035B-49F9-977D-411AD31788CB",
"locations": {"type": "LineString", "coordinates": []},
"markers": [
{
"type": "device_status",
"data": {
"start": {
"recorded_at": "2021-03-02T00:00:00.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:39:51.002000Z"
}
},
"end": {
"recorded_at": "2021-03-03T00:00:00.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3934, 37.7942]
},
"recorded_at": "2019-09-13T19:40:51.002000Z"
}
},
"duration": 86400,
"value": "inactive",
"reason": "stopped_programmatically"
},
"marker_id": "3b0bf6a4-b584-41b7-acc7-e696bc0454d9"
}
],
"started_at": "2021-03-02T00:00:00.000Z",
"completed_at": "2021-03-03T00:00:00.000Z",
"distance": 0,
"duration": 0,
"steps": 0,
"tracking_rate": 0,
"inactive_reasons": [],
"inactive_duration": 0,
"active_duration": 0,
"stop_duration": 0,
"walk_duration": 0,
"drive_duration": 0
"geotags": 0,
"geofences_visited": 0
}
Get location history of device. The data follows the summary format.
GET /devices/{device_id}/history/{date}
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of a tracked device, case sensitive
date - a string representing specific date in UTC format YYYY-MM-DD
Query string parameters
timezone - timezone string to get device history for different timezones (example: 'Europe/Zaporozhye')
The response includes:
| Field | Description |
|---|---|
| name | Name associated with the driver |
| device_id | Device Identifier that uniquely identifies a device within HyperTrack |
| tracking_rate | Percentage of the time when device was tracked, relative to the time you intended to track the device that day. Disabling permissions for example would reduce the percentage. Use this to review devices that did not track as intended, understand the reasons why, and take corrective action. |
| geotags | Number of geotag events sent. The number of markers depends on your use case and implementation. Use this to review how much work was done by each user. |
| geotags_route_to_duration | Amount of time (in seconds) the user was en-route to geotags. (field only shows when there was at least one geotag sent) |
| geofences_visited | Number of geofences visited by this user. |
| geofences_visited_duration | Amount of time (in seconds) the user spent at geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_duration | Amount of time (in seconds) the user was en-route to geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_idle_time | Amount of time (in seconds) the user was stopped while en-route to geofences. (field only shows when there was at least one geofence visited) |
| active_duration | Amount of time (in seconds) the user was active. |
| inactive_duration | Amount of time (in seconds) the user was inactive. |
| stop_duration | Amount of time (in seconds) the user was stopped. Use this to review time spent at work or customer locations. |
| walk_duration | Amount of time (in seconds) the user was walking. |
| drive_duration | Amount of time (in seconds) the user was driving. |
| steps | Total steps walked by the driver on this day. Use this to review the amount of movement at work or customer locations. |
| distance | Total distance travelled by the driver on this day. Use this to review expenses, payouts and reimbursements related to distance driven. |
| duration | Total duration for which the driver was tracked on this day. |
| locations | Object representing the location time series of the trips. Follows GeoJSON geometry of type LineString |
| markers | Array of markers |
Get device history within a time range
Get single device history within a time range example:
curl \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/devices/{device_id}/history?from={from}&to={to}'
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.getHistory(deviceId, {from}, {to}).then(history => {
// Process device history
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
"""
Arguments:
- device_id: string
- from: string
- to: string
"""
device_history = hypertrack.devices.get_history(device_id, from, to)
print(device_history)
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/devices/{device_id}/history?from={from}&to={to}")
.get()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices/{device_id}/history?from={from}&to={to}';
$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/devices/{device_id}/history?from={from}&to={to}")
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
HTTP 200 - Single device history within time range response
{
"name": "Mary Poppins"
"device_id": "9B207303-035B-49F9-977D-411AD31788CB",
"locations": {"type": "LineString", "coordinates": []},
"markers": [
{
"type": "device_status",
"data": {
"start": {
"recorded_at": "2021-03-02T00:00:00.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:39:51.002000Z"
}
},
"end": {
"recorded_at": "2021-03-03T00:00:00.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3934, 37.7942]
},
"recorded_at": "2019-09-13T19:40:51.002000Z"
}
},
"duration": 86400,
"value": "inactive",
"reason": "stopped_programmatically"
},
"marker_id": "3b0bf6a4-b584-41b7-acc7-e696bc0454d9"
}
],
"started_at": "2021-03-02T00:00:00.000Z",
"completed_at": "2021-03-03T00:00:00.000Z",
"distance": 0,
"duration": 0,
"steps": 0,
"tracking_rate": 0,
"inactive_reasons": [],
"inactive_duration": 0,
"active_duration": 0,
"stop_duration": 0,
"walk_duration": 0,
"drive_duration": 0
"geotags": 0,
"geofences_visited": 0
}
Get location history of device within a time range.
GET /devices/{device_id}/history?from={from}&to={to}
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of a tracked device, case sensitive
Query string parameters
from - ISO 8601 timestamp indicating the start of the time range
to - ISO 8601 timestamp indicating the end of the time range
The response includes:
| Field | Description |
|---|---|
| name | Name associated with the driver |
| device_id | Device Identifier that uniquely identifies a device within HyperTrack |
| tracking_rate | Percentage of the time when device was tracked, relative to the time you intended to track the device that day. Disabling permissions for example would reduce the percentage. Use this to review devices that did not track as intended, understand the reasons why, and take corrective action. |
| geotags | Number of geotag events sent. The number of markers depends on your use case and implementation. Use this to review how much work was done by each user. |
| geotags_route_to_duration | Amount of time (in seconds) the user was en-route to geotags. (field only shows when there was at least one geotag sent) |
| geofences_visited | Number of geofences visited by this user. |
| geofences_visited_duration | Amount of time (in seconds) the user spent at geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_duration | Amount of time (in seconds) the user was en-route to geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_idle_time | Amount of time (in seconds) the user was stopped while en-route to geofences. (field only shows when there was at least one geofence visited) |
| active_duration | Amount of time (in seconds) the user was active. |
| inactive_duration | Amount of time (in seconds) the user was inactive. |
| stop_duration | Amount of time (in seconds) the user was stopped. Use this to review time spent at work or customer locations. |
| walk_duration | Amount of time (in seconds) the user was walking. |
| drive_duration | Amount of time (in seconds) the user was driving. |
| steps | Total steps walked by the driver on this day. Use this to review the amount of movement at work or customer locations. |
| distance | Total distance travelled by the driver on this day. Use this to review expenses, payouts and reimbursements related to distance driven. |
| duration | Total duration for which the driver was tracked on this day. |
| locations | Object representing the location time series of the trips. Follows GeoJSON geometry of type LineString |
| markers | Array of markers |
Export account data
Export account data example:
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/history/{date}
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.getAccountHistory("2020-02-20").then(history => {
// Process history
}).catch(error => {
// Error handling
})
import requests
ACCOUNT_ID = {AccountId}
SECRET_KEY = {SecretKey}
response = requests.get(f"https://v3.api.hypertrack.com/devices/history/2020-02-20",
json={},
headers={'Content-Type': 'application/json'},
auth=(ACCOUNT_ID, SECRET_KEY))
print(response.json())
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/devices/history/{date}")
.get()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices/history/{date}';
$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/devices/history/{date}")
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
Get data for all tracked devices for a specified day. Data is available for the the last 60 days, excluding today.
GET /devices/history/{date}
HTTP 200 - Devices history response
{
"url": "https://live-misc.s3.amazonaws.com/device-leaderboard-api/42256004-3cee-4953-883c-1f57f0e602c9/2020-02-20T00%3A00%3A00%2B00%3A00-2020-02-21T00%3A00%3A00%2B00%3A00-28f53956-4b94-45f2-b3ac-7d944a7e7bc1.json.gz?AWSAccessKeyId=123&Signature=123%2B6ZYezNLickN%2FTK%2BX4&Expires=1591142754"
}
Authentication: Basic Auth or OAuth Token
Path Parameters
date - a string representing specific date in UTC format YYYY-MM-DD
JSON sample of file content
[
{
"name": "Mary Poppins"
"device_id": "9B207303-035B-49F9-977D-411AD31788CB",
"locations": {"type": "LineString", "coordinates": []},
"markers": [
{
"type": "device_status",
"data": {
"start": {
"recorded_at": "2021-03-02T00:00:00.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:39:51.002000Z"
}
},
"end": {
"recorded_at": "2021-03-03T00:00:00.000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3934, 37.7942]
},
"recorded_at": "2019-09-13T19:40:51.002000Z"
}
},
"duration": 86400,
"value": "inactive",
"reason": "stopped_programmatically"
},
"marker_id": "3b0bf6a4-b584-41b7-acc7-e696bc0454d9"
}
],
"started_at": "2021-03-02T00:00:00.000Z",
"completed_at": "2021-03-03T00:00:00.000Z",
"distance": 0,
"duration": 0,
"steps": 0,
"tracking_rate": 0,
"inactive_reasons": [],
"inactive_duration": 0,
"active_duration": 0,
"stop_duration": 0,
"walk_duration": 0,
"drive_duration": 0
"trips": [
{
"trip_id": "61f658c5-14ba-4f2e-b38c-3ff830688737",
"started_at": "2021-03-02T03:02:08.064Z",
"completed_at": "2021-03-03T03:25:29.895Z",
"device_id": "9B207303-035B-49F9-977D-411AD31788CB",
"views": {
"embed_url": "https://embed.hypertrack.com/trips/61f658c5-14ba-4f2e-b38c-3ff830688737?publishable_key=xyz",
"share_url": "https://trck.at/xyz"
},
"metadata": null,
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.393197, 37.787077]
},
"radius": 30,
"scheduled_at": null,
"arrived_at": null,
"exited_at": null
}
}
],
"geotags": 0,
"geofences_visited": 0
}...
]
The API call returns a pre-signed URL that you can easily download. The link is valid for 60min after calling the API. The json file contains a json array, with each item representing one driver. Each user contains the following fields:
| Field | Description |
|---|---|
| name | Name associated with the driver |
| device_id | Device Identifier that uniquely identifies a device within HyperTrack |
| tracking_rate | Percentage of the time when device was tracked, relative to the time you intended to track the device that day. Disabling permissions for example would reduce the percentage. Use this to review devices that did not track as intended, understand the reasons why, and take corrective action. |
| geotags | Number of geotag events sent. The number of markers depends on your use case and implementation. Use this to review how much work was done by each user. |
| geotags_route_to_duration | Amount of time (in seconds) the user was en-route to geotags. (field only shows when there was at least one geotag sent) |
| geofences_visited | Number of geofences visited by this user. |
| geofences_visited_duration | Amount of time (in seconds) the user spent at geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_duration | Amount of time (in seconds) the user was en-route to geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_idle_time | Amount of time (in seconds) the user was stopped while en-route to geofences. (field only shows when there was at least one geofence visited) |
| trips | Data for trips created for this user. |
| trips_destinations_visited | Total trips that had destinations visited. (field only shows when there was at least one trip created) |
| trips_destinations_delayed | Total trips that had delayed visits to their destinations. (field only shows when there was at least one trip created) |
| trips_destinations_deviated | Total trips that had deviated completion location in relation to their destination location. (field only shows when there was at least one trip created) |
| trips_estimated_distance | Total estimated distance for all trips created for this driver. (field only shows when there was at least one trip created) |
| active_duration | Amount of time (in seconds) the user was active. |
| inactive_duration | Amount of time (in seconds) the user was inactive. |
| stop_duration | Amount of time (in seconds) the user was stopped. Use this to review time spent at work or customer locations. |
| walk_duration | Amount of time (in seconds) the user was walking. |
| drive_duration | Amount of time (in seconds) the user was driving. |
| steps | Total steps walked by the driver on this day. Use this to review the amount of movement at work or customer locations. |
| distance | Total distance travelled by the driver on this day. Use this to review expenses, payouts and reimbursements related to distance driven. |
| duration | Total duration for which the driver was tracked on this day. |
| locations | Object representing the location time series of the trips. Follows GeoJSON geometry of type LineString |
| markers | Array of markers |
Export account data for a date range
Export account data example:
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/history?from_date={from_date}&to_date={to_date}
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.getAccountHistoryForTimeRange("2021-09-10", "2021-09-20").then(history => {
// Process history
}).catch(error => {
// Error handling
})
import requests
ACCOUNT_ID = {AccountId}
SECRET_KEY = {SecretKey}
response = requests.get(f"https://v3.api.hypertrack.com/devices/history?from_date=2021-09-10&to_date=2021-09-20",
json={},
headers={'Content-Type': 'application/json'},
auth=(ACCOUNT_ID, SECRET_KEY))
print(response.json())
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/devices/history?from_date={from_date}&to_date={to_date}")
.get()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices/history?from_date={from_date}&to_date={to_date}';
$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/devices/history?from_date={from_date}&to_date={to_date}")
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
Authentication: Basic Auth or OAuth Token
Query string parameters
from_date - Date String indicating the start of the time range
to_date - Date String indicating the end of the time range
JSON sample of file content
[
{
"name": "Alex ",
"tracking_rate": 100.0,
"duration": 73950,
"distance": 42708,
"inactive_reasons": [],
"inactive_duration": 0,
"active_duration": 73950,
"stop_duration": 64999,
"drive_duration": 7240,
"walk_duration": 1711,
"steps": 121,
"trips": 0,
"trips_destinations_visited": 0,
"trips_destinations_delayed": 0,
"trips_destinations_deviated": 0,
"trips_estimated_distance": 0,
"geotags": 0,
"geotags_route_to_duration": 0,
"geofences_visited": 0,
"geofences_visited_duration": 0,
"geofences_route_to_duration": 0,
"geofences_route_to_idle_time": 0,
"date": "2021-09-03"
}, {
"name": "Eugene",
"tracking_rate": 100.0,
"duration": 36216,
"distance": 25675,
"inactive_reasons": [],
"inactive_duration": 0,
"active_duration": 36216,
"stop_duration": 29426,
"drive_duration": 4804,
"walk_duration": 1986,
"steps": 282888,
"trips": 0,
"trips_destinations_visited": 0,
"trips_destinations_delayed": 0,
"trips_destinations_deviated": 0,
"trips_estimated_distance": 0,
"geotags": 0,
"geotags_route_to_duration": 0,
"geofences_visited": 0,
"geofences_visited_duration": 0,
"geofences_route_to_duration": 0,
"geofences_route_to_idle_time": 0,
"date": "2021-09-03"
},...
]
The API call returns a pre-signed URL that you can easily download. The link is valid for 60min after calling the API. The json file contains a json array, with each item representing one driver. Each user contains the following fields:
| Field | Description |
|---|---|
| name | Name associated with the driver |
| device_id | Device Identifier that uniquely identifies a device within HyperTrack |
| tracking_rate | Percentage of the time when device was tracked, relative to the time you intended to track the device that day. Disabling permissions for example would reduce the percentage. Use this to review devices that did not track as intended, understand the reasons why, and take corrective action. |
| geotags | Number of geotag events sent. The number of markers depends on your use case and implementation. Use this to review how much work was done by each user. |
| geotags_route_to_duration | Amount of time (in seconds) the user was en-route to geotags. (field only shows when there was at least one geotag sent) |
| geofences_visited | Number of geofences visited by this user. |
| geofences_visited_duration | Amount of time (in seconds) the user spent at geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_duration | Amount of time (in seconds) the user was en-route to geofences. (field only shows when there was at least one geofence visited) |
| geofences_route_to_idle_time | Amount of time (in seconds) the user was stopped while en-route to geofences. (field only shows when there was at least one geofence visited) |
| active_duration | Amount of time (in seconds) the user was active. |
| inactive_duration | Amount of time (in seconds) the user was inactive. |
| stop_duration | Amount of time (in seconds) the user was stopped. Use this to review time spent at work or customer locations. |
| walk_duration | Amount of time (in seconds) the user was walking. |
| drive_duration | Amount of time (in seconds) the user was driving. |
| steps | Total steps walked by the driver on this day. Use this to review the amount of movement at work or customer locations. |
| distance | Total distance travelled by the driver on this day. Use this to review expenses, payouts and reimbursements related to distance driven. |
| duration | Total duration for which the driver was tracked on this day |
| date | Date for which data was asked for |
Delete device
Delete single device example:
curl -X DELETE \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.delete(deviceId).then(() => {
// Device deleted
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.devices.delete({deviceId})
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/devices/{device_id}")
.delete(null)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
url = 'https://v3.api.hypertrack.com/devices/{device_id}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"method" => "DELETE",
"http" => [
"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/devices/{device_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Delete a device. Once deleted, the device will not be able send location data again. Deleted devices can be undeleted with an Undelete Device API call as described below.
DELETE /devices/{device_id}
HTTP 204 - Device removed (no content)
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of a tracked device, case sensitive
Query Parameters
full_deletion=true - for privacy related deletion requests (e.g., GDPR). If this is set, tracking of the device will stop immediately and all the data for this device will be deleted within 30 days of receiving the request. To enable this feature, please reach out to us via email.
Undelete device
Undelete single device example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}/undelete
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.devices.undelete(deviceId).then(() => {
// Device deleted
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.devices.undelete({deviceId})
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/devices/{device_id}/undelete")
.post(null)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/devices/{device_id}/undelete';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"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/devices/{device_id}/undelete")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Undelete a previously deleted device. Once the device undeleted, it can track again.
POST /devices/{device_id}/undelete
HTTP 200 - Device undeleted (no content)
Authentication: Basic Auth or OAuth Token
Path Parameters
device_id - a string representing the ID of a device that was previously deleted, case sensitive
Generate invitation links
Generate invitation links example request with its response below:
payload='{
"metadata":
[
{"driver_id": "ABC1"},
{"driver_id": "ABC2"},
{"driver_id": "ABC3"}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/invitation_links
-H "Content-Type: application/json" \
-d $payload
[
{
"url": "https://hypertrack-logistics.app.link/2peqNytrWab",
"metadata": {"driver_id": "ABC1"}},
{
"url": "https://hypertrack-logistics.app.link/3peqNytrWab",
"metadata": {"driver_id": "ABC2"}
},
{
"url": "https://hypertrack-logistics.app.link/4peqNytrWab",
"metadata": {"driver_id": "ABC3"}
}
]
payload='{
"metadata":
[
{"driver_id": "ABC1"},
{"driver_id": "ABC2"},
{"driver_id": "ABC3"}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/invitation_links
-H "Content-Type: application/json" \
-d $payload
[
{
"url": "https://hypertrack-logistics.app.link/2peqNytrWab",
"metadata": {"driver_id": "ABC1"}},
{
"url": "https://hypertrack-logistics.app.link/3peqNytrWab",
"metadata": {"driver_id": "ABC2"}
},
{
"url": "https://hypertrack-logistics.app.link/4peqNytrWab",
"metadata": {"driver_id": "ABC3"}
}
]
payload='{
"metadata":
[
{"driver_id": "ABC1"},
{"driver_id": "ABC2"},
{"driver_id": "ABC3"}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/invitation_links
-H "Content-Type: application/json" \
-d $payload
[
{
"url": "https://hypertrack-logistics.app.link/2peqNytrWab",
"metadata": {"driver_id": "ABC1"}},
{
"url": "https://hypertrack-logistics.app.link/3peqNytrWab",
"metadata": {"driver_id": "ABC2"}
},
{
"url": "https://hypertrack-logistics.app.link/4peqNytrWab",
"metadata": {"driver_id": "ABC3"}
}
]
payload='{
"metadata":
[
{"driver_id": "ABC1"},
{"driver_id": "ABC2"},
{"driver_id": "ABC3"}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/invitation_links
-H "Content-Type: application/json" \
-d $payload
[
{
"url": "https://hypertrack-logistics.app.link/2peqNytrWab",
"metadata": {"driver_id": "ABC1"}},
{
"url": "https://hypertrack-logistics.app.link/3peqNytrWab",
"metadata": {"driver_id": "ABC2"}
},
{
"url": "https://hypertrack-logistics.app.link/4peqNytrWab",
"metadata": {"driver_id": "ABC3"}
}
]
payload='{
"metadata":
[
{"driver_id": "ABC1"},
{"driver_id": "ABC2"},
{"driver_id": "ABC3"}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/invitation_links
-H "Content-Type: application/json" \
-d $payload
[
{
"url": "https://hypertrack-logistics.app.link/2peqNytrWab",
"metadata": {"driver_id": "ABC1"}},
{
"url": "https://hypertrack-logistics.app.link/3peqNytrWab",
"metadata": {"driver_id": "ABC2"}
},
{
"url": "https://hypertrack-logistics.app.link/4peqNytrWab",
"metadata": {"driver_id": "ABC3"}
}
]
payload='{
"metadata":
[
{"driver_id": "ABC1"},
{"driver_id": "ABC2"},
{"driver_id": "ABC3"}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/invitation_links
-H "Content-Type: application/json" \
-d $payload
[
{
"url": "https://hypertrack-logistics.app.link/2peqNytrWab",
"metadata": {"driver_id": "ABC1"}},
{
"url": "https://hypertrack-logistics.app.link/3peqNytrWab",
"metadata": {"driver_id": "ABC2"}
},
{
"url": "https://hypertrack-logistics.app.link/4peqNytrWab",
"metadata": {"driver_id": "ABC3"}
}
]
Generate unique invitation links that you can use to invite your drivers to download HyperTrack Visits App via your preferred approach which may include email, SMS, etc. Once your driver downloads HyperTrack Visits App, it will be automatically connected to your HyperTrack account and have metadata assigned by you.
POST /devices/invitation_links
Authentication: Basic Auth or OAuth Token
Invite users to install Visits App
Generate invitation links example request with its response below:
payload='
[
{
"email":"alex@example.com",
"metadata":[
{
"driver_id":"delivery_driver_ABC121"
}
]
},
{
"email":"denys@example.com",
"metadata":[
{
"driver_id":"delivery_driver_ABC122"
}
]
}
]
'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/invite
-H "Content-Type: application/json" \
-d $payload
Use this API to send multiple email invitations to drivers to download and install Visits App. Each user can install and download with metadata assigned by you for each user from unique links sent in the invitations emails.
POST /devices/invite
Authentication: Basic Auth or OAuth Token
Set available devices
Set devices as available using a profile filter example:
payload='{
"profile_filter": {
"store_id": "S11223"
}
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/available
-d $payload
Make one or more devices available for nearby search using the API. When the payload parameters are not provided, all devices are made available.
POST /devices/available
Authentication: Basic Auth or OAuth Token
Payload Parameters
device_ids - array of strings representing the ID of devices [The device_id must be all caps]
profile_filter - JSON object with key-value pair that can be used to set availability for a subset of devices based on the device profile
Response Attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique device identifier, case sensitive |
| location | object | (optional) |
| location.speed | float | (optional) speed in m/s |
| location.accuracy | float | (optional) accuracy in m |
| location.bearing | float | (optional) bearing in degrees starting at due north and continuing clockwise around the compass |
| location.geometry | object | Location in GeoJSON format |
| location.geometry.type | string | As of right now, only Point is supported |
| location.geometry.coordinates | array | Array of longitude, latitude and optional altitude |
| location.recorded_at | string | ISO 8601 date when the location was recorded |
| device_status | object | Device status. |
| device_status.value | string | Can be one of active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status. |
| device_status.data | object | Extra information about device status |
| device_status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| device_status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| device_status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| battery | object | Battery data |
| battery.battery_percent | object | Battery percentage of the device at battery.recorded_at time |
| battery.recorded_at | object | Client timestamp when battery measurement was taken |
| device_info | object | Device information |
| device_info.timezone | string | The timezone on the device in TZ format |
| device_info.os_name | string | The operating system of the device, can be one of iOS or Android |
| device_info.device_brand | string | The brand of the device |
| device_info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| device_info.device_model | string | The device model |
| device_info.network_operator | string | The network operator for the device |
| device_info.os_version | string | The version of the operating system on the device |
| device_info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| metadata | object | Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API |
| registered_at | string | ISO 8601 date when the device was registered |
| name | object | The name of the device submitted via Mobile SDKs (Android, iOS) or Devices API |
Set unavailable devices
Set devices as unavailable using a profile filter example:
payload='{
"profile_filter": {
"store_id": "S11223"
}
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/unavailable
-d $payload
Make one or more devices unavailable for nearby search using the API. When the payload parameters are not provided, all devices are made unavailable.
POST /devices/unavailable
Authentication: Basic Auth or OAuth Token
Payload Parameters
device_ids - array of strings representing the ID of devices [The device_id must be all caps]
profile_filter - JSON object with key-value pair that can be used to set availability for a subset of devices based on the device profile
Response Attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique device identifier, case sensitive |
| location | object | (optional) |
| location.speed | float | (optional) speed in m/s |
| location.accuracy | float | (optional) accuracy in m |
| location.bearing | float | (optional) bearing in degrees starting at due north and continuing clockwise around the compass |
| location.geometry | object | Location in GeoJSON format |
| location.geometry.type | string | As of right now, only Point is supported |
| location.geometry.coordinates | array | Array of longitude, latitude and optional altitude |
| location.recorded_at | string | ISO 8601 date when the location was recorded |
| device_status | object | Device status. |
| device_status.value | string | Can be one of active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status. |
| device_status.data | object | Extra information about device status |
| device_status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| device_status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| device_status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| battery | object | Battery data |
| battery.battery_percent | object | Battery percentage of the device at battery.recorded_at time |
| battery.recorded_at | object | Client timestamp when battery measurement was taken |
| device_info | object | Device information |
| device_info.timezone | string | The timezone on the device in TZ format |
| device_info.os_name | string | The operating system of the device, can be one of iOS or Android |
| device_info.device_brand | string | The brand of the device |
| device_info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| device_info.device_model | string | The device model |
| device_info.network_operator | string | The network operator for the device |
| device_info.os_version | string | The version of the operating system on the device |
| device_info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| metadata | object | Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API |
| registered_at | string | ISO 8601 date when the device was registered |
| name | object | The name of the device submitted via Mobile SDKs (Android, iOS) or Devices API |
Get available devices
GET available devices filtered on device_ids example:
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/available?device_ids=["00112233-000D-4ABD-9FF8-CBBB4BEFBB1C"]
-d $payload
Get one or more available devices using the API. When the query parameters are not provided, all available devices are returned.
GET /devices/available
Authentication: Basic Auth or OAuth Token
Query Parameters
device_ids- (optional) array of strings representing the ID of devices [The device_id must be all caps] - e.g. ['00112233-000D-4ABD-9FF8-CBBB4BEFBB1C']profile_filter- (optional) JSON object with key-value pair that can be used to set availability for a subset of devices based on the device profile - e.g {'store_id': 'S1223'}
Response Attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique device identifier, case sensitive |
| location | object | (optional) |
| location.speed | float | (optional) speed in m/s |
| location.accuracy | float | (optional) accuracy in m |
| location.bearing | float | (optional) bearing in degrees starting at due north and continuing clockwise around the compass |
| location.geometry | object | Location in GeoJSON format |
| location.geometry.type | string | As of right now, only Point is supported |
| location.geometry.coordinates | array | Array of longitude, latitude and optional altitude |
| location.recorded_at | string | ISO 8601 date when the location was recorded |
| device_status | object | Device status. |
| device_status.value | string | Can be one of active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status. |
| device_status.data | object | Extra information about device status |
| device_status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| device_status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| device_status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| battery | object | Battery data |
| battery.battery_percent | object | Battery percentage of the device at battery.recorded_at time |
| battery.recorded_at | object | Client timestamp when battery measurement was taken |
| device_info | object | Device information |
| device_info.timezone | string | The timezone on the device in TZ format |
| device_info.os_name | string | The operating system of the device, can be one of iOS or Android |
| device_info.device_brand | string | The brand of the device |
| device_info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| device_info.device_model | string | The device model |
| device_info.network_operator | string | The network operator for the device |
| device_info.os_version | string | The version of the operating system on the device |
| device_info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| metadata | object | Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API |
| registered_at | string | ISO 8601 date when the device was registered |
| name | object | The name of the device submitted via Mobile SDKs (Android, iOS) or Devices API |
Get unavailable devices
GET unavailable devices filtered on device_ids example:
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/unavailable?device_ids=["00112233-000D-4ABD-9FF8-CBBB4BEFBB1C"]
-d $payload
Get one or more unavailable devices using the API. When the query parameters are not provided, all unavailable devices are returned.
GET /devices/unavailable
Authentication: Basic Auth or OAuth Token
Query Parameters
device_ids- (optional) array of strings representing the ID of devices [The device_id must be all caps] - e.g. ['00112233-000D-4ABD-9FF8-CBBB4BEFBB1C']profile_filter- (optional) JSON object with key-value pair that can be used to set availability for a subset of devices based on the device profile - e.g {'store_id': 'S1223'}
Response Attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique device identifier, case sensitive |
| location | object | (optional) |
| location.speed | float | (optional) speed in m/s |
| location.accuracy | float | (optional) accuracy in m |
| location.bearing | float | (optional) bearing in degrees starting at due north and continuing clockwise around the compass |
| location.geometry | object | Location in GeoJSON format |
| location.geometry.type | string | As of right now, only Point is supported |
| location.geometry.coordinates | array | Array of longitude, latitude and optional altitude |
| location.recorded_at | string | ISO 8601 date when the location was recorded |
| device_status | object | Device status. |
| device_status.value | string | Can be one of active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status. |
| device_status.data | object | Extra information about device status |
| device_status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| device_status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| device_status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| battery | object | Battery data |
| battery.battery_percent | object | Battery percentage of the device at battery.recorded_at time |
| battery.recorded_at | object | Client timestamp when battery measurement was taken |
| device_info | object | Device information |
| device_info.timezone | string | The timezone on the device in TZ format |
| device_info.os_name | string | The operating system of the device, can be one of iOS or Android |
| device_info.device_brand | string | The brand of the device |
| device_info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| device_info.device_model | string | The device model |
| device_info.network_operator | string | The network operator for the device |
| device_info.os_version | string | The version of the operating system on the device |
| device_info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| metadata | object | Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API |
| registered_at | string | ISO 8601 date when the device was registered |
| name | object | The name of the device submitted via Mobile SDKs (Android, iOS) or Devices API |
Drivers
Drivers API helps you manage your fleet on HyperTrack System
With Drivers API you can do the following
- Create and manage Drivers in the HyperTrack system
- Manage driver schedules to plan order scheduled in the future
Create Driver
POST /drivers
Authentication: Basic Auth or OAuth Token
Request Attributes for Create Driver API
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| driver_handle | string | Mandatory | Unique handle of the driver for identification purposes, the handle needs to be url safe and case insensitive |
| ops_group_handle | string | Optional | Unique handle for the ops group with which you want to map the driver with (mandatory) [You can associate a driver with a single group, if left out, driver is assigned to a default ops group] |
| name | string | Optional | Name of the driver |
| device_id | string | Optional | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device [This can be provided at later stage in case driver has not yet installed application] |
| home | object | Optional | Details of Driver Home [If ops group is setup such that Operations starts from Driver's home, then driver home needs to be set] |
| home.address | string | Optional | Address of driver home |
| home.geometry | object | Optional | Location in GeoJSON format |
| schedule | array | Optional | Array of schedule objects representing the driver's schedule (Optional) |
| schedule.date | date | Optional | Date represented as YYYY-MM-DD to indicate a schedule date |
| schedule.start_time | Timestring | Optional | Time string in (HH:MM) format indicating the time at which shift starts |
| schedule.end_time | Timestring | Optional | Time string in (HH:MM) format indicating the time at which shift ends |
| schedule.ops_group_handle | string | Optional | Unique handle for the ops group with which you want to map the driver within a shift (optional) |
| schedule.priority | string | Optional | Priority of a driver within a shift (optional) |
| schedule.day_of_week | string | Optional | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
| product_types | array | Optional | Product types associated with the driver, array of strings (product) |
| profile | object | Optional | Profile details (metadata) to be associated with driver |
| unavailable_on | array | Optional | List of dates (ISO 8601 date string) indicating leaves for a driver |
NOTE: Use a combination of date with start_time and end_time for daywise schedules and day_of_week with start_time and end_time for recurring schedules. A driver can have only 1 mode of schedule.
Create new driver request:
payload='{
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"driver_handle":"test1-driver-1",
"name": "Om Shah",
"home":{
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034",
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
}
},
"product_types":[
"Food"
],
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"profile":{
"name":"Test Driver A"
}
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
driver_data = {
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"driver_handle":"test1-driver-1",
"name": "Om Shah",
"home":{
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034",
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
}
},
"product_types":[
"Food"
],
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"profile":{
"name":"Test Driver A"
}
}
response = requests.post("https://v3.api.hypertrack.com/drivers",
json=driver_data,
headers=AUTH_HEADER)
HTTP 201 - New driver response
{
"driver_handle":"test1-driver-1",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"product_types":[
"Food"
],
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"name": "Om Shah",
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"home":{
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
},
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034"
},
"profile":{
"name":"Test Driver A"
},
"work_status":{
"available":false,
"tracking":false
},
"deleted":false,
"unavailable_on": ["2023-06-06"],
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| driver_handle | string | Unique handle of the driver for identification purposes which is case insensitive (mandatory) |
| ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with (mandatory) |
| device_id | string | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device (Optional) |
| name | string | Name of the driver |
| home | object | Details of Driver Home (optional) |
| home.address | string | Address of driver home (optional) |
| home.geometry | object | Location in GeoJSON format |
| schedule | array | Array of schedule objects representing the driver's schedule (Optional) |
| schedule.date | date | Date represented as YYYY-MM-DD to indicate a schedule date |
| schedule.start_time | Timestring | Time string in (HH:MM) format indicating the time at which shift starts |
| schedule.end_time | Timestring | Time string in (HH:MM) format indicating the time at which shift ends |
| schedule.ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with in a shift (optional) |
| schedule.priority | string | Priority of a driver within a shift (optional) |
| schedule.day_of_week | string | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
| product_types | array | Product types associated with the driver, array of strings (product) |
| profile | object | Profile details (metadata) to be associated with driver |
| work_status | object | Current working status of the driver |
| work_status.available | boolean | Whether the driver is available or not |
| work_status.tracking | boolean | Whether the driver is tracking or not |
| unavailable_on | array | List of dates (ISO 8601 date string) indicating leaves for a driver |
Update Driver
PATCH /drivers/{driver_handle}
Authentication: Basic Auth or OAuth Token
All the fields in update request are optional, pass only the field(s) you want to patch, other fields already present in driver will not be updated.
Request Attributes for Update Driver API
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| ops_group_handle | string | Optional | Unique handle for the ops group with which you want to map the driver with (mandatory) [You can only associate a single ops group with a driver] |
| device_id | string | Optional | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device [This can be provided at later stage in case driver has not yet installed application] |
| name | string | Optional | Name of the driver |
| home | object | Optional | Details of Driver Home [If ops group is setup such that Operations starts from Driver's home, then driver home needs to be set] |
| home.address | string | Optional | Address of driver home |
| home.geometry | object | Optional | Location in GeoJSON format |
| schedule | array | Optional | Array of schedule objects representing the driver's schedule (Optional) |
| schedule.date | date | Optional | Date represented as YYYY-MM-DD to indicate a schedule date |
| schedule.start_time | Timestring | Optional | Time string in (HH:MM) format indicating the time at which shift starts |
| schedule.end_time | Timestring | Optional | Time string in (HH:MM) format indicating the time at which shift ends |
| schedule.ops_group_handle | string | Optional | Unique handle for the ops group with which you want to map the driver with in a shift (optional) |
| schedule.priority | string | Optional | Priority of a driver within a shift (optional) |
| schedule.day_of_week | string | Optional | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
| product_types | array | Optional | Product types associated with the driver, array of strings (product) |
| profile | object | Optional | Profile details (metadata) to be associated with driver |
| unavailable_on | array | Optional | List of dates (ISO 8601 date string) indicating leaves for a driver |
NOTE: Use a combination of date with start_time and end_time for daywise schedules and day_of_week with start_time and end_time for recurring schedules. A driver can have only 1 mode of schedule.
Update driver request:
payload='{
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"name": "Om Shah",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"home":{
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034",
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
}
},
"product_types":[
"Food"
],
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"profile":{
"name":"Test Driver A"
},
"unavailable_on": ["2023-06-06"]
}'
curl -X PATCH \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/test-driver-1 \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
driver_data = {
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"name": "Om Shah",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"home":{
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034",
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
}
},
"product_types":[
"Food"
],
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"profile":{
"name":"Test Driver A"
},
"unavailable_on": ["2023-06-06"]
}
response = requests.patch("https://v3.api.hypertrack.com/drivers/test-driver-1",
json=driver_data,
headers=AUTH_HEADER)
HTTP 200 - updated driver response
{
"driver_handle":"test1-driver-1",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"product_types":[
"Food"
],
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"name": "Om Shah",
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"home":{
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
},
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034"
},
"profile":{
"name":"Test Driver A"
},
"work_status":{
"available":false,
"tracking":false
},
"deleted":false,
"unavailable_on": ["2023-06-06"],
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| driver_handle | string | Unique handle of the driver for identification purposes which is case insensitive (mandatory) |
| ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with (mandatory) |
| device_id | string | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device (Optional) |
| name | string | Name of the driver |
| home | object | Details of Driver Home (optional) |
| home.address | string | Address of driver home (optional) |
| home.geometry | object | Location in GeoJSON format |
| schedule | array | Array of schedule objects representing the driver's schedule (Optional) |
| schedule.date | date | Date represented as YYYY-MM-DD to indicate a schedule date |
| schedule.start_time | Timestring | Time string in (HH:MM) format indicating the time at which shift starts |
| schedule.end_time | Timestring | Time string in (HH:MM) format indicating the time at which shift ends |
| schedule.ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with in a shift (optional) |
| schedule.priority | string | Priority of a driver within a shift (optional) |
| schedule.day_of_week | string | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
| product_types | array | Product types associated with the driver, array of strings (product) |
| profile | object | Profile details (metadata) to be associated with driver |
| work_status | object | Current working status of the driver |
| work_status.available | boolean | Whether the driver is available or not |
| work_status.tracking | boolean | Whether the driver is tracking or not |
| unavailable_on | array | List of dates (ISO 8601 date string) indicating leaves for a driver |
Get Driver by Handle
GET /drivers/{driver_handle}
Authentication: Basic Auth or OAuth Token
This api returns the driver and all the devices that have been associated with this driver now or in past.
Get driver request:
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/test-driver-1 \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/drivers/test-driver-1",
headers=AUTH_HEADER)
HTTP 200 - get driver response
{
"driver_handle":"test-driver-1",
"ops_group_handle":"262e24e0-a227-48aa-b96d-abd8edf94bf5",
"product_types":[
"1",
"2"
],
"device_id":"00112233-99C8-42D3-B2F3-AD840229DF4E",
"name": "Om Shah",
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"home":{
"geometry":{
"coordinates":[
77.62323191601925,
12.975845440925694
],
"type":"Point"
},
"address":"Dummy driver address"
},
"profile":{
"dummy_key":"dummy_value"
},
"work_status":{
"available":true,
"tracking":false
},
"deleted":false,
"device_info": {
"timezone":"America/Los Angeles",
"os_version":"12.1.4",
"os_name":"iOS",
"device_model":"IPhone X",
"device_brand":"Apple",
"os_hardware_identifier":"4f8eb0f4-0b8c-40db-8c6b-e0c71d5940e8",
"name":"Func Test Device",
"sdk_version":"func test app",
"network_operator":"T-Mobile"
},
"location":{
"geometry":{
"type":"Point",
"coordinates":[
77.6699336128807,
12.918871943587638
]
}
},
"unavailable_on": ["2023-06-06"],
"device_status":{
"value":"available",
"data":{
"recorded_at":"2022-10-22T22:07:24.111Z"
}
}
"devices":[
{
"device_id":"00112233-99C8-42D3-B2F3-AD840229DF4E",
"start_time":"2022-10-22T22:07:22.795Z",
"end_time": "2022-10-27T22:05:12.884Z"
}
]
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| driver_handle | string | Unique handle of the driver for identification purposes and which is case insensitive (mandatory) |
| ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with (mandatory) |
| device_id | string | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device (Optional) |
| name | string | Name of the driver |
| home | object | Details of Driver Home (optional) |
| home.address | string | Address of driver home (optional) |
| home.geometry | object | Location in GeoJSON format |
| schedule | array | Array of schedule objects representing the driver's schedule (Optional) |
| schedule.date | date | Date represented as YYYY-MM-DD to indicate a schedule date |
| schedule.start_time | Timestring | Time string in (HH:MM) format indicating the time at which shift starts |
| schedule.end_time | Timestring | Time string in (HH:MM) format indicating the time at which shift ends |
| schedule.ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with in a shift (optional) |
| schedule.priority | string | Priority of a driver within a shift (optional) |
| schedule.day_of_week | string | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
| work_status | object | Current working status of the driver |
| work_status.available | boolean | Whether the driver is available or not |
| work_status.tracking | boolean | Whether the driver is tracking or not |
| profile | object | Profile details (metadata) to be associated with driver |
| device_info | object | device_info. same fields supports as in devices api |
| device_info.timezone | string | The timezone on the device in TZ format |
| device_info.os_name | string | The operating system of the device, can be one of iOS or Android |
| device_info.device_brand | string | The brand of the device |
| device_info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| device_info.device_model | string | The device model |
| device_info.network_operator | string | The network operator for the device |
| device_info.os_version | string | The version of the operating system on the device |
| device_info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| device_info.name | string | Name of the device |
| device_status | object | Linked Device status. |
| device_status.value | string | Can be one of active, inactive, disconnected, available or unavailable. Please read here to understand how HyperTrack tracks device status. |
| device_status.data | object | Extra information about device status |
| device_status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| device_status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| device_status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| location | object | location of the driver |
| location.geometry.type | string | as of right now, only Point is supported |
| location.geometry.coordinates | array | array of longitude, latitude and (optional) altitude |
| unavailable_on | array | List of dates (ISO 8601 date string) indicating leaves for a driver |
| devices | array | list of devices that is associated with driver or were associated with driver |
| devices.device | object | A device that is associated with driver or was associated with driver |
| devices.device.device_id | string | Id of the device |
| devices.device.start_time | string | ISO8601 format date when the device was associated with this driver |
| devices.device.end_time | string | ISO8601 format date when the device was disassociated with this driver |
List Drivers
GET /drivers
query parameters
| Name | Type | Description |
|---|---|---|
| ops_group_handle | string | handle of the ops group where the drivers will be searched in |
| profile | object | fields in profile that must match the drivers profile |
| work_status | object | tracking or available status of driver to match |
| include_deleted | boolean | whether to include the deleted drivers in result, default false |
Authentication: Basic Auth or OAuth Token
List drivers returns a list the drivers.
List drivers request:
curl -X GET \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/drivers?work_status={"available": true}' \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get('https://v3.api.hypertrack.com/drivers?work_status={"available": true}',
headers=AUTH_HEADER)
HTTP 200 - List drivers response
{
"drivers":[
{
"driver_handle":"e60a2f4b-9452-43e9-b021-f6f9b3966c25",
"ops_group_handle":"9bf021e5-1cfd-4afe-895c-a406cf92030c",
"product_types":[
"1",
"2"
],
"device_id":"00112233-BA86-43B8-B31C-D7239FC98D7B",
"name": "Om Shah",
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"home":{
"geometry":{
"coordinates":[
77.62889638031433,
12.981546251203618
],
"type":"Point"
},
"address":"Dummy driver address"
},
"profile":{
"dummy_key":"dummy_value"
},
"work_status":{
"available":true,
"tracking":false
},
"deleted":false
},
{
"driver_handle":"10bd0295-b6c1-452e-9257-7bab3005cade",
"ops_group_handle":"a50c1b88-ea18-48fa-9d16-c6ea8bd65c80",
"product_types":[
"1",
"2"
],
"device_id":"00112233-C6AE-4B46-8130-4D6668998A1E",
"name": "Kunal LM",
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"home":{
"geometry":{
"coordinates":[
77.62889638031433,
12.981546251203618
],
"type":"Point"
},
"address":"Dummy driver address"
},
"profile":{
"dummy_key":"dummy_value"
},
"work_status":{
"available":true,
"tracking":false
},
"deleted":false,
"unavailable_on": ["2023-06-06"],
}
]
}
Response Attributes
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| drivers | array | Mandatory | list of drivers that satisfy search criteria |
| drivers.driver.driver_handle | string | Mandatory | Unique handle of the driver for identification purposes which is case insensitive |
| drivers.driver.ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with (mandatory) | |
| drivers.driver.device_id | string | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device | |
| drivers.driver.name | string | Name of the driver | |
| drivers.driver.home | object | Details of Driver Home [If ops group is setup such that Operations starts from Driver's home, then driver home needs to be set] | |
| drivers.driver.home.address | string | Address of driver home | |
| drivers.driver.home.geometry | object | Location in GeoJSON format | |
| drivers.driver.schedule | array | Array of schedule objects representing the driver's schedule (Optional) | |
| drivers.driver.schedule.date | date | Date represented as YYYY-MM-DD to indicate a schedule date | |
| drivers.driver.schedule.start_time | Timestring | Time string in (HH:MM) format indicating the time at which shift starts | |
| drivers.driver.schedule.end_time | Timestring | Time string in (HH:MM) format indicating the time at which shift ends | |
| drivers.driver.schedule.ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with in a shift (optional) | |
| schedule.priority | string | Priority of a driver within a shift (optional) | |
| drivers.driver.schedule.day_of_week | string | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
|
| drivers.driver.product_types | array | Product types associated with the driver, array of strings (product) | |
| drivers.driver.profile | object | Profile details (metadata) to be associated with driver | |
| drivers.driver.work_status | object | Current working status of the driver | |
| drivers.driver.work_status.available | boolean | Whether the driver is available or not | |
| drivers.driver.work_status.tracking | boolean | Whether the driver is tracking or not | |
| drivers.driver.unavailable_on | array | List of dates (ISO 8601 date string) indicating leaves for a driver |
Invite Driver
This API creates unique invite links to send out to your drivers to install the HyperTrack mobile app.
POST /drivers/{driver_handle}/invite
Authentication: Basic Auth or OAuth Token
Invite driver request
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/test-driver-1/invite \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.post("https://v3.api.hypertrack.com/drivers/test-driver-1/invite",
headers=AUTH_HEADER)
HTTP 200 - invite driver response
{
"driver_handle": "driver_123",
"invite_link": "https://hypertrack-logistics.app.link/wqepoifv8f34c"
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| driver_handle | string | Unique handle of the driver |
| invite_link | string | Unique link to invite this driver. Share this link with your driver to install the HyperTrack mobile app tied to your account and this driver |
Delete Driver
DELETE /drivers/{driver_handle}
Authentication: Basic Auth or OAuth Token
Delete driver request:
curl -X DELETE \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/test-driver-1 \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.delete("https://v3.api.hypertrack.com/drivers/test-driver-1",
headers=AUTH_HEADER)
HTTP 204
Undelete Driver
POST /drivers/{driver_handle}/undelete
Authentication: Basic Auth or OAuth Token
Undelete driver request:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/test-driver-1/undelete \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.post("https://v3.api.hypertrack.com/drivers/test-driver-1/undelete",
headers=AUTH_HEADER)
HTTP 200 - Undelete driver response
{
"driver_handle":"test1-driver-1",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"product_types":[
"Food"
],
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"name": "Om Shah",
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"home":{
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
},
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034"
},
"profile":{
"name":"Test Driver A"
},
"work_status":{
"available":false,
"tracking":false
},
"deleted":false,
"unavailable_on": ["2023-06-06"],
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| driver_handle | string | Unique handle of the driver for identification purposes which is case insensitive (mandatory) |
| ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with (mandatory) |
| device_id | string | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device (Optional) |
| name | string | Name of the driver |
| home | object | Details of Driver Home (optional) |
| home.address | string | Address of driver home (optional) |
| home.geometry | object | Location in GeoJSON format |
| schedule | array | Array of schedule objects representing the driver's schedule (Optional) |
| schedule.date | date | Date represented as YYYY-MM-DD to indicate a schedule date |
| schedule.start_time | Timestring | Time string in (HH:MM) format indicating the time at which shift starts |
| schedule.end_time | Timestring | Time string in (HH:MM) format indicating the time at which shift ends |
| schedule.ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with in a shift (optional) |
| schedule.priority | string | Priority of a driver within a shift (optional) |
| schedule.day_of_week | string | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
| product_types | array | Product types associated with the driver, array of strings (product) |
| profile | object | Profile details (metadata) to be associated with driver |
| work_status | object | Current working status of the driver |
| work_status.available | boolean | Whether the driver is available or not |
| work_status.tracking | boolean | Whether the driver is tracking or not |
| unavailable_on | array | List of dates (ISO 8601 date string) indicating leaves for a driver |
Set Driver Work Status
POST /drivers/{driver_handle}/work_status
Authentication: Basic Auth or OAuth Token
Work status of a driver determines whether the driver is working and/or available for new work. Use this api to change the work status of driver using api.
Request Attributes for Set Driver Work Status API
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| tracking | bool | Optional | Set the tracking status of the driver |
| available | bool | Optional | Set the availability status of the driver |
Set work status driver request:
payload='{
"tracking": true,
"available": true
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/test-driver-1/work_status \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
driver_data = {
"tracking": True,
"available": True
}
response = requests.post("https://v3.api.hypertrack.com/drivers/test-driver-1/work_status",
json=driver_data,
headers=AUTH_HEADER)
HTTP 200 - driver response
{
"driver_handle":"test1-driver-1",
"ops_group_handle":"5c5a43a0-19ef-4b96-9539-8ab6c4e4238a",
"product_types":[
"Food"
],
"device_id":"BB898EC6-63A9-4E60-97E1-D1042F8CDF33",
"name": "Om Shah",
"schedule":[
{
"start_time": "07:00",
"end_time": "12:00",
"date": "2023-04-04"
},
{
"start_time": "04:00",
"end_time": "18:00",
"date": "2023-04-04"
}
],
"home":{
"geometry":{
"coordinates":[
77.61119269564921,
12.93458618334973
],
"type":"Point"
},
"address":"123 Street, Koramangala, Bangalore, Karnataka, India, 560034"
},
"profile":{
"name":"Test Driver A"
},
"work_status":{
"available":false,
"tracking":false
},
"deleted":false,
"unavailable_on": ["2023-06-06"],
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| driver_handle | string | Unique handle of the driver for identification purposes which is case insensitive (mandatory) |
| ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with (mandatory) |
| device_id | string | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device (Optional) |
| name | string | Name of the driver |
| home | object | Details of Driver Home (optional) |
| home.address | string | Address of driver home (optional) |
| home.geometry | object | Location in GeoJSON format |
| schedule | array | Array of schedule objects representing the driver's schedule (Optional) |
| schedule.date | date | Date represented as YYYY-MM-DD to indicate a schedule date |
| schedule.start_time | Timestring | Time string in (HH:MM) format indicating the time at which shift starts |
| schedule.end_time | Timestring | Time string in (HH:MM) format indicating the time at which shift ends |
| schedule.ops_group_handle | string | Unique handle for the ops group with which you want to map the driver with in a shift (optional) |
| schedule.priority | string | Priority of a driver within a shift (optional) |
| schedule.day_of_week | string | Enumerated string representing the day of the week - MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY SUNDAY (optional) |
| product_types | array | Product types associated with the driver, array of strings (product) |
| profile | object | Profile details (metadata) to be associated with driver |
| work_status | object | Current working status of the driver |
| work_status.available | boolean | Whether the driver is available or not |
| work_status.tracking | boolean | Whether the driver is tracking or not |
| unavailable_on | array | List of dates (ISO 8601 date string) indicating leaves for a driver |
Get Driver History
GET /drivers/{driver_handle}/history
query parameters
| Name | Type | Description |
|---|---|---|
| from_time | string | ISO8601 format date |
| to_time | object | ISO8601 format date |
Authentication: Basic Auth or OAuth Token
This api return the history of the driver including the summary of all the device that are/were associated with this driver as json data.
Get driver history request:
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/test-driver-1/history \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/drivers/test-driver-1/history",
headers=AUTH_HEADER)
HTTP 200 - get driver history response
{
"driver_handle":"aashish",
"locations":[
{
"type":"LineString",
"coordinates":[
[
-121.892715,
37.414802,
16.71,
"2022-10-17T22:34:50.250Z"
],
[
-121.892715,
37.414802,
16.73,
"2022-10-17T22:43:49.462Z"
],
[
-121.892715,
37.414802,
16.63,
"2022-10-17T22:44:37.186Z"
],
[
-121.892715,
37.414802,
16.76,
"2022-10-17T22:44:40.429Z"
],
[
-121.892715,
37.414802,
16.72,
"2022-10-17T22:59:29.769Z"
]
]
}
],
"markers":[
{
"device_id":"E81C2873-5B33-4443-8082-FF8995239C84",
"timestamp":"2022-10-17T22:33:50.973Z",
"type":"device_linked"
},
{
"type":"device_status",
"data":{
"start":{
"recorded_at":"2022-10-17T22:33:50.973Z",
"location":{
"recorded_at":"2022-10-17T22:34:50.250Z",
"geometry":{
"type":"Point",
"coordinates":[
-121.892715,
37.414802
]
}
}
},
"end":{
"recorded_at":"2022-10-17T22:59:29.769Z",
"location":{
"recorded_at":"2022-10-17T22:59:29.769Z",
"geometry":{
"type":"Point",
"coordinates":[
-121.892715,
37.414802
]
}
}
},
"duration":1539,
"value":"active",
"address":"Apartments, Piper Drive, Milpitas, Santa Clara County, California, 95035-8004, United States of America",
"activity":"stop",
"steps":0
},
"marker_id":"167121fc-c0f7-44c6-84fc-87e5889f3a06"
},
{
"type":"device_status",
"data":{
"start":{
"recorded_at":"2022-10-17T22:59:29.769Z",
"location":{
"recorded_at":"2022-10-17T22:59:29.769Z",
"geometry":{
"type":"Point",
"coordinates":[
-121.892715,
37.414802
]
}
}
},
"end":{
"recorded_at":"2022-10-18T00:00:00.000Z",
"location":{
"recorded_at":"2022-10-17T22:59:29.769Z",
"geometry":{
"type":"Point",
"coordinates":[
-121.892715,
37.414802
]
}
}
},
"duration":3630,
"value":"inactive",
"reason":"sdk_killed_by_user"
},
"marker_id":"97e71bcd-8b58-4a51-bb1a-256f10e159a0"
}
],
"started_at":"2022-10-17T00:00:00.000Z",
"completed_at":"2022-10-18T00:00:00.000Z",
"distance":0,
"duration":1539,
"steps":0
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| driver_handle | string | Unique handle of the driver for identification purposes which is case insensitive (mandatory) |
| locations | array | List of locations of the drivers devices |
| markers | array | List of markers summarising the history of the driver |
| started_at | string | Time from where the history is requested from |
| completed_at | string | Time to where the history is requested to |
| distance | int | Distance tracked during the duration of history |
| duration | object | Duration tracked during the duration of history |
| steps | int | Number of steps taken by driver during the duration of history |
Create Ops Groups
Ops Groups help business manage their operations into different groups, typically if a business has multiple stores/warehouses, then each becomes an Ops Group in HyperTrack and would have their own fleet associated to fulfill their orders
POST /drivers/ops-groups
Authentication: Basic Auth or OAuth Token
Request Attributes to Create an Ops Group
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| ops_group_handle | string | Mandatory | Unique handle for each Ops Group to be used in Drivers and Orders APIs, the handle needs to be url safe |
| ops_group_label | string | Mandatory | Label for the Ops Group e.g City, Warehouse, Store |
| ops_group_home | object | Optional | Details of Ops Group Home [Only needed if route_start_location is ops_group_home then ops group home needs to be set] |
| ops_group_home.address | string | Optional | Address of Ops group home |
| ops_group_home.geometry | object | Optional | Location in GeoJSON format |
| route_start_location | Enum string | Mandatory | Config which defines where the route starts from, enumerated as driver_home, ops_group_home or live_location |
| route_completion_type | Enum string | Mandatory | Config which defines how the route ends, enumerated as end_at_last_order, return_to_start_location or manual |
Planning Configuration Fields
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| objective_fn | Enum string | Optional | Config which defines the optimization factor, enumerated as minimise_time or minimise_distance |
| route_max_distance | number | Optional | Maximum distance an associated driver should travel during a route, this is used in planning phase |
| route_capacity | Enum string | Optional | Maximum number of orders a driver can fulfill as part of single route |
| default_shift_start_time | Enum string | Optional | Time at which drivers start their shifts by default |
| default_shift_end_time | Enum string | Optional | Time at which drivers end their shifts by default |
| timezone | Enum string | Optional | Timezone string in which the Ops group operates in |
| order_tracking_mode | Enum string | Optional | Config which defines whether orders are tracked automatically at shift start, enumerated as manual or auto. Default is manual |
| shift_availability_mode | Enum string | Optional | Config which defines whether drivers are automatically made available/unavailable at shift start/end, enumerated as manual or auto. Default is manual |
Create new Ops Group request:
payload='{
"ops_group_handle":"store_berk",
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store Berkley address"
},
"objective_fn": "minimise_time",
"route_capacity": 10,
"route_max_distance": 12000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "18:00",
"timezone": "America/Los Angeles"
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/ops-groups \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
ops_group_data = {
"ops_group_handle":"store_berk",
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store Berkley address"
},
"objective_fn": "minimise_time",
"route_capacity": 10,
"route_max_distance": 12000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "18:00",
"timezone": "America/Los Angeles"
}
response = requests.post("https://v3.api.hypertrack.com/drivers/ops-groups",
json=driver_data,
headers=AUTH_HEADER)
HTTP 201 - New Ops Group response
{
"ops_group_handle": "store_berk",
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store Berkley address"
},
"objective_fn": "minimise_time",
"route_capacity": 10,
"route_max_distance": 12000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "18:00",
"timezone": "America/Los Angeles",
"order_tracking_mode": "manual",
"shift_availability_mode": "manual"
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs |
| ops_group_label | string | Label for the Ops Group e.g City, Warehouse, Store |
| ops_group_home | object | Details of Ops Group Home [If ops group is setup such that Operations starts from Ops Group home, then ops group home needs to be set] |
| ops_group_home.address | string | Address of Ops group home |
| ops_group_home.geometry | object | Location in GeoJSON format |
| route_start_location | Enum string | Config which defines where the route starts from, enumerated as driver_home, ops_group_home or live_location |
| route_completion_type | Enum string | Config which defines how the route ends, enumerated as end_at_last_order, return_to_start_location or manual |
| objective_fn | Enum string | Config which defines the optimization factor, enumerated as minimise_time or minimise_distance |
| route_max_distance | number | Maximum distance an associated driver should travel during a route, this is used in planning phase |
| route_capacity | Enum string | Maximum number of orders a driver can fulfill as part of single route |
| default_shift_start_time | Enum string | Time at which drivers start their shifts by default |
| default_shift_end_time | Enum string | Time at which drivers end their shifts by default |
| timezone | Enum string | Timezone string in which the Ops group operates in |
| order_tracking_mode | Enum string | Config which defines whether orders are tracked automatically at shift start, enumerated as manual or auto. Default is manual |
| shift_availability_mode | Enum string | Config which defines whether drivers are automatically made available/unavailable at shift start/end, enumerated as manual or auto. Default is manual |
Update Ops Group
PATCH /drivers/ops-groups/{ops_group_handle}
Authentication: Basic Auth or OAuth Token
All the fields in update request are optional, pass only the field(s) you want to patch, other fields already present in driver will not be updated.
Request Attributes for Update Ops Group API
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| ops_group_label | string | Optional | Label for the Ops Group e.g City, Warehouse, Store |
| ops_group_home | object | Optional | Details of Ops Group Home [Only needed if route_start_location is ops_group_home then ops group home needs to be set] |
| ops_group_home.address | string | Optional | Address of Ops group home |
| ops_group_home.geometry | object | Optional | Location in GeoJSON format |
| route_start_location | Enum string | Optional | Config which defines where the route starts from, enumerated as driver_home, ops_group_home or live_location |
| route_completion_type | Enum string | Optional | Config which defines how the route ends, enumerated as end_at_last_order, return_to_start_location or manual |
Planning Configuration Fields
| Name | Type | Optional/Mandatory | Description |
|---|---|---|---|
| objective_fn | Enum string | Optional | Config which defines the optimization factor, enumerated as minimise_time or minimise_distance |
| route_max_distance | number | Optional | Maximum distance an associated driver should travel during a route, this is used in planning phase |
| route_capacity | Enum string | Optional | Maximum number of orders a driver can fulfill as part of single route |
| default_shift_start_time | Enum string | Optional | Time at which drivers start their shifts by default |
| default_shift_end_time | Enum string | Optional | Time at which drivers end their shifts by default |
| timezone | Enum string | Optional | Timezone string in which the Ops group operates in |
| order_tracking_mode | Enum string | Optional | Config which defines whether orders are tracked automatically at shift start, enumerated as manual or auto. Default is manual |
| shift_availability_mode | Enum string | Optional | Config which defines whether drivers are automatically made available/unavailable at shift start/end, enumerated as manual or auto. Default is manual |
Update Ops Group request:
payload='{
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store Berkley address"
},
"objective_fn": "minimise_time",
"route_capacity": 12,
"route_max_distance": 14000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "19:00",
"timezone": "America/Los Angeles",
"order_tracking_mode": "manual",
"shift_availability_mode": "manual"
}'
curl -X PATCH \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/ops-groups/store_berk \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
ops_group_data = {
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store Berkley address"
},
"objective_fn": "minimise_time",
"route_capacity": 12,
"route_max_distance": 14000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "19:00",
"timezone": "America/Los Angeles",
"order_tracking_mode": "manual",
"shift_availability_mode": "manual"
}
response = requests.patch("https://v3.api.hypertrack.com/drivers/ops-groups/store_berk",
json=driver_data,
headers=AUTH_HEADER)
HTTP 200 - updated ops group response
{
"ops_group_handle": "store_berk",
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store Berkley address"
},
"objective_fn": "minimise_time",
"route_capacity": 10,
"route_max_distance": 12000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "18:00",
"timezone": "America/Los Angeles",
"order_tracking_mode": "manual",
"shift_availability_mode": "manual"
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs |
| ops_group_label | string | Label for the Ops Group e.g City, Warehouse, Store |
| ops_group_home | object | Details of Ops Group Home [If ops group is setup such that Operations starts from Ops Group home, then ops group home needs to be set] |
| ops_group_home.address | string | Address of Ops group home |
| ops_group_home.geometry | object | Location in GeoJSON format |
| route_start_location | Enum string | Config which defines where the route starts from, enumerated as driver_home, ops_group_home or live_location |
| route_completion_type | Enum string | Config which defines how the route ends, enumerated as end_at_last_order, return_to_start_location or manual |
| objective_fn | Enum string | Config which defines the optimization factor, enumerated as minimise_time or minimise_distance |
| route_max_distance | number | Maximum distance an associated driver should travel during a route, this is used in planning phase |
| route_capacity | Enum string | Maximum number of orders a driver can fulfill as part of single route |
| default_shift_start_time | Enum string | Time at which drivers start their shifts by default |
| default_shift_end_time | Enum string | Time at which drivers end their shifts by default |
| timezone | Enum string | Timezone string in which the Ops group operates in |
| order_tracking_mode | Enum string | Config which defines whether orders are tracked automatically at shift start, enumerated as manual or auto. Default is manual |
| shift_availability_mode | Enum string | Config which defines whether drivers are automatically made available/unavailable at shift start/end, enumerated as manual or auto. Default is manual |
Get Ops Group By Handle
Get Details about any Ops Group already created on HT
GET /drivers/ops-groups/{ops_group_handle}
Authentication: Basic Auth or OAuth Token
Get Ops Group request:
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/drivers/ops-groups/store_berk \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/drivers/ops-groups/store_berk",
headers=AUTH_HEADER)
HTTP 200 - get Ops Group response
{
"ops_group_handle": "store_berk",
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store Berkley address"
},
"objective_fn": "minimise_time",
"route_capacity": 10,
"route_max_distance": 12000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "18:00",
"timezone": "America/Los Angeles",
"order_tracking_mode": "manual",
"shift_availability_mode": "manual"
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs |
| ops_group_label | string | Label for the Ops Group e.g City, Warehouse, Store |
| ops_group_home | object | Details of Ops Group Home [If ops group is setup such that Operations starts from Ops Group home, then ops group home needs to be set] |
| ops_group_home.address | string | Address of Ops group home |
| ops_group_home.geometry | object | Location in GeoJSON format |
| route_start_location | Enum string | Config which defines where the route starts from, enumerated as driver_home, ops_group_home or live_location |
| route_completion_type | Enum string | Config which defines how the route ends, enumerated as end_at_last_order, return_to_start_location or manual |
| objective_fn | Enum string | Config which defines the optimization factor, enumerated as minimise_time or minimise_distance |
| route_max_distance | number | Maximum distance an associated driver should travel during a route, this is used in planning phase |
| route_capacity | Enum string | Maximum number of orders a driver can fulfill as part of single route |
| default_shift_start_time | Enum string | Time at which drivers start their shifts by default |
| default_shift_end_time | Enum string | Time at which drivers end their shifts by default |
| timezone | Enum string | Timezone string in which the Ops group operates in |
| order_tracking_mode | Enum string | Config which defines whether orders are tracked automatically at shift start, enumerated as manual or auto. Default is manual |
| shift_availability_mode | Enum string | Config which defines whether drivers are automatically made available/unavailable at shift start/end, enumerated as manual or auto. Default is manual |
List Ops Groups
All Ops Groups being created for a business can be listed using Ops Groups API
GET /drivers/ops-groups
Authentication: Basic Auth or OAuth Token
Query Parameters
pagination_token- (optional) a string representing the next pagination token used to fetch the next page of data.limit- (optional) a number representing the limit on the number of ops groups to be returned.
List Ops Groups request:
curl -X GET \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/drivers/ops-groups' \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get('https://v3.api.hypertrack.com/drivers/ops-groups',
headers=AUTH_HEADER)
HTTP 200 - list Ops Groups response
HTTP 200 - List All Ops Groups
{
"ops_groups": [
{
"ops_group_handle": "store_sf",
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.4275288309666,
37.759384264709496
],
"type":"Point"
},
"address":"Store SF address"
},
"objective_fn": "minimise_time",
"route_capacity": 10,
"route_max_distance": 12000,
"default_shift_start_time": "07:00",
"default_shift_end_time": "18:00",
"timezone": "America/Los Angeles"
},
{
"ops_group_handle": "store_sea",
"ops_group_label": "Store",
"route_start_location": "ops_group_home",
"route_completion_type": "end_at_last_order",
"ops_group_home": {
"geometry":{
"coordinates":[
-122.32740790560293,
47.61564604710583
],
"type":"Point"
},
"address":"Store Seattle address"
},
"objective_fn": "minimise_time",
"route_capacity": 12,
"route_max_distance": 15000,
"default_shift_start_time": "07:30",
"default_shift_end_time": "18:30",
"timezone": "America/Los Angeles"
}
],
"pagination_token": "effss343fgsdCss2ee"
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| ops_groups | array | Array of ops groups |
| ops_groups.ops_group.ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs |
| ops_groups.ops_group.ops_group_label | string | Label for the Ops Group e.g City, Warehouse, Store |
| ops_groups.ops_group.ops_group_home | object | Details of Ops Group Home [If ops group is setup such that Operations starts from Ops Group home, then ops group home needs to be set] |
| ops_groups.ops_group.ops_group_home.address | string | Address of Ops group home |
| ops_groups.ops_group.ops_group_home.geometry | object | Location in GeoJSON format |
| ops_groups.ops_group.route_start_location | Enum string | Config which defines where the route starts from, enumerated as driver_home, ops_group_home or live_location |
| ops_groups.ops_group.route_completion_type | Enum string | Config which defines how the route ends, enumerated as end_at_last_order, return_to_start_location or manual |
| ops_groups.ops_group.objective_fn | Enum string | Config which defines the optimization factor, enumerated as minimise_time or minimise_distance |
| ops_groups.ops_group.route_max_distance | number | Maximum distance an associated driver should travel during a route, this is used in planning phase |
| ops_groups.ops_group.route_capacity | Enum string | Maximum number of orders a driver can fulfill as part of single route |
| ops_groups.ops_group.default_shift_start_time | Enum string | Time at which drivers start their shifts by default |
| ops_groups.ops_group.default_shift_end_time | Enum string | Time at which drivers end their shifts by default |
| ops_groups.ops_group.timezone | Enum string | Timezone string in which the Ops group operates in |
| pagination_token | string | String representing the next pagination token used to fetch the next page of data |
Orders
The Orders API can be used to plan, manage, and track orders.
Plan Orders
Batch and Sequence Orders
Post orders to link example:
payload='{
"plan_mode": "scheduled",
"ops_group_handle": "SAN_JOSE_WH",
"orders": [
{
"order_handle": "order-112233",
"scheduled_after": "2023-03-14T22:00:00Z",
"scheduled_at": "2023-03-14T23:00:00Z",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233322"},
},
{
"order_handle": "order-112244",
"scheduled_after": "2023-03-14T23:00:00Z",
"scheduled_at": "2023-03-14T23:30:00Z",
"destination": {
"address": "425 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233321"},
},
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
order_data = {
"plan_mode": "scheduled",
"ops_group_handle": "SAN_JOSE_WH",
"orders": [
{
"order_handle": "order-112233",
"scheduled_after": "2023-03-14T22:00:00Z",
"scheduled_at": "2023-03-14T23:00:00Z",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233322"},
},
{
"order_handle": "order-112244",
"scheduled_after": "2023-03-14T23:00:00Z",
"scheduled_at": "2023-03-14T23:30:00Z",
"destination": {
"address": "425 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233321"},
},
]
}
route = requests.post('https://v3.api.hypertrack.com/orders', json=payload, headers=AUTH_HEADER)
Post orders that need to be planned.
POST /orders
Authentication: Basic Auth or OAuth Token
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| plan_mode | string | Mandatory | enum string one of scheduled, pool, on_demand OR manual |
| ops_group_handle | string | Optional | Unique handle for Ops Group for which the orders are to be planned |
| driver_handle | string | Optional | Unique identifier of the driver to plan the orders for |
| orders | array | Mandatory | Array of order objects |
| orders.order_handle | string | Mandatory | Unique handle for Order |
| orders.scheduled_at | Datetime string | Mandatory | Schedule time by which order needs to be fulfilled |
| orders.scheduled_after | Datetime string | Optional | Schedule time after which the driver needs to fulfill order (similar to slot start) |
| orders.destination | object | Mandatory | Object representing destination of the order |
| orders.destination.geometry | object | Optional | Geometry in GeoJSON format; optional if address is given (address is then used to geocode) |
| orders.destination.radius | integer | Optional | Radius of circular geofence (Only needed if destination geofence is of type circle) |
| orders.destination.address | string | Optional | Address of destination; if only address is provided, address is geocoded; if both address and geometry is provided, address is used as a label |
| orders.expected_service_time | integer | Optional | Time in seconds which is expected at the order destination for fulfillment |
| orders.capacity_used | integer | Optional | Volumetric units which is to be occupied by the order |
| orders.product_type | array | Optional | Array of string representing skills required to fulfill the order |
| orders.type | Enum string | Optional | Type of order enumerated as drop or pick |
| orders.type_index | integer | Optional | Index of order of the same type and order handle |
| orders.metadata | object | Optional | Metadata for order |
Note: driver_handle only is permitted when plan_mode is either on_demand or manual
Track Orders
Using Orders
Track using a bag of orders example:
payload='{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"track_mode": "on_time",
"orders": [
{
"order_handle": "order-112233",
"scheduled_after": "2023-03-14T22:00:00Z",
"scheduled_at": "2023-03-14T23:00:00Z",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233322"},
},
{
"order_handle": "order-112244",
"scheduled_after": "2023-03-14T23:00:00Z",
"scheduled_at": "2023-03-14T23:30:00Z",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233321"},
},
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/track \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
order_data = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"track_mode": "on_time",
"orders": [
{
"order_handle": "order-112233",
"scheduled_after": "2023-03-14T22:00:00Z",
"scheduled_at": "2023-03-14T23:00:00Z",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233322"},
},
{
"order_handle": "order-112244",
"scheduled_after": "2023-03-14T23:00:00Z",
"scheduled_at": "2023-03-14T23:30:00Z",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"radius": 50
},
"product_type": ["plumber"],
"capacity_used": 1,
"expected_service_time": 800,
"type": "drop",
"metadata": {"customerId": "2233321"},
},
]
}
route = requests.post('https://v3.api.hypertrack.com/orders/track', json=payload, headers=AUTH_HEADER)
HTTP 201 - Track Using a Bag of Orders response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"tracking",
"track_mode":"on_time",
"assigned_at": "2023-03-14T22:21:00Z",
"created_at": "2023-03-14T22:20:00Z",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z"
},
"orders":[
{
"order_handle": "order-112233",
"route_handle":"route-1",
"fulfillment_attempt":1,
"status": "ongoing",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"track_mode":"on_time",
"created_at":"2023-03-14T22:20:00Z",
"assigned_at": "2023-03-14T22:21:00Z",
"started_at": "2023-03-14T22:21:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"share_url": "https://trck.at/abcdef"
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Track orders fulfilled by a driver who is identified by device_id
POST /orders/track
Authentication: Basic Auth or OAuth Token
Request attributes
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| track_mode | Enum string | Mandatory | Tracking Intent of API enumerated as on_time OR flex |
| device_id | string | Optional | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device |
| driver_handle | string | Optional | Unique identifier of the driver to track orders with which is case insensitive |
| orders | array | Mandatory | Array of order objects |
| orders.order_handle | string | Mandatory | Unique handle for Order |
| orders.scheduled_at | Datetime string | Optional | Schedule time by which order needs to be fulfilled. Mandatory for on_time orders; optional for flex orders |
| orders.scheduled_after | Datetime string | Optional | Schedule time after which the driver needs to fulfill order (similar to slot start) |
| orders.destination | object | Mandatory | Object representing destination of the order |
| orders.destination.geometry | object | Mandatory | Geometry in GeoJSON format |
| orders.destination.radius | integer | Optional | Radius of circular geofence (Only needed if destination geofence is of type circle) |
| orders.expected_service_time | integer | Optional | Time in seconds which is expected at the order destination for fulfillment |
| orders.destination.address | string | Optional | Address label. If not provided, address is reversed geocoded based on the geometry provided. |
| orders.capacity_used | integer | Optional | Volumetric units which is to be occupied by the order |
| orders.product_type | array | Optional | Array of string representing skills required to fulfill the order |
| orders.type | Enum string | Optional | Type of order enumerated as drop or pick |
| orders.type_index | integer | Optional | Index of order of the same type and order handle |
| orders.metadata | object | Optional | Metadata for order |
NOTE: Please provide either device_id OR driver_handle but not both.
Response attributes
| Name | Type | Description |
|---|---|---|
| orders | array | Array of order objects |
| order | object | Definition of a order object |
| order.order_handle | string | Unique handle for the Order |
| order.fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| order.status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| order.ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| order.device_id | string | Device Identifier that uniquely identifies a device within HyperTrack |
| order.driver_handle | string | Unique handle for the driver which is case insensitive |
| order.route_handle | string | Unique handle for the route of which the order is part of |
| order.track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| order.plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| order.created_at | timestamp | Timestamp representing the creation time of the order |
| order.started_at | timestamp | Timestamp representing when the order tracking was started |
| order.share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| order.scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| order.scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| order.completed_at | timestamp | Timestamp at which the order was completed |
| order.cancelled_at | timestamp | Timestamp at which the order was cancelled |
| order.disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| order.enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| order.assigned_at | timestamp | Timestamp at which the order was assigned |
| order.metadata | object | Metadata for an order |
| order.region | object | Object containing the city, state, and country of the order destination |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | integer | Radius (in meters) of a circular order destination |
| order.destination.address | string | Destination address for the order |
| order.risk_status | boolean | Flag indicating if a risk exists or not |
| order.risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| order.arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| order.expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| order.actual_service_time | integer | Actual time spent by the driver at the customer location |
| order.product_type | array | List of strings representing specific product types associated with the order |
| order.type | string | Indicates "drop"/"pickup" label associated with the order |
| order.type_index | integer | Index of order of the same type and order handle |
| order.capacity_used | integer | Indicates the capacity utilized by the order |
| order.estimate | object | Estimate object containing the estimate metrics (Only present for non terminal orders) |
| order.estimate.arrive_at | timestamp | Order Estimated arrival timestamp |
| order.estimate.start_by | timestamp | Order Estimated start time |
| order.estimate.distance | integer | Estimated distance to fulfill the order |
| order.estimate.duration | integer | Estimated duration to fulfill the order |
| order.distance | integer | Actual distance travelled to fulfill the order (Only present for orders in terminal state) |
| order.duration | integer | Actual duration taken to fulfill the order (Only present for orders in terminal state) |
| route_handle | string | Unique handle for the route |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, assigned, tracking, completed |
| plan_mode | string | Mode with which route is planned enumerated as scheduled, pool, on_demand OR manual |
| version | integer | Integer indicating the version of the route |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| estimate | object | Object containing the estimate metrics |
| estimate.start_by | object | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the route |
| estimate.duration | integer | Estimated duration to fulfill the route |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| started_at | timestamp | Timestamp at which the route was started |
| assigned_at | timestamp | Timestamp at which the route was assigned |
| created_at | timestamp | Timestamp at which the route was created |
| completed_at | timestamp | Timestamp at which all orders in the route were completed |
| device_id | string | Unique identifier for the driver fulfilling the order in the route |
| driver_handle | string | Unique handle for the driver |
| metadata | object | Route metadata |
| embed_url | string | URL string that can be used to embed the route tracking in customer dashboards |
| markers | array | Array of markers generated during the route |
| distance | integer | Distance travelled during the whole route |
| duration | integer | Duration spent during the whole route |
| polyline | integer | Polyline (linestring geoJSON) representing route travelled |
| tracking_rate | float | Number indicating the tracking rate of the driver during the route |
| region | object | Object containing the city/state/country of the route |
Using Route
Track Orders using Route Handle example:
payload='{
"track_mode": "on_time",
"route_handle": "route-1",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF"
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/track \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
order_data = {
"track_mode": "on_time",
"route_handle": "route_12123",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF"
}
route = requests.post('https://v3.api.hypertrack.com/orders/track', json=payload, headers=AUTH_HEADER)
HTTP 200 - Track Orders Using Route Handle response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"tracking",
"track_mode":"on_time",
"assigned_at": "2023-03-14T22:21:00Z",
"created_at": "2023-03-14T22:20:00Z",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z"
},
"orders":[
{
"order_handle": "order-112233",
"route_handle":"route-1",
"fulfillment_attempt":1,
"status": "ongoing",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"track_mode":"on_time",
"created_at":"2023-03-14T22:20:00Z",
"assigned_at": "2023-03-14T22:21:00Z",
"started_at": "2023-03-14T22:21:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"share_url": "https://trck.at/abcdef"
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Track orders using the Route handle
POST /orders/track
Authentication: Basic Auth or OAuth Token
Request attributes
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| track_mode | Enum string | Mandatory | Tracking Intent of API enumerated as on_time OR flex |
| route_handle | string | Mandatory | Unique handle for Route |
| device_id | string | Optional | Unique ID of the device obtained through HyperTrack when application (with HT SDK) is installed on the device |
| driver_handle | string | Optional | Unique identifier of the driver to track route with which is case insensitive |
NOTE: Please provide either device_id OR driver_handle but not both.
Response attributes
| Name | Type | Description |
|---|---|---|
| orders | array | Array of order objects |
| order | object | Definition of a order object |
| order.order_handle | string | Unique handle for the Order |
| order.fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| order.status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| order.ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| order.device_id | string | Device Identifier that uniquely identifies a device within HyperTrack |
| order.driver_handle | string | Unique handle for the driver which is case insensitive |
| order.route_handle | string | Unique handle for the route of which the order is part of |
| order.track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| order.plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| order.created_at | timestamp | Timestamp representing the creation time of the order |
| order.started_at | timestamp | Timestamp representing when the order tracking was started |
| order.share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| order.scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| order.scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| order.completed_at | timestamp | Timestamp at which the order was completed |
| order.cancelled_at | timestamp | Timestamp at which the order was cancelled |
| order.disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| order.enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| order.assigned_at | timestamp | Timestamp at which the order was assigned |
| order.metadata | object | Metadata for an order |
| order.region | object | Object containing the city, state, and country of the order destination |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | integer | Radius (in meters) of a circular order destination |
| order.destination.address | string | Destination address for the order |
| order.risk_status | boolean | Flag indicating if a risk exists or not |
| order.risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| order.arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| order.expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| order.actual_service_time | integer | Actual time spent by the driver at the customer location |
| order.product_type | array | List of strings representing specific product types associated with the order |
| order.type | string | Indicates "drop"/"pickup" label associated with the order |
| order.type_index | integer | Index of order of the same type and order handle |
| order.capacity_used | integer | Indicates the capacity utilized by the order |
| order.estimate | object | Estimate object containing the estimate metrics (Only present for non terminal orders) |
| order.estimate.arrive_at | timestamp | Order Estimated arrival timestamp |
| order.estimate.start_by | timestamp | Order Estimated start time |
| order.estimate.distance | integer | Estimated distance to fulfill the order |
| order.estimate.duration | integer | Estimated duration to fulfill the order |
| order.distance | integer | Actual distance travelled to fulfill the order (Only present for orders in terminal state) |
| order.duration | integer | Actual duration taken to fulfill the order (Only present for orders in terminal state) |
| route_handle | string | Unique handle for the route |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, assigned, tracking, completed |
| plan_mode | string | Mode with which route is planned enumerated as scheduled, pool, on_demand OR manual |
| version | integer | Integer indicating the version of the route |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| estimate | object | Object containing the estimate metrics |
| estimate.start_by | object | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the route |
| estimate.duration | integer | Estimated duration to fulfill the route |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| started_at | timestamp | Timestamp at which the route was started |
| assigned_at | timestamp | Timestamp at which the route was assigned |
| created_at | timestamp | Timestamp at which the route was created |
| completed_at | timestamp | Timestamp at which all orders in the route were completed |
| device_id | string | Unique identifier for the driver fulfilling the order in the route |
| driver_handle | string | Unique handle for the driver |
| metadata | object | Route metadata |
| embed_url | string | URL string that can be used to embed the route tracking in customer dashboards |
| markers | array | Array of markers generated during the route |
| distance | integer | Distance travelled during the whole route |
| duration | integer | Duration spent during the whole route |
| polyline | integer | Polyline (linestring geoJSON) representing route travelled |
| tracking_rate | float | Number indicating the tracking rate of the driver during the route |
| region | object | Object containing the city/state/country of the route |
Get Orders
Using Route
curl -X GET \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75' \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get('https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75',
headers=AUTH_HEADER)
HTTP 200 - Get route response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"completed",
"distance": 2383,
"duration": 1243,
"tracking_rate": 0.94,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348, 34, '2023-03-14T22:22:000Z'],
[-122.272057, 37.80295, 34, '2023-03-14T22:23:000Z'],
[-122.272057, 37.80295, 34, '2023-03-14T22:24:000Z'],
[-122.278011, 37.805288, 34, '2023-03-14T22:25:000Z'],..
]
},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"completed_at": "2023-03-14T22:50:00Z",
"track_mode":"on_time",
"version":1,
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
}
"estimate":{
"start_by":"2023-03-14T23:20:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
"assigned_at": "2023-03-14T22:22:00Z",
"planned_at": "2023-03-14T22:22:00Z",
"created_at": "2023-03-14T22:20:00Z",
"orders":[
{
"order_handle": "order-112233",
"fulfillment_attempt":1,
"status": "assigned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"driver_handle": "San-Jose-Driver-1",
"route_handle":"route-1",
"track_mode":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"assigned_at": "2023-03-14T22:22:00Z",
"planned_at": "2023-03-14T22:22:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"type": "drop",
"type_index": 0,
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"estimate":{
"start_by": "2023-03-14T23:20:00Z",
"distance": 3728,
"duration": 729,
"arrive_at": "2023-03-14T23:31:00Z"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"driver_handle": "San-Jose-Driver-1",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Get a route using the route_handle.
GET /orders/routes/{route_handle}
Authentication: Basic Auth or OAuth Token
Path Parameters
route_handle- a string representing the route_handle
Response attributes
| Name | Type | Description |
|---|---|---|
| orders | array | Array of order objects |
| order | object | Definition of a order object |
| order.order_handle | string | Unique handle for the Order |
| order.fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| order.status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| order.ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| order.device_id | string | Device Identifier that uniquely identifies a device within HyperTrack |
| order.driver_handle | string | Unique handle for the driver which is case insensitive |
| order.route_handle | string | Unique handle for the route of which the order is part of |
| order.track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| order.plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| order.created_at | timestamp | Timestamp representing the creation time of the order |
| order.started_at | timestamp | Timestamp representing when the order tracking was started |
| order.share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| order.scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| order.scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| order.completed_at | timestamp | Timestamp at which the order was completed |
| order.cancelled_at | timestamp | Timestamp at which the order was cancelled |
| order.disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| order.enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| order.assigned_at | timestamp | Timestamp at which the order was assigned |
| order.metadata | object | Metadata for an order |
| order.region | object | Object containing the city, state, and country of the order destination |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | integer | Radius (in meters) of a circular order destination |
| order.destination.address | string | Destination address for the order |
| order.risk_status | boolean | Flag indicating if a risk exists or not |
| order.risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| order.arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| order.expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| order.actual_service_time | integer | Actual time spent by the driver at the customer location |
| order.product_type | array | List of strings representing specific product types associated with the order |
| order.type | string | Indicates "drop"/"pickup" label associated with the order |
| order.type_index | integer | Index of order of the same type and order handle |
| order.capacity_used | integer | Indicates the capacity utilized by the order |
| order.estimate | object | Estimate object containing the estimate metrics (Only present for non terminal orders) |
| order.estimate.arrive_at | timestamp | Order Estimated arrival timestamp |
| order.estimate.start_by | timestamp | Order Estimated start time |
| order.estimate.distance | integer | Estimated distance to fulfill the order |
| order.estimate.duration | integer | Estimated duration to fulfill the order |
| order.distance | integer | Actual distance travelled to fulfill the order (Only present for orders in terminal state) |
| order.duration | integer | Actual duration taken to fulfill the order (Only present for orders in terminal state) |
| route_handle | string | Unique handle for the route |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, assigned, tracking, completed |
| plan_mode | string | Mode with which route is planned enumerated as scheduled, pool, on_demand OR manual |
| version | integer | Integer indicating the version of the route |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| estimate | object | Object containing the estimate metrics |
| estimate.start_by | object | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the route |
| estimate.duration | integer | Estimated duration to fulfill the route |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| started_at | timestamp | Timestamp at which the route was started |
| assigned_at | timestamp | Timestamp at which the route was assigned |
| created_at | timestamp | Timestamp at which the route was created |
| completed_at | timestamp | Timestamp at which all orders in the route were completed |
| device_id | string | Unique identifier for the driver fulfilling the order in the route |
| driver_handle | string | Unique handle for the driver |
| metadata | object | Route metadata |
| embed_url | string | URL string that can be used to embed the route tracking in customer dashboards |
| markers | array | Array of markers generated during the route |
| distance | integer | Distance travelled during the whole route |
| duration | integer | Duration spent during the whole route |
| polyline | integer | Polyline (linestring geoJSON) representing route travelled |
| tracking_rate | float | Number indicating the tracking rate of the driver during the route |
| region | object | Object containing the city/state/country of the route |
Using Parameters
List orders example:
curl -X GET \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/orders' \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get('https://v3.api.hypertrack.com/orders',
headers=AUTH_HEADER)
HTTP 200 - List orders response
{
"orders":[
{
"order_handle": "order-112233",
"fulfillment_attempt":1,
"status": "assigned",
"plan_mode": "scheduled",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"driver_handle": "San-Jose-Driver-1",
"route_handle":"route-1",
"created_at":"2023-03-14T23:00:00Z",
"assigned_at": "2023-03-14T23:02:00Z",
"planned_at": "2023-03-14T23:02:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"type": "drop",
"type_index": 0,
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"estimate":{
"start_by": "2023-03-14T23:20:00Z",
"distance": 3728,
"duration": 729,
"arrive_at": "2023-03-14T23:31:00Z"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"pagination_token":"effss3ggCss2ss"
}
List orders filtered and sorted based on the below parameters.
GET /orders
Authentication: Basic Auth or OAuth Token
Query Parameters
Business Filters
ops_group_handle- (optional) a string representing the ops group handle to filter by.track_mode- (optional) a string representing the tracking mode to filter by.plan_mode- (optional) a string representing the planning mode to filter by.region_filter- (optional) a JSON encoded string to filter by city/state/country. e.g {”city”:<>, “state”:<>, “country”:<>}.order_metadata_filter- (optional) a JSON encoded string of order metadata to filter by.
Order Status Filters
status- (optional) string enumerated asplanned,unplanned,assigned,ongoing,disabled,cancelled,completedindicating the status to filter by.
Driver Filters
device_id- (optional) a string representing the device_id to filter by.driver_handle- (optional) a string representing the handle of the driver to filter by.
Time Range Filters
created_at_from- (optional) lower end of range filter for creation timecreated_at_to- (optional) upper end of range filter for creation timecreated_at_date- (optional) date string to filter orders created on a particular day (here account timezone will be considered)completed_at_from- (optional) lower end of range filter for completion timecompleted_at_to- (optional) upper end of range filter for completion timecompleted_at_date- (optional) date string to filter orders completed on a particular day (here account timezone will be considered)cancelled_at_from- (optional) lower end of range filter for cancellation timecancelled_at_to- (optional) upper end of range filter for cancellation timecancelled_at_date- (optional) date string to filter orders cancelled on a particular day (here account timezone will be considered)scheduled_at_from- (optional) lower end of range filter for scheduled timescheduled_at_to- (optional) upper end of range filter for scheduled timescheduled_at_date- (optional) date string to filter orders scheduled on a particular day (here account timezone will be considered)planned_at_from- (optional) lower end of range filter for planned timeplanned_at_to- (optional) upper end of range filter for planned timeplanned_at_date- (optional) date string to filter orders planned on a particular day (here account timezone will be considered)
Note : Date and time should be in valid ISO 8601 timestamp format.
Sorting and Pagination Parameters
sort_direction- (optional) string 'asc' or 'desc' indicating the preferred sort type.pagination_token- (optional) a string representing the next pagination token used to fetch the next page of data.limit- (optional) a number representing the limit on the number of orders returned.
List orders response attributes
| Name | Type | Description |
|---|---|---|
| orders | array | Array of order objects |
| pagination_token | string | String representing the next pagination token used to fetch the next page of data |
| order | object | Definition of a order object |
| order.order_handle | string | Unique handle for the Order |
| order.fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| order.status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| order.ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs. The handle needs to be url safe. |
| order.device_id | string | Device Identifier that uniquely identifies a device within HyperTrack |
| order.route_handle | string | Unique handle for the route of which the order is part of |
| order.driver_handle | string | Unique handle for the driver |
| order.intent | string | Intent of API enumerated as self_improving, on_time OR flex |
| order.created_at | timestamp | Timestamp representing the creation time of the order |
| order.started_at | timestamp | Timestamp representing when the order tracking was started |
| order.assigned_at | timestamp | Timestamp at which the order was assigned |
| order.planned_at | timestamp | Timestamp at which the order was planned |
| order.share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| order.scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| order.scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| order.completed_at | timestamp | Timestamp at which the order was completed |
| order.cancelled_at | timestamp | Timestamp at which the order was cancelled |
| order.disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| order.estimate | object | Estimate object containing the estimate metrics (Only present for non terminal orders) |
| order.estimate.arrive_at | timestamp | Estimated arrival timestamp |
| order.estimate.start_by | timestamp | Estimated start time |
| order.estimate.distance | integer | Estimated distance to fulfill the order |
| order.estimate.duration | integer | Estimated duration to fulfill the order |
| order.distance | integer | Actual distance travelled to fulfill the order (Only present for orders in terminal state) |
| order.duration | integer | Actual duration taken to fulfill the order (Only present for orders in terminal state) |
| order.enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| order.metadata | object | Metadata for an order |
| order.region | object | Object containing the city, state, and country of the order destination |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | integer | Radius (in meters) of a circular order destination |
| order.destination.address | string | Destination address for the order |
| order.risk_status | boolean | Flag indicating if a risk exists or not |
| order.risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| order.arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| order.expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| order.product_type | array | List of strings representing specific product types associated with the order |
| order.type | string | Indicates "drop"/"pickup" label associated with the order |
| order.type_index | integer | Index of order of the same type and order handle |
| order.capacity_used | integer | Indicates the capacity utilized by the order |
Get Order Timeline
Get order example:
curl -X GET \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/orders/order-122332' \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get('https://v3.api.hypertrack.com/orders/order-122332',
headers=AUTH_HEADER)
HTTP 200 - Get order response
{
"order_handle": "order-122332",
"fulfillment_attempt":1,
"status": "ongoing",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"route_handle" : "08e15437-dd50-44d0-81f2-64874d59b440",
"driver_handle": "San-Jose-Driver-1",
"track_mode":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"assigned_at": "2023-03-14T23:02:00Z",
"planned_at": "2023-03-14T23:02:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"type_index": 0,
"capacity_used":5,
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"images":[
"https://live-ht-image-bucket.s3.amazonaws.com/7jkhfjkahjknjkn/jkkhajksdjksajjk/ghjkahskuhkhjkkj-bsnjknk160729",
"https://live-ht-image-bucket.s3.amazonaws.com/7jkhfjkahjknjkn/jkkhajiojiopdksc/skuhkhjkkj-bsnjknk160729"
]
"estimate":{
"arrive_at":"2023-03-14T23:35:00Z",
"start_by":"2023-03-14T23:25:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
}
Get an order with it's timeline based on the order_handle.
GET /orders/{order_handle}
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle - a string representing the order_handle
Get order response attributes
| Name | Type | Description |
|---|---|---|
| order_handle | string | Unique handle for the Order |
| fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs. The handle needs to be url safe. |
| device_id | string | Device Identifier that uniquely identifies a device within HyperTrackÏ√ |
| driver_handle | string | Unique handle for the driver which is case insensitive |
| route_handle | string | Unique handle for the route of which the order is part of |
| track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| created_at | timestamp | Timestamp representing the creation time of the order |
| started_at | timestamp | Timestamp representing when the order tracking was started |
| share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| completed_at | timestamp | Timestamp at which the order was completed |
| cancelled_at | timestamp | Timestamp at which the order was cancelled |
| disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| assigned_at | timestamp | Timestamp at which the order was assigned |
| planned_at | timestamp | Timestamp at which the order was planned |
| metadata | object | Metadata for an order |
| region | object | Object containing the city, state, and country of the order destination |
| destination | object | Defined order destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | integer | Radius (in meters) of a circular order destination |
| destination.address | string | Destination address for the order |
| risk_status | boolean | Flag indicating if a risk exists or not |
| risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| product_type | array | List of strings representing specific product types associated with the order |
| type | string | Indicates "drop"/"pickup" label associated with the order |
| type_index | integer | Index of order of the same type and order handle |
| capacity_used | integer | Indicates the capacity utilized by the order |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| images | array | Links for images taken as proof of work during fulfillment |
| completed_at_destination | boolean | Flag indicating whether the order was completed at the delivery location |
| cancelled_at_destination | boolean | Flag indicating whether the order was cancelled at the delivery location |
| order_score | integer | Score indicating the performance of the order |
| estimate | object | Estimate object containing the estimate metrics |
| estimate.arrive_at | timestamp | Estimated arrival timestamp |
| estimate.start_by | timestamp | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the order |
| estimate.duration | integer | Estimated duration to fulfill the order |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| distance | integer | Actual distance travelled to fulfill the order |
| duration | integer | Actual duration taken to fulfill the order |
| polyline | string | Actual route traversal polyline to the order destination |
| tracking_rate | float | Number indicating the tracking rate of the driver during the delivery |
| deviation_from_destination | integer | Deviation in meters between the order destination location and completion location |
| actual_service_time | integer | Actual time spent by the driver at the customer location |
| markers | object | Array of markers |
| events | object | Array of events that occurred during the order journey |
| previous_fulfillments | object | Array of fulfillment objects containing historic fulfillment_attempts for the order with the same handle |
Manage Routes
Get Routes
List routes example:
curl -X GET \
-u {AccountId}:{SecretKey} \
'https://v3.api.hypertrack.com/orders/routes' \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get('https://v3.api.hypertrack.com/routes',
headers=AUTH_HEADER)
HTTP 200 - List routes response
{
"routes":[
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"assigned",
"plan_mode":"scheduled",
"assigned_at": "2023-03-14T22:22:00Z",
"planned_at": "2023-03-14T22:22:00Z",
"created_at": "2023-03-14T22:20:00Z",
"version":1,
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"estimate":{
"start_by":"2023-03-14T23:20:00Z",
"distance": 7728,
"duration": 1429,
},
"orders":[
{
"order_handle": "order-112233",
"status": "assigned",
"type": "drop",
"type_index": 0,
"created_at": "2023-03-14T22:22:00Z",
"estimate": {
"distance": 323,
"duration": 89,
"start_by": "2023-03-14T22:22:00.000Z",
"arrive_at": "2023-03-14T22:22:02.000Z"
}
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"driver_handle": "San-Jose-Driver-1",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
},..
],
"pagination_token":"effss3ggCss2ss"
}
List routes filtered and sorted based on the below parameters.
GET /orders/routes
Authentication: Basic Auth or OAuth Token
Query Parameters
Business Filters
ops_group_handle- (optional) a string representing the ops group handle to filter by.track_mode- (optional) a string representing the tracking mode to filter by.plan_mode- (optional) a string representing the planning mode to filter by.region_filter- (optional) a JSON encoded string to filter by city/state/country. e.g {”city”:<>, “state”:<>, “country”:<>}.route_metadata_filter- (optional) a JSON encoded string of route metadata to filter by.
Driver Filters
device_id- (optional) a string representing the device_id to filter by.
Route Status Filters
status- (optional) string enumerated asplanned,assigned,tracking,completed,summarizingindicating the status to filter by.
Time Range Filters
created_at_from- (optional) lower end of range filter for creation timecreated_at_to- (optional) upper end of range filter for creation timecreated_at_date- (optional) date string to filter routes created on a particular day (here account timezone will be considered)completed_at_from- (optional) lower end of range filter for completion timecompleted_at_to- (optional) upper end of range filter for completion timecompleted_at_date- (optional) date string to filter routes completed on a particular day (here account timezone will be considered)started_at_from- (optional) lower end of range filter for tracking start timestarted_at_to- (optional) upper end of range filter for tracking start timestarted_at_date- (optional) date string to filter routes tracking started on a particular day (here account timezone will be considered)start_by_from- (optional) lower end of range filter for latest start by timestart_by_to- (optional) upper end of range filter for latest start by timestart_by_date- (optional) date string to filter routes whose latest start by in a particular day (here account timezone will be considered)planned_at_from- (optional) lower end of range filter for planned timeplanned_at_to- (optional) upper end of range filter for planned timeplanned_at_date- (optional) date string to filter routes planned on a particular day (here account timezone will be considered)
Note : Date and time should be in valid ISO 8601 timestamp format.
Sorting and Pagination Parameters
sort_direction- (optional) string 'asc' or 'desc' indicating the preferred sort type.pagination_token- (optional) a string representing the next pagination token used to fetch the next page of data.limit- (optional) a number representing the limit on the number of routes returned.
List routes response attributes
| Name | Type | Description |
|---|---|---|
| routes | array | Array of route objects |
| route.orders | array | Array of order objects |
| pagination_token | string | String representing the next pagination token used to fetch the next page of data |
| route.order | object | Definition of a order object |
| route.order.order_handle | string | Unique handle for the Order |
| route.order.status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| route.order.type | string | Indicates "drop"/"pickup" label associated with the order |
| route.order.type_index | integer | Index of order of the same type and order handle |
| route.order.started_at | timestamp | Timestamp representing when the order tracking was started |
| route.order.cancelled_at | timestamp | Timestamp at which the order was cancelled |
| route.order.completed_at | timestamp | Timestamp at which the order was completed |
| route.order.expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| route.order.actual_service_time | integer | Actual time spent by the driver at the customer location |
| route.order.estimate | Object | Object containing the estimate metrics |
| route.order.estimate.arrive_at | timestamp | Order Estimated arrival timestamp |
| route.order.estimate.start_by | timestamp | Order Estimated start time |
| route.order.estimate.distance | integer | Estimated distance to fulfill the order |
| route.order.estimate.duration | integer | Estimated duration to fulfill the order |
| route.route_handle | string | Unique handle for the route. |
| route.ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| route.status | string | Status representing the stage in which the order is in right now, enumerated values among planned, assigned, tracking, completed |
| route.intent | string | Intent of API enumerated as self_improving, on_time OR flex |
| route.version | integer | Integer indicating the version of the route |
| route.started_at | timestamp | Timestamp at which the route was started |
| route.completed_at | timestamp | Timestamp at which all orders in the route were completed |
| route.assigned_at | timestamp | Timestamp at which the route was assigned |
| route.planned_at | timestamp | Timestamp at which the route was planned |
| route.created_at | timestamp | Timestamp at which the route was created |
| route.estimate | object | Object containing the estimate metrics (Only present for routes in non terminal state) |
| route.estimate.start_by | object | Estimated start time |
| route.estimate.distance | integer | Estimated distance to fulfill the route |
| route.estimate.duration | integer | Estimated duration to fulfill the route |
| route.duration | integer | Duration spent during the whole route (Only present for routes in terminal state) |
| route.polyline | integer | Polyline (linestring geoJSON) representing route travelled (Only present for routes in terminal state) |
| route.device_id | string | Unique identifier for the driver fulfilling the order in the route |
| route.driver_handle | string | Unique handle for the driver which is case insensitive |
| route.metadata | object | Route metadata |
| route.embed_url | string | URL string that can be used to embed the route tracking in customer dashboards |
| route.region | object | Object containing the city/state/country of the route |
Complete Route
Complete route example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75/complete \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.post("https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75/complete",
headers=AUTH_HEADER)
HTTP 200 - Complete route response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"completed",
"completed_at": "2023-03-14T23:44:00Z"
"intent":"on_time",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z",
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[77.72123, 12.89617],
[77.72169, 12.89595],
[77.72214, 12.89572]
]
},
"start_location":{"type": "Point", "coordinates": [-121.8924515, 37.4124516]},
"end_location":{"type": "Point", "coordinates": [-121.8984515, 37.5124516]}
},
"orders":[
{
"order_handle": "order-112233",
"fulfillment_attempt":1,
"status": "assigned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Complete a route using the route_handle.
POST /orders/routes/{route_handle}/complete
Authentication: Basic Auth or OAuth Token
Path Parameters
route_handle- a string representing the route_handle
Response attributes
| Name | Type | Description |
|---|---|---|
| orders | array | Array of order objects |
| order | object | Definition of a order object |
| order.order_handle | string | Unique handle for the Order |
| order.fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| order.status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| order.ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| order.device_id | string | Device Identifier that uniquely identifies a device within HyperTrack |
| order.driver_handle | string | Unique handle for the driver which is case insensitive |
| order.route_handle | string | Unique handle for the route of which the order is part of |
| order.track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| order.plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| order.created_at | timestamp | Timestamp representing the creation time of the order |
| order.started_at | timestamp | Timestamp representing when the order tracking was started |
| order.share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| order.scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| order.scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| order.completed_at | timestamp | Timestamp at which the order was completed |
| order.cancelled_at | timestamp | Timestamp at which the order was cancelled |
| order.disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| order.enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| order.assigned_at | timestamp | Timestamp at which the order was assigned |
| order.metadata | object | Metadata for an order |
| order.region | object | Object containing the city, state, and country of the order destination |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | integer | Radius (in meters) of a circular order destination |
| order.destination.address | string | Destination address for the order |
| order.risk_status | boolean | Flag indicating if a risk exists or not |
| order.risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| order.arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| order.expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| order.actual_service_time | integer | Actual time spent by the driver at the customer location |
| order.product_type | array | List of strings representing specific product types associated with the order |
| order.type | string | Indicates "drop"/"pickup" label associated with the order |
| order.type_index | integer | Index of order of the same type and order handle |
| order.capacity_used | integer | Indicates the capacity utilized by the order |
| order.estimate | object | Estimate object containing the estimate metrics (Only present for non terminal orders) |
| order.estimate.arrive_at | timestamp | Order Estimated arrival timestamp |
| order.estimate.start_by | timestamp | Order Estimated start time |
| order.estimate.distance | integer | Estimated distance to fulfill the order |
| order.estimate.duration | integer | Estimated duration to fulfill the order |
| order.distance | integer | Actual distance travelled to fulfill the order (Only present for orders in terminal state) |
| order.duration | integer | Actual duration taken to fulfill the order (Only present for orders in terminal state) |
| route_handle | string | Unique handle for the route |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Orders APIs. The handle needs to be url safe. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, assigned, tracking, completed |
| plan_mode | string | Mode with which route is planned enumerated as scheduled, pool, on_demand OR manual |
| version | integer | Integer indicating the version of the route |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| estimate | object | Object containing the estimate metrics |
| estimate.start_by | object | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the route |
| estimate.duration | integer | Estimated duration to fulfill the route |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| started_at | timestamp | Timestamp at which the route was started |
| assigned_at | timestamp | Timestamp at which the route was assigned |
| created_at | timestamp | Timestamp at which the route was created |
| completed_at | timestamp | Timestamp at which all orders in the route were completed |
| device_id | string | Unique identifier for the driver fulfilling the order in the route |
| driver_handle | string | Unique handle for the driver |
| metadata | object | Route metadata |
| embed_url | string | URL string that can be used to embed the route tracking in customer dashboards |
| markers | array | Array of markers generated during the route |
| distance | integer | Distance travelled during the whole route |
| duration | integer | Duration spent during the whole route |
| polyline | integer | Polyline (linestring geoJSON) representing route travelled |
| tracking_rate | float | Number indicating the tracking rate of the driver during the route |
| region | object | Object containing the city/state/country of the route |
Reassign Route
Assign route example:
payload='{
"device_id": "00000-11FD334-AS433-223DF"
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75/reassign \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
payload = {
"device_id": "00000-11FD334-AS433-223DF"
}
response = requests.post("https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75/reassign",
json=payload,
headers=AUTH_HEADER)
HTTP 200 - Assign route response
{
"route_handle":"fc2870fa-ff94-411c-ad12-1360cc28cd75",
"ops_group_handle": "SAN_JOSE_WH",
"status":"assigned",
"intent":"on_time",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z"
},
"orders":[
{
"order_handle": "order-112233",
"fulfillment_attempt":1,
"status": "assigned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-11FD334-AS433-223DF",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Re-Assign route using the route_handle.
POST /orders/routes/{route_handle}/reassign
Authentication: Basic Auth or OAuth Token
Path Parameters
route_handle- a string representing the route_handle
Assign route request attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | UUID of the device to assign |
| driver_handle | string | Unique identifier of the driver to assign (case insensitive) |
NOTE: Please provide either device_id OR driver_handle but not both.
Update Metadata
Update route metadata example:
payload='{
"metadata": {"routePlan": "122322"}
}'
curl -X PATCH \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75 \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
payload = {
"metadata": {"routePlan": "122322"}
}
response = requests.patch("https://v3.api.hypertrack.com/orders/routes/fc2870fa-ff94-411c-ad12-1360cc28cd75",
data=payload, headers=AUTH_HEADER)
HTTP 200 - Update route response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"assigned",
"intent":"on_time",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z"
},
"orders":[
{
"order_handle": "order-112233",
"fulfillment_attempt":1,
"status": "assigned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"routePlan": "122322"},"
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Update route metadata using the route_handle.
PATCH /orders/routes/{route_handle}
Authentication: Basic Auth or OAuth Token
Path Parameters
route_handle- a string representing the route_handle
Update Route metadata request attributes
| Name | Type | Description |
|---|---|---|
| metadata | object | Metadata for the route |
Add Order
Add orders example:
payload='{
"orders": [ { "order_handle":"order-112233" }, { "order_handle":"order-112244"}]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/routes/route-1/add \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
payload = {
"orders": [ { "order_handle":"order-112233" }, { "order_handle":"order-112244"}]
}
response = requests.post("https://v3.api.hypertrack.com/orders/routes/route-1/add",
params=payload, headers=AUTH_HEADER)
HTTP 200 - Add orders response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"planned",
"intent":"on_time",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z",
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[77.72123, 12.89617],
[77.72169, 12.89595],
[77.72214, 12.89572]
]
},
"start_location":{"type": "Point", "coordinates": [-121.8924515, 37.4124516]},
"end_location":{"type": "Point", "coordinates": [-121.8984515, 37.5124516]}
},
"orders":[
{
"order_handle": "order-112244",
"fulfillment_attempt":1,
"status": "assigned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Add orders to a route.
POST /orders/routes/{route_handle}/add
Authentication: Basic Auth or OAuth Token
Path Parameters
route_handle- a string representing the route_handle
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| orders | array | Mandatory | Array of order objects |
| orders.order_handle | string | Mandatory | Unique handle for Order to be added |
| orders.type | string | Optional | type string of Order to be added |
| orders.type_index | integer | Optional | type index of Order to be added |
| resequence | boolean | Optional | Flag to add each order to the route at the most optimal position |
Remove Order
Remove orders example:
payload='{
"orders": [ { "order_handle":"order-112233" }]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/routes/route-1/remove \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
payload = {
"orders": [ { "order_handle":"order-112233" }]
}
response = requests.post("https://v3.api.hypertrack.com/orders/routes/route-1/remove",
params=payload, headers=AUTH_HEADER)
HTTP 200 - Remove orders response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"planned",
"intent":"on_time",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z",
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[77.72123, 12.89617],
[77.72169, 12.89595],
[77.72214, 12.89572]
]
},
"start_location":{"type": "Point", "coordinates": [-121.8924515, 37.4124516]},
"end_location":{"type": "Point", "coordinates": [-121.8984515, 37.5124516]}
},
"orders":[
{
"order_handle": "order-112244",
"fulfillment_attempt":1,
"status": "assigned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Remove orders from a route using the route_handle.
POST /orders/routes/{route_handle}/remove
Authentication: Basic Auth or OAuth Token
Path Parameters
route_handle- a string representing the route_handle
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| orders | array | Mandatory | Array of order objects |
| orders.order_handle | string | Mandatory | Unique handle for Order to be removed |
| orders.type | string | Optional | type string of Order to be removed |
| orders.type_index | integer | Optional | type index of Order to be removed |
Resequence Orders
Resequence orders example:
payload='{
"orders": [{"order_handle":"order-112244"}, {"order_handle":"order-112233"}]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/routes/route-1/resequence \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
payload = {
"orders": [{"order_handle":"order-112244"}, {"order_handle":"order-112233"}]
}
response = requests.post("https://v3.api.hypertrack.com/orders/routes/route-1/resequence",
params=payload, headers=AUTH_HEADER)
HTTP 200 - Resequence orders response
{
"route_handle":"route-1",
"ops_group_handle": "SAN_JOSE_WH",
"status":"planned",
"intent":"on_time",
"version":1,
"estimate":{
"start_by":"2023-03-14T23:20:00Z",
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[77.72123, 12.89617],
[77.72169, 12.89595],
[77.72214, 12.89572]
]
},
"start_location":{"type": "Point", "coordinates": [-121.8924515, 37.4124516]},
"end_location":{"type": "Point", "coordinates": [-121.8984515, 37.5124516]}
},
"orders":[
{
"order_handle": "order-112244",
"fulfillment_attempt":1,
"status": "assigned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5
}..
],
"device_id":"00000-ASD2-W2112F-AGHY3-2FFA",
"metadata":{"planId": "1223322"},
"embed_url":"https://embed.hypertrack.com/dkdkddnd"
}
Re-sequence the orders in a given route using the route_handle.
POST /orders/routes/{route_handle}/resequence
Authentication: Basic Auth or OAuth Token
Path Parameters
route_handle- a string representing the route_handle
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| orders | array | Mandatory | Array of order objects |
| orders.order_handle | string | Mandatory | Unique handle for Orders of a route |
| orders.type | string | Optional | type string of Order to be resequenced |
| orders.type_index | integer | Optional | type index of Order to be resequenced |
Note: Re sequence operation requires all order handles to be present as part of request
Manage Orders
Complete
Complete order example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/test_order_4/complete \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.post("https://v3.api.hypertrack.com/orders/test_order_4/complete",
headers=AUTH_HEADER)
HTTP 200 - Complete order response
{
"order_handle": "order-122332",
"fulfillment_attempt":1,
"status": "completed",
"completed_at": "2023-03-14T23:40:00Z",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"estimate":{
"arrive_at":"2023-03-14T23:35:00Z",
"start_by":"2023-03-14T23:25:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
}
Complete order using the order_handle.
POST /orders/{order_handle}/complete
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle- a string representing the order_handle
Query Parameters
type[Optional] - type string of order to complete (such aspick,drop)type_index[Optional] - type index of order to complete (such as 0, 1)
Get order response attributes
| Name | Type | Description |
|---|---|---|
| order_handle | string | Unique handle for the Order |
| fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs. The handle needs to be url safe. |
| device_id | string | Device Identifier that uniquely identifies a device within HyperTrackÏ√ |
| driver_handle | string | Unique handle for the driver which is case insensitive |
| route_handle | string | Unique handle for the route of which the order is part of |
| track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| created_at | timestamp | Timestamp representing the creation time of the order |
| started_at | timestamp | Timestamp representing when the order tracking was started |
| share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| completed_at | timestamp | Timestamp at which the order was completed |
| cancelled_at | timestamp | Timestamp at which the order was cancelled |
| disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| assigned_at | timestamp | Timestamp at which the order was assigned |
| planned_at | timestamp | Timestamp at which the order was planned |
| metadata | object | Metadata for an order |
| region | object | Object containing the city, state, and country of the order destination |
| destination | object | Defined order destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | integer | Radius (in meters) of a circular order destination |
| destination.address | string | Destination address for the order |
| risk_status | boolean | Flag indicating if a risk exists or not |
| risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| product_type | array | List of strings representing specific product types associated with the order |
| type | string | Indicates "drop"/"pickup" label associated with the order |
| type_index | integer | Index of order of the same type and order handle |
| capacity_used | integer | Indicates the capacity utilized by the order |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| images | array | Links for images taken as proof of work during fulfillment |
| completed_at_destination | boolean | Flag indicating whether the order was completed at the delivery location |
| cancelled_at_destination | boolean | Flag indicating whether the order was cancelled at the delivery location |
| order_score | integer | Score indicating the performance of the order |
| estimate | object | Estimate object containing the estimate metrics |
| estimate.arrive_at | timestamp | Estimated arrival timestamp |
| estimate.start_by | timestamp | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the order |
| estimate.duration | integer | Estimated duration to fulfill the order |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| distance | integer | Actual distance travelled to fulfill the order |
| duration | integer | Actual duration taken to fulfill the order |
| polyline | string | Actual route traversal polyline to the order destination |
| tracking_rate | float | Number indicating the tracking rate of the driver during the delivery |
| deviation_from_destination | integer | Deviation in meters between the order destination location and completion location |
| actual_service_time | integer | Actual time spent by the driver at the customer location |
| markers | object | Array of markers |
| events | object | Array of events that occurred during the order journey |
| previous_fulfillments | object | Array of fulfillment objects containing historic fulfillment_attempts for the order with the same handle |
Cancel
Cancel order example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/test_order_2/cancel \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.post("https://v3.api.hypertrack.com/orders/test_order_2/cancel",
headers=AUTH_HEADER)
HTTP 200 - Cancel order response
{
"order_handle": "order-122332",
"fulfillment_attempt":1,
"status": "cancelled",
"cancelled_at": "2023-03-14T23:40:00Z",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"estimate":{
"arrive_at":"2023-03-14T23:35:00Z",
"start_by":"2023-03-14T23:25:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
}
Cancel order using the order_handle.
POST /orders/{order_handle}/cancel
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle - a string representing the order_handle
Query Parameters
type[Optional] - type string of order to cancel (such aspick,drop)type_index[Optional] - type index of order to cancel (such as 0, 1)
Get order response attributes
| Name | Type | Description |
|---|---|---|
| order_handle | string | Unique handle for the Order |
| fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs. The handle needs to be url safe. |
| device_id | string | Device Identifier that uniquely identifies a device within HyperTrackÏ√ |
| driver_handle | string | Unique handle for the driver which is case insensitive |
| route_handle | string | Unique handle for the route of which the order is part of |
| track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| created_at | timestamp | Timestamp representing the creation time of the order |
| started_at | timestamp | Timestamp representing when the order tracking was started |
| share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| completed_at | timestamp | Timestamp at which the order was completed |
| cancelled_at | timestamp | Timestamp at which the order was cancelled |
| disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| assigned_at | timestamp | Timestamp at which the order was assigned |
| planned_at | timestamp | Timestamp at which the order was planned |
| metadata | object | Metadata for an order |
| region | object | Object containing the city, state, and country of the order destination |
| destination | object | Defined order destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | integer | Radius (in meters) of a circular order destination |
| destination.address | string | Destination address for the order |
| risk_status | boolean | Flag indicating if a risk exists or not |
| risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| product_type | array | List of strings representing specific product types associated with the order |
| type | string | Indicates "drop"/"pickup" label associated with the order |
| type_index | integer | Index of order of the same type and order handle |
| capacity_used | integer | Indicates the capacity utilized by the order |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| images | array | Links for images taken as proof of work during fulfillment |
| completed_at_destination | boolean | Flag indicating whether the order was completed at the delivery location |
| cancelled_at_destination | boolean | Flag indicating whether the order was cancelled at the delivery location |
| order_score | integer | Score indicating the performance of the order |
| estimate | object | Estimate object containing the estimate metrics |
| estimate.arrive_at | timestamp | Estimated arrival timestamp |
| estimate.start_by | timestamp | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the order |
| estimate.duration | integer | Estimated duration to fulfill the order |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| distance | integer | Actual distance travelled to fulfill the order |
| duration | integer | Actual duration taken to fulfill the order |
| polyline | string | Actual route traversal polyline to the order destination |
| tracking_rate | float | Number indicating the tracking rate of the driver during the delivery |
| deviation_from_destination | integer | Deviation in meters between the order destination location and completion location |
| actual_service_time | integer | Actual time spent by the driver at the customer location |
| markers | object | Array of markers |
| events | object | Array of events that occurred during the order journey |
| previous_fulfillments | object | Array of fulfillment objects containing historic fulfillment_attempts for the order with the same handle |
Reassign
Reassign order to a driver example:
payload='{
"driver_handle": "sam@8303"
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/test_order_4/reassign \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
payload = {
"driver_handle": "sam@8303"
}
response = requests.post("https://v3.api.hypertrack.com/orders/test_order_4/reassign",
params=payload, headers=AUTH_HEADER)
HTTP 200 - Reassign order to a driver response
{
"order_handle": "test_order_4",
"fulfillment_attempt":1,
"status": "assigned",
"driver_handle": "sam@8303",
"assigned_at": "2023-08-29T02:00:000Z",
"route_handle": "732893000-98900-hjhkh",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-08-14T23:00:00Z",
"scheduled_at":"2023-08-29T08:00:000Z",
"scheduled_after":"2023-08-29T06:00:000Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"estimate":{
"arrive_at":"2023-08-29T23:35:00Z",
"start_by":"2023-08-29T23:25:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
}
Reassigns an order to a driver in an optimal manner.
POST /orders/{order_handle}/reassign
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle- a string representing the order_handle
Query Parameters
type[Optional] - type string of order to reassign (such aspick,drop)type_index[Optional] - type index of order to reassign (such as 0, 1)
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| driver_handle | string | Mandatory | Unique identifier of the driver to assign |
| ops_group_handle | string | Optional | Unique identifier of the ops group to associate the order while assignment |
Note: ops_group_handle is needed for cases where driver is associated with multiple ops groups via schedule linking
Disable
Unsnooze order example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/test_order_4/disable \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.post("https://v3.api.hypertrack.com/orders/test_order_4/disable",
headers=AUTH_HEADER)
HTTP 200 - Snooze order response
{
"order_handle": "order-122332",
"fulfillment_attempt":1,
"status": "snoozed",
"disabled_at": "2023-03-14T23:40:00Z",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"estimate":{
"arrive_at":"2023-03-14T23:35:00Z",
"start_by":"2023-03-14T23:25:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
}
Disable an order using the order_handle.
POST /orders/{order_handle}/disable
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle- a string representing the order_handle
Query Parameters
type[Optional] - type string of order to disable (such aspick,drop)type_index[Optional] - type index of order to disable (such as 0, 1)
Get order response attributes
| Name | Type | Description |
|---|---|---|
| order_handle | string | Unique handle for the Order |
| fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs. The handle needs to be url safe. |
| device_id | string | Device Identifier that uniquely identifies a device within HyperTrackÏ√ |
| driver_handle | string | Unique handle for the driver which is case insensitive |
| route_handle | string | Unique handle for the route of which the order is part of |
| track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| created_at | timestamp | Timestamp representing the creation time of the order |
| started_at | timestamp | Timestamp representing when the order tracking was started |
| share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| completed_at | timestamp | Timestamp at which the order was completed |
| cancelled_at | timestamp | Timestamp at which the order was cancelled |
| disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| assigned_at | timestamp | Timestamp at which the order was assigned |
| planned_at | timestamp | Timestamp at which the order was planned |
| metadata | object | Metadata for an order |
| region | object | Object containing the city, state, and country of the order destination |
| destination | object | Defined order destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | integer | Radius (in meters) of a circular order destination |
| destination.address | string | Destination address for the order |
| risk_status | boolean | Flag indicating if a risk exists or not |
| risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| product_type | array | List of strings representing specific product types associated with the order |
| type | string | Indicates "drop"/"pickup" label associated with the order |
| type_index | integer | Index of order of the same type and order handle |
| capacity_used | integer | Indicates the capacity utilized by the order |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| images | array | Links for images taken as proof of work during fulfillment |
| completed_at_destination | boolean | Flag indicating whether the order was completed at the delivery location |
| cancelled_at_destination | boolean | Flag indicating whether the order was cancelled at the delivery location |
| order_score | integer | Score indicating the performance of the order |
| estimate | object | Estimate object containing the estimate metrics |
| estimate.arrive_at | timestamp | Estimated arrival timestamp |
| estimate.start_by | timestamp | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the order |
| estimate.duration | integer | Estimated duration to fulfill the order |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| distance | integer | Actual distance travelled to fulfill the order |
| duration | integer | Actual duration taken to fulfill the order |
| polyline | string | Actual route traversal polyline to the order destination |
| tracking_rate | float | Number indicating the tracking rate of the driver during the delivery |
| deviation_from_destination | integer | Deviation in meters between the order destination location and completion location |
| actual_service_time | integer | Actual time spent by the driver at the customer location |
| markers | object | Array of markers |
| events | object | Array of events that occurred during the order journey |
| previous_fulfillments | object | Array of fulfillment objects containing historic fulfillment_attempts for the order with the same handle |
Enable
Unsnooze order example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/test_order_4/enable \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.post("https://v3.api.hypertrack.com/orders/test_order_4/enable",
headers=AUTH_HEADER)
HTTP 200 - Unsnooze order response
{
"order_handle": "order-122332",
"fulfillment_attempt":1,
"status": "ongoing",
"enabled_at": "2023-03-14T23:45:00Z",
"disabled_at": "2023-03-14T23:40:00Z",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"estimate":{
"arrive_at":"2023-03-14T23:35:00Z",
"start_by":"2023-03-14T23:25:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
}
Enable an order using the order_handle.
POST /orders/{order_handle}/enable
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle- a string representing the order_handle
Query Parameters
type[Optional] - type string of order to enable (such aspick,drop)type_index[Optional] - type index of order to enable (such as 0, 1)
Get order response attributes
| Name | Type | Description |
|---|---|---|
| order_handle | string | Unique handle for the Order |
| fulfillment_attempt | integer | Integer identifying the attempt count. This can used to fetch historic order data for the order handle. |
| status | string | Status representing the stage in which the order is in right now, enumerated values among planned, unplanned, assigned, ongoing, disabled, cancelled, completed |
| ops_group_handle | string | Unique handle for each Ops Group to be used in Drivers and Orders APIs. The handle needs to be url safe. |
| device_id | string | Device Identifier that uniquely identifies a device within HyperTrackÏ√ |
| driver_handle | string | Unique handle for the driver which is case insensitive |
| route_handle | string | Unique handle for the route of which the order is part of |
| track_mode | string | mode with which Order is tracked enumerated as on_time OR flex |
| plan_mode | string | mode with which Order is planned enumerated as scheduled, pool, on_demand OR manual |
| created_at | timestamp | Timestamp representing the creation time of the order |
| started_at | timestamp | Timestamp representing when the order tracking was started |
| share_url | string | URL to be shared with the customer to track the driver approaching the order destination |
| scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| completed_at | timestamp | Timestamp at which the order was completed |
| cancelled_at | timestamp | Timestamp at which the order was cancelled |
| disabled_at | timestamp | Timestamp at which the order was disabled/snoozed |
| enabled_at | timestamp | Timestamp at which the order was enabled/unsnoozed |
| assigned_at | timestamp | Timestamp at which the order was assigned |
| planned_at | timestamp | Timestamp at which the order was planned |
| metadata | object | Metadata for an order |
| region | object | Object containing the city, state, and country of the order destination |
| destination | object | Defined order destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | integer | Radius (in meters) of a circular order destination |
| destination.address | string | Destination address for the order |
| risk_status | boolean | Flag indicating if a risk exists or not |
| risks | object | Object containing key value pairs where the key is the risk_name and the value is the severity of the risk indicated by color (red/yellow/green) |
| arrived_at | timestamp | Timestamp at which the driver arrived at the order destination |
| expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| product_type | array | List of strings representing specific product types associated with the order |
| type | string | Indicates "drop"/"pickup" label associated with the order |
| type_index | integer | Index of order of the same type and order handle |
| capacity_used | integer | Indicates the capacity utilized by the order |
| start_location | object | GeoJSON geometry of type Point for start location point |
| end_location | object | GeoJSON geometry of type Point for end location point |
| images | array | Links for images taken as proof of work during fulfillment |
| completed_at_destination | boolean | Flag indicating whether the order was completed at the delivery location |
| cancelled_at_destination | boolean | Flag indicating whether the order was cancelled at the delivery location |
| order_score | integer | Score indicating the performance of the order |
| estimate | object | Estimate object containing the estimate metrics |
| estimate.arrive_at | timestamp | Estimated arrival timestamp |
| estimate.start_by | timestamp | Estimated start time |
| estimate.start_location | object | Estimated start location |
| estimate.end_location | object | Estimated end location |
| estimate.distance | integer | Estimated distance to fulfill the order |
| estimate.duration | integer | Estimated duration to fulfill the order |
| estimate.polyline | string | Estimated route traversal polyline to the order destination |
| distance | integer | Actual distance travelled to fulfill the order |
| duration | integer | Actual duration taken to fulfill the order |
| polyline | string | Actual route traversal polyline to the order destination |
| tracking_rate | float | Number indicating the tracking rate of the driver during the delivery |
| deviation_from_destination | integer | Deviation in meters between the order destination location and completion location |
| actual_service_time | integer | Actual time spent by the driver at the customer location |
| markers | object | Array of markers |
| events | object | Array of events that occurred during the order journey |
| previous_fulfillments | object | Array of fulfillment objects containing historic fulfillment_attempts for the order with the same handle |
Reschedule
Reschedule orders example:
payload='{
"scheduled_at": "2023-08-29T08:00:000Z",
"scheduled_after": "2023-08-29T06:00:000Z"
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/test_order_4/reschedule \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
payload = {
"scheduled_at": "2023-08-29T08:00:000Z",
"scheduled_after": "2023-08-29T06:00:000Z"
}
response = requests.post("https://v3.api.hypertrack.com/orders/test_order_4/reschedule",
params=payload, headers=AUTH_HEADER)
HTTP 200 - Reschedule order response
{
"order_handle": "test_order_4",
"fulfillment_attempt":1,
"status": "unplanned",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-08-14T23:00:00Z",
"scheduled_at":"2023-08-29T08:00:000Z",
"scheduled_after":"2023-08-29T06:00:000Z",
"metadata":{"customerId": "1223344"},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
}
Reschedule an order using the order_handle.
POST /orders/{order_handle}/reschedule
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle- a string representing the order_handle
| Name | Type | Mandatory/Optional | Description |
|---|---|---|---|
| scheduled_at | Datetime string | Mandatory | New Schedule time by which order needs to be fulfilled |
| scheduled_after | Datetime string | Optional | New Schedule time after which the driver needs to fulfill order (similar to slot start) |
Update
Update order data example:
payload='{
"metadata": {"customerId": "1122334", "priority": 1},
"scheduled_at": "2023-03-15 22:00:00",
"scheduled_after": "2023-03-15 23:00:00",
"capacity_used": 10
}'
curl -X PATCH \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/order-112233 \
-H 'Content-Type: application/json' \
-d $payload
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
order_data = {
"metadata": {"customerId": "1122334", "priority": 1},
"scheduled_at": "2023-03-15 22:00:00",
"scheduled_after": "2023-03-15 23:00:00",
"capacity_used": 10
}
response = requests.patch("https://v3.api.hypertrack.com/orders/order-112233",
params=order_metadata,
headers=AUTH_HEADER)
HTTP 200 - Patch order metadata response
{
"order_handle": "order-122332",
"fulfillment_attempt":1,
"status": "ongoing",
"ops_group_handle": "SAN_JOSE_WH",
"device_id": "00000-122DS-FD3322-22331-ASDD3",
"intent":"on_time",
"created_at":"2023-03-14T23:00:00Z",
"scheduled_at":"2023-03-14T23:50:00Z",
"scheduled_after":"2023-03-14T23:20:00Z",
"metadata":{"customerId": "1122334", "priority": 1},
"region":{
"city":"San Francisco",
"state":"California",
"country":"United States of America"
},
"destination":{
"geometry":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"radius":50,
"address":"Mission Peak, Fremont CA 94539"
},
"risk_status": false,
"expected_service_time":600,
"product_type":["plumber"],
"type":"drop",
"capacity_used":5,
"estimate":{
"arrive_at":"2023-03-14T23:35:00Z",
"start_by":"2023-03-14T23:25:00Z",
"start_location":{
"type": "Point",
"coordinates": [-122.4433564, 37.7606091]
},
"end_location":{
"type": "Point",
"coordinates": [-121.8984515, 37.5124516]
},
"distance":1000,
"duration":600,
"polyline": {
"type": "LineString",
"coordinates": [
[-122.271154, 37.804348],
[-122.272057, 37.80295],
[-122.272057, 37.80295],
[-122.278011, 37.805288]
]
}
},
}
Update order using the order_handle. Updating order attributes will change the route and ETAs of pending orders on the route.
PATCH /orders/{order_handle}
Authentication: Basic Auth or OAuth Token
Path Parameters
order_handle- a string representing the order_handle
Query Parameters
type[Optional] - type string of order to update (such aspick,drop)type_index[Optional] - type index of order to update (such as 0, 1)
Update order request attributes
| Name | Type | Description |
|---|---|---|
| metadata | object | Metadata for an order |
| scheduled_at | timestamp | Timestamp by which the order needs to be fulfilled |
| scheduled_after | timestamp | Timestamp after which the order needs to be fulfilled |
| destination | object | Defined order destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | integer | Radius (in meters) of a circular order destination |
| destination.address | string | Destination address for the order |
| expected_service_time | integer | Time in seconds that the driver is expected to spend at the order destination |
| product_type | array | List of strings representing specific product types associated with the order |
| type | string | Indicates "drop"/"pickup" label associated with the order |
| capacity_used | integer | Indicates the capacity utilized by the order |
Geofences
Manage Geofences on the HyperTrack platform. With HyperTrack Geofences API, you can create and manage the throughput of your businesses key locations.
Create geofences
payload='{
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [ 122.395223, 37.7947633]
},
"metadata": {
"station": "A"
},
"radius": 50
},
{
"geometry": {
"type": "Polygon",
"coordinates": [[
[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]
]]
},
"metadata": {
"dropoff": "1ABC"
}
}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences
-H 'Content-Type: application/json' \
-d $payload
let payload = {
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [ 122.395223, 37.7947633]
},
"metadata": {
"station": "A"
},
"radius": 50
},
{
"geometry": {
"type": "Polygon",
"coordinates": [[
[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]
]]
},
"metadata": {
"dropoff": "1ABC"
}
}
]
};
fetch(https://v3.api.hypertrack.com/geofences, {
method: "POST",
body: JSON.stringify(payload),
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
payload = {
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [ 122.395223, 37.7947633]
},
"metadata": {
"station": "A"
},
"radius": 50
},
{
"geometry": {
"type": "Polygon",
"coordinates": [[
[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]
]]
},
"metadata": {
"dropoff": "1ABC"
}
}
]
}
response = requests.request("POST", "https://v3.api.hypertrack.com/geofences/", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n" +
" \"geofences\": [\n" +
" {\n" +
" \"geometry\": {\n" +
" \"type\": \"Point\",\n" +
" \"coordinates\": [ 122.395223, 37.7947633]\n" +
" },\n" +
" \"metadata\": {\n" +
" \"station\": \"A\"\n" +
" },\n" +
" \"radius\": 50\n" +
" },\n" +
" {\n" +
" \"geometry\": {\n" +
" \"type\": \"Polygon\",\n" +
" \"coordinates\": [[[-122.395237, 37.7947693],\n" +
" [-122.402321, 37.794374],\n" +
" [-122.401371, 37.790205],\n" +
" [-122.389450, 37.791271],\n" +
" [-122.395237, 37.7947693]]]\n" +
" },\n" +
" \"metadata\": {\n" +
" \"dropoff\": \"1ABC\"\n" +
" }\n" +
" }\n" +
" ]\n" +
"}\n");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences")
.post(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/geofences';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [ 122.395223, 37.7947633]
},
"metadata": {
"station": "A"
},
"radius": 50
},
{
"geometry": {
"type": "Polygon",
"coordinates": [[
[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]
]]
},
"metadata": {
"dropoff": "1ABC"
}
}
]
}'
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
],
'content' => $payload
]);
$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/geofences")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [ 122.395223, 37.7947633]
},
"metadata": {
"station": "A"
},
"radius": 50
},
{
"geometry": {
"type": "Polygon",
"coordinates": [[
[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]
]]
},
"metadata": {
"dropoff": "1ABC"
}
}
]
}.to_json
response = http.request(request)
puts response.read_body
HTTP 201 - New geofence response payload
[
{
"geofence_id":"000111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"geometry":{
"type":"Point",
"coordinates": [122.395223, 37.7947633]
},
"metadata":{
"station": "A"
},
"radius":50,
},
{
"geofence_id":"0002223047-3b28-a8ec-e934e870c515",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"geometry":{
"type":"Polygon",
"coordinates": [[
[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]
]]
},
"metadata":{
"dropoff": "1ABC"
},
}
]
Create geofences for all your drivers or for a single driver.
POST /geofences
Authentication: Basic Auth or OAuth Token
Path Parameters
geofences - an array of geofences
geofences request attributes
| Name | Type | Description |
|---|---|---|
| geofences | array | Array of geofence objects (optional) |
| geofences[].geometry | object | GeoJSON geometry of type Point or Polygon |
| geofences[].geometry.type | string | Either Point or Polygon |
| geofences[].geometry.coordinates | array | Array of longitude and latitude in case of Point type; Polygon type contains array of positions (First and last positions need to be same to complete the loop |
| geofences[].radius | int | Defines the radius (in meters) of a circular geofence (optional, default is 30) |
| geofences[].metadata | object | Any metadata you want to assign to this geofence (optional) |
| device_id | string | Unique identifier representing a device, case sensitive (optional); When device_id is provided, the geofence will only apply to this one device; When this optional |
| metadata_filter | object | A key and value pair representing a group of devices (optional); When metadata_filter is provided, only devices registered with this key and value pair will be allowed to interact with the geofence |
| parameter is omitted, the geofence applies to all devices |
Update geofence metadata
payload='{
"metadata": {
"geofence_stop_id": "ABC123"
}
}'
curl -X PATCH \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/{geofence_id}
-H 'Content-Type: application/json' \
-d $payload
let payload = {
"metadata": {
"geofence_stop_id": "ABC123"
}
};
fetch(https://v3.api.hypertrack.com/geofences/{geofence_id}, {
method: "PATCH",
body: JSON.stringify(payload),
headers: {
"Content-Type": "application/json"
}
});
import requests
payload = {
"metadata": {
"geofence_stop_id": "ABC123"
}
}
response = requests.request("PATCH", "https://v3.api.hypertrack.com/geofences/{geofence_id}", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n" +
" \"metadata\": {\n" +
" "geofence_stop_id\": \"ABC123\"\n" +
" }\n" +
"}\n");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences/{geofence_id}")
.patch(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/geofences/{geofence_id}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"metadata": {
"geofence_stop_id": "ABC123"
}
}'
$context = stream_context_create([
"http" => [
"method" => "PATCH",
"header" => $basicAuth
],
'content' => $payload
]);
$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/geofences/{geofence_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"metadata": {
"geofence_stop_id": "ABC123"
}
}.to_json
response = http.request(request)
puts response.read_body
Update geofence metadata for any created geofence
PATCH /geofences/{geofence_id}
This will merge the supplied JSON with the existing metadata.
For example, if the existing metadata is{"foo": "bar"} and the PATCH request contains the payload
{"new": "value"}, the resulting geofence metadata value will be {"foo": "bar", "new": "value"}. Key collisions
are overwriting the previous keys.
Authentication: Basic Auth or OAuth Token
Path Parameters
geofence_id - a string representing the geofence ID for which metadata is being updated
Get geofence
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/{geofence_id}
-H 'Content-Type: application/json' \
-d $payload
fetch(https://v3.api.hypertrack.com/geofences/{geofence_id}, {
method: "GET",
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
response = requests.request("GET", "https://v3.api.hypertrack.com/geofences/{geofence_id}", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences/{geofence_id}")
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/geofences/{geofence_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'
url = URI("https://v3.api.hypertrack.com/geofences/{geofence_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)
HTTP 200 - Geofences response payload
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [122.395223, 37.794763]
}
"radius":50,
"region": {
"country": "United States of America",
"state": "California",
"city": "Mountain View",
"geohash": "9q9htz9p"
}
}
Get full geofence by geofence_id.
GET /geofences/{geofence_id}
Authentication: Basic Auth or OAuth Token
geofences response attributes
| Name | Type | Description |
|---|---|---|
| geometry | object | GeoJSON geometry of type Point or Polygon |
| geometry.type | string | Either Point or Polygon |
| geometry.coordinates | array | Array of longitude and latitude in case of Point type; Polygon type contains array of positions (First and last positions need to be same to complete the loop |
| radius | int | Defines the radius (in meters) of a circular geofence (optional) |
| metadata | object | Any metadata you want to assign to this geofence (optional) |
| device_id | string | Unique identifier representing a device, case sensitive (optional) |
| region | object | data about the region this geofence is in. Includes country, state, city and geohash |
Get all geofences
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/
-H 'Content-Type: application/json' \
-d $payload
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/?pagination_token={pagination_token}
-H 'Content-Type: application/json' \
-d $payload
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/?device_id={device_id}
-H 'Content-Type: application/json' \
-d $payload
// Get geofences created for all drivers
fetch(https://v3.api.hypertrack.com/geofences/, {
method: "GET",
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
// Get next page of geofences created for all drivers
fetch(https://v3.api.hypertrack.com/geofences/?pagination_token={pagination_token}, {
method: "GET",
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
// Get geofences created for selected drivers
fetch(https://v3.api.hypertrack.com/geofences/?device_id={device_id}, {
method: "GET",
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
# Get geofences created for all drivers
response = requests.request("GET", "https://v3.api.hypertrack.com/geofences", auth=("{AccountId}", "{SecretKey}"))
# Get next page of geofences created for all drivers
response = requests.request("GET", "https://v3.api.hypertrack.com/geofences/?pagination_token={pagination_token}", auth=("{AccountId}", "{SecretKey}"))
# Get geofences created for selected drivers
response = requests.request("GET", "https://v3.api.hypertrack.com/geofences/?device_id={device_id}", auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
// Get geofences created for all drivers
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences")
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
// Get next page of geofences created for all drivers
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences/?pagination_token={pagination_token}")
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
// Get geofences created for selected drivers
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences/?device_id={device_id}")
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
// Get geofences created for all drivers
$url = 'https://v3.api.hypertrack.com/geofences';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => $basicAuth
]
]);
$requestAll->setHeaders(array(
'Authorization' => $basicAuth
));
try {
$responseAll = $requestAll->send();
echo $responseAll->getBody();
} catch (HttpException $ex) {
echo $ex;
}
// Get next page geofences created for all drivers
$url = 'https://v3.api.hypertrack.com/geofences/?pagination_token={pagination_token}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => $basicAuth
]
]);
$requestAll->setHeaders(array(
'Authorization' => $basicAuth
));
try {
$responseAll = $requestAll->send();
echo $responseAll->getBody();
} catch (HttpException $ex) {
echo $ex;
}
// Get geofences created for selected drivers
$requestAllDevice = new HttpRequest();
$requestAllDevice->setUrl('https://v3.api.hypertrack.com/geofences/?device_id={device_id}');
$requestAllDevice->setMethod(HTTP_METH_GET);
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"header" => $basicAuth
]
]);
$requestAllDevice->setHeaders(array(
'Authorization' => $basicAuth
));
try {
$response = $requestAllDevice->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
?>
require 'uri'
require 'net/http'
require 'base64'
# Get geofences created for all drivers
url = URI("https://v3.api.hypertrack.com/geofences")
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)
# Get next page of geofences created for all drivers
url = URI("https://v3.api.hypertrack.com/geofences/?pagination_token={pagination_token}")
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)
# Get geofences created for selected drivers
url = URI("https://v3.api.hypertrack.com/geofences/?device_id={device_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)
HTTP 200 - Geofences response payload
{
"data": [
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425"
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [122.395223, 37.794763]
}
"radius":50,
"address": "123 Main St, Springfield, Big County, California, 12345677, United States of America",
"region": {
"country": "United States of America",
"state": "California",
"city": "Springfield",
"geohash": "46xg3rg1"
}
}
],
"links": {
"next": "https://v3.api.hypertrack.com/geofences/?pagination_token=eyJhY2NvdW50X2lkIj"
},
"pagination_token": "eyJhY2NvdW50X2lkIj"
}
Get all geofences with a paginated response
GET /geofences
Get next page of all geofences
GET /geofences/?pagination_token={pagination_token}
You may optionally pass in a device_id to get geofences created for this driver
GET /geofences/?device_id={device_id}
To get all geofences filtered by metadata:
GET /geofences?metadata_filter={url_encoded_json}
metadata_filter - a URL encoded string for JSON metadata to search for matching keys and values for geofence metadata in your account.
Authentication: Basic Auth or OAuth Token
get all geofences response attributes
| Name | Type | Description |
|---|---|---|
| data | array | Array of geofence objects (optional) |
| data[].geometry | object | GeoJSON geometry of type Point or Polygon |
| data[].geometry.type | string | Either Point or Polygon |
| data[].geometry.coordinates | array | Array of longitude and latitude in case of Point type; Polygon type contains array of positions (First and last positions need to be same to complete the loop |
| data[].radius | int | Defines the radius (in meters) of a circular geofence (optional, default is 30) |
| data[].metadata | object | Any metadata you want to assign to this geofence (optional) |
| data[].device_id | string | Unique identifier representing a device, case sensitive (optional) |
| data[].address | string | Address generated via reverse geocoding (optional; omitted if reverse geocoding of coordinates failed) |
| data[].region | object | region object with country, state, city and geohash (optional; omitted if reverse geocoding of coordinates failed) |
| links.next | string | API endpoint URL to get the next page of data (null if last page) |
| pagination_token | string | Pagination Token to pass in order to get the next page of data |
Delete geofences
curl -X DELETE \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/{geofence_id}
-H 'Content-Type: application/json' \
-d $payload
fetch(https://v3.api.hypertrack.com/geofences/{geofence_id}, {
method: "DELETE",
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
response = requests.request("DELETE", "https://v3.api.hypertrack.com/geofences/{geofence_id}", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences/{geofence_id}")
.delete()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/geofences/{geofence_id}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "DELETE",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/geofences/{geofence_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
Delete a created geofence
DELETE /geofences/{geofence_id}
Authentication: Basic Auth or OAuth Token
Deactivate geofences
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/{geofence_id}/deactivate
-H 'Content-Type: application/json' \
-d $payload
fetch(https://v3.api.hypertrack.com/geofences/{geofence_id}/deactivate, {
method: "POST",
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
response = requests.request("POST", "https://v3.api.hypertrack.com/geofences/{geofence_id}/deactivate", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences/{geofence_id}/deactivate")
.post()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/geofences/{geofence_id}/deactivate';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/geofences/{geofence_id}/deactivate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
Deactivate a geofence
POST /geofences/{geofence_id}/deactivate
Authentication: Basic Auth or OAuth Token
Activate geofences
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/{geofence_id}/activate
-H 'Content-Type: application/json' \
-d $payload
fetch(https://v3.api.hypertrack.com/geofences/{geofence_id}/activate, {
method: "POST",
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
response = requests.request("POST", "https://v3.api.hypertrack.com/geofences/{geofence_id}/activate", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/geofences/{geofence_id}/activate")
.post()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/geofences/{geofence_id}/activate';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/geofences/{geofence_id}/activate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
Activate an inactive geofence
POST /geofences/{geofence_id}/activate
Authentication: Basic Auth or OAuth Token
Get geofence visits
Get geofence visits.
HTTP 200 response with a payload representing geofence markers matching the query result.
{
"data": [
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"driver_handle": " TestDriver1",
"marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
"metadata": null,
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [-122.395223, 37.7947633]
},
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {
"location": {
"type":"Point",
"coordinates": [-122.154223, 37.132763]
},
"recorded_at": "2019-07-01T13:50:00.000000Z"
},
"duration": 900,
"route_to": {
"duration": 3600,
"distance": 2374
},
"value": "exit"
},
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "A2DA5B2A-1B23-1244-1235-A134BD212415",
...
}...
],
"links": {
"next": 'https://v3.api.hypertrack.com/geofences/visits?geofence_id=00001111-4047-4b28-a6ec-f934e870c425&pagination_token=eyJhY2NvdW50X2lkIj'
}
}
{
"data": [
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"driver_handle": " TestDriver1",
"marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
"metadata": null,
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [-122.395223, 37.7947633]
},
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {
"location": {
"type":"Point",
"coordinates": [-122.154223, 37.132763]
},
"recorded_at": "2019-07-01T13:50:00.000000Z"
},
"duration": 900,
"route_to": {
"duration": 3600,
"distance": 2374
},
"value": "exit"
},
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "A2DA5B2A-1B23-1244-1235-A134BD212415",
...
}...
],
"links": {
"next": 'https://v3.api.hypertrack.com/geofences/visits?geofence_id=00001111-4047-4b28-a6ec-f934e870c425&pagination_token=eyJhY2NvdW50X2lkIj'
}
}
{
"data": [
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"driver_handle": " TestDriver1",
"marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
"metadata": null,
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [-122.395223, 37.7947633]
},
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {
"location": {
"type":"Point",
"coordinates": [-122.154223, 37.132763]
},
"recorded_at": "2019-07-01T13:50:00.000000Z"
},
"duration": 900,
"route_to": {
"duration": 3600,
"distance": 2374
},
"value": "exit"
},
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "A2DA5B2A-1B23-1244-1235-A134BD212415",
...
}...
],
"links": {
"next": 'https://v3.api.hypertrack.com/geofences/visits?geofence_id=00001111-4047-4b28-a6ec-f934e870c425&pagination_token=eyJhY2NvdW50X2lkIj'
}
}
{
"data": [
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"driver_handle": " TestDriver1",
"marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
"metadata": null,
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [-122.395223, 37.7947633]
},
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {
"location": {
"type":"Point",
"coordinates": [-122.154223, 37.132763]
},
"recorded_at": "2019-07-01T13:50:00.000000Z"
},
"duration": 900,
"route_to": {
"duration": 3600,
"distance": 2374
},
"value": "exit"
},
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "A2DA5B2A-1B23-1244-1235-A134BD212415",
...
}...
],
"links": {
"next": 'https://v3.api.hypertrack.com/geofences/visits?geofence_id=00001111-4047-4b28-a6ec-f934e870c425&pagination_token=eyJhY2NvdW50X2lkIj'
}
}
{
"data": [
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
"metadata": null,
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [-122.395223, 37.7947633]
},
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {
"location": {
"type":"Point",
"coordinates": [-122.154223, 37.132763]
},
"recorded_at": "2019-07-01T13:50:00.000000Z"
},
"duration": 900,
"route_to": {
"duration": 3600,
"distance": 2374
},
"value": "exit"
},
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "A2DA5B2A-1B23-1244-1235-A134BD212415",
...
}...
],
"links": {
"next": 'https://v3.api.hypertrack.com/geofences/visits?geofence_id=00001111-4047-4b28-a6ec-f934e870c425&pagination_token=eyJhY2NvdW50X2lkIj'
}
}
{
"data": [
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"driver_handle": " TestDriver1",
"marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
"metadata": null,
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [-122.395223, 37.7947633]
},
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [-122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {
"location": {
"type":"Point",
"coordinates": [-122.154223, 37.132763]
},
"recorded_at": "2019-07-01T13:50:00.000000Z"
},
"duration": 900,
"route_to": {
"duration": 3600,
"distance": 2374
},
"value": "exit"
},
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "A2DA5B2A-1B23-1244-1235-A134BD212415",
...
}...
],
"links": {
"next": 'https://v3.api.hypertrack.com/geofences/visits?geofence_id=00001111-4047-4b28-a6ec-f934e870c425&pagination_token=eyJhY2NvdW50X2lkIj'
}
}
With this API, you can get markers for your previously created geofences. Each marker represents an driver visiting a geofence.
To get all markers for your account, sorted by last visited, call: GET /geofences/visits
To get all markers for a given geofence_id, call the API with the geofence_id parameter:
GET /geofences/visits?geofence_id={geofence_id}
To get all markers for a given driver's device, use the device_id parameter:
GET /geofences/visits?device_id={device_id}
To get all visits of a driver, use the driver_handle parameter:
GET /geofences/visits?driver_handle={driver_handle}
Authentication: Basic Auth or OAuth Token
The JSON response contains two keys named data and links, where data contains an array of markers ordered in descending time, and links contains a url to retrieve the next page of results. If there is not a next page found, the next object will be null.
Response Attributes
| Name | Type | Description |
|---|---|---|
| data | Array | Array of geofence markers returned |
| data.geofence_id | String | geofence_id of the current marker |
| data.marker_id | String | Unique identifier for this geofence marker |
| data.device_id | String | device_id of app user for this marker (i.e., geofence visit) |
| data.driver_handle | String | Unique handle of the driver |
| data.account_id | String | account_id of app user for this marker (i.e., geofence visit); will always be the account_id corresponding to you auth headers |
| data.trip_id | String | trip_id of this marker; only supported for trip specific geofences (optional) |
| data.created_at | String | ISO 8601 Date and time when the marker was created (server timestamp) |
| data.metadata | String | Geofence metadata of the geofence creating this marker (optional) |
| data.geometry | Object | Geofence geometry of the geofence creating this marker |
| data.route_to | Object | Object describing the route since last geofence marker (optional) |
| data.route_to.distance | int | Distance travelled since last geofence marker or start of tracking session in [meters] |
| data.route_to.duration | int | Duration since last geofence marker or start of tracking session in [seconds] |
| data.route_to.idle_time | int | Duration at stops since last geofence marker or start of tracking session in [seconds] |
| data.route_to.started_at | String | ISO 8601 Date and time when route_to calculation started |
| data.duration | int | Duration of the visit in [seconds] |
| data.geofence_type | String | Type of geofence. Can be account, device or trip |
| data.arrival | object | Object representing details about the geofence arrival |
| data.arrival.location | object | Location object that triggered geofence arrival |
| data.arrival.location.type | string | As of right now, only Point is supported |
| data.arrival.location.coordinates | array | Array of longitude, latitude and (optional) elevation |
| data.arrival.recorded_at | string | ISO 8601 date when the location triggering arrival was recorded |
| data.exit | object | Object representing details about the geofence exit. Does not exist when the user is still inside the geofence. {optional} |
| data.exit.location | object | Location object that triggered geofence exit. Only set when geofence was exited due to a location. Can be empty when marker was closed to due a health event. (optional) |
| data.exit.location.type | string | As of right now, only Point is supported |
| data.exit.location.coordinates | array | Array of longitude, latitude and (optional) elevation |
| data.exit.recorded_at | string | ISO 8601 date when the event triggering exit was recorded |
Patch geofence visits
HTTP 200 response with a payload representing geofence markers matching the query result. Note that this payload will apply to
marker_idas described in the PATCH API.
payload='{
"metadata": {
"message": "Package left at the door",
"tracking_id": "384748984"
}
}'
payload='{
"metadata": {
"message": "Package left at the door",
"tracking_id": "384748984"
}
}'
payload='{
"metadata": {
"message": "Package left at the door",
"tracking_id": "384748984"
}
}'
payload='{
"metadata": {
"message": "Package left at the door",
"tracking_id": "384748984"
}
}'
payload='{
"metadata": {
"message": "Package left at the door",
"tracking_id": "384748984"
}
}'
payload='{
"metadata": {
"message": "Package left at the door",
"tracking_id": "384748984"
}
}'
Patch a geofence visit to attach visit specific metadata.
PATCH /geofences/visits/{marker_id}
Authentication: Basic Auth or OAuth Token
Geotags
Use the HyperTrack Geotags API to access comprehensive details regarding you order tracked using geotags generated by your drivers in the field. Take advantage of our diverse set of filters designed to facilitate data segmentation and summarization. These filters empower you to effectively analyze the progression of work in the field.
Get Orders with Geotags
Fetch all orders with the corresponding geotags.
GET /geotags
Authentication: Basic Auth or OAuth Token
Query Parameters (Filters)
order_handle(optional) - String representing the orderdriver_handle(optional)- String representing the unique identifier for the driverfrom_geotag_type(optional) - String representing type of geotag corresponding to start of a segment during order fulfillmentto_geotag_type(optional) - String representing type of geotag corresponding to end of a segment during order fulfillmentdriver_name(optional) - Name of the driver fulfilling the orderdriver_profile_filter(optional) - Metadata associated with the driver fulfilling the ordermetadata_filter(optional) - Metadata associated with the geotagops_group_handle(optional) - String representing ops group handleregion(optional) - Region JSON string with country, state and cityfrom_time(optional) - ISO 8601 datetime indicating the start time (Defaults to past 24 hours from current time)to_time(optional) - ISO 8601 datetime indicating the end time (Defaults to current time)pagination_token(optional)- Identifier used to fetch the next page of dataaggregate(optional) - Flag to retrieve aggregated data over the provided time range
Note: The from_time and to_time fields allow you to provide a timerange filter that fetches the Orders fulfilled within the given duration. This is powerful since the summary data will be calculated comprehensively over this provided timerange.
Usage
Fetch orders (with geotags) for a driver
Fetch all orders fulfilled by a driver using the driver_handle in a given timerange.
GET /geotags?from_time={from_time}&to_time={to_time}&driver_handle={driver_handle}
Request - GET Orders (with Geotags) filtered by Drivers
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&driver_handle=108103 \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&driver_handle=108103",
headers=AUTH_HEADER)
Response - HTTP 200 - GET Orders (with Geotags) filtered by Drivers
{
"orders": [{
{
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 0,
"driver_handle": "108103",
"driver_name": "James",
"duration": 38,
"geotags": [
{
"deviation": null,
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 0,
"driver_handle": "108103",
"driver_name": "James",
"duration": 38,
"expected_location": null,
"geotag_id": "6bef936e-5ade-4315-872d-da6ac75b8v97",
"geotag_type": "Logout",
"location": {
"address": "#1 Market, India",
"geometry": {
"coordinates": [
85.845967,
20.312069
],
"type": "Point"
},
"radius": null
},
"metadata": {
"AppName": "FCC",
"AppVersion": "1.0.5",
"FccName": ""
},
"ops_group_handle": "SJC_FCC",
"order_handle": "order-1",
"recorded_at": "2023-08-01T20:17:19.165Z",
"region": {
"city": "Bhubaneswar Municipal Corporation",
"country": "India",
"state": "Odisha"
},
"start_location": null,
"system_generated_order_handle": true,
"tracking_rate": 0.97
}
],
"last_geotag_recorded_at": "2023-08-01T20:17:19.165Z",
"ops_group_handle": "default",
"order_handle": "be9b166b5aae2ceb63800b102c51e6b5",
"system_generated_order_handle": true,
"tracking_rate": 0.97
},
}],
"pagination_token": "kyJuZXh0X2ZldGNoX3JlY29yZGVkX2F0IjogIjIwMjMtMDgtMDFUMTQ6MTA6MzIuNTkyWiJ9"
}
Fetch orders (with geotags) for an ops group
Fetch all orders fulfilled by drivers belonging to an ops group in a given timerange.
GET /geotags?from_time={from_time}&to_time={to_time}&ops_group_handle={ops_group_handle}
Request - GET Orders (with Geotags) filtered by Ops group
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&ops_group_handle=SJC_FCC \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&ops_group_handle=SJC_FCC",
headers=AUTH_HEADER)
Response - HTTP 200 - GET Orders (with Geotags) filtered by Ops group
{
"orders": [{
{
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 0,
"driver_handle": "108103",
"driver_name": "James",
"duration": 38,
"geotags": [
{
"deviation": null,
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 0,
"driver_handle": "108103",
"driver_name": "James",
"duration": 38,
"expected_location": null,
"geotag_id": "6bef936e-5ade-4315-872d-da6ac75b8v97",
"geotag_type": "Logout",
"location": {
"address": "#1 Market, India",
"geometry": {
"coordinates": [
85.845967,
20.312069
],
"type": "Point"
},
"radius": null
},
"metadata": {
"AppName": "FCC",
"AppVersion": "1.0.5",
"FccName": ""
},
"ops_group_handle": "SJC_FCC",
"order_handle": "order-1",
"recorded_at": "2023-08-01T20:17:19.165Z",
"region": {
"city": "Bhubaneswar Municipal Corporation",
"country": "India",
"state": "Odisha"
},
"start_location": null,
"system_generated_order_handle": true,
"tracking_rate": 0.97
}
],
"last_geotag_recorded_at": "2023-08-01T20:17:19.165Z",
"ops_group_handle": "default",
"order_handle": "be9b166b5aae2ceb63800b102c51e6b5",
"system_generated_order_handle": true,
"tracking_rate": 0.97
},
}],
"pagination_token": "kyJuZXh0X2ZldGNoX3JlY29yZGVkX2F0IjogIjIwMjMtMDgtMDFUMTQ6MTA6MzIuNTkyWiJ9"
}
Fetch order segments (with geotags)
A segment in an order is identified by a geotag_type. Fetch specific segments within orders fulfilled using the from_geotag_type and to_geotag_type filters for a given timerange.
GET /geotags?from_geotag_type={from_geotag_type}&to_geotag_type={to_geotag_type}&{from_time}&to_time={to_time}
Request - GET Orders (with Geotags) between geotag_type
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&from_geotag_type=assigned&to_geotag_type=completed \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&from_geotag_type=assigned&to_geotag_type=completed",
headers=AUTH_HEADER)
Response - HTTP 200 - GET Orders (with Geotags) between geotag_type
{
"orders": [{
{
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 1500,
"driver_handle": "108103",
"driver_name": "James",
"duration": 18,
"geotags": [
{
"deviation": null,
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 1000,
"driver_handle": "108103",
"driver_name": "James",
"duration": 10,
"expected_location": null,
"geotag_id": "6bef936e-5ade-4315-872d-da6ac75b8v97",
"geotag_type": "assigned",
"location": {
"address": "#1 Market, India",
"geometry": {
"coordinates": [
85.845967,
20.312069
],
"type": "Point"
},
"radius": null
},
"metadata": {
"AppName": "FCC",
"AppVersion": "1.0.5",
"FccName": "",
},
"ops_group_handle": "default",
"order_handle": "order-1",
"recorded_at": "2023-08-01T20:17:19.165Z",
"region": {
"city": "Bhubaneswar Municipal Corporation",
"country": "India",
"state": "Odisha"
},
"start_location": null,
"system_generated_order_handle": true,
"tracking_rate": 0.97
},
{
"deviation": null,
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 500,
"driver_handle": "108103",
"driver_name": "James",
"duration": 3,
"expected_location": null,
"geotag_id": "6bef936e-5ade-4315-872d-da6ac75b8v97",
"geotag_type": "arrived",
"location": {
"address": "#1 Market, India",
"geometry": {
"coordinates": [
85.845967,
20.312069
],
"type": "Point"
},
"radius": null
},
"metadata": {
"AppName": "FCC",
"AppVersion": "1.0.5",
"FccName": "",
},
"ops_group_handle": "default",
"order_handle": "order-1",
"recorded_at": "2023-08-01T20:20:19.165Z",
"region": {
"city": "Bhubaneswar Municipal Corporation",
"country": "India",
"state": "Odisha"
},
"start_location": null,
"system_generated_order_handle": true,
"tracking_rate": 0.97
},
{
"deviation": null,
"device_id": "c7f78b9a-01fa-5ff2-b137-eeb934d141d6",
"distance": 0,
"driver_handle": "108103",
"driver_name": "James",
"duration": 5,
"expected_location": null,
"geotag_id": "6bef936e-5ade-4315-872d-da6ac75b8v97",
"geotag_type": "completed",
"location": {
"address": "#1 Market, India",
"geometry": {
"coordinates": [
85.845967,
20.312069
],
"type": "Point"
},
"radius": null
},
"metadata": {
"AppName": "FCC",
"AppVersion": "1.0.5",
"FccName": "",
},
"ops_group_handle": "default",
"order_handle": "order-1",
"recorded_at": "2023-08-01T20:25:19.165Z",
"region": {
"city": "Bhubaneswar Municipal Corporation",
"country": "India",
"state": "Odisha"
},
"start_location": null,
"system_generated_order_handle": true,
"tracking_rate": 0.97
}
],
"last_geotag_recorded_at": "2023-08-01T20:25:19.165Z",
"ops_group_handle": "default",
"order_handle": "be9b166b5aae2ceb63800b102c51e6b5",
"system_generated_order_handle": true,
"tracking_rate": 0.97
},
}],
"pagination_token": "kyJuZXh0X2ZldGNoX3JlY29yZGVkX2F0IjogIjIwMjMtMDgtMDFUMTQ6MTA6MzIuNTkyWiJ9"
}
Fetch order aggregates (with geotags)
Fetch aggregate metrics for the orders fulfilled in a given timerange.
GET /geotags?{from_time}&to_time={to_time}&aggregate=true
Request - GET Orders (with Geotags) with aggregate
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&aggregate=true \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/geotags?from_time=2023-08-01T00:00:00Z&to_time=2023-08-01T23:59:59Z&aggregate=true",
headers=AUTH_HEADER)
Response - HTTP 200 - GET Orders (with Geotags) with aggregate
{
"aggregate": {
"count": 386,
"deviation": {
"max": 0.0,
"mean": 0.0,
"mean_by_driver": 0.0,
"min": 0.0,
"stdev": 0.0,
"sum": 0.0
},
"distance": {
"max": 346000.0,
"mean": 2004.0,
"mean_by_driver": 1938.0,
"min": 0.0,
"stdev": 21072.37,
"sum": 773459.0
},
"duration": {
"max": 1047775.0,
"mean": 5232.0,
"mean_by_driver": 5062.0,
"min": 0.0,
"stdev": 54049.2,
"sum": 2019740.0
},
"geotags": {
"count": 1129,
"count_mean": 2.92
},
"tracking_rate": 0.88
},
}
Get Geotag Timeline
Fetch a geotag identified by the geotag_id
GET /geotags/{geotag_id}
Authentication: Basic Auth or OAuth Token
Path Parameters
geotag_id - string representing the unique identifier of a geotag (case sensitive)
Get Geotag Timeline Request:
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geotags/befe814d-79e5-44d5-ac03-c4e47e0931c9 \
-H 'Content-Type: application/json'
import requests
import base64
AUTHORIZATION_TOKEN = "Basic {}".format(
base64.b64encode(f"{ACCOUNT_ID}:{SECRET_KEY}".encode("utf-8")).decode("utf-8")
)
AUTH_HEADER = {"Authorization": AUTHORIZATION_TOKEN}
response = requests.get("https://v3.api.hypertrack.com/geotags/befe814d-79e5-44d5-ac03-c4e47e0931c9",
headers=AUTH_HEADER)
HTTP 200 - get geotag timeline response
{
"geotag_id": "befe814d-79e5-44d5-ac03-c4e47e0931c9",
"order_handle": "ORD79789080-1",
"geotag_type": "PICKUP",
"ops_group_handle": "HUB_ID_3",
"system_generated_order_handle": false,
"recorded_at": "2023-04-19T14:00:58Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"driver_handle": "RASHID.397y",
"metadata": {
"regionId": 12234,
"zoneId": 3
},
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3599933082254,
37.753651385106075
]
},
"address": "Dolores St &, 19th St, San Francisco, CA 94114"
},
"expected_location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.4297458,
37.7617545
]
},
"address": "3750 18th St, San Francisco, CA 94114"
},
"distance": 2300,
"duration": 1200,
"tracking_rate": 86.5,
"deviation": 500,
"start_location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.4526714,
37.7652444
]
},
"address": "941 Cole St, San Francisco, CA 94117"
},
"region": {
"city": "San Francisco",
"state": "California",
"country": "United States of America"
}
}
Response
get geotag timeline response attributes
| Name | Type | Description |
|---|---|---|
| location | Location | Geometry location for a geotag |
| tracking_rate | float | Driver tracking rate during the lifespan of the geotag |
| order_handle | string | String representing order handle with which the geotag is associated |
| driver_name | string | String representing the name of the driver |
| recorded_at | string | ISO 8601 date when the geotag was created |
| start_location | Location | Start Geometry location for a geotag |
| duration | int | Time taken from start location to the geotag location |
| ops_group_handle | string | String representing the ops group handle |
| deviation | int | Deviation in meters from the expected location |
| device_id | UUID | String representing the ID of the device |
| system_generated_order_handle | bool | Boolean representing whether the handle was automatically generated by HT system or sent along with geotag data |
| geotag_id | UUID | Unique ID to identify a geotag |
| geotag_type | string | String representing type of Geotag |
| distance | int | Distance from the tracking start for the geotag |
| expected_location | Location | Expected Geometry location for a geotag |
| driver_handle | string | String representing the handle for the driver which is case insensitive |
| region | Region | Region for a geotag |
| metadata | dict | Optional metadata associated with the geotag |
Nearby
Nearby API allows you to identify drivers near a location of interest for an efficient dispatch. The API operates on the current locations of your fleet.
Nearby api solves following use cases for your fleet:
- Make a request to get nearby drivers
- Make a request to get ETA of a list of drivers
- Make a request to get ETA of nearby drivers
Api Specification
POST /nearby/v3
Authentication: Basic Auth or OAuth Token
Request Attributes for Nearby API
| Name | Type | Description |
|---|---|---|
| order | object | Order which the nearby api aims to fulfill. |
| order.destination | object | destination location around which to search drivers. (mandatory) |
| order.destination.geometry.type | string | as of right now, only Point is supported |
| order.destination.geometry.coordinates | array | array of longitude, latitude |
| order.order_id | string | order id (optional) |
| order.metadata | object | order metadata (optional) |
| search_type | string | type of nearby api search. region for finding nearby devices, eta for finding estimates of nearby devices or a list of drivers, (mandatory) |
| search_filter | object | filters to apply on nearby search results, driver_list filter can only be used with eta search_type and if used cannot be combined with any other filter |
| search_filter.search_radius | int | maximum distance (haversine) in meters of drivers from order destination, maximum of 160934 meters (100 miles), (optional) |
| search_filter.include_on_trip | boolean | true when on trip drivers are also needed as part of response (default value is false) |
| search_filter.driver_profile | object | used to specify a filter that is applied on the drivers returned in a nearby search result; For example, this profile filter can represent attributes describing your gig workers, such as a team assignment, gig category, etc. (optional) |
| search_filter.driver_list | array | array of device ids whose estimates to order destination will be calculated. Only for search type eta, if present other filters are not allowed (optional) |
Response data
The Nearby API returns the following data.
| Name | Type | Description |
|---|---|---|
| drivers | array | list of driver objects |
| drivers.device | object | device related information of the driver |
| drivers.device.device_id | string | device id of the device |
| drivers.device.info | object | device_info. same fields supports as in devices api |
| drivers.device.info.timezone | string | The timezone on the device in TZ format |
| drivers.device.info.os_name | string | The operating system of the device, can be one of iOS or Android |
| drivers.device.info.device_brand | string | The brand of the device |
| drivers.device.info.sdk_version | string | The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
| drivers.device.info.device_model | string | The device model |
| drivers.device.info.network_operator | string | The network operator for the device |
| drivers.device.info.os_version | string | The version of the operating system on the device |
| drivers.device.info.os_hardware_identifier | string | Hardware identifier returned from the OS. (OS specific. Android uses ANDROID_ID; iOS uses identifierForVendor |
| drivers.device.info.name | string | Name of the device |
| drivers.device.profile | object | Device metadata submitted via Mobile SDKs (Android, iOS) or Devices API |
| drivers.device.status | object | Device status. |
| drivers.device.status.value | string | Can be one of active, inactive, disconnected, available or unavailable. Please read here to understand how HyperTrack tracks device status. |
| drivers.device.status.data | object | Extra information about device status |
| drivers.device.status.data.recorded_at | string | ISO 8601 date when the device status was recorded (optional) |
| drivers.device.status.data.activity | string | Device activity (optional). If available, can be one of stop, walk, or drive |
| drivers.device.status.data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled |
| drivers.location | object | location of the driver |
| drivers.location.geometry.type | string | as of right now, only Point is supported |
| drivers.location.geometry.coordinates | array | array of longitude, latitude and (optional) altitude |
| drivers.duration | float | time needed to reach the nearest location in [seconds]; null if no location was found, only for eta search_type |
| drivers.distance | float | distance of the nearest location from the requested location in [meters]; null if no location was found. for eta search_type its the actual drive distance, for region search_type its the haversine distance. |
| drivers.ongoing_trip | object | Ongoing trip summary (only present if device has any ongoing trip and request has include_on_trip as true) |
| drivers.ongoing_trip.trip_id | string | Trip id which is still ongoing (only present if device has any ongoing trip and request has include_on_trip as true) |
| drivers.ongoing_trip.destination | object | Destination geometry for Ongoing trip (only present if device has any ongoing trip and request has include_on_trip as true) |
| drivers.ongoing_trip.remaining_distance | int | Distance (in meters) device needs to travel to reach trip destination (only present if device has any ongoing trip and request has include_on_trip as true) |
| drivers.ongoing_trip.remaining_duration | int | Time (in seconds) needed for device to travel to reach trip destination (only present if device has any ongoing trip and request has include_on_trip as true) |
| summary | object | Summary of the nearby request |
| summary.total_drivers | int | Total number of drivers found in nearby region matching the filters |
| summary.processed_drivers | int | Number of drivers processed and returned in drivers response |
| summary.unprocessed_drivers | int | Number of drivers that have not been processed |
| summary.outside_region_drivers | int | Number of drivers outside nearby region (default value of search_filter.search_radius), only returned if driver_list filter is specified |
| summary.no_route_drivers | int | Number of drivers in nearby region which had no route to order destination |
Example 1: Get all nearby drivers
Use this api to get all the nearby drivers from order destination. A maximum of 1000 drivers are returned in order of their haversine distance from order destination around search radius of 100 miles (160934 meters). Note: if the search_radius filter is not specified it uses the maximum allowed search radius.
Use this POST Device Nearby API request as an example to find available devices near location of interest to perform a dispatch operation.
payload='{
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"region"
}'
curl -X POST </span>
-u {AccountId}:{SecretKey} </span>
https://v3.api.hypertrack.com/nearby/v3
-H 'Content-Type: application/json' </span>
-d $payload
let payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"region"
};
fetch("https://v3.api.hypertrack.com/nearby/v3", {
method: "POST",
body: JSON.stringify(payload),
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"region"
}
response = requests.request("POST", "https://v3.api.hypertrack.com/nearby/v3", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n" +
" \"order\":{\n" +
" \"destination\":{\n" +
" \"geometry\":{\n" +
" \"coordinates\":[\n" +
" -122.3599933082254,\n" +
" 37.753651385106075\n" +
" ],\n" +
" \"type\":\"Point\"\n" +
" }\n" +
" }\n" +
" },\n" +
" \"search_type\":\"region\"\n" +
"}\n");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/nearby/v3")
.post(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/nearby/v3';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$data = array(
'order' => array(
'destination' => array(
'geometry' => array(
'coordinates' => array(-122.359993, 37.753651),
'type' => "Point"
)
)
),
'search_type' => "region"
);
$payload = http_build_query($data);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => $basicAuth,
'content' => $payload
)
);
$context = stream_context_create($opts);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/nearby/v3")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"region"
}.to_json
response = http.request(request)
Nearby API request response example. This is the list of devices which are ranked based on their distance from the location of interest (nearest first).
{
"drivers":[
{
"device":{
"device_id":"00112233-2F48-4DA1-ACEA-8A8D530670CF",
"info":{
"timezone":"America/Los Angeles",
"os_name":"iOS",
"device_brand":"Apple",
"sdk_version":"func test app",
"device_model":"IPhone X",
"network_operator":"T-Mobile",
"name":"Func Test Device",
"os_version":"12.1.4",
"os_hardware_identifier":"719bef31-e487-46e0-86f1-5f32589fd9eb"
},
"profile":{
"gig_type":"ridesharing"
},
"status":{
"value":"active",
"data":{
"activity":"drive",
"recorded_at":"2022-06-30T13:35:14.806Z"
}
}
},
"location":{
"coordinates":[
-122.3999933082254,
37.793651385106074
],
"type":"Point"
},
"duration":null,
"distance":9303,
"ongoing_trip":null,
"error":null
}
],
"summary":{
"total_drivers":1,
"processed_drivers":1,
"unprocessed_drivers":0,
"outside_region_drivers":0,
"no_route_drivers":0
}
}
Example 2: Get nearby drivers filtered by profile
Use this api to get the nearby drivers which satify the search_filter criteria. In this example only the nearby drivers within 15000 meters are returned whose profile specify gig_type as ridesharing.
Use this POST Device Nearby API request as an example to find and filter available devices near location of interest to perform a dispatch operation.
payload='{
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
},
"order_id": "your_order_id",
"metadata": {"order_type": "grocery"}
},
"search_type":"region",
"search_filter":{
"driver_profile":{
"gig_type":"ridesharing"
},
"include_on_trip":true,
"search_radius":15000
},
}'
curl -X POST </span>
-u {AccountId}:{SecretKey} </span>
https://v3.api.hypertrack.com/nearby/v3
-H 'Content-Type: application/json' </span>
-d $payload
let payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
},
"order_id": "your_order_id",
"metadata": {"order_type": "grocery"}
},
"search_type":"region",
"search_filter":{
"driver_profile":{
"gig_type":"ridesharing"
},
"include_on_trip":true,
"search_radius":15000
},
};
fetch("https://v3.api.hypertrack.com/nearby/v3", {
method: "POST",
body: JSON.stringify(payload),
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
},
"order_id": "your_order_id",
"metadata": {"order_type": "grocery"}
},
"search_type":"region",
"search_filter":{
"driver_profile":{
"gig_type":"ridesharing"
},
"include_on_trip":True,
"search_radius":15000
},
}
response = requests.request("POST", "https://v3.api.hypertrack.com/nearby/v3", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n" +
" \"order\":{\n" +
" \"destination\":{\n" +
" \"geometry\":{\n" +
" \"coordinates\":[\n" +
" -122.3599933082254,\n" +
" 37.753651385106075\n" +
" ],\n" +
" \"type\":\"Point\"\n" +
" }\n" +
" },\n" +
" \"order_id\": \"your_order_id\",\n" +
" \"metadata\": {\"order_type\": \"grocery\"}\n" +
" },\n" +
" \"search_type\":\"region\",\n" +
" \"search_filter\":{\n" +
" \"driver_profile\":{\n" +
" \"gig_type\":\"ridesharing\"\n" +
" },\n" +
" \"include_on_trip\":true,\n" +
" \"search_radius\":15000\n" +
" },\n" +
"}\n");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/nearby/v3")
.post(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/nearby/v3';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$data = array(
'order' => array(
'destination' => array(
'geometry' => array(
'coordinates' => array(
-122.3599933082254,
37.753651385106075
),
'type' => "Point"
)
),
'order_id' => "your_order_id",
'metadata' => array('order_type' => "grocery")
),
'search_type' => "region",
'search_filter' => array(
'driver_profile' => array(
'gig_type' => "ridesharing"
),
'include_on_trip' => TRUE,
'search_radius' => 15000
),
)
$payload = http_build_query($data);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => $basicAuth,
'content' => $payload
)
);
$context = stream_context_create($opts);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/nearby/v3")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
},
"order_id": "your_order_id",
"metadata": {"order_type": "grocery"}
},
"search_type":"region",
"search_filter":{
"driver_profile":{
"gig_type":"ridesharing"
},
"include_on_trip":true,
"search_radius":15000
},
}.to_json
response = http.request(request)
Nearby API request response example. This is the list of devices which are ranked based on their distance from the location of interest (nearest first).
{
"drivers":[
{
"device":{
"device_id":"00112233-2F48-4DA1-ACEA-8A8D530670CF",
"info":{
"timezone":"America/Los Angeles",
"os_name":"iOS",
"device_brand":"Apple",
"sdk_version":"func test app",
"device_model":"IPhone X",
"network_operator":"T-Mobile",
"name":"Func Test Device",
"os_version":"12.1.4",
"os_hardware_identifier":"719bef31-e487-46e0-86f1-5f32589fd9eb"
},
"profile":{
"gig_type":"ridesharing"
},
"status":{
"value":"active",
"data":{
"activity":"drive",
"recorded_at":"2022-06-30T13:35:14.806Z"
}
}
},
"location":{
"coordinates":[
-122.3999933082254,
37.793651385106074
],
"type":"Point"
},
"duration":null,
"distance":9303,
"ongoing_trip":null,
"error":null
}
],
"summary":{
"total_drivers":1,
"processed_drivers":1,
"unprocessed_drivers":0,
"outside_region_drivers":0,
"no_route_drivers":0
}
}
Example 3: Get ETA of a list of drivers
Use this api to get the estimate of drive duration and drive distance for a specified list of drivers to order destination. response contains drivers sorted in ascending order of drive duration. Typical use case will be to get nearby drivers using region search, filter relevent drivers and fetch their estimates to order destination.
Use this POST Device Nearby API request as an example to get estimates of a list of drivers to the location of interest.
payload='{
"order":{
"destination":{
"geometry":{
"coordinates":[
35.502007,
47.892524
],
"type":"Point"
}
}
},
"search_type":"eta",
"search_filter": {
"driver_list": [
"00112233-6A5F-4F6E-9231-8480A4438064",
"00112233-2A7E-4D17-BF76-90926FD82E7C",
"00112233-B622-486D-A76F-FEB522B345EA",
"00112233-B622-486D-A76F-FEB522B345EB",
"00112233-B622-486D-A76F-FEB522B345EC",
"00112233-B622-486D-A76F-FEB522B345ED",
"00112233-B622-486D-A76F-FEB522B345EE",
"00112233-B622-486D-A76F-FEB522B345E0",
"00112233-B622-486D-A76F-FEB522B345E1",
"00112233-B622-486D-A76F-FEB522B345E2",
"00112233-B622-486D-A76F-FEB522B345E3",
"00112233-B622-486D-A76F-FEB522B345E4",
"00112233-B622-486D-A76F-FEB522B345E5",
"00112233-B622-486D-A76F-FEB522B345E6"
]
}
}'
curl -X POST </span>
-u {AccountId}:{SecretKey} </span>
https://v3.api.hypertrack.com/nearby/v3
-H 'Content-Type: application/json' </span>
-d $payload
let payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
35.502007,
47.892524
],
"type":"Point"
}
}
},
"search_type":"eta",
"search_filter": {
"driver_list": [
"00112233-6A5F-4F6E-9231-8480A4438064",
"00112233-2A7E-4D17-BF76-90926FD82E7C",
"00112233-B622-486D-A76F-FEB522B345EA",
"00112233-B622-486D-A76F-FEB522B345EB",
"00112233-B622-486D-A76F-FEB522B345EC",
"00112233-B622-486D-A76F-FEB522B345ED",
"00112233-B622-486D-A76F-FEB522B345EE",
"00112233-B622-486D-A76F-FEB522B345E0",
"00112233-B622-486D-A76F-FEB522B345E1",
"00112233-B622-486D-A76F-FEB522B345E2",
"00112233-B622-486D-A76F-FEB522B345E3",
"00112233-B622-486D-A76F-FEB522B345E4",
"00112233-B622-486D-A76F-FEB522B345E5",
"00112233-B622-486D-A76F-FEB522B345E6"
]
}
};
fetch("https://v3.api.hypertrack.com/nearby/v3", {
method: "POST",
body: JSON.stringify(payload),
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
35.502007,
47.892524
],
"type":"Point"
}
}
},
"search_type":"eta",
"search_filter": {
"driver_list": [
"00112233-6A5F-4F6E-9231-8480A4438064",
"00112233-2A7E-4D17-BF76-90926FD82E7C",
"00112233-B622-486D-A76F-FEB522B345EA",
"00112233-B622-486D-A76F-FEB522B345EB",
"00112233-B622-486D-A76F-FEB522B345EC",
"00112233-B622-486D-A76F-FEB522B345ED",
"00112233-B622-486D-A76F-FEB522B345EE",
"00112233-B622-486D-A76F-FEB522B345E0",
"00112233-B622-486D-A76F-FEB522B345E1",
"00112233-B622-486D-A76F-FEB522B345E2",
"00112233-B622-486D-A76F-FEB522B345E3",
"00112233-B622-486D-A76F-FEB522B345E4",
"00112233-B622-486D-A76F-FEB522B345E5",
"00112233-B622-486D-A76F-FEB522B345E6"
]
}
}
response = requests.request("POST", "https://v3.api.hypertrack.com/nearby/v3", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n" +
" \"order\":{\n" +
" \"destination\":{\n" +
" \"geometry\":{\n" +
" \"coordinates\":[\n" +
" 35.502007,\n" +
" 47.892524\n" +
" ],\n" +
" \"type\":\"Point\"\n" +
" }\n" +
" }\n" +
" },\n" +
" \"search_type\":\"eta\",\n" +
" \"search_filter\":{\n" +
" \"driver_list\": [\n" +
" \"00112233-6A5F-4F6E-9231-8480A4438064\",\n" +
" \"00112233-2A7E-4D17-BF76-90926FD82E7C\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345EA\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345EB\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345EC\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345ED\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345EE\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345E0\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345E1\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345E2\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345E3\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345E4\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345E5\",\n" +
" \"00112233-B622-486D-A76F-FEB522B345E6\"\n" +
" ]\n" +
" }\n" +
"}\n");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/nearby/v3")
.post(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/nearby/v3';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$data = array(
'order' => array(
'destination' => array(
'geometry' => array(
'coordinates' => array(35.502007, 47.892524),
'type' => "Point"
)
)
),
'search_type' => "eta",
'search_filter' => array(
'driver_list' => array(
"00112233-6A5F-4F6E-9231-8480A4438064",
"00112233-2A7E-4D17-BF76-90926FD82E7C",
"00112233-B622-486D-A76F-FEB522B345EA",
"00112233-B622-486D-A76F-FEB522B345EB",
"00112233-B622-486D-A76F-FEB522B345EC",
"00112233-B622-486D-A76F-FEB522B345ED",
"00112233-B622-486D-A76F-FEB522B345EE",
"00112233-B622-486D-A76F-FEB522B345E0",
"00112233-B622-486D-A76F-FEB522B345E1",
"00112233-B622-486D-A76F-FEB522B345E2",
"00112233-B622-486D-A76F-FEB522B345E3",
"00112233-B622-486D-A76F-FEB522B345E4",
"00112233-B622-486D-A76F-FEB522B345E5",
"00112233-B622-486D-A76F-FEB522B345E6"
)
)
);
$payload = http_build_query($data);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => $basicAuth,
'content' => $payload
)
);
$context = stream_context_create($opts);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/nearby/v3")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"order":{
"destination":{
"geometry":{
"coordinates":[
35.502007,
47.892524
],
"type":"Point"
}
}
},
"search_type":"eta",
"search_filter": {
"driver_list": [
"00112233-6A5F-4F6E-9231-8480A4438064",
"00112233-2A7E-4D17-BF76-90926FD82E7C",
"00112233-B622-486D-A76F-FEB522B345EA",
"00112233-B622-486D-A76F-FEB522B345EB",
"00112233-B622-486D-A76F-FEB522B345EC",
"00112233-B622-486D-A76F-FEB522B345ED",
"00112233-B622-486D-A76F-FEB522B345EE",
"00112233-B622-486D-A76F-FEB522B345E0",
"00112233-B622-486D-A76F-FEB522B345E1",
"00112233-B622-486D-A76F-FEB522B345E2",
"00112233-B622-486D-A76F-FEB522B345E3",
"00112233-B622-486D-A76F-FEB522B345E4",
"00112233-B622-486D-A76F-FEB522B345E5",
"00112233-B622-486D-A76F-FEB522B345E6"
]
}
}.to_json
response = http.request(request)
Nearby API request response example. This is the list of devices which are ranked based on their drive duration from the location of interest (nearest first).
{
"drivers":[
{
"device":{
"device_id":"00112233-2A7E-4D17-BF76-90926FD82E7C",
"info":{
"timezone":"America/Los Angeles",
"os_name":"iOS",
"device_brand":"Apple",
"sdk_version":"func test app",
"device_model":"IPhone X",
"network_operator":"T-Mobile",
"name":"Func Test Device",
"os_version":"12.1.4",
"os_hardware_identifier":"ac75716e-4cef-4ef6-be1c-92cfc8e7c2f4"
},
"profile":{
"key_0":"dc202869-c931-4093-b778-9908a8eb3904"
},
"status":{
"value":"active",
"data":{
"activity":"unknown",
"recorded_at":"2022-06-27T07:59:37.290Z"
}
}
},
"location":{
"geometry":{
"type":"Point",
"coordinates":[
35.402007,
47.792524
]
}
},
"duration":2927,
"distance":21528,
"ongoing_trip":null,
"error":null
}
],
"summary":{
"total_drivers":14,
"processed_drivers":1,
"unprocessed_drivers":1,
"outside_region_drivers":12,
"no_route_drivers":0
}
}
Example 4: Get ETA of nearby drivers
Use this api to get the estimate of drive duration and drive distance for nearby drivers to order destination. response contains drivers sorted in ascending order of drive duration. Note: this api will first search nearby drivers and then return durations of top 8 drivers.
Use this POST Device Nearby API request as an example find the drive duration of nearby drivers to the location of interest.
payload='{
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"eta"
}'
curl -X POST </span>
-u {AccountId}:{SecretKey} </span>
https://v3.api.hypertrack.com/nearby/v3
-H 'Content-Type: application/json' </span>
-d $payload
let payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"eta"
};
fetch("https://v3.api.hypertrack.com/nearby/v3", {
method: "POST",
body: JSON.stringify(payload),
headers: {
"Content-Type": "application/json"
}
}).then(res=>res.json())
.then(res => console.log(res));
import requests
payload = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"eta"
}
response = requests.request("POST", "https://v3.api.hypertrack.com/nearby/v3", data=json.dumps(payload).encode("utf-8"), auth=("{AccountId}", "{SecretKey}"))
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n" +
" \"order\":{\n" +
" \"destination\":{\n" +
" \"geometry\":{\n" +
" \"coordinates\":[\n" +
" -122.3599933082254,\n" +
" 37.753651385106075\n" +
" ],\n" +
" \"type\":\"Point\"\n" +
" }\n" +
" }\n" +
" },\n" +
" \"search_type\":\"eta\"\n" +
"}\n");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/nearby/v3")
.post(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
<?php
$url = 'https://v3.api.hypertrack.com/nearby/v3';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$data = array(
'order' => array(
'destination' => array(
'geometry' => array(
'coordinates' => array(-122.359993, 37.753651),
'type' => "Point"
)
)
),
'search_type' => "eta"
);
$payload = http_build_query($data);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => $basicAuth,
'content' => $payload
)
);
$context = stream_context_create($opts);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/nearby/v3")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"order":{
"destination":{
"geometry":{
"coordinates":[
-122.3599933082254,
37.753651385106075
],
"type":"Point"
}
}
},
"search_type":"eta"
}.to_json
response = http.request(request)
Nearby API request response example. This is the list of devices which are ranked based on their drive duration from the location of interest (nearest first).
{
"drivers":[
{
"device":{
"device_id":"00112233-2A7E-4D17-BF76-90926FD82E7C",
"info":{
"timezone":"America/Los Angeles",
"os_name":"iOS",
"device_brand":"Apple",
"sdk_version":"func test app",
"device_model":"IPhone X",
"network_operator":"T-Mobile",
"name":"Func Test Device",
"os_version":"12.1.4",
"os_hardware_identifier":"ac75716e-4cef-4ef6-be1c-92cfc8e7c2f4"
},
"profile":{
"key_0":"dc202869-c931-4093-b778-9908a8eb3904"
},
"status":{
"value":"active",
"data":{
"activity":"unknown",
"recorded_at":"2022-06-27T07:59:37.290Z"
}
}
},
"location":{
"geometry":{
"type":"Point",
"coordinates":[
35.402007,
47.792524
]
}
},
"duration":2927,
"distance":21528,
"ongoing_trip":null,
"error":null
}
],
"summary":{
"total_drivers":1,
"processed_drivers":1,
"unprocessed_drivers":0,
"outside_region_drivers":0,
"no_route_drivers":0
}
}
Consider on-trip drivers
By default nearby API results do not include drivers which are on a trip, but if include_on_trip flag is sent as true, then these devices are also considered.
In these cases HyperTrack does smart lookup taking into account the ongoing trip destination.
If device is on a trip with multiple orders, then the last order to be delivered is considered.
For these devices, HyperTrack sends some extra fields namely trip_destination, trip_remaining_distance, trip_remaining_duration as part of device data in response
Webhooks
Webhooks let you subscribe to a real-time stream of location, and trip status data generated by HyperTrack. Rather than making an API call, HyperTrack can send an HTTPS request to an endpoint that you specify. Events are published for all devices associated with the account.
The HyperTrack mobile SDKs send a time-series of events from the device to the HyperTrack server. These events are processed and then posted to your servers on Webhooks. A webhook is an HTTPS POST call from the HyperTrack servers to a configurable destination.
After receiving a webhook on your own server, you can trigger updates on your mobile or web apps in near real-time and implement your live location features.
Setting up HyperTrack Webhooks requires configurations on your server and the HyperTrack dashboard.
The server receiving webhooks needs to be configured appropriately to consume webhooks.
Static Endpoint URL
Your server needs to expose a public HTTPS endpoint capable of receiving external, incoming requests. It is important to have a static endpoint URL that will be accessible at all times.
HTTPS POST Method
Webhooks are realized through HTTPS POST requests to the configured endpoint. Your server needs to support this method and be able to parse the payload provided with the request.
JSON Payload
The payload you will receive with POST requests is formatted in JSON. You need to implement the capability to parse JSON objects in order to leverage the HTTP request 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). This is critical if you want to verify the signature of a webhook.
Payload and Headers
Webhooks from HyperTrack will be sent with headers and a JSON payload. Please ensure to verify the headers and implement your server to handle these correctly.
Header: Content-Type
The header is set to application/json for all webhooks. Please ensure to parse every webhook with this content type. The actual content is represented in JSON.
Header: x-hypertrack-signature
HyperTrack signs each webhook POST request. Please see this guide for further instructions.
Responding to webhooks
Make sure to respond to HyperTrack webhooks with the appropriate status code. The connection will time out in 10 seconds. If your endpoint does not respond before the connection times out or if your endpoint returns a status code outside the range of 200–4xx, HyperTrack will consider the delivery of the webhook as a failed attempt and retry as described below.
Retry algorithm
If HyperTrack doesn't receive a successful response from your server, it attempts to deliver the webhook again. By default, if the initial delivery of the webhook fails, HyperTrack attempts up to three retries with a delay between failed attempts set at 20 seconds.
The retries will always refer to the same x-amz-sns-message-id. By comparing the IDs of the webhooks you have processed with incoming webhooks, you can understand whether the message is a retry attempt.
Order of webhooks
HyperTrack will attempt to deliver webhooks in the same order they were received. However, network issues could potentially result in out-of-order webhooks.
Before handling events, you should compare the recorded_at property of the JSON payload and ensure to store events in the order they were recorded as opposed to when they were received.
Webhook Payload
The overall POST payload has a static structure. The type of the webhook indicates the structure of the data object.
[{
"created_at": "2019-02-27T22:50:29.000000Z",
"data": { ... },
"location": { ... },
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-02-27T22:50:24.000000Z",
"type": "",
"version": "2.0.0"
}]
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique device identifier, case sensitive (Present where the webhook originates from a device) |
| created_at | string | ISO 8601 date and time when webhook was sent (server timestamp) |
| recorded_at | string | ISO 8601 date and time when event was recorded (client timestamp). Not available for trip webhooks (e.g. start and completion) |
| type | string | Type of webhook data. Can be one of the types below (location, device_status, battery, trip, registration_update, reinstall, geotag, geofence, order). More types might be added over time. |
| data | object | Data corresponding to the type. See detailed description below. |
| location | object | GeoJSON object with type and coordinates. Provided as context to trip delay webhooks only |
| version | string | Version string of the webhook. |
Depending on the type of webhook, the JSON payload will vary. However, the overall structure is fixed.
Currently, the following types are supported:
| Feature | Type | Description |
|---|---|---|
| Locations | location | Location stream |
| Device Status | device_status | Device status changes (active, inactive, disconnected and activity changes) |
| Battery | battery | Battery changes (low, normal and charging) |
| Trips | trip | Trip start, destination arrival, destination exit, trip delays, and trip completion events |
| Geotags | geotag | Geotags stream |
| Orders | order | Orders lifecycle changes like order start, completion, cancellation, eta change etc |
Location Payload
{
"created_at":"2019-07-01T20:00:01.247377Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at":"2019-07-01T20:00:00.000000Z",
"type":"location",
"data":{
"accuracy":9.64,
"geometry":{
"type":"Point",
"coordinates":[
-6.2755,
57.6398983124
]
},
"speed":0.0,
"bearing":313.94
},
"version":"2.0.0"
}
| Name | Type | Description |
|---|---|---|
| data.geometry | object | Location in GeoJSON format |
| data.geometry.type | string | As of right now, only Point is supported |
| data.geometry.coordinates | array | Array of longitude, latitude and (optional) altitude (in m) |
| data.accuracy | float | (optional) accuracy in m |
| data.bearing | float | (optional) bearing in degrees starting at due north and continuing clockwise around the compass |
| data.speed | float | (optional) speed in m/s |
Device Status Payload
{
"device_id": "AAAAAAAA-7101-48A9-86C4-B762993ACC5A",
"recorded_at": "2021-10-27T00:40:53.811Z",
"metadata": {
"invite_id": "https://hypertrack-logistics.app.link/xxxx",
"email": "alex+test123@hypertrack.com"
},
"version": "2.0.0",
"location": {
"type": "Point",
"coordinates": [
-122.503655,
37.76097,
24.98
]
},
"created_at": "2021-10-27T00:42:01.166509Z",
"name": "Alex",
"data": {
"value": "inactive",
"inactive_reason": {
"name": "Location permission denied",
"description": " User explicitly denied permissions in response to system prompt or in Settings > App Name > Location.",
"code": "OL1",
"user_action_required": "Change location permission to \"Always\" in Settings > App Name > Location",
"type": "location_permission_denied"
}
},
"type": "device_status"
}
| Name | Type | Description |
|---|---|---|
| data.value | string | Device status. One of active, inactive or disconnected. Please read here to understand how HyperTrack tracks device status. |
| data.activity | string | For active devices only, can be one walk,drive, or stop |
| data.reason | string | For inactive devices only. Can be one of: location_permissions_denied,location_services_disabled,motion_activity_permissions_denied,motion_activity_services_disabled,motion_activity_services_unavailable,tracking_stopped,tracking_service_terminated,uninstalled. Please read here to understand how HyperTrack tracks device status. |
| data.start | object | Available in case of data.value is active and an activity has been completed, Gives information of when and where the activity started |
| data.end | object | Available in case of data.value is active and an activity has been completed, Gives information of when and where the activity ended |
| data.distance | int | Available in case of data.value is active and an activity has been completed |
| data.duration | int | Available in case of data.value is active and an activity has been completed |
| location | object | Location in GeoJSON format |
| location.type | string | As of right now, only Point is supported |
| location.coordinates | array | Array of longitude latitude and (optional) altitude (in m) |
Battery Payload
2.0.0 Payload
{
"created_at":"2019-07-01T20:00:01.247377Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at":"2019-07-01T20:00:00.000000Z",
"type":"battery",
"data":{
"value":"low"
},
"location":{
"type":"Point",
"coordinates":[
-6.2755,
57.6398983124
]
},
"version":"2.0.0"
}
| Name | Type | Description |
|---|---|---|
| data.value | string | Battery status. Values include low, normal and charging |
| location | object | Location in GeoJSON format |
| location.type | string | As of right now, only Point is supported |
| location.coordinates | array | Array of longitude latitude and (optional) altitude (in m) |
2.1.0 Payload
{
"created_at":"2021-12-21T20:36:37.752Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at":"2021-12-21T20:36:34.410Z",
"type":"battery",
"data":{
"value":"low",
"battery_percent":75
},
"version":"2.1.0"
}
| Name | Type | Description |
|---|---|---|
| data.value | string | Battery status. Values include low, normal and charging |
| data.battery_percent | int | Battery percentage |
Trip Payload
{
"created_at": "2019-07-01T14:00:00.000000Z",
"data": {
"value": "created",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" }
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0"
}
If you start trips, you will receive trip events whenever ...
- a new trip is created successfully
- a device enters or exits a trip destination
- a trip with a scheduled arrival time is estimated to be delayed
- a trip is completed successfully and a summary is available
- when there is change in ETA (change in minutes described as integer)
| Name | Type | Description |
|---|---|---|
| data.value | string | One of: created, destination_arrival, destination_exit, delayed, first_eta, eta_change or completed |
| data.trip_id | string | Unique identifier of the trip, case sensitive |
| data.trip_metadata | Object | Metadata that you have assigned to this trip (optional) |
| data.arrive_at | string | Timestamp with new arrived date, only available if value is delayed |
| data.remaining_duration | int | Time remaining (in seconds) as per ETA calculations, only available if value is eta_change or first_eta |
| data.remaining_distance | int | Distance remaining (in meters) as per ETA calculations, only available if value is eta_change or first_eta |
| data.destination_id | string | Unique identifier of the trip destination, case sensitive (Only available for trips with multiple orders) |
| data.destination_metadata | Object | Metadata that you have assigned to the trip destination (Only available for trips with multiple orders) |
| data.duration | int | Duration of trip (in seconds), only available if value is completed |
| data.distance | int | Distance travelled during trip (in meters), only available if value is completed |
| data.duration_at_destination | int | Duration spent at the destination before trip completion, only available if value is completed |
Device Registration Payload
{
"created_at": "2020-07-01T14:00:00.000000Z",
"data": {
"value": "registration",
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "registration",
"version": "2.0.0"
}
This webhook is generated when a new device is registered for the first time with the hypertrack platform.
| Name | Type | Description |
|---|---|---|
| data.value | string | Label indicating registration |
Device Registration Update Payload
{
"created_at": "2020-07-01T14:00:00.000000Z",
"data": {
"value": "device_info",
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"name": "Thomas Phone",
"metadata": { "driver_id": 1234 },
"type": "registration_update",
"version": "2.0.0"
}
This webhook is generated when a new device updates its device information, which also may include name and/or its metadata.
| Name | Type | Description |
|---|---|---|
| data.value | string | Label indicating device information update |
Host Application Reinstallation Payload
{
"created_at": "2020-07-01T18:00:00.000000Z",
"data": {
"value": "reinstall",
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "reinstall",
"version": "2.0.0"
}
This webhook is generated when a device performs a reinstallation of the application integrated with the Hypertrack SDK.
| Name | Type | Description |
|---|---|---|
| data.value | string | Label indicating reinstallation |
Geotag Payload
{
"created_at": "2019-07-01T14:01:00.000000Z",
"recorded_at": "2019-07-01T14:00:00.000000Z",
"data": {
"order_handle": "order-1",
"geotag_type": "arrived",
"metadata": { "orderId": "123490809808" },
"deviation": 14,
"distance": 238,
"duration": 63,
"location": {
"type": "Point",
"coordinates": [ -6.2755, 57.6398983 ]
},
"expected_location": {
"type": "Point",
"coordinates": [ -6.2756, 57.6398983 ]
},
"driver_handle": "James",
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "geotag",
"version": "3.0.0"
}
| Name | Type | Description |
|---|---|---|
| data.order_handle | string | Unique identifier for an order |
| data.geotag_type | string | Label identifying a segment of order fulfillment |
| data.driver_handle | string | Unique identifier for a driver |
| data.metadata | Object | Metadata that you have assigned to this geotag (optional) |
| data.location | Object | Location in GeoJSON format |
| data.expected_location | Object | Location in GeoJSON format |
| data.location.type | string | As of right now, only Point is supported |
| data.location.coordinates | array | Array of longitude latitude and (optional) altitude (in m) |
| data.expected_location.type | string | As of right now, only Point is supported |
| data.expected_location.coordinates | array | Array of longitude latitude and (optional) altitude (in m) |
| data.deviation | int | Deviation between expected location and actual location |
| data.distance | int | Distance travelled since last geotag |
| data.duration | int | Time since last geotag |
Geofence Payload
{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"data": {
"arrival": {
"location": {
"coordinates": [
-122.394223, 37.792763, 822.58
],
"type": "Point"
},
"recorded_at": "2021-07-15T13:29:21.085Z"
},
"duration": 3738,
"exit": {
"location": {
"coordinates": [
-122.394223, 37.792763, 822.58
],
"type": "Point"
},
"recorded_at": "2021-07-15T14:31:38.789Z"
},
"geofence_id": "00001111-d30d-4a4a-b965-95f3f743256e",
"geofence_metadata": {
"name": "Main store",
},
"geometry": {
"coordinates": [
-122.394223, 37.792763
],
"type": "Point"
},
"marker_id": "00001111-b97b-490d-8d04-a539477df0be",
"radius": 50,
"route_to": {
"distance": 1234,
"duration": 3600,
"idle_time": 1800,
"prev_marker_id": "00001111-2dac-40a7-973b-9e3d66898a7d",
"started_at": "2021-07-15T12:29:16.424Z",
},
"value": "exit"
},
"location": {
"type": "Point",
"coordinates": [
-122.394223,
37.792763
]
},
"recorded_at": "2021-07-15T13:29:21.085Z",
"created_at": "2021-07-15T13:29:21.085Z",
"version": "2.0.0",
"type": "geofence"
}
| Name | Type | Description |
|---|---|---|
| data.arrival | object | Object representing details about the geofence arrival |
| data.arrival.location | object | Location object that triggered geofence arrival |
| data.arrival.location.type | string | As of right now, only Point is supported |
| data.arrival.location.coordinates | array | Array of longitude, latitude and (optional) elevation |
| data.arrival.recorded_at | string | ISO 8601 date when the location triggering arrival was recorded |
| data.exit | object | Object representing details about the geofence exit. Does not exist when the user is still inside the geofence. {optional} |
| data.exit.location | object | Location object that triggered geofence exit. Only set when geofence was exited due to a location. Can be empty when marker was closed to due a health event. (optional) |
| data.exit.location.type | string | As of right now, only Point is supported |
| data.exit.location.coordinates | array | Array of longitude, latitude and (optional) elevation |
| data.exit.recorded_at | string | ISO 8601 date when the event triggering exit was recorded |
| data.duration | int | Duration of the visit in [seconds] |
| data.geometry | Object | Geofence geometry of the geofence creating this marker |
| data.marker_id | String | Unique identifier for this geofence marker |
| data.route_to | object | Object describing the route since last geofence marker (optional) |
| data.route_to.distance | int | Distance travelled since last geofence marker or start of tracking session in [meters] |
| data.route_to.duration | int | Duration since last geofence marker or start of tracking session in [seconds] |
| data.route_to.idle_time | int | Duration at stops since last geofence marker or start of tracking session in [seconds] |
| data.route_to.started_at | String | ISO 8601 Date and time when route_to calculation started |
| data.value | String | 'entry' or 'exit' - value indicating if this was an entry or exit event |
Order Payload
Webhooks are sent at different stages of an order's lifecycle. Sample webhook payloads for each of order lifecycle stages can be found below.
Order Planning Started Webhook
Order Planning Started Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"planning_started",
"planning_sequence_number": 1,
"plan_id": "f9212af2-71e8-40f0-84bd-005424a80a4d",
"planning_started_reason": "api",
"started_at": "2021-01-01T14:00:00.000000Z",
"ops_group_handle": "OPS_123"
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | planning_started |
| data.planning_sequence_number | integer | Yes | Sequence Number of the plan for this specific plan ID |
| data.plan_id | string | Yes | Unique identifier of the plan which is getting planned |
| data.planning_started_reason | string | Yes | Trigger reason for this specific planning |
| data.started_at | string | Yes | Timestamp at which plan was started |
| data.ops_group_handle | string | Yes | Ops group handle for which the planning is triggered |
Order Planning Completed Webhook
Order Planning Completed Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"planning_completed",
"planning_sequence_number": 1,
"plan_id": "f9212af2-71e8-40f0-84bd-005424a80a4d",
"num_orders": 10,
"num_routes": 2,
"num_unplanned_orders": 2,
"completed_at": "2021-01-01T14:01:00.000000Z",
"route_handles_created": ["6784e919-71e8-40f0-84bd-005424a80a4d"],
"route_handles_modified": ["f9212af2-7168-4f61-b686-2020f547637f"],
"started_at": "2021-01-01T14:00:00.000000Z",
"ops_group_handle": "OPS_123"
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | planning_completed |
| data.planning_sequence_number | integer | Yes | Sequence Number of the plan for this specific plan ID |
| data.plan_id | string | Yes | Unique identifier of the plan which is getting planned |
| data.num_orders | integer | Yes | Number of Orders planned |
| data.num_orders | integer | Yes | Number of Orders planned |
| data.num_routes | integer | Yes | Number of Routes planned |
| data.num_unplanned_orders | integer | Yes | Number of Orders which could not be planned |
| data.started_at | string | Yes | Timestamp at which plan was started |
| data.completed_at | string | Yes | Timestamp at which plan was completed |
| data.route_handles_created | string | Yes | Route handles which got created in this planning instance |
| data.route_handles_modified | string | Yes | Route handles which got modified in this planning instance |
| data.ops_group_handle | string | Yes | Ops group handle for which the planning is triggered |
Order Planning Failed Webhook
Order Planning Failed Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"planning_failed",
"planning_sequence_number": 1,
"plan_id": "f9212af2-71e8-40f0-84bd-005424a80a4d",
"failure_reason": "No Available Drivers",
"num_orders": 10,
"num_unplanned_orders": 2,
"started_at": "2021-01-01T14:00:00.000000Z",
"ops_group_handle": "OPS_123"
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | planning_failed |
| data.planning_sequence_number | integer | Yes | Sequence Number of the plan for this specific plan ID |
| data.plan_id | string | Yes | Unique identifier of the plan which is getting planned |
| data.num_orders | integer | Yes | Number of Orders planned |
| data.failure_reason | string | Yes | Faiure reason for Planning |
| data.num_unplanned_orders | integer | Yes | Number of Orders which could not be planned |
| data.started_at | string | Yes | Timestamp at which plan was started |
| data.ops_group_handle | string | Yes | Ops group handle for which the planning is triggered |
Order Started Webhook
Order Started Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"started",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | started |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
Order Assigned Webhook
Order Assigned Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"assigned",
"order_handle":"DGC127092",
"assigned_at": "2021-01-01T14:00:00.000Z",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"assigned",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | assigned |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.assigned_at | timestamp | Yes | Timestamp indicating when the order was assigned |
| data.status | string | Yes | Status of the order - assigned |
| data.metadata | object | No | Metadata that you have assigned to this order |
Order First ETA Webhook
Order First ETA Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"first_eta",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"remaining_distance": 2582,
"remaining_duration": 410,
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | first_eta |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.remaining_distance | int | Yes | Distance remaining in meters |
| data.remaining_duration | int | Yes | Time remaining to reach destination as per current location in seconds |
Order ETA Change Webhook
Order ETA Change Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"eta_change",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"remaining_distance": 2382,
"remaining_duration": 359,
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | eta_change |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.remaining_distance | int | Yes | Distance remaining in meters |
| data.remaining_duration | int | Yes | Time remaining to reach destination as per current location in seconds |
Order Delayed Webhook
Order Delayed Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"delayed",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
},
"arrive_at":"2021-01-01T14:25:00.000000Z",
"scheduled_at":"2021-01-01T14:23:00.000000Z"
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | delayed |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.arrive_at | timestamp | Yes | Timestamp indicating the new expected arrival time |
| data.scheduled_at | timestamp | Yes | Timestamp indicating the provided scheduled time for order fulfillment |
Order N-Minutes away Webhook
Order N-Minutes away Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"n_minutes_away",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"remaining_distance": 2164,
"remaining_duration": 300,
"remaining_minutes": 5,
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | n_minutes_away |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.remaining_distance | int | Yes | Distance remaining in meters |
| data.remaining_duration | int | Yes | Time remaining to reach destination as per current location in seconds |
| data.remaining_minutes | int | Yes | Time remaining in minutes (by default webhook is sent when order is 60 min away or 15 min away) |
Order Disabled Webhook
Order Disabled Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"disabled",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"disabled",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | disabled |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - disabled |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
Order Enabled Webhook
Order Enabled Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"enabled",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | enabled |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
Order Updated Webhook
Order Updated Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"updated",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | updated |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
Order Arrived Webhook
Order Arrived Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"arrived",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"arrival": {
"location": {
"coordinates": [-6.2785, 57.6388983, 0],
"type": "Point"
}
"recorded_at": "2021-01-01T14:05:10.000000Z",
},
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"scheduled_at":"2021-01-01T14:23:00.000000Z",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | arrived |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.scheduled_at | timestamp | Yes | Timestamp indicating the provided scheduled time for order fulfillment |
| data.arrival | object | Yes | Contains location and recorded_at timestamp of the arrival |
Order Exited Webhook
Order Exited Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"exited",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"exit": {
"location": {
"coordinates": [-6.2785, 57.6388983, 0],
"type": "Point"
}
"recorded_at": "2021-01-01T14:05:10.000000Z",
},
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | exited |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.exit | object | Yes | Contains location and recorded_at timestamp of the exit from the order destination location |
Order Completed Webhook
Order Completed Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"completed",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"distance":1834,
"duration":408,
"deviation":75,
"actual_service_time": 35,
"status":"completed",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | completed |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - completed |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.distance | int | Yes | Total distance travelled to fulfill the order |
| data.duration | int | Yes | Total time in seconds since order start |
| data.deviation | int | Yes | Deviation between order destination location and actual location where the order is completed |
| data.actual_service_time | int | No | Total time spent by driver at the destination, in case the completion happened after the arrival |
Order Cancelled Webhook
Order Cancelled Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"cancelled",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"distance":1834,
"duration":408,
"status":"cancelled",
"share_url":"https://trck.at/vr1RNLq",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | completed |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - completed |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.distance | int | Yes | Total distance travelled to fulfill the order |
| data.duration | int | Yes | Total time in seconds since order start |
Orders at risk Payload
Order at risk Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"order",
"data":{
"value":"risk_updated",
"order_handle":"DGC127092",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"ongoing",
"share_url":"https://trck.at/vr1RNLq",
"risks":{
"deviating_from_expected_route": "red",
"moving_too_slow": "yellow"
}
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
Following are the Risk elements:
delayed_from_scheduled_at: risk element that an order is delayed from the scheduled time of delivery.delayed_from_initial_eta: risk element that an order is delayed beyond the initial ETA communicated to the customeris_offline: risk element that an order is at risk because the device is not sending updates.deviating_from_expected_route: risk element that an order will be at risk because the driver is deviating from the expected route.moving_away_from_destination: risk element that an order will be at risk because the driver is moving away from the destination.in_low_battery: risk element that an order is at risk because the device may shut off before order completion.moving_too_slow: risk element that an order will be at risk because the driver is moving too slowly to fulfill the order.in_outage: risk element that an order is at risk because of a user-driven or software-driven action. eg: turn off GPS, background process killed etc.
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | risk_updated |
| data.order_handle | string | Yes | Unique handle for the Order |
| data.route_handle | string | Yes | Unique identifier of the route containing the order |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the order |
| data.status | string | Yes | Status of the order - ongoing |
| data.share_url | string | Yes | Contains tracking url of the order to provide real time visibility of driver on route of this order |
| data.metadata | object | No | Metadata that you have assigned to this order |
| data.risk_elements | object | Yes | Order at risk state |
| data.risk_elements.is_offline | object | No | Risk element evaluating the online/offline status of driver with a value of red or yellow |
| data.risk_elements.deviating_from_expected_route | object | No | Risk element evaluating the deviation in route taken by driver against the expected route with a value of red or yellow |
| data.risk_elements.moving_away_from_destination | object | No | Risk element evaluating the direction of driver, if he is moving away from destination with a value of red or yellow |
| data.risk_elements.in_low_battery | object | No | Risk element evaluating the battery status of the driver's device with a value of red or yellow |
| data.risk_elements.moving_too_slow | object | No | Risk element evaluating the speed of driver with a value of red or yellow |
| data.risk_elements.in_outage | object | No | Risk element evaluating the outage status of driver with a value of red or yellow |
Route Created Webhook
Route Created Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"route",
"data":{
"value":"created",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"planned",
"embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | created |
| data.route_handle | string | Yes | Unique identifier of the route |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the route |
| data.status | string | Yes | Status of the route - planned |
| data.metadata | object | No | Metadata that you have assigned to this route |
| data.embed_url | string | Yes | Embeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders |
Route Assigned Webhook
Route Assigned Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"route",
"data":{
"value":"assigned",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"assigned",
"assigned_at": "2021-01-01T14:00:00.000Z",
"embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | assigned |
| data.route_handle | string | Yes | Unique identifier of the route |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the route |
| data.assigned_at | timestamp | Yes | Timestamp indicating when the route was assigned |
| data.status | string | Yes | Status of the route - assigned |
| data.metadata | object | No | Metadata that you have assigned to this route |
| data.embed_url | string | Yes | Embeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders |
Route Estimate Generated Webhook
Route Estimate Generated Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"route",
"data":{
"value":"estimate_generated",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"planned",
"embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
"estimate":{
"distance": 7382,
"duration": 1263,
"start_by": "2021-01-01T14:05:00.000Z"
}
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | estimate_generated |
| data.route_handle | string | Yes | Unique identifier of the route |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the route |
| data.status | string | Yes | Status of the route - planned |
| data.metadata | object | No | Metadata that you have assigned to this route |
| data.embed_url | string | Yes | Embeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders |
| data.estimate | object | Yes | Object containing the estimate metrics for the route |
| data.estimate.distance | int | Yes | Estimated total distance in meters to be travelled by the driver to fulfill the orders |
| data.estimate.duration | int | Yes | Estimated total duration in seconds it would take for the driver to fulfill the orders |
| data.estimate.start_by | timestamp | Yes | Estimated start time for the route to ensure all orders are fulfilled within the provided order scheduled times |
Route Started Webhook
Route Started Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"route",
"data":{
"value":"started",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"tracking",
"embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | started |
| data.route_handle | string | Yes | Unique identifier of the route |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the route |
| data.status | string | Yes | Status of the route - tracking |
| data.metadata | object | No | Metadata that you have assigned to this route |
| data.embed_url | string | Yes | Embeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders |
Route Completed Webhook
Route Completed Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"route",
"data":{
"value":"completed",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"completed",
"distance": 6278,
"duration": 1273,
"embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | completed |
| data.route_handle | string | Yes | Unique identifier of the route |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the route |
| data.status | string | Yes | Status of the route - completed |
| data.metadata | object | No | Metadata that you have assigned to this route |
| data.embed_url | string | Yes | Embeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders |
| data.distance | int | Yes | Total distance in meters travelled by the driver to fulfill the orders |
| data.duration | int | Yes | Total duration in seconds it took for the driver to fulfill the orders |
Route Updated Webhook
Route Updated Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"route",
"data":{
"value":"updated",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"status":"tracking",
"embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | updated |
| data.route_handle | string | Yes | Unique identifier of the route |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the route |
| data.status | string | Yes | Status of the route - tracking |
| data.metadata | object | No | Metadata that you have assigned to this route |
| data.embed_url | string | Yes | Embeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders |
Route Request Version Missing Webhook
Route Request Version Missing Webhook Payload
{
"created_at":"2021-01-01T14:01:00.000000Z",
"recorded_at":"2021-01-01T14:00:00.000000Z",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"account_id":"6784e919-7168-4f61-b686-2020f547637f",
"type":"route",
"data":{
"value":"request_version_missing",
"route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"driver_handle": "Driver-1",
"route_version": 3,
"route_operation": "add_orders",
"message": "Multiple version exist for route. Specify the latest version in the API",
"status":"tracking",
"embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
"metadata":{
"storeId":"123490809808",
"customerName":"Andrew"
}
},
"version":"3.0.0"
}
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data.value | string | Yes | request_version_missing |
| data.route_handle | string | Yes | Unique identifier of the route |
| data.driver_handle | string | No | Unique identifier of the driver fulfilling the route |
| data.route_version | number | Yes | Current version of the route |
| data.route_operation | string | Yes | Enum string representing the Operation performed using API, reaction to which this webhook is sent, one of add_orders, remove_orders, resequence_orders, update, complete, reassign OR tracking |
| data.message | string | Yes | Multiple version exist for route. Specify the latest version in the API. |
| data.status | string | Yes | Status of the route - tracking |
| data.metadata | object | No | Metadata that you have assigned to this route |
| data.embed_url | string | Yes | Embeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders |
SDKs
Android
HyperTrack SDK for Android API reference
Refer to the integration guide for additional details.
iOS
HyperTrack SDK for iOS API Reference
Refer to the integration guide for additional details.
React Native
HyperTrack SDK for React Native API Reference
Refer to the integration guide for additional details.
Flutter
HyperTrack SDK for Flutter API Reference
Refer to the integration guide for additional details.
Ionic Capacitor
HyperTrack SDK for Ionic Capacitor API Reference
Refer to the integration guide for additional details.
Views
Android
Android Views are implemented using GraphQL subscriptions and enable server-to-client communication without the need to integrate Webhooks on the backend.
The module handles websockets and provides easy-to-consume methods to retrieve device status and subscribe to programmatic notifications about key moments in the movement tracking of devices and trips, as they happen.
Get device status
// Get SDK instance with Context reference
// replace <PUBLISHABLE_KEY> with your own key
HyperTrackViews hypertrackView = HyperTrackViews.getInstance(this, <PUBLISHABLE_KEY>);
// replace <DEVICE_ID> with your device ID
hypertrackView.getDeviceMovementStatus(<DEVICE_ID>,
new Consumer<MovementStatus>() {
@Override
public void accept(MovementStatus movementStatus) {
Log.d(TAG, "Got movement status data " + movementStatus);
}
});
val hyperTrackView = HyperTrackViews.getInstance(this, PUBLISHABLE_KEY)
hyperTrackView.getDeviceMovementStatus(DEVICE_ID)
{Log.d(TAG, "Got movement status $it")}
Get device information by device ID. The callback receives a MovementStatus object describing the device.
Movement Status
The device movement status object encapsulates all data associated with a device, similar to the Device API. It provides the latest snapshot of the device state, including ...
- Device location, including coordinates, speed, altitude, bearing, accuracy, and timestamp of record
- Device status, including activity and timestamp of record
- Battery information, can be one of
BATTERY_CHARGING,BATTERY_LOW, andBATTERY_NORMAL - General device information
- Share and embed view URLs associated with the device
- Trips associated with the device
Location Object
Location location = movementStatus.location;
if (location != null) {
Log.d(TAG, "Got device location " + location +
" with latitude " + location.getLatitude() +
" and longitude " + location.getLongitude());
}
val location = movementStatus?.location
location?.let {
Log.d(TAG, "Got device location $location " +
"with latitude ${location.latitude}" +
"and longitude ${location.longitude}")
| Accessor method | Type | Description |
|---|---|---|
| getLatitude() | double |
Latitude in degrees. Negatives are for southern hemisphere. |
| getLongitude() | double |
Longitude in degrees. Negatives are for western hemisphere. |
| getAltitude() | Double |
Altitude in m. Could be null, if value is not available. |
| getSpeed() | Double |
Speed in m/s. Could be null, if device is stationary |
| getBearing() | Double |
Bearing in degrees starting at due north and continuing clockwise around the compass |
| getAccuracy() | Double |
Horizontal accuracy in m |
| getRecordedAt() | String |
ISO 8601 date when the location was recorded |
Device Status Object
DeviceStatus status = movementStatus.deviceStatus;
if (status != null) {
Log.d(TAG, "Device is " + (status.isDisconnected() ? "disconnected" : "connected"));
}
val status = movementStatus?.deviceStatus
status?.let {
Log.d(TAG, "Device is ${(if (status.isDisconnected) "disconnected" else "connected")}")
}
| Member | Type | Description |
|---|---|---|
| createdAt | String |
ISO 8601 date when the device status was created |
| isActive() | boolean |
Returns true if device is active (it's current location is known and updated) and false otherwise |
| isDisconnected() | boolean |
Returns true if device is disconnected (it's location wasn't updated for a while) and false otherwise |
| isInactive() | boolean |
Returns true if tracking data is unavailable because of lack of permissions or tracking was stopped intentionally and false otherwise |
| status | int |
Property provides more extended description of current state, e.g. whether it it is driving, if active, etc. See JavaDoc for the list of possible values and their meaning. |
Device Info Properties
DeviceInfo deviceInfo = movementStatus.deviceInfo;
if (deviceInfo != null) {
Log.d(TAG, "Got status for device " + deviceInfo.name);
}
val deviceInfo = movementStatus?.deviceInfo
deviceInfo?.let {
Log.d(TAG, "Status from device ${deviceInfo.name}")
}
| Parameter | Type | Description |
|---|---|---|
| appName | String |
Name of the hosting app |
| appVersionNumber | String |
Version of the hosting app |
| appVersionString | String |
Version of the hosting app |
| deviceBrand | String |
The device brand |
| deviceModel | String |
The device model |
| name | String |
The name of the device |
| osName | String |
The operating system of the device, can be one of iOS or Android |
| osVersion | String |
The version of the operating system on the device |
| sdkVersion | String |
The HyperTrack SDK version on the device. Can be reviewed here: Android, iOS, React Native |
DeviceViewUrls Properties
This object incapsulates resources that could be used to open WebView Widget (embedded view) or for sharing location via link.
String shareUrl = movementStatus.deviceViewUrls.embedUrl;
Uri uri = Uri.parse(shareUrl + PUBLISHABLE_KEY);
Intent intent = new Intent(Intent.ACTION_VIEW, uri);
if (intent.resolveActivity(getPackageManager()) != null) {
startActivity(intent);
}
val shareUrl = movementStatus.deviceViewUrls.embedUrl
val uri = Uri.parse(shareUrl!! + PUBLISHABLE_KEY)
val intent = Intent(Intent.ACTION_VIEW, uri)
if (intent.resolveActivity(packageManager) != null) {
startActivity(intent)
}
| Parameter | Type | Description |
|---|---|---|
| embedUrl | String |
Embeddable view URL |
| shareUrl | String |
Sharable view URL |
Trip Properties
Trip{
tripId="3737e382-b251-11e9-a7f6-f6b591671d93",
startedAt="2019-07-29T22:35:49.963554Z",
completedAt="",
status="active",
destination=Destination{
geometry=Geometry{
coordinates=[-122.437941, 37.800563]
},
radius=30,
scheduledAt=""
},
estimate=Estimate{ ... },
metadata="",
summary=""
}
| Method | Type | Description |
|---|---|---|
| getTripId() | String |
Unique identifier of the newly created trip, case sensitive |
| getStatus() | String |
Trip status, can be either active or completed |
| getStartedAt() | String |
Timestamp for trip starting time |
| getMetadata() | String |
Metadata provided at trip start |
| getSummary() | String |
Trip summary, only provided upon completion of a trip |
| getDestination() | Trip.Destination |
Destination of the trip, or null if trip has no destination |
| getEstimate() | Trip.Estimate |
Trip summary, only provided for trips with status active |
| getCompletedAt() | String |
ISO 8601 date when the trips was completed or null if it haven't been completed |
Trip Estimate Properties
Estimate{
arriveAt="",
route=Route{ ... }
}
| Method | Type | Description |
|---|---|---|
| getArriveAt() | String |
Timestamp for estimated arrival |
| getRoute() | Trip.Route |
Planned route segments to destination |
Trip Route Properties
Route{
distance=210,
duration=1720,
startAddress="1 Embarcadero Center, San Francisco, CA, 94122",
endAddress="353 Sacramento St, San Francisco, CA, 94122",
polyline=Polyline{ ... }
}
| Method | Type | Description |
|---|---|---|
| getDistance() | Integer |
Timestamp for estimated arrival |
| getDuration() | Integer |
Duration in seconds |
| getStartAddress() | String |
Street address lookup for segment start |
| getEndAddress() | String |
Street address lookup for segment end |
| getPoints() | List of List of Double |
Planned route segments to destination, as array of longitude, latitude and altitude (optional) tuples |
Trip Destination Properties
Destination{
geometry=Geometry{ ... },
radius=30,
scheduledAt="2019-07-29T22:35:49.963554Z"
}
| Method | Type | Description |
|---|---|---|
| getLatitude() | Double |
Latitude coordinate of destination center point in degrees. Negatives are for southern hemisphere |
| getLongitude() | Double |
Longitude coordinate of destination center point in degrees. Negatives are for western hemisphere |
| getRadius() | Integer |
Radius (in meters) of a circular trip destination |
| getScheduledAt() | String |
Timestamp for scheduled arrival |
Subscribe to updates
// Get SDK instance with Context reference
// replace <PUBLISHABLE_KEY> with your own key
HyperTrackViews hypertrackView = HyperTrackViews.getInstance(this, <PUBLISHABLE_KEY>);
// replace <DEVICE_ID> with your device ID
hypertrackView.subscribeToDeviceUpdates(<DEVICE_ID>,
new DeviceUpdatesHandler() {
@Override
public void onLocationUpdateReceived(@NonNull Location location) {
Log.d(TAG, "onLocationUpdateReceived: " + location);
}
@Override
public void onBatteryStateUpdateReceived(@BatteryState int i) {
Log.d(TAG, "onBatteryStateUpdateReceived: " + i);
}
@Override
public void onStatusUpdateReceived(@NonNull StatusUpdate statusUpdate) {
Log.d(TAG, "onStatusUpdateReceived: " + statusUpdate);
}
@Override
public void onTripUpdateReceived(@NonNull Trip trip) {
Log.d(TAG, "onTripUpdateReceived: " + trip);
}
@Override
public void onError(Exception e, String deviceId) {
Log.w(TAG, "onError: ", e);
}
@Override
public void onCompleted(String deviceId) {
Log.d(TAG, "onCompleted: " + deviceId);
}
}
);
You can subscribe to receive device state changes as they come in. The DeviceUpdatesHandler should implement and override the following interface methods:
| Method | Parameter | Description |
|---|---|---|
| onLocationUpdateReceived | Location |
Location update |
| onBatteryStateUpdateReceived | BatteryState |
Battery update, can be one of BATTERY_CHARGING, BATTERY_LOW, and BATTERY_NORMAL |
| onStatusUpdateReceived | StatusUpdate |
Status update |
| onTripUpdateReceived | Trip |
Trip update |
| onError | Exception, Device ID (String) |
Error with exception details and device ID |
| onCompleted | Device ID (String) |
Completion with Device ID |
StatusUpdate Properties
StatusUpdate{
value="WALK",
hint="",
recordedAt="2019-07-29T22:35:49.963554Z"
}
| Parameter | Type | Description |
|---|---|---|
| value | String |
Health event type, can be one of DRIVE, STOP, or WALK |
| hint | String |
Health hint. Additional information about the health event |
| recordedAt | String |
ISO 8601 date when the device status was recorded |
Unsubscribe from updates
You can unsubscribe from all the updates that you are subscribed to using below method:
| Method | Parameter | Description |
|---|---|---|
| stopAllUpdates | void |
Stops all the updates, that were scheduled for this SDK instance. |
hypertrackView.stopAllUpdates();
iOS
Refer to the integration guide for additional details.
Device Status
A device is either active or inactive at any given time.
Active
Location and activity data is tracking as expected.
Inactive
Location or activity data are not tracking. Error codes for reasons are documented in this section.
See this example how Device API provides insight into device outage status. Also, see this example how you can use a webhook payload device status update to help you receive outage codes and act on them.
Disconnected
HyperTrack platform is unable to sync with the device.
HyperTrack is a cloud platform to track ground truth of the device. There are times when the platform goes out of sync with the device. If and when the connection between device and platform is restored, the platform syncs up offline data and updates it for consumption in the cloud.
In the event that the device never returns to sync with the platform (can happen when device is lost or app is uninstalled), the device status will remain disconnected.
To understand how tracking status is defined and used in HyperTrack API, please refer to the following:
GeoJSON
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [125.6, 10.1, 123]
},
"properties": {
"name": "Dinagat Islands"
}
}
The GeoJSON format adopted by HyperTrack is based on the RFC 7946 specification. It is used as a generalized construct to encode geographic data structures using a JSON format. It supports a variety of types, with Point being the most commonly used.
HTTP Errors
We are adopting the RFC 7807 standard for our error messages.
{
"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"
}
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), the append additional properties as documented in the respective error section.
| 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) |
Trips API
The Trips API can return one of the following errors. Please review the reference carefully to understand the error reasons and potential steps to overcome the issues faced.
Wrong content-type
{
"status": 400,
"code": "wrong_content_format",
"title": "Wrong content format",
"type": "https://docs.hypertrack.com/#trips-api-wrong-content-type",
"detail": "The content submitted in the request body is not in valid JSON format"
}
Potential reasons:
- Libraries, functions, and formatters can be used unintnetionally to generate different content formats
Potential actions: Please double check that the body you generate for the request is in valid JSON format. You can use this small tool to ensure your JSON is valid.
Trip not found
{
"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"
}
Potential reasons:
- Trip IDs have the same format as Webhook and Devices IDs. You might have mixed up the IDs
- Usage of UUID types in database or language could change the formatting (e.g. case sensitivity)
Potential actions: Ensure that the right ID is used - with uppercase letters and no changes to the format(e.g. don't escape the -).
Order not found
{
"status": 404,
"title": "Order does not exist",
"code": "order_not_found",
"detail": "The requested order does not exist. Please review the invalid parameters",
"type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-not-found"
}
Potential reasons:
- Order IDs might have mixed up the IDs
- Usage of IDs in database or language could change the formatting (e.g. case sensitivity)
Potential actions: Ensure that the right ID is used.
Order can not be added
{
"status": 400,
"title": "Order can not be added",
"detail": "Trip is already completed/cancelled. Order can not be added now",
"code": "wrong_content_format",
"type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-can-not-be-added"
}
Potential reasons:
- Trip in which order is being added would already be completed or cancelled
Potential actions: Ensure that the order additions are done on an active trip only
Order Sequence Can not be Updated
{
"status": 400,
"title": "Order sequence can not be updated",
"detail"" "Trip is already completed/cancelled. Order sequence can not be updated now",
"code": "wrong_content_format",
"type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-sequence-can-not-be-updated"
}
Potential reasons:
- Trip for which order sequence is being updated would already be completed or cancelled
Potential actions: Ensure that the order sequence updates are done for an active trip only
Order can not be updated
{
"status": 400,
"title": "Order can not be updated",
"details": "Order is already either completed or cancelled",
"code": "wrong_content_format",
"type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-can-not-be-updated"
}
Potential reasons:
- Order which is being updated would already be completed or cancelled
Potential actions: Ensure that the order updates are done for an active order only
Trip Order Mismatch Error
{
"status": 400,
"title": "Order does not belong to this trip"
"detail": "The requested order does not belong to the provided trip. Please review the paramters",
"code": "wrong_content_format",
"type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-trip-order-mismatch-error"
}
Potential reasons:
- Order belongs to a different Trip
Potential actions: Ensure that the order to trip ID mappings are done correctly at your end.
Invalid Order Metadata
{
"status": 400,
"title": "Invalid Order Metadata",
"detail": "Metadata needs to be a valid JSON. Please review the parameters.",
"code": "wrong_content_format",
"type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-invalid-order-metadata"
}
Potential reasons:
- Improper escaping of metadata JSON
Potential actions: Ensure that the metadata is a valid JSON.
Order Validation Error
{
"status": 400,
"title": "Order request is malformed",
"detail": "The request format does not have correct format. Please review the invalid parameters",
"code": "validation_error",
"type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-validation-error"
}
Potential reasons:
- Desitnation without a
geometryobject is not valid - Geometry types other that
Pointare not supported - Coordinates in GeoJSON require two float numbers in an array
- Radius needs to be a positive integer value
scheduled_atneeds to be a string formatted as ISO 8601
Potential actions: Please review and fix the invalid parameters in invalid_params. You can also use this small tool to ensure your request body complies with our JSON schema for the API call.
Device not found
{
"status": 400,
"code": "device_not_found",
"title": "Device could not be found",
"type": "https://docs.hypertrack.com/#trips-api-device-not-found",
"detail": "Device with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}
Potential reasons:
- The referenced device got remove from HyperTrack systems
- Device IDs have the same format as Webhook and Trip IDs. You might have mixed up the IDs
- Usage of UUID types in database or language could change the formatting (e.g. case sensitivity)
Potential actions:
- Please verify that the referenced device is still available. You can use the Devices API for that
- Ensure that the right ID is used - with uppercase letters and no changes to the format(e.g. don't escape the
-).
Route not found
{
"status": 400,
"code": "route_not_found",
"title": "Route could not be found",
"type": "https://docs.hypertrack.com/#trips-api-route-not-found",
"detail": "Could not generate a route from the device location to the set destination"
}
Potential reasons:
- Destination GeoJSON couldn't be geocoded due to a wrong format
- No route could be found between the device location and destination
Potential actions:
- Ensure that coordinates in GeoJSON have longitude first and latitude second. You can use this small tool to verify your coordinates.
- Ensure that there are possible direct connections from the device location to the destination
Validation error
{
"status": 400,
"code": "validation_error",
"title": "Trip request is malformed",
"type": "https://docs.hypertrack.com/#trips-api-validation-error",
"detail": "The request format does not have the correct format. Please review the invalid parameters",
"invalid_params": [
{
"name": "destination.geometry.type",
"reason": "Only supported type is 'Point'. Received 'Polygon' instead"
}
]
}
Potential reasons:
- Desitnation without a
geometryobject is not valid - Geometry types other that
Pointare not supported - Coordinates in GeoJSON require two float numbers in an array
- Radius needs to be a positive integer value
scheduled_atneeds to be a string formatted as ISO 8601
Potential actions: Please review and fix the invalid parameters in invalid_params. You can also use this small tool to ensure your request body complies with our JSON schema for the API call.
Completion not possible
{
"status": 400,
"code": "completion_not_possible",
"title": "Trip cannot be completed",
"type": "https://docs.hypertrack.com/#trips-api-completion-not-possible",
"detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' cannot be completed"
}
Potential reasons:
- The referenced trip has already been completed (status is set to complete)
Potential actions:
- Ensure that the referenced trip is in status
active. You can use the Get trip by ID endpoint for that
Unauthorized
// HTTP Status: 401
{
"message": "Unauthorized"
}
Potential reasons:
Authorizationheader in the request is invalid or missing- Defined a different
Authorizationstrategy than Basic Auth - Base 64 encoding of {AccountId}:{SecretKey} isn't done correctly
Potential actions:
- Ensure you follow the API auth guidelines and try cURL to validate the token manually
Route creation failed
{
"status": 500,
"code": "route_error",
"title": "Failed to generate the route",
"type": "https://docs.hypertrack.com/#trips-api-route-creation-failed",
"detail": "Server could not complete the route generation"
}
Potential reasons:
- HyperTrack systems couldn't process the request at this time
Potential actions:
- The request may succeed if you try again sometime later
- Reach out to us via email or our customer support slack channel
Devices API
The Devices API can return one of the following errors. Please review the reference carefully to understand the error reasons and potential steps to overcome the issues faced.
Unauthorized
{
"message": "Unauthorized"
}
HTTP 401 (Unauthorized)
Potential reason: The Authorization header in the request is invalid or missing.
Potential actions:
- Review the Auth documentation and try cURL to validate the token manually
Device not found
{
"status": 404,
"code": "device_not_found",
"title": "Device could not be found",
"type": "https://docs.hypertrack.com/#devices-api-trip-not-found",
"detail": "Device with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}
HTTP 404 (Not Found)
Potential reasons:
- The referenced device got remove from HyperTrack systems
- Device IDs have the same format as Webhook and Trip IDs. You might have mixed up the IDs
- Usage of UUID types in database or language could change the formatting (e.g. case sensitivity)
Potential actions:
- Please verify that the referenced device is still available. You can use the Devices API for that
- Ensure that the right ID is used - with uppercase letters and no changes to the format(e.g. don't escape the
-).
Method Not Allowed
{
"status": 405,
"code": "method_not_allowed",
"title": "Method Not Allowed",
"type": "https://docs.hypertrack.com/#devices-api-method-not-allowed"
}
HTTP 405 (Method Not Allowed)
Potential reasons:
- The endpoint is not supporting the HTTP method requested.
Potential actions:
- Please verify that the referenced HTTP method is supported. You can use the Devices API for that.
Validation Error
{
"status": 400,
"code": "validation_error",
"title": "Device request is malformed",
"detail": "The request format does not have the correct format. Please review the invalid parameters",
"validation_errors": [
{
"field": "name",
"message": "Name cannot be empty."
}
],
"type": "https://docs.hypertrack.com/#devices-api-validation-error"
}
HTTP 400 (Bad Request)
Potential reasons:
- The set name was empty. Empty device names will prohibit you from searching, filtering, and sorting by device name in HyperTrack views.
Potential actions:
- Please provide a name that is not empty and can uniquely qualify a device
Properties Cannot Be Patched
{
"status": 400,
"code": "cannot_patch_property",
"title": "Properties cannot be patched",
"detail": "The property {x} is immutable. You can only patch: name and metadata",
"type": "https://docs.hypertrack.com/#devices-api-properties-cannot-be-patched"
}
HTTP 400 (Bad Request)
Potential reasons:
- Fields other than name and metadata were provided in the patch body. The request failed without any changes to the device resource.
Potential actions:
- Every field other than name and metadata is immutable on the device resource. Please remove all other fields from the patch body and try again.
Wrong content-type
{
"status": 400,
"code": "wrong_content_format",
"title": "Wrong content format",
"type": "https://docs.hypertrack.com/#devices-api-wrong-content-type",
"detail": "The content submitted in the request body is not in valid JSON format"
}
Potential reasons:
- Libraries, functions, and formatters can be used unintnetionally to generate different content formats
Potential actions: Please double check that the body you generate for the request is in valid JSON format. You can use this small tool to ensure your JSON is valid.
Legacy APIs
Trips
Manage Trips on the HyperTrack platform. With Trips API, you may be able to create and manage a trip with or without destination.
Start trip with one or multiple orders
Trip with orders request example:
payload='{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"service_time": 500
},
{
"order_id": "65fd526e-415e-497c-aa5c-4ffed9968262",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"service_time": 200
}
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips \
-H 'Content-Type: application/json' \
-d $payload
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let tripData = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"service_time": 500
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"service_time": 200
}
]
};
hypertrack.trips.create(tripData).then(trip => {
// Trip created
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
trip_data = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"service_time": 500
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"service_time": 200
}
]
}
trip = hypertrack.trips.create(trip_data)
print(trip)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n
\"device_id\": \"00112233-4455-6677-8899-AABBCCDDEEFF\",\n
\"orders\": [\n
{\n
\"order_id\":\"96f7ec96-402c-47a7-b0a1-eb6b91640a58\",\n
\"destination\": {\n
\"geometry\": {\n
\"type\": \"Point\",\n
\"coordinates\": [-122.398096, 37.793038]\n
},\n
\"address\": \"420 Montgomery Street, San Francisco, CA 94108, United States\",\n
\"radius\": 50\n
},\n
\"scheduled_at": "2021-02-18T14:30:00.000Z\",\n
\"service_time": 300\n
},\n
{\n
\"order_id\": \"73d4bc1e-7d82-4541-9f90-a5007badb98c\"\n
\"destination\": {\n
\"geometry\": {\n
\"type\": \"Point\",\n
\"coordinates\": [-122.404514, 37.793738]\n
},\n
\"address\": \"600 Kearny St, San Francisco, CA 94108, United States\",\n
\"radius"\: 50\n
},\n
\"scheduled_at\": \"2021-02-18T15:10:00.000Z\",\n
\"service_time\": 500\n
},\n
{\n
\"order_id\": \"73d4bc1e-7d82-4541-9f90-a5007badb98c\"\n
\"destination\": {\n
\"geometry\": {\n
\"type\": \"Point\",\n
\"coordinates\": [-122.406215, 37.794271]\n
},\n
\"address\": \"756 Grant Ave, San Francisco, CA 94108, United States\",\n
\"radius"\: 50\n
},\n
\"scheduled_at\": \"2021-02-18T15:25:00.000Z\",\n
\"service_time\": 200\n
}\n
]\n
}");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips")
.post(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/trips';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"service_time": 500
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"service_time": 200
}
]
}'
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
],
'content' => $payload
]);
$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")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"service_time": 500
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"service_time": 200
}
]
}.to_json
response = http.request(request)
puts response.read_body
Start a new trip for a device with one or multiple orders.
POST /trips
Authentication: Basic Auth or OAuth Token
Trip with multiple orders request attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique identifier representing a device, case sensitive |
| orders | array | Array of order Object |
| order | object | Definition of a order object |
| route | string | Specifies the route type used to route the orders. Can be fixed or flexible. fixed (default value) means orders will be routed in the sequence they appear in the orders object and ETAs are included. flexible does not provide any routes and no ETAs are provided. |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Definition of a order destination |
| order.destination.geofence_id | string | Unique identifier representing the geofence to be used for order destination, case sensitive |
| order.destination.geometry | object | GeoJSON geometry of type Point |
| order.destination.geometry.type | string | As of right now, only Point is supported |
| order.destination.geometry.coordinates | array | Array of longitude and latitude (in that order) |
| order.destination.radius | int | Defines the radius (in meters) of a circular order destination (optional, default is 30) |
| order.scheduled_at | string | Timestamp for scheduled arrival (optional) |
| order.service_time | int | Time to service at order destination place (optional, in seconds) |
| order.metadata | object | Optional JSON metadata you want to assign to this order |
| completion_type | string | Optional string. Specifies the completion logic of trips. Can be end_at_source_location or end_at_last_order (default) |
| metadata | object | Optional JSON metadata you want to assign to this trip |
HTTP 201 - New trip with destination
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T14:20:00.000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "420 Montgomery Street, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"service_time": 500,
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T14:50:00.000Z",
"route": {
"distance": 16366,
"duration": 3284,
"remaining_duration": 2360,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "600 Kearny St, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"order_id": "65fd526e-415e-497c-aa5c-4ffed9968262"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"service_time": 200,
"arrived_at": null,
"exited_at": null,
"share_url": "https://trck.at/abcd234",
"delayed": True,
"estimate": {
"arrive_at": "2021-02-18T15:30:00.000Z",
"route": {
"distance": 31366,
"duration": 5284,
"remaining_duration": 3860,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "756 Grant Ave, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
}
]
}
Trip with multiple orders response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.estimate | object | Estimates (route and arrival time) for order Only available if order is not completed, cancelled and have not yet been arrved |
| order.images | array | Array of image expirable links referring to photos taken as proof of delivery from Visits app |
| order.estimate.arrive_at | string | Timestamp for estimated arrival |
| order.estimate.route | object | Planned route segments to destination |
| order.estimate.route.distance | int | Route distance in meters |
| order.estimate.route.duration | int | Route duration in seconds |
| order.estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| order.estimate.route.start_place | string | Start place for segment start |
| order.estimate.route.end_place | string | End place for segment end |
| order.estimate.route.polyline | object | GeoJSON geometry of type LineString |
| order.metadata | object | Metadata provided for order |
| metadata | object | Metadata provided for trip |
Order.estimate object would only be present if we were able to generate the estimate either at the time of Trip Creation OR upon receiving first location after Trip Creation.
Please keep in mind that new trips do not have the summary property (outlining the trip history). The summary is only provided upon completion of a trip.
This API returns HTTP 201 once the trip is successfully created.
Complete trip
Complete trip example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/complete
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.complete(tripId).then(() => {
// Complete procedure initiated
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.trips.complete({tripId})
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/complete")
.post()
.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}/complete';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/trips/{trip_id}/complete")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Complete an ongoing trip.
POST /trips/{trip_id}/complete
The request will start the procedure and confirm a pending completion with a trips webhook. Until the completion is done, the trip will have the status processing_completion.
Calling trip completion on a trip that is not active will result in HTTP 409 responses.
Authentication: Basic Auth or OAuth Token
HTTP 202 - Trip completion initiated
{
"message": "pending completion for trip '00112233-4455-6677-8899-AABBCCDDEEFF'"
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
Completion finished
As soon as the trip was completed on HyperTrack systems, it will be extended with a summary property.
Ongoing orders which are part of the trip are marked as cancelled upon trip completion
Orders for cancelled trips do not have an estimate property because routing was cancelled.
HTTP 200 - Completed trip
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": "2021-02-18T16:34:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"status": "completed",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": "2021-02-18T15:00:00.000Z",
"status": "completed",
"share_url": "https://trck.at/abcd53",
"delayed": True,
"arrived_at": null,
"exited_at": null,
"summary": {
"distance": 1230,
"duration": 3600,
....
}
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": "2021-02-18T15:00:00.000Z",
"service_time": 500,
"status": "completed",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"summary": {
"distance": 3230,
"duration": 3600,
....
}
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": "2021-02-18T15:00:00.000Z",
"status": "completed",
"service_time": 200,
"arrived_at": null,
"exited_at": null,
"share_url": "https://trck.at/abcd234",
"delayed": False,
"summary": {
"distance": 530,
"duration": 3600,
....
}
}
],
"summary": {
...
}
}
Completed Trip response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.metadata | object | Metadata provided for order |
| order.summary | object | Order summary. Available for completed orders |
| metadata | object | Metadata provided for trip |
| summary | object | Trip summary |
Cancel an Order
Cancel Order:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/orders/{order_id}/cancel
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.orders.cancel(orderId).then(() => {
// Complete procedure initiated
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.orders.cancel({orderId})
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/orders/{order_id}/cancel")
.post()
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/orders/{order_id}/cancel';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/orders/{order_id}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Cancel an order using order ID.
POST /orders/{order_id}/cancel
Authentication: Basic Auth or OAuth Token
HTTP 200 - Order cancelled
{
"message": "Order with id {order_id} is cancelled"
}
Path Parameters
order_id- a string representing the ID of an order, case sensitive
Complete an Order of a trip
Complete Order of a trip example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/complete
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.orders.complete(tripId).then(() => {
// Complete procedure initiated
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.trips.orders.complete({tripId})
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/complete")
.post()
.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}/orders/{order_id}/complete';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/complete")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Complete an order of an ongoing trip.
POST /trips/{trip_id}/orders/{order_id}/complete
Authentication: Basic Auth or OAuth Token
HTTP 200 - Order of a Trip completed
{
"message": "Order with id {order_id} is completed"
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
order_id- a string representing the ID of an order belonging to the above trip, case sensitive
HTTP 200 - Order of a trip after completed
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States"
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": "2021-02-18T15:00:00.000Z",
"status": "completed",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"summary": {
"distance": 1230,
"duration": 3600,
....
}
]
}
Trip with completed order response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.images | array | Array of image expirable links referring to photos taken as proof of delivery from Visits app |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.metadata | object | Metadata provided for order |
| order.summary | object | Order summary. Available for completed orders |
| metadata | object | Metadata provided for trip |
Cancel an Order of a trip
Cancel Order of a trip example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/cancel
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.orders.cancel(tripId).then(() => {
// Complete procedure initiated
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.trips.orders.cancel({tripId})
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/cancel")
.post()
.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}/orders/{order_id}/cancel';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Cancel an order of an ongoing trip.
POST /trips/{trip_id}/orders/{order_id}/cancel
Authentication: Basic Auth or OAuth Token
HTTP 200 - Order of a Trip cancelled
{
"message": "Order with id {order_id} is cancelled"
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
order_id- a string representing the ID of an order belonging to the above trip, case sensitive
HTTP 200 - Order of a trip after cancellation
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States"
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "cancelled",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
},...
]
}
Trip with cancelled order response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order.order_id | string | Unique ID associated with the order object |
| order | object | Defined order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.images | array | Array of image expirable links referring to photos taken as proof of delivery from Visits app |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.metadata | object | Metadata provided for order |
| metadata | object | Metadata provided for trip |
Snooze an Order of a trip
Disable Order of a trip example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/disable
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.orders.disable(tripId).then(() => {
// Complete procedure initiated
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.trips.orders.disable({tripId})
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/disable")
.post()
.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}/orders/{order_id}/disable';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/disable")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Snooze an order of an ongoing trip.
POST /trips/{trip_id}/orders/{order_id}/disable
Authentication: Basic Auth or OAuth Token
HTTP 200 - Order of a Trip cancelled
{
"message": "Order with id {order_id} is disabled"
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
order_id- a string representing the ID of an order belonging to the above trip, case sensitive
HTTP 200 - Order of a trip after cancellation
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States"
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "disabled",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
},...
]
}
Trip with disabled order response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.images | array | Array of image expirable links referring to photos taken as proof of delivery from Visits app |
| order.exited_at | string | Timestamp first exit from order destination |
| order.metadata | object | Metadata provided for order |
| metadata | object | Metadata provided for trip |
Re-add an Order of a trip
Enable Order of a trip example:
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/enable
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.orders.enable(tripId).then(() => {
// Complete procedure initiated
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.trips.orders.enable({tripId})
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/enable")
.post()
.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}/orders/{order_id}/enable';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
]
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}/enable")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Re-add an order of an ongoing trip.
POST /trips/{trip_id}/orders/{order_id}/enable
Authentication: Basic Auth or OAuth Token
HTTP 200 - Order of a Trip cancelled
{
"message": "Order with id {order_id} is enabled"
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
order_id- a string representing the ID of an order belonging to the above trip, case sensitive
HTTP 200 - Order of a trip after cancellation
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States"
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T14:20:00.000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "420 Montgomery Street, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},...
]
}
Trip with ongoing order response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.images | array | Array of image expirable links referring to photos taken as proof of delivery from Visits app |
| order.estimate | object | Estimates (route and arrival time) for order Only available if order is not completed, cancelled and have not yet been arrved |
| order.estimate.arrive_at | string | Timestamp for estimated arrival |
| order.estimate.route | object | Planned route segments to destination |
| order.estimate.route.distance | int | Route distance in meters |
| order.estimate.route.duration | int | Route duration in seconds |
| order.estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| order.estimate.route.start_place | string | Start place for segment start |
| order.estimate.route.end_place | string | End place for segment end |
| order.estimate.route.polyline | object | GeoJSON geometry of type LineString |
| order.metadata | object | Metadata provided for order |
| metadata | object | Metadata provided for trip |
Update an Order of a trip
Update an Order of a Trip example:
payload='{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1257 Taylor St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:30:00.000Z",
"service_time": 300
}'
curl -X PUT \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id} \
-H 'Content-Type: application/json' \
-d $payload
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let orderData = {
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1257 Taylor St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:30:00.000Z",
"service_time": 300
};
hypertrack.trips.orders.update(order_id, orderData).then(trip => {
// Trip created
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
order_data = {
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1257 Taylor St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:30:00.000Z",
"service_time": 300
}
trip = hypertrack.trips.orders.update(order_id, order_data)
print(trip)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n
\"order_id\":\"96f7ec96-402c-47a7-b0a1-eb6b91640a58\",\n
\"destination\": {\n
\"geometry\": {\n
\"type\": \"Point\",\n
\"coordinates\": [-122.41281, 37.7930436]\n
},\n
\"address\": \"1257 Taylor St, San Francisco, CA 94108, United States\",\n
\"radius\": 50\n
},\n
\"scheduled_at": "2021-02-18T15:30:00.000Z\",\n
\"service_time": 300\n
}");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}")
.put(body)
.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}/orders/{order_id}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1257 Taylor St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:30:00.000Z",
"service_time": 300
}'
$context = stream_context_create([
"http" => [
"method" => "PUT",
"header" => $basicAuth
],
'content' => $payload
]);
$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}/orders/{order_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1257 Taylor St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:30:00.000Z",
"service_time": 300
}.to_json
response = http.request(request)
puts response.read_body
Update an order of an ongoing trip.
PUT /trips/{trip_id}/orders/{order_id}
Authentication: Basic Auth or OAuth Token
HTTP 200 - Order of a trip after updation
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1257 Taylor St, San Francisco, CA 94108, United States"
},
"scheduled_at": "2021-02-18T15:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "disabled",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
},...
]
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
order_id- a string representing the ID of an order belonging to the above trip, case sensitive
Trip with updated order response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.estimate | object | Estimates (route and arrival time) for order Only available if order is not completed, cancelled and have not yet been arrved |
| order.images | array | Array of image expirable links referring to photos taken as proof of delivery from Visits app |
| order.estimate.arrive_at | string | Timestamp for estimated arrival |
| order.estimate.route | object | Planned route segments to destination |
| order.estimate.route.distance | int | Route distance in meters |
| order.estimate.route.duration | int | Route duration in seconds |
| order.estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| order.estimate.route.start_place | string | Start place for segment start |
| order.estimate.route.end_place | string | End place for segment end |
| order.estimate.route.polyline | object | GeoJSON geometry of type LineString |
| order.metadata | object | Metadata provided for order |
| metadata | object | Metadata provided for trip |
Patch Metadata of an Order of a trip
Patch Metadata of an Order of a trip example:
payload='{
"metadata": {
"new_key": new_value
},
}'
curl -X PATCH \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id} \
-H 'Content-Type: application/json' \
-d $payload
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let order_data = {
"metadata": {
"new_key": new_value
}
}
hypertrack.trips.orders.patch(tripId, order_id, order_data).then(() => {
// Complete procedure initiated
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
order_data = {
"metadata": {
"new_key": new_value
}
}
hypertrack = Client({AccountId}, {SecretKey})
hypertrack.trips.orders.patch({tripId, order_id, order_data})
OkHttpClient client = new OkHttpClient();
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
RequestBody body = RequestBody.create(mediaType,"{\n
\"metadata\": {\n
\"new_key\": new_value\n
}\n
}");
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}")
.patch()
.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}/orders/{order_id}';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"metadata": {
"new_key": new_value
}
}'
$context = stream_context_create([
"http" => [
"method" => "PATCH",
"header" => $basicAuth
]
'content' => $payload
]);
$response = file_get_contents($url, false, $context);
echo $response;
?>
require 'uri'
require 'net/http'
require 'base64'
url = URI("https://v3.api.hypertrack.com/trips/{trip_id}/orders/{order_id}")
request.body = {
"metadata": {
"new_key": new_value
}
}.to_json
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
response = http.request(request)
puts response.read_body
Patch metadata on an order of an ongoing trip.
PATCH /trips/{trip_id}/orders/{order_id}
Authentication: Basic Auth or OAuth Token
HTTP 200 - Trip with order metadata updated
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"metadata": {
"new_key": new_value
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T14:20:00.000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "420 Montgomery Street, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"service_time": 500,
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T14:50:00.000Z",
"route": {
"distance": 16366,
"duration": 3284,
"remaining_duration": 2360,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "600 Kearny St, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"order_id": "65fd526e-415e-497c-aa5c-4ffed9968262"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"service_time": 200,
"arrived_at": null,
"exited_at": null,
"share_url": "https://trck.at/abcd234",
"delayed": True,
"estimate": {
"arrive_at": "2021-02-18T15:30:00.000Z",
"route": {
"distance": 31366,
"duration": 5284,
"remaining_duration": 3860,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "756 Grant Ave, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
}
]
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
order_id- a string representing the ID of an order belonging to the above trip, case sensitive
Trip with updated order metadata attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.metadata | object | Updated Metadata provided for order |
| order.images | array | Array of image expirable links referring to photos taken as proof of delivery from Visits app |
| metadata | object | Metadata provided for trip |
Add Orders to an ongoing trip
Add orders to an Ongoing Trip request example:
payload='{
"orders": [
{
"order_id": "e5c4331d-0b19-463e-bbe1-39b571e36ab3",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1320 Washington St, San Francisco, CA 94109, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:45:00.000Z",
"service_time": 300
},..
]
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders \
-H 'Content-Type: application/json' \
-d $payload
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let ordersData = {
"orders": [
{
"order_id": "e5c4331d-0b19-463e-bbe1-39b571e36ab3",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1320 Washington St, San Francisco, CA 94109, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:45:00.000Z",
"service_time": 300
},..
]
};
hypertrack.trips.orders.add(trip_id, ordersData).then(trip => {
// Orders added
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
orders_data = {
"orders": [
{
"order_id": "e5c4331d-0b19-463e-bbe1-39b571e36ab3",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1320 Washington St, San Francisco, CA 94109, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:45:00.000Z",
"service_time": 300
},..
]
}
trip = hypertrack.trips.orders.add(trip_id, trip_data)
print(trip)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n
\"orders\": [\n
{\n
\"order_id\":\"e5c4331d-0b19-463e-bbe1-39b571e36ab3\",\n
\"destination\": {\n
\"geometry\": {\n
\"type\": \"Point\",\n
\"coordinates\": [-122.398096, 37.793038]\n
},\n
\"address\": \"1320 Washington St, San Francisco, CA 94109, United States\",\n
\"radius\": 50\n
},\n
\"scheduled_at": "2021-02-18T15:45:00.000Z\",\n
\"service_time": 300\n
}\n
]\n
}");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders")
.post(body)
.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}/orders';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"orders": [
{
"order_id": "e5c4331d-0b19-463e-bbe1-39b571e36ab3",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1320 Washington St, San Francisco, CA 94109, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:45:00.000Z",
"service_time": 300
},..
]
}'
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
],
'content' => $payload
]);
$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}/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"orders": [
{
"order_id": "e5c4331d-0b19-463e-bbe1-39b571e36ab3",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1320 Washington St, San Francisco, CA 94109, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:45:00.000Z",
"service_time": 300
},..
]
}.to_json
response = http.request(request)
puts response.read_body
Add orders to an ongoing trip.
POST /trips/{trip_id}/orders
Authentication: Basic Auth or OAuth Token
HTTP 201 - Order of a trip after addition
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
...
{
"order_id": "e5c4331d-0b19-463e-bbe1-39b571e36ab3",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1320 Washington St, San Francisco, CA 94109, United States"
},
"scheduled_at": "2021-02-18T15:45:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "disabled",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
}
]
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
Trip with ongoing order response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.estimate | object | Estimate (route and arrival time) for order. Only available if order is not completed, cancelled and have not yet arrived. If the order destination is estimated to be longer than four hours away, the estimate object is returned empty for this order. |
| order.estimate.arrive_at | string | Timestamp for estimated arrival |
| order.estimate.route | object | Planned route segments to destination |
| order.estimate.route.distance | int | Route distance in meters |
| order.estimate.route.duration | int | Route duration in seconds |
| order.estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| order.estimate.route.start_place | string | Start place for segment start |
| order.estimate.route.end_place | string | End place for segment end |
| order.estimate.route.polyline | object | GeoJSON geometry of type LineString |
| order.metadata | object | Metadata provided for order |
| metadata | object | Metadata provided for trip |
Update Sequence of Orders of an ongoing trip
Update Sequence of Orders of a Trip example:
payload='{
"order_ids":[
"96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"65fd526e-415e-497c-aa5c-4ffed9968262",
"73d4bc1e-7d82-4541-9f90-a5007badb98c",
"e5c4331d-0b19-463e-bbe1-39b571e36ab3"
]
}'
curl -X PUT \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}/orders \
-H 'Content-Type: application/json' \
-d $payload
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let orderData = {
"order_ids":[
"96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"65fd526e-415e-497c-aa5c-4ffed9968262",
"73d4bc1e-7d82-4541-9f90-a5007badb98c",
"e5c4331d-0b19-463e-bbe1-39b571e36ab3"
]
};
hypertrack.trips.orders.update_sequence(trip_id, orderData).then(trip => {
// Trip created
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
order_data = {
"order_ids":[
"96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"65fd526e-415e-497c-aa5c-4ffed9968262",
"73d4bc1e-7d82-4541-9f90-a5007badb98c",
"e5c4331d-0b19-463e-bbe1-39b571e36ab3"
]
}
trip = hypertrack.trips.orders.update_sequence(trip_id, order_data)
print(trip)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n
\"order_ids\":[\n
\"96f7ec96-402c-47a7-b0a1-eb6b91640a58\",\n
\"65fd526e-415e-497c-aa5c-4ffed9968262\",\n
\"73d4bc1e-7d82-4541-9f90-a5007badb98c\",\n
\"e5c4331d-0b19-463e-bbe1-39b571e36ab3\"\n
]\n
}");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips/{trip_id}/orders/")
.put(body)
.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}/orders/';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"order_ids":[
"96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"65fd526e-415e-497c-aa5c-4ffed9968262",
"73d4bc1e-7d82-4541-9f90-a5007badb98c",
"e5c4331d-0b19-463e-bbe1-39b571e36ab3"
]
}'
$context = stream_context_create([
"http" => [
"method" => "PUT",
"header" => $basicAuth
],
'content' => $payload
]);
$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}/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"order_ids":[
"96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"65fd526e-415e-497c-aa5c-4ffed9968262",
"73d4bc1e-7d82-4541-9f90-a5007badb98c",
"e5c4331d-0b19-463e-bbe1-39b571e36ab3"
]
}.to_json
response = http.request(request)
puts response.read_body
Update sequence of orders of an ongoing trip.
PUT /trips/{trip_id}/orders
Authentication: Basic Auth or OAuth Token
HTTP 201 - Trip with updated order sequence
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": null,
"started_at": "2021-02-18T14:00:00.000Z",
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T14:20:00.000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "420 Montgomery Street, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"order_id": "65fd526e-415e-497c-aa5c-4ffed9968262"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"service_time": 200,
"arrived_at": null,
"exited_at": null,
"share_url": "https://trck.at/abcd234",
"delayed": True,
"estimate": {
"arrive_at": "2021-02-18T15:30:00.000Z",
"route": {
"distance": 31366,
"duration": 5284,
"remaining_duration": 3860,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "756 Grant Ave, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "ongoing",
"service_time": 500,
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T14:50:00.000Z",
"route": {
"distance": 16366,
"duration": 3284,
"remaining_duration": 2360,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "600 Kearny St, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"order_id": "e5c4331d-0b19-463e-bbe1-39b571e36ab3",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.41281, 37.7930436]
},
"address": "1320 Washington St, San Francisco, CA 94109, United States"
},
"scheduled_at": "2021-02-18T15:45:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": null,
"status": "disabled",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"estimate": {
"arrive_at": "2021-02-18T15:25:00.000Z",
"route": {
"distance": 16366,
"duration": 3284,
"remaining_duration": 2360,
"start_place": "333 Post St, San Francisco, CA 94108, United States",
"end_place": "600 Kearny St, San Francisco, CA 94108, United States",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
}
]
}
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
Trip with updated sequence response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.estimate | object | Estimates (route and arrival time) for order Only available if order is not completed, cancelled and have not yet been arrved |
| order.estimate.arrive_at | string | Timestamp for estimated arrival |
| order.estimate.route | object | Planned route segments to destination |
| order.estimate.route.distance | int | Route distance in meters |
| order.estimate.route.duration | int | Route duration in seconds |
| order.estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| order.estimate.route.start_place | string | Start place for segment start |
| order.estimate.route.end_place | string | End place for segment end |
| order.estimate.route.polyline | object | GeoJSON geometry of type LineString |
| order.metadata | object | Metadata provided for order |
| metadata | object | Metadata provided for trip |
Get trips
Get all trips example:
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.getAll().then(trips => {
// Process trips
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
"""
Arguments:
- trip_status: string status `active` or `completed` or `processing_completion`. `completed` by default
- pagination_token: string token received from previous call to request next page
"""
trips = hypertrack.trips.get_all()
print(trips)
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")
.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';
$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")
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
Get all trips in your account. Returns ongoing trips by default.
GET /trips
Authentication: Basic Auth or OAuth Token
Query Parameters
status- (optional) a string representing the trip status to filter by. Default isactive.from_date- (optional) date string to filtertrip.started_at; omitting this will show latest tripsto_date- (optional) date string to filtertrip.started_at; omitting this will show latest tripsdevice_id- (optional) device_id to filter trips for; by default, trips for all devices are shown
HTTP 200 - Trips payload
{
"data":[
{
"trip_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"started_at": "2019-05-03T06:25:51.238000Z",
"completed_at": null,
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"metadata": {
"customer_id": "ABC123"
},
"orders": [
..
],
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944]
},
"radius": 30,
"scheduled_at": "2019-05-03T06:25:51.238000Z",
"arrived_at": null,
"exited_at": null
},
"estimate": {
"arrive_at": "2019-05-03T06:25:51.238000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "Mannat Manzil #48,2nd cross, 3rd Main,Amrita Nagar, 3rd Phase, Choodasandra, Bengaluru, Karnataka 560035, India",
"end_place": "4, Muniswamy Garden, A - Block, Bengaluru, Karnataka 560025, India",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
},
{
"trip_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"started_at": "2019-05-03T06:25:51.238000Z",
"completed_at": "2019-05-03T06:25:51.238000Z",
"status": "completed",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"metadata": {
"customer_id": "ABC123"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944]
},
"radius": 30,
"scheduled_at": "2019-05-03T06:25:51.238000Z",
"arrived_at": "2019-05-03T06:25:51.238000Z"
},
"summary": {
...
}
}, ...
],
"links":{
"next": "https://v3.api.hypertrack.com/trips?pagination_token=abc"
}
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.estimate | object | Estimates (route and arrival time) for order Only available if order is not completed, cancelled and have not yet been arrved |
| order.estimate.arrive_at | string | Timestamp for estimated arrival |
| order.estimate.route | object | Planned route segments to destination |
| order.estimate.route.distance | int | Route distance in meters |
| order.estimate.route.duration | int | Route duration in seconds |
| order.estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| order.estimate.route.start_place | string | Start place for segment start |
| order.estimate.route.end_place | string | End place for segment end |
| order.estimate.route.polyline | object | GeoJSON geometry of type LineString |
| order.metadata | boolean | Metadata provided for order |
| order.delayed | boolean | Flag indicating whether there was a delay in delivering the order |
| order.arrived | boolean | Flag indicating if the driver arrived at the order location |
| order.delayed_time | int | Time in seconds indicating the delay in delivering the order |
| order.tracked | boolean | Flag indicating if the trip was tracked |
| order.on_time | boolean | Flag indicating whether the driver delivered before the scheduled time |
| order.completed_at_destination | boolean | Flag indicating whether the order was completed at close to the delivery location |
| order.duration_at_destination | int | The time in seconds spent at the customer location on delivery |
| order.summary | object | Order summary. Available for completed orders |
| destination | object | Defined trip destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | int | Radius (in meters) of a circular trip destination |
| destination.scheduled_at | string | Timestamp for scheduled arrival |
| destination.arrived_at | string | Timestamp first enter to destination |
| destination.exited_at | string | Timestamp first exit from destination |
| estimate | object | Estimates (route and arrival time). Only available for active trips. If the trip is estimated to be longer than four hours away from the destination, the estimate object is returned empty. |
| estimate.arrive_at | string | Timestamp for estimated arrival |
| estimate.route | objects | Planned route segments to destination |
| estimate.route.distance | int | Route distance in meters |
| estimate.route.duration | int | Route duration in seconds |
| estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| estimate.route.start_place | string | Start place for segment start |
| estimate.route.end_place | string | End place for segment end |
| estimate.route.polyline | object | GeoJSON geometry of type LineString |
| summary | object | Trip summary. Available for completed trips as well as for ongoing trips for a given trip_id |
| metadata | object | Metadata provided at trip start |
Orders array would be present in response if trip was created with orders in the first place.
Get trips by its metadata
Get trips by its metadata example: {"order_id":"1858268501"}
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips?metadata_filter=%7B%27order_id%27%3A+%271858268501%27%7D
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.getAll().then(trips => {
// Process trips
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
"""
Arguments:
- trip_status: string status `active` or `completed` or `processing_completion`. `completed` by default
- pagination_token: string token received from previous call to request next page
"""
trips = hypertrack.trips.get_all()
print(trips)
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?metadata_filter=%7B%27order_id%27%3A+%271858268501%27%7D")
.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?metadata_filter=%7B%27order_id%27%3A+%271858268501%27%7D';
$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?metadata_filter=%7B%27order_id%27%3A+%271858268501%27%7D")
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
Get trips by filtering for its metadata. By default, it will return matching results only trips status of which are set to active. In order to get trips that are completed, you should pass status query parameter set to completed.
GET /trips?metadata_filter=url_encoded_json
Authentication: Basic Auth or OAuth Token
Path Parameters
metadata_filter- a URL encoded string for JSON metadata to search for matching keys and values for trips associated with your account.from_date- date string to filter trip.started_atto_date- date string to filter trip.started_at
HTTP 200 - Trips payload
{
"data": [{
"trip_id": "c59b5596-7262-474e-a09a-f50f4d05208b",
"device_id": "78E344D6-B491-45E0-A600-34D8D3D85C54",
"started_at": "2020-09-14T04:07:41.243059Z",
"completed_at": "2020-09-14T05:22:26.612Z",
"status": "completed",
"views": {
"embed_url": "https://embed.hypertrack.com/trips/c59b5596-7262-474e-a09a-f50f4d05208b?publishable_key=kvhdzbufwQ4eIdo08jZVlBs8nuY-sEZcpyxi4m5smgnOOX9SuD-QY4CAN3CEUzlhCWqHHkqXDmGviL5t1mSxOw",
"share_url": "https://trck.at/mmmnx2havh"
},
"device_info": {
"os_version": "6.0.1",
"sdk_version": "4.5.3"
},
"metadata": {
"store_id": "VND-122125",
"sequence_number": 3,
"ht_view_text_ongoing": "Your order with ferns n petals is on the way",
"ht_view_href_text_completed": "Your order has been delivered. Track order status",
"ht_view_hide_summary_completed": true,
"RT_id": "VND-122125-20200914933503",
"ht_view_href_completed": "https://www.fnp.com",
"ht_view_text_completed": "Your order has been delivered.Track order status",
"delivery_boy_phone": "6261010969",
"recipient_name": "B.P Palsodkar",
"delivery_boy_id": "4095176",
"order_id": "1858268501"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [81.5955381, 21.2176175]
},
"radius": 30,
"scheduled_at": "2020-09-14T20:00:40.915000Z",
"address": "Sai Mandir Rd, Changurabhata, Raipur, Chhattisgarh 492013, India"
},
"orders": [
..
],
"summary": {
...
},
"analytics": {
"total_duration": 21005,
"active_count": 7,
"active_duration": 3602,
"stop_count": 3,
"stop_duration": 884,
"active_distance": 14819,
"drive_count": 4,
"drive_duration": 2718,
"drive_distance": 14819,
"inactive_count": 2,
"inactive_duration": 883
},
"eta_relevance_data": {
"status": true
}
}],
"pagination_token": null,
"links": {}
}
Get trip summary
Get trip summary example:
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.get(tripId).then(trip => {
// Process trip
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
trip = hypertrack.trips.get({tripId})
print(trip)
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
Get summary for a trip. Available for both ongoing and completed trips.
GET /trips/{trip_id}
Authentication: Basic Auth or OAuth Token
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
HTTP 200 - Completed trip
{
"trip_id": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"completed_at": "2021-02-18T16:34:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"status": "completed",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"orders": [
{
"order_id": "96f7ec96-402c-47a7-b0a1-eb6b91640a58",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
},
"address": "420 Montgomery Street, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T14:30:00.000Z",
"service_time": 300,
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": "2021-02-18T15:00:00.000Z",
"status": "completed",
"share_url": "https://trck.at/abcd53",
"delayed": True,
"arrived_at": null,
"exited_at": null,
"summary": {
"distance": 1230,
"duration": 3600,
....
}
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.404514, 37.793738]
},
"address": "600 Kearny St, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:10:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": "2021-02-18T15:00:00.000Z",
"service_time": 500,
"status": "completed",
"share_url": "https://trck.at/abcd53",
"delayed": False,
"arrived_at": null,
"exited_at": null,
"summary": {
"distance": 3230,
"duration": 3600,
....
}
},
{
"order_id": "73d4bc1e-7d82-4541-9f90-a5007badb98c"
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.406215, 37.794271]
},
"address": "756 Grant Ave, San Francisco, CA 94108, United States",
"radius": 50
},
"scheduled_at": "2021-02-18T15:25:00.000Z",
"started_at": "2021-02-18T14:00:00.000Z",
"completed_at": "2021-02-18T15:00:00.000Z",
"status": "completed",
"service_time": 200,
"arrived_at": null,
"exited_at": null,
"share_url": "https://trck.at/abcd234",
"delayed": False,
"summary": {
"distance": 530,
"duration": 3600,
....
}
}
],
"summary": {
...
}
}
Response Attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| orders | array | Array of order objects |
| order | object | Defined order object |
| order.order_id | string | Unique ID associated with the order object |
| order.destination | object | Defined order destination |
| order.destination.geometry | object | GeoJSON geometry of type Point for destination point |
| order.destination.radius | int | Radius (in meters) of a circular trip destination |
| order.scheduled_at | string | Timestamp for scheduled arrival |
| order.started_at | string | Timestamp when order was started tracking |
| order.completed_at | string | Timestamp when order was completed |
| order.status | string | Order status, can be ongoing, completed, cancelled or disabled |
| order.share_url | string | Shareable order view |
| order.arrived_at | string | Timestamp first enter to order destination |
| order.exited_at | string | Timestamp first exit from order destination |
| order.estimate | object | Estimates (route and arrival time) for order Only available if order is not completed, cancelled and have not yet been arrved |
| order.estimate.arrive_at | string | Timestamp for estimated arrival |
| order.estimate.route | object | Planned route segments to destination |
| order.estimate.route.distance | int | Route distance in meters |
| order.estimate.route.duration | int | Route duration in seconds |
| order.estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| order.estimate.route.start_place | string | Start place for segment start |
| order.estimate.route.end_place | string | End place for segment end |
| order.estimate.route.polyline | object | GeoJSON geometry of type LineString |
| order.metadata | boolean | Metadata provided for order |
| order.delayed | boolean | Flag indicating whether there was a delay in delivering the order |
| order.arrived | boolean | Flag indicating if the driver arrived at the order location |
| order.delayed_time | int | Time in seconds indicating the delay in delivering the order |
| order.tracked | boolean | Flag indicating if the trip was tracked |
| order.on_time | boolean | Flag indicating whether the driver delivered before the scheduled time |
| order.completed_at_destination | boolean | Flag indicating whether the order was completed at close to the delivery location |
| order.duration_at_destination | int | The time in seconds spent at the customer location on delivery |
| order.summary | object | Order summary. Available for completed orders |
| destination | object | Defined trip destination |
| destination.geometry | object | GeoJSON geometry of type Point for destination point |
| destination.radius | int | Radius (in meters) of a circular trip destination |
| destination.scheduled_at | string | Timestamp for scheduled arrival |
| destination.arrived_at | string | Timestamp first enter to destination |
| destination.exited_at | string | Timestamp first exit from destination |
| estimate | object | Estimates (route and arrival time). Only available for active trips. If the trip is estimated to be longer than four hours away from the destination, the estimate object is returned empty. |
| estimate.arrive_at | string | Timestamp for estimated arrival |
| estimate.route | objects | Planned route segments to destination |
| estimate.route.distance | int | Route distance in meters |
| estimate.route.duration | int | Route duration in seconds |
| estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| estimate.route.start_place | string | Start place for segment start |
| estimate.route.end_place | string | End place for segment end |
| estimate.route.polyline | object | GeoJSON geometry of type LineString |
| summary | object | Trip summary. Available for completed trips as well as for ongoing trips for a given trip_id |
| metadata | object | Metadata provided at trip start |
Orders array would be present in response if trip was created with orders in the first place.
Trip summary
For completed and ongoing trips, the response will include summary object giving location and marker details about the full trip.
Trips API: Summary available for completed trips
{
"summary": {
"locations": {
"type": "LineString",
"coordinates": [
[-122.3996, 37.79396136184457, 123, "2019-09-13T18:21:51.002000Z"],
[
-122.39982803643629,
37.79423869055751,
null,
"2019-09-13T18:21:51.802000Z"
]
]
},
"distance": 1234,
"duration": 9887,
"duration_at_destination": 0,
"started_at": "2019-09-13T18:04:20.467000Z",
"completed_at": "2019-09-13T20:49:08.226000Z",
"device_id": "FC772B07-2F27-4EB9-8A3B-F21D7F63A436",
"markers": [
{
"type": "device_status",
"marker_id": "372cb712-55d8-447f-b33b-ea4f9be7b236",
"data": {
"value": "inactive",
"start": {
"recorded_at": "2019-09-13T19:40:51.002000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:39:51.002000Z"
}
},
"end": {
"recorded_at": "2019-09-13T20:40:51.002000Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T20:40:52.002000Z"
}
},
"reason": "tracking_stopped"
}
},
{
"type": "trip_marker",
"marker_id": "4d4e5cc0-c183-46e5-b6f9-d0a4c48c4e54",
"data": {
"recorded_at": "2019-09-13T20:40:52.002000Z",
"location": {
"coordinates": [-122.3996, 37.7939],
"type": "Point"
},
"metadata": {
"id": "1235"
},
"route_to": {
"duration": 2654,
"distance": 377,
"start_location": {
"geometry": {
"type": "Point",
"coordinates": [-122.3996, 37.7939]
},
"recorded_at": "2019-09-13T19:33:51.002000Z"
}
}
}
},
{
"data": {
"address": "123 Main St, CA 90701, USA",
"arrival": {
"location": {
"geometry": {
"coordinates": [
-122.3996,
37.7939
5.76
],
"type": "Point"
},
"recorded_at": "2019-09-13T19:33:51.002000Z"
}
},
"duration": 3600,
"exit": {
"location": {
"geometry": {
"coordinates": [
-122.3996,
37.7939
5.76
],
"type": "Point"
},
"recorded_at": "2019-09-13T20:33:51.002000Z"
}
},
"geofence": {
"geofence_id": "28c6fcb7-0f57-4cdc-8544-0ea073081b25",
"geometry": {
"coordinates": [
-122.3996,
37.7939
],
"type": "Point"
},
"radius": 500
}
},
"marker_id": "f8bfb5d3-e282-4ab7-a828-a204e98f1bce",
"type": "destination"
}
]
}
}
| Name | Type | Description |
|---|---|---|
| summary.locations | object | Object representing the location time series of the full trip. Follows GeoJSON geometry of type LineString |
| summary.locations.type | string | As of right now, only LineString is supported |
| summary.locations.coordinates | array | Array of coordinates arrays; each item follows [longitude, latitude, elevation, timestamp]; elevation can be null |
| summary.distance | int | Distance for entire trip, in meters |
| summary.duration | int | Duration for entire trip, in seconds |
| summary.duration_at_destination | int | Duration the driver spent at the trip destination, in seconds |
| summary.started_at | string | ISO 8601 date when the trip started |
| summary.completed_at | string | ISO 8601 date when the trip was completed |
| summary.device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| summary.markers | array | Array of markers |
| summary.markers[].type | string | Marker type; can be one of device_status, geofence, destination or trip_marker |
| summary.markers[].marker_id | string | Unique marker identifier |
| summary.markers[].data | object | Marker data; dependent on marker type |
Detailed description of device_status markers data field:
| Name | Type | Description |
|---|---|---|
| address | string | Address. Only available for active markers (value=active) at stops (activity=stop) |
| activity | string | Activity. Can be one of stop, drive or walk. Only available for active markers (value=active) |
| duration | int | Duration of marker in [seconds] |
| end | object | End of the device status segment |
| end.location | object | Location object when the device_status changed |
| end.location.geometry | object | GeoJSON geometry of type Point |
| end.location.geometry.type | string | As of right now, only Point is supported |
| end.location.geometry.coordinates | array | Array of longitude and latitude |
| end.location.recorded_at | string | ISO 8601 date when the location was recorded |
| end.recorded_at | string | ISO 8601 date when the device status change was recorded |
| start | object | Start of the device status segment |
| start.location | object | Location object when the device_status changed |
| start.location.geometry | object | GeoJSON geometry of type Point |
| start.location.geometry.type | string | As of right now, only Point is supported |
| start.location.geometry.coordinates | array | Array of longitude and latitude |
| start.location.recorded_at | string | ISO 8601 date when the location was recorded |
| start.recorded_at | string | ISO 8601 date when the device status change was recorded |
| steps | int | Number of steps in current marker. Only available for active markers (value=active) |
| value | string | Device status. Can be one of active, inactive or disconnected. Active markers show the activity |
Detailed description of trip_marker markers data field:
| Name | Type | Description |
|---|---|---|
| location | object | Location object where the geotag was created |
| location.geometry | object | GeoJSON geometry of type Point |
| location.geometry.type | string | As of right now, only Point is supported |
| location.location.geometry.coordinates | array | Array of longitude and latitude |
| metadata | object | Any metadata assigned to this geotag |
| recorded_at | string | ISO 8601 date when geotag was recorded |
| route_to | object | Object giving details about the route taken to this geotag |
| route_to.distance | int | Distance traveled from previous geotag (or fist location), in meter |
| route_to.duration | int | Duration traveled from previous geotag (or fist location), in seconds |
| route_to.start_location | object | Location object where route_to calculation is based on. Starting point of route to this geotag. |
| route_to.start_location.geometry | object | GeoJSON geometry of type Point of start location |
| route_to.start_location.geometry.type | string | As of right now, only Point is supported |
| route_to.start_location.geometry.coordinates | array | Array of longitude and latitude |
| route_to.start_location.recorded_at | array | ISO 8601 date when the start location was recorded |
Get trip analytics
Get trip summary example:
curl \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/{trip_id}
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
hypertrack.trips.get(tripId).then(trip => {
// Process trip
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
trip = hypertrack.trips.get({tripId})
print(trip)
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
Get analytics data for a given trip
GET /trips/{trip_id}/analytics
Authentication: Basic Auth or OAuth Token
Path Parameters
trip_id - a string representing the ID of a trip, case sensitive
Query Parameters
from- (optional) ISO 8601 timestamp indicating the start of the time range; defaults totrip.started_atif omittedto- (optional) ISO 8601 timestamp indicating the end of the time range; defaults totrip.completed_at(or current time for ongoing trips) if omitted
curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips/00001111-4047-4b28-a6ec-f934e870c425/analytics
-H 'Content-Type: application/json'
HTTP 200 - Trip analytics response payload
{
"trip_id": "00001111-4047-4b28-a6ec-f934e870c425",
"analytics": {
"active_count': 1,
"active_duration": 100,
"active_duration_at_destination": 50,
"drive_count": 1,
"drive_duration": 50,
"inactive_count": 1,
"inactive_duration": 100,
"last_recorded_at_destination": "2022-02-22T02:22:22.000Z"
"stop_count": 1,
"stop_duration": 100,
"total_duration": 250,
"tracking_rate": 0.4
}
}
Start trip with destination
Trip with destination request example:
payload='{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [-122.398096, 37.793038]
}
}
}'
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/trips \
-H 'Content-Type: application/json' \
-d $payload
// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let tripData = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [35.107479, 47.856564]
},
"radius": 50
}
};
hypertrack.trips.create(tripData).then(trip => {
// Trip created
}).catch(error => {
// Error handling
})
from hypertrack.rest import Client
from hypertrack.exceptions import HyperTrackException
hypertrack = Client({AccountId}, {SecretKey})
trip_data = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [35.10747945667027, 47.8565694654932]
},
"radius": 50
}
}
trip = hypertrack.trips.create(trip_data)
print(trip)
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,"{\n" +
" \"device_id\": \"00112233-4455-6677-8899-AABBCCDDEEFF\",\n" +
" \"destination\": {\n" +
" \"geometry\": {\n" +
" \"type\": \"Point\",\n" +
" \"coordinates\": [-122.398096, 37.793038]\n" +
" }\n" +
" }\n" +
"}");
String authString = "Basic " +
Base64.getEncoder().encodeToString(
String.format("%s:%s", "account_id_value","secret_key_value")
.getBytes()
);
Request request = new Request.Builder()
.url("https://v3.api.hypertrack.com/trips")
.post(body)
.addHeader("Authorization", authString)
.build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
<?php
$url = 'https://v3.api.hypertrack.com/trips';
$basicAuth = "Authorization: Basic " . base64_encode('{AccountId}' . ':' . '{SecretKey}');
$payload = '{
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.398096,
37.793038
]
}
}
}'
$context = stream_context_create([
"http" => [
"method" => "POST",
"header" => $basicAuth
],
'content' => $payload
]);
$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")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic ' + Base64.strict_encode64( '{AccountId}' + ':' + '{SecretKey}' ).chomp
request.body = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.398096,
37.793038
]
}
}
}.to_json
response = http.request(request)
puts response.read_body
Start a new trip for a device with a destination
POST /trips
Authentication: Basic Auth or OAuth Token
Trip with destination request attributes
| Name | Type | Description |
|---|---|---|
| device_id | string | Unique identifier representing a device, case sensitive |
| destination | object | Definition of a trip destination (optional) |
| destination.geometry | object | GeoJSON geometry of type Point or Polygon |
| destination.geometry.type | string | Point or Polygon are supported |
| destination.geometry.coordinates | array | Array of longitude and latitude in case of Point type; Polygon type contains array of arrays of positions (First and last positions need to be same to complete the loop) |
| destination.radius | int | Defines the radius (in meters) of a circular trip destination (optional, default is 30); Only valid for Point destinations |
| destination.scheduled_at | string | Timestamp for scheduled arrival (optional) |
| metadata | object | Optional JSON metadata you want to assign to this trip |
For the purpose of consistency, you can provide destination address string via ht_view_destination_address field inside metadata.
If present this field would be used as destination address across all interfaces (APIs, views)
HTTP 201 - New trip with destination
{
"completed_at": null,
"status": "active",
"views": {
"embed_url": "https://embed.hypertrack.com/dkdkddnd",
"share_url": "https://trck.at/abcdef"
},
"destination": {
"geometry": {
"type": "Point",
"coordinates": [
-122.3980960195712,
37.7930386903944
]
},
"radius": 30,
"scheduled_at": null,
"arrived_at": null,
"exited_at": null
},
"estimate": {
"arrive_at": "2019-05-03T06:25:51.238000Z",
"route": {
"distance": 14666,
"duration": 2884,
"remaining_duration": 1560,
"start_place": "Mannat Manzil #48,2nd cross, 3rd Main,Amrita Nagar, 3rd Phase, Choodasandra, Bengaluru, Karnataka 560035, India",
"end_place": "4, Muniswamy Garden, A - Block, Bengaluru, Karnataka 560025, India",
"polyline": {
"type": "LineString",
"coordinates": [
[ -122.3980960195712, 37.7930386903944 ]
, ... ]
}
}
}
}
Trip with destination response attributes
| Name | Type | Description |
|---|---|---|
| trip_id | string | Unique identifier of the newly created trip, case sensitive |
| device_id | string | Unique identifier of the device associated with the trip, case sensitive |
| started_at | string | Timestamp for trip starting time |
| completed_at | string | Timestamp of trip completion time (only set when trip is completed), can be null |
| status | string | Trip status, can be active, completed or processing_completion |
| views.embed_url | string | Embeddable trip view |
| views.share_url | string | Shareable trip view |
| destination | object | Defined trip destination |
| destination.geometry | object | GeoJSON geometry of type Point or Polygon for destination |
| destination.radius | int | Radius (in meters) of a circular trip destination. Only returned for Point geofences |
| destination.scheduled_at | string | Timestamp for scheduled arrival |
| destination.arrived_at | string | Timestamp first enter to destination |
| destination.exited_at | string | Timestamp first exit from destination |
| estimate | object | Estimates (route and arrival time) Only available for active trips. If the trip is estimated to be longer than four hours away from the destination, the estimate object is returned empty. |
| estimate.arrive_at | string | Timestamp for estimated arrival |
| estimate.route | objects | Planned route segments to destination |
| estimate.route.distance | int | Route distance in meters |
| estimate.route.duration | int | Route duration in seconds |
| estimate.route.remaining_duration | int | Remaining route duration in seconds, can be null |
| estimate.route.start_place | string | Start place for segment start |
| estimate.route.end_place | string | End place for segment end |
| estimate.route.polyline | object | GeoJSON geometry of type LineString |
| metadata | object | Metadata provided at trip start |
Please keep in mind that new trips do not have the summary property (outlining the trip history). The summary is only provided upon completion of a trip.
This API returns HTTP 201 once the trip is successfully created. If a trip with same destination and metadata already exists, the API will return existing trip with HTTP status 200.