Live Tracking API

Introduction

Live Tracking is an efficient system that offers a comprehensive solution for managing and monitoring various assets, including vehicles, users, and drivers. Live Tracking API provides real-time information on the location, status, and activity of assets. Additionally, users can also receive events based on the activity of the assets enabling real-time monitoring.

With its advanced capabilities, Live Tracking changes how businesses manage and monitor their assets, providing a powerful tool for optimizing operations and enhancing efficiency.

Current Live Tracking API version provides the following abilities:

1. Create and manage assets.
2. Query past track of assets.
3. Search for assets in an area.
4. Create monitors to track assets.
5. Create alerts based on asset activity.

Asset

The Asset services in Live Tracking API allow businesses to create and manage assets. An asset represents an entity that needs to be tracked in your project. Users can define assets using a variety of properties like a unique ID for the asset, custom attributes of the asset for easy search and filter, among other properties. Once an asset is created, users can configure it to be tracked by using the GPS information from the asset.

Live Tracking API helps businesses in tracking real-time information about the location of an asset including their exact position, speed, last location and among other details. The real-time information of an asset can then be used to generate events based on certain pre-defined criteria. A combination of real-time information and events based on this information can be utilized to optimize logistics and improve operational efficiency.

Let’s take a look at some of the methods available to monitor and manage assets.

Create an Asset

Users can create new assets by sending a POST request with relevant details of the asset like name, ID, attributes, etc. The service responds with an asset ID which can be used to perform all other asset operations. A restaurant delivery service, for example, can utilize this API method to create a new set of assets representing each delivery vehicle in their fleet, simplifying management and tracking.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location --request POST 'https://api.nextbillion.io/skynet/asset?key=<your_api_key>'
2
--header 'Content-Type: application/json'
3
--data-raw '{...}'

Sample API Response

1
{
2
  "status": "Ok",
3
  "data": {
4
    "id": "4ba554b9-ef1c-48f0-9833-636edcf89256"
5
  }
6
}

Get an Asset

Users can retrieve a specific asset and its related information by providing the asset ID as a path parameter. The response containing all the details of the requested asset can be easily consumed within the user’s software applications or platforms. For example, a logistics company that provides delivery services to restaurants can use this API method to retrieve the information of a specific delivery truck within its fleet management system.

Request Parameter

Response Schema

Sample API Request

1
curl --location --request GET 'https://api.nextbillion.io/skynet/asset/38a530ca-18c4-482b-8fb4-c40c5b1349ee?key=<your_api_key>'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": {
4
       "asset": "{...}"
5
   }
6
}

Update an Asset

Use this method to update the data related to an asset by sending a PUT request with the asset ID as a path parameter and asset details to be updated in the request body. For example, a restaurant delivery service can utilize this API method to update the metadata of their delivery vehicles. This would allow the service to manage the details of each vehicle more efficiently, ensuring that the information is up-to-date and relevant to their customers.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location --request PUT 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256?key=<your_api_key>'
2
--header 'Content-Type: application/json'
3
--data-raw '{...}'

Sample API Response

1
{
2
"status": "Ok"
3
}

Update Asset Attributes

This method enables users to update the attributes of an asset. Users can use this method to maintain custom attributes such as shift timing, driver name or any other useful information related to the asset. These attributes can be utilized for filtering assets in search queries, configuring monitors, and obtaining asset lists.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location --request PUT 'https://api.nextbillion.io/skynet/asset/788bfcbb-e067-48fb-a4a8-a09d9530aee8/attributes?key=<your_api_key>' --header 'Content-Type: application/json' --data-raw '{...}'

Sample API Response

1
{
2
  "status": "Ok"
3
}

Bind Device to Asset

This method is used to bind a GPS device to an asset where, a device is any physical GPS device capable of sending tracking information and an asset is any vehicle or moving object that needs to be tracked. An asset needs to be linked to a GPS device to be able to upload location information of its movement. Users can bind one device to multiple assets, but it is not recommended to do so simultaneously (lest multiple assets will have the same tracking information). The devices bound to assets can be updated from time to time as the business requirements change. Users can use this method to do so by providing the new device_id in the request body. The service will overwrite the existing device_id.

This method has applications in fleet management, asset tracking, logistics, supply chain management, asset security and field service management. It enables users to bind GPS devices to assets such as vehicles, equipment, or shipments, allowing real-time tracking, monitoring, and optimization of asset movement.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location --request POST 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/bind?key=<your_api_key>' --header 'Content-Type: application/json' --data-raw '{...}

Sample API Response

1
{
2
  "status": "Ok"
3
}

Delete An asset

Users can send a DELETE request with the asset id as a path parameter to delete an existing asset. For example, a logistics service provider can leverage this API method to delete assets such as delivery vehicles that are no longer needed or are beyond repair. Please note that on deleting an asset the related tracking data is also deleted.

Request Parameter

Response Schema

Sample API Request

1
curl --location --request DELETE 'https://api.nextbillion.io/skynet/asset/cc2987a9-5fc7-438c-b026-09792c6687f8?key=<your_api_key>'

Sample API Response

1
{
2
  "status": "Ok"
3
}

Get Asset List

Use this method to get a list of assets by sending a GET request with filter criteria properties as request parameters. The service returns a paginated response containing a list of assets along with details of their latest tracked location. The pagination feature allows users to break down the list of assets into smaller, more manageable subsets, making it easier for users to navigate through larger sets of data on their software applications or platforms. For example, a restaurant delivery service can use this API method to retrieve a list of all their available delivery vehicles that have specific area attributes. This would enable them to efficiently manage their fleet and ensure that all available vehicles are properly accounted for.

Request Parameter

Response Schema

Sample API Request

1
curl --location 'https://api.nextbillion.io/skynet/asset/list?include_all_of_attributes=vehicle_type:mini-bus&sort=created_at:desc&ps=500&pn=1&key=<your_api_key>'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": {
4
       "list": "[...]",
5
       "page": "{...}"
6
   }
7
}

Upload locations of an Asset

Use this method to upload location information for assets by sending a POST request with asset ID as a path parameter and the details of the location details in the request body. This API method is useful for building applications that require location-based tracking and monitoring, such as fleet management systems, asset tracking platforms, and logistics management solutions.

For example, when a delivery truck starts its journey, the API method is used to upload the truck's id or external_id, service_id, name along with current location data, such as timestamp, accuracy, speed, bearing, altitude, and metadata. As the truck continues on its journey, the API method can be used to upload the updated location data at regular intervals. The restaurant delivery service provider can use this real-time location data to optimize delivery routes, track the progress of their delivery trucks, and ensure that deliveries are made on time.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location --request POST 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/track?key=<your_api_key>'
2
--header 'Content-Type: application/json' --data-raw '{...}

Sample API Response

1
{
2
  "status": "Ok"
3
}

Track locations of an Asset

This method allows users to retrieve the location data of an asset within their software applications or platforms with pagination support. This API endpoint supports optional filters such as start_time, end_time, and geometry_type, providing users with more control over the returned data. For example, a restaurant delivery service provider that wants to track the location of their delivery vehicle can use this method to retrieve the current and past locations of a vehicle, as well as additional details such as accuracy, speed, and timestamp. They can also filter the results based on specific timeframes and choose to display the location data in various formats such as polyline, polyline6, or geojson. This information can help the company optimize its delivery routes, estimate delivery times, and ensure that its trucks are operating efficiently.

Request Parameter

Response Schema

Sample API Request

1
curl --location --request GET 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/location/list?key=<your_api_key>&geometry_type=geojson&correction=mapmatch=1,interpolate=1,mode=car'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": {
4
       "list": "[...]",
5
       "page": "{...}",
6
       "geojson":"{...}"
7
   }
8
}

Track the last location of an Asset

Use this method to get the last known location of an asset by sendinging the id of the asset as a path parameter to get the last tracked location of the asset along with its details such as accuracy, speed, bearing along with other details of the asset.

Suppose you are developing a restaurant delivery management software and want to display the last location of each delivery vehicle in real-time to the users of your application. You can use this method to fetch the last known location of each vehicle and display it on a map interface in your application. This will provide your users with accurate and up-to-date information about the last location of their delivery vehicles.

Request Parameter

Response Schema

Sample API Request

1
curl --location --request GET 'https://api.nextbillion.io/skynet/asset/4ba554b9-ef1c-48f0-9833-636edcf89256/location/last?key=<your_api_key>'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": "{...}"
4
}

Event History of an Asset

Use this method to get the history of an asset’s events. An event refers to an occurrence or incident that is detected by the tracking system in real-time. Live Tracking API can generate events when an asset

1. moves into or out of a monitored geofence
2. exceeds the specified speed limits
3. is idle for a specified amount of time

Events form a crucial aspect of Live Tracking, as they provide real-time information about the movement and status of assets, enabling businesses to optimize their operations, improve safety and provide better customer service.

Users can send a GET request along with an asset ID as a path parameter to retrieve the event history of an asset within their software applications or platforms with pagination support. This method is useful in building software applications that need to track the movement of their assets to make further decisions like tracking compliance, disbursing reimbursements, ensuring service delivery, etc.

Request Parameter

Response Schema

Sample API Request

1
curl --location --request GET 'https://api.nextbillion.io/skynet/asset/e232b966-b30c-49b9-9e11-56065409519e/event/list?key=<your_api_key>&monitor_id=6ef9582e-f75e-4ca1-b4f1-e3aedec7274e'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": "{...}"
4
}

Search

The Search service of Live Tracking API allows users to search for active assets within a specific area or a bounding box. It uses a specified search area to return a list of active assets that fall within it. An asset is considered active if it has been tracked (location uploaded) at least once during the last 7 days. Once a search request is submitted successfully, the service responds with a paginated result listing all the assets found. This can be particularly useful for applications that require proximity-based search functionality such as restaurant or store locators, or for tracking the location of assets in a fleet management system.

Around Search

Use this method to search for active assets within a specified radius of a location coordinate. For example, a restaurant delivery service can search for all available delivery vehicles that are within a 5000 m radius of a specified location using this API method. They can also apply a filter to their search to only retrieve assets that are currently available for use. The API will return a list of available delivery vehicles within the specified radius along with their location, metadata, and other details allowing the company to plan its logistics more efficiently.

Request Parameter

Response Schema

Sample API Request

1
curl --location 'https://api.nextbillion.io/skynet/search/around?key=<your_api_key>&center=34.04937853,-118.27333793&radius=5000&include_all_of_attributes=driver_name:John Blake|vehicle_type:Pickup'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": "{...}"
4
}

Bound Search

Use this method to search for active assets within a specified geographic boundary. It takes a bound parameter which is a pipe (|) delimited string of two latitude and longitude coordinates, the first being the southwest coordinate and the second being the northeast coordinate of the bounding box. Please note that the bounding box area is limited to a maximum of 3000 km². The API also supports filtering the search results based on multiple conditions specified in the ‘filter’ parameter as a pipe-delimited string of key-value pairs. Once a valid request is submitted, the service responds with a paginated list of assets found within the specified bound.

This service can be useful to, for example, a restaurant delivery service may use this API method to find all their delivery vehicles that are currently within a specific area. They can use the bound parameter to specify the coordinates of the boundary that defines the area and filter the search results to only include bikes or trucks. This would allow the service to efficiently allocate its resources and optimize its delivery routes. The API method returns a response with information about each asset that matches the search criteria including the asset's ID, name, last tracked location, and any attributes attached to the asset.

Request Parameter

Response Schema

Sample API Request

1
curl --location 'https://api.nextbillion.io/skynet/search/bound?bound=34.04497533,-118.27710928|34.05875233,-118.26048106&include_all_of_attributes=driver_name:John Blake|vehicle_type:Pickup&key=<your_api_key>'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": "{...}"
4
}

GET Polygon Search

The "Polygon Search" API method allows you to search for active assets within a polygon defined by a set of coordinates. With this API, you can filter active assets based on multiple conditions and retrieve information like asset name, description, last tracked location, tags, and attributes.

This API is particularly useful for businesses that need to track assets and equipment in specific geographical areas. Please note that the search polygon size is limited to a maximum area of 3000 km². For example, a restaurant delivery service can use this API to locate all their delivery vehicles within a specific delivery zone. In addition to location tracking, this API also enables the filtering of assets based on different parameters such as the asset's creation and update time, tags, and other details which can help the restaurant delivery service provider to efficiently manage their assets and delivery operations.

Request Parameter

Response Schema

Sample API Request

1
curl --location 'https://api.nextbillion.io/skynet/search/polygon?key=<your_api_key>&polygon=34.05875233,-118.26048106|34.04611166,-118.25533831|34.02778645,-118.25705256|34.02991749,-118.30796578|34.07309507,-118.30796578|34.05875233,-118.26048106&include_all_of_attributes=driver_name:John Blake|vehicle_type:Pickup'

Sample API Response

1
{
2
   "status": "Ok",
3
   "data": "{...}"
4
}

POST Polygon Search

POST Polygon Search allows users to search for active assets in a large polygon with many coordinates. The underlying behavior is similar to the GET method. It is recommended to use the POST method in case of large or complex polygons with a big set of boundary coordinates which, otherwise, may cause the request to breach the URL limits of a GET endpoint. You can also use this method if you prefer to input polygon boundaries in GeoJSON format. Please note that the search polygon size is limited to a maximum area of 3000 km².

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location 'https://api.nextbillion.io/skynet/search/polygon?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

Sample Response

1
{
2
   "status": "Ok",
3
   "msg": "",
4
   "data": "{...}"
5
}

Monitor

The monitor service of Live Tracking API is a feature that enables users to define and manage monitoring zones or geofences for tracking assets in real-time. A geofence is a virtual boundary that can be defined around a specific area, such as a building, a parking lot, or a city block. When an asset enters or exits the geofence, the monitoring service generates an event that can be captured by the Live Tracking API. The monitoring service also allows tracking the asset activity while it is on move through the idle and speeding alerts.

The Monitor service can be used in a variety of industries such as logistics, transportation, and security, to track and monitor the movement of assets in real-time. For example, a logistics company may use the monitor service to track the movement of its delivery trucks and monitor their arrival and departure from different warehouses or distribution centers. A security company may use the monitor service to set up speeding and idle alerts to track the movements and flag any suspicious activity by the asset.

Let’s take a look at the methods and properties available for leveraging the Monitor service.

Create a Monitor

This method enables users to create monitors that track specific activities, providing valuable functionality for various purposes. It is particularly beneficial for managing vehicle fleets, tracking deliveries and monitoring equipment in restricted areas. By assigning attributes to monitors, users can conveniently monitor assets that share common attributes, facilitating collective monitoring of asset activities. For instance, attributes like "shift_1" or "area_Los Angeles" can be employed to group assets and monitor their activities efficiently. The method also allows users to specify the type of activity the monitor should detect, enabling focused monitoring of specific events. For example, a monitor can be configured to create an event when an asset enters a geofence, enabling accurate tracking of asset movements or track the speed of the asset while it is moving or just raise a flag when it is idle.

Request Parameter

Request Body

Response Schema

Example 1 - Create an enter & exit type Monitor

Let’s create a monitor for tracking the entry and exit of an asset into a geofence. In the create request we:

1. Set the type to enter_and_exit
2. Add the ID of the geofence that would be used to determine the monitored area.
3. Add the attributes matching the asset whose activity needs to be monitored.

Request

1
curl --location 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

Response

1
{
2
  "status": "Ok",
3
  "data": {
4
    "id": "9a504acb-1889-4c79-a221-cd2c330f2a5b"
5
  }
6
}

Example 2 - Create a speeding type Monitor

Next, we will create a monitor for tracking the entry and exit of an asset into a geofence. In the create request we:

1. Set the type to speeding
2. Add the desired configuration to the speeding_config attribute
3. Add the attributes matching the asset whose activity needs to be monitored.

Request

1
curl --location 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

Response

1
{
2
  "status": "Ok",
3
  "data": {
4
    "id": "77202940-f2ec-4841-a8b7-f962def95006"
5
  }
6
}

Example 3 - Create an idle type Monitor

Next, we will create a monitor for tracking the entry and exit of an asset into a geofence. In the create request we:

1. Set the type to idle
2. Add the desired configuration to the idle_config attribute
3. Add the attributes matching the asset whose activity needs to be monitored.

Request

1
curl --location 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

Response

1
{
2
"status": "Ok",
3
"data": {
4
"id": "a272012e-623a-4d74-b434-08801629dbb8"
5
}

Get a Monitor

This method retrieves the details and information of a specific monitor. By using this method, users can access the associated data of a monitor. This allows for easy retrieval of monitor-specific information for analysis, monitoring purposes or making any necessary adjustments to the monitor's settings.

Request Parameter

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/skynet/monitor/36c171d5-bdf1-47c2-9531-4c02820ab70e?key=<your_api_key>'

Sample Response

1
{
2
  "status": "Ok",
3
  "data": '{...}'
4
}

Update a Monitor

This method enables users to modify the settings and parameters of an existing monitor. By using this method, users can make changes to the monitor's type, attributes, description, geofence associations, configurations for speed or idle events, among other properties of the monitor. This flexibility allows for updates and adjustments to the monitoring configuration based on changing requirements or evolving business needs.

Request Parameter

Request Body

Response Schema

Sample Request

1
curl --location --request PUT 'https://api.nextbillion.io/skynet/monitor/3123a566-1c64-4ada-846c-d1e9f6bcc049?key=<your_api_key>' --header 'Content-Type: application/json' --data-raw '{...}'

Sample Response

1
{
2
  "status": "Ok"
3
}

Get Monitor List

This method retrieves a list of monitors available in the system along with pagination information. It provides users with an overview of all the monitors that have been created. The method allows for easy access to monitor details such as their names, types, descriptions, and associated attributes. This information can be valuable for monitoring configurations, analyzing monitoring patterns and managing the monitoring system effectively.

Request Parameter

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/skynet/monitor/list?key=<your_api_key>&pn=1&ps=4&sort=created_at:desc'

Sample Response

1
{
2
  "status": "Ok",
3
  "data": "{..}"
4
  

Delete a Monitor

This method allows users to delete an existing monitor from the system. It is useful when a monitor is no longer needed or if changes to monitoring requirements are necessary. By removing a monitor, users can effectively stop tracking specific activities associated with that monitor.

Request Parameter

Response Schema

Sample Request

1
curl --location --request DELETE 'https://api.nextbillion.io/skynet/monitor/675c983c-8147-4d5a-9c14-d754a8e57c0d?key=<your_api_key>'

Sample Response

1
{
2
  "status": "Ok"
3
}

Capturing Events

Live Tracking API’s Asset and Monitor methods allow users to create events when a desired activity is exhibited by an asset. The events created can be accessed in 2 ways. First is the Event History of an Asset, which would give the requested events upon receiving a request. Another method is by using webhooks.

Webhooks are used for event-driven communication between applications. Therefore, webhooks play a key role in implementing live tracking based alerts. Let’s dive into the webhook capabilities offered by NextBillion’s Live Tracking API.

How does the Live Tracking API use a webhook?

A webhook enables Live Tracking API to push event information in real-time to the user’s application. An HTTPS POST method is used to deliver the JSON payload to a configured webhook URL as soon as an event is created. Live Tracking API currently supports following events:

• enter - Entry of an asset into a given geofence.
• exit - Exit of an asset from a given geofence.
• speeding - Asset is moving at a speed more than the specified limit
• idle - Asset is not moving or idle.

The information related to these events can be used to execute multiple actions in user’s application systems as needed.

Steps to set-up a webhook

• Get a webhook URL from the application that needs to receive the event information.
• Configure the URL to receive events from Live Tracking API using the configurations method listed below.
• Use the Test Webhook Configuration method to verify that the webhook is able to receive events from the Live Tracking service.
• Start receiving information about the Live Tracking events through a HTTPS POST request on the webhook URL.

Live Tracking API’s configuration methods

Users can view and modify the webhooks configured for their account or key through the config methods available as part of NextBillion’s Live Tracking API.

Add or Update Webhook Configuration

Use this method to add new or modify the existing webhooks. The new or the modified webhooks can be passed using the request body as an array of strings. Multiple webhooks can be configured to receive the events. Please note that the webhooks will be configured to the key that is passed as a request parameter. They will be eligible to receive only those events, through a POST request, that are associated with the same key.

Request Parameter

Request Body

Response Schema

Sample Request

1
curl --location --request PUT 'https://api.nextbillion.io/skynet/config?key=<your_api_key>'
2
--header 'Content-Type: application/json'
3
--data-raw '{...}

Sample Request

1
{
2
  "status": "Ok"
3
}

Get Webhook Configuration

Please note that the webhooks returned are associated with the key that is used in the input request. The webhooks returned can receive the event information through a POST request.

Request Parameter

Response Schema

Sample Request

1
curl --location --request GET 'https://api.nextbillion.io/skynet/config?key=<your_api_key>'

Sample Response

1
{
2
  "status": "Ok",
3
  "data": {
4
    "config": {
5
      "webhook": ["https://my-company/api/testhook", "https://my-company/api/testhook1"]
6
    }
7
  }
8
}

Test Webhook Configuration

Use this method to test the webhooks configured. Once the webhooks are added the users can validate, if they are able to receive the events data, through the test service. The Live Tracking API will send a sample event to all the configured webhook URLs if they are validated successfully. Please note that API response will always be Ok and the actual event information will be sent to all the configured webhooks. Please verify the information received.

Request Parameter

Response Schema

Sample Request

1
curl --location --request POST 'https://api.nextbillion.io/skynet/config/testwebhook?key=<your_api_key>'

Sample Response

1
{
2
  "status": "Ok"
3
}

Sample Event schema

This section gives a walkthrough of the POST request schema that will be used to carry the event information. Let’s take a look at the properties:

Example Event

1
{
2
  "events": "[...]",
3
  "timestamp": "...",
4
  "extra": "{...}"
5
}

Leveraging event information

Once the event information is received on the webhook URL and the JSON payload is parsed into the end application, it can leveraged in multiple ways as per the business need - notifications can be triggered for certain sensitive events on any desired medium, or the event information can be stored in a database, or the information can be pushed to a dashboard for real-time decision making etc.

Trips

The trips feature of Live Tracking API provides increased flexibility to track specified periods or only the desired movements of an asset. When an asset is on the move users can start a trip by providing details like planned stops, name of the trip and any other custom details. Once the trip is ended, users can get tracking details along with distance, duration and geometries of the routes covered for analyzing the trip and deriving critical business insights.

Trips is a useful way to address business requirements related to service compliance, fleet tracking and safety. Let’s dive deeper into the methods available for this feature.

Start a Trip

Users can start new trips by sending a POST request with relevant details of the trip like name, any custom ID, the asset which is making this trip, the stops that the asset needs to make and other attributes. The service will respond with a trip ID which can be used to perform other trip operations using the available methods. A food delivery service, for example, can utilize this API method to start a new trip whenever any of its delivery vans/bikes are on the move to deliver orders. The data generated can be used to analyze and establish service compliance and other business rules.

Request Parameter

Request Body

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/skynet/trip/start?key=<your_api_key>' 
2
--header 'Content-Type: application/json' 
3
--data '{...}'

Sample Response

1
{
2
   "status": "Ok",
3
   "data": {
4
       "id": "Test_trip"
5
   }
6
}

Get a Trip

Retrieve the details of a trip using this method. Users need to make a GET request with the desired trip ID provided as a path parameter and the service will respond with all details about the trip like name, status of the trip, asset to which it is linked to and stops that were made or are to be made during the trip depending on its status.

Request Parameter

Response Schema

1
curl --location 'https://api.nextbillion.io/skynet/trip/Test_trip?key=<your_api_key>'

Sample Response

1
{
2
   "status": "Ok",
3
   "data": '{...}'
4
}

Update a Trip

Update the details of a trip using this method by providing the details to be updated in the request body. Users can update the details of a trip while it is active, but not once it has ended. However, please be cautious when using this method as the information updated using this method will overwrite any existing information for the fields that were updated. Service will respond with an acknowledgement once the trip is successfully updated.

Request Parameter

Request Body

Response Schema

Sample Request

1
curl --location --request PUT 'https://api.nextbillion.io/skynet/trip/Test_trip?key=<you_api_key>' --header 'Content-Type: application/json' --data {...}

Sample Response

1
{
2
   "status": "Ok"
3
}

End a Trip

Users can end a trip by using this method and just the ID of the trip that they want to end.

Request Parameter

Request Body

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/skynet/trip/end?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

Sample Response

1
{
2
   "status": "Ok"
3
}

Summary of a Trip

Once a trip has ended, users can retrieve the locations tracked, distance covered, stops made, route taken and a host of other relevant information by using this method. The summary can, however, only be generated for the trips that have ended. Also, the fields related to routes taken like tracked locations, distance, duration and geometry will only be returned if there are a minimum number of locations tracked so that a feasible movement trajectory can be generated.

Request Parameter

Response Schema

Sample Request

1
curl --location 'https://api.nextbillion.io/skynet/trip/Test_trip/summary?key=<your_api_key>'

Sample Request

1
{
2
   "status": "Ok",
3
   "data": '{...}'
4
  }

Delete a Trip

Users can delete an existing trip by providing its ID in the path parameter.

Request Parameter

Response Schema

Sample Request

1
curl --location --request DELETE 'https://api.nextbillion.io/skynet/trip/Test_trip?key=<your_api_key>'

Sample Response

1
{
2
   "status": "Ok"
3
}

Trip Subscription

Users can subscribe to active trips to get real-time updates as the trips progress. To subscribe, users need to connect to a web-socket server. Once the connection is established, users can send the required act ion message to the web-socket. The action message, in general, contains information about the type of action to perform along with the required details to implement the action.

Upon successfully subscribing to a trip, users would receive real-time updates on the web-socket connection as new locations are tracked by the asset, while it is moving.

Let’s dive deep to understand the complete lifecycle of a subscription.

Connect to Web Socket Server

To connect to the web socket users can send a request to the following server from their application

A few points regarding the connection and its characteristics

• A connection is valid for 5 minutes only.
• A ping frame is sent by the server to the client every 1 minute. Clients can choose to respond with a pong frame immediately or at any desired frequency higher than every 5 minutes.
• Alternatively, users can also send a heartbeat frame to the server to keep the connection alive at a frequency higher than every 5 minutes. See here for an example heartbeat message.

Action Message Body

Once the connection is established users can send the appropriate action message to make the web-socket perform the desired behavior. Below is the input schema to configure action messages.

Action Response Schema

Stream Data Schema

When a trip is subscribed, the response from the web-socket containing the details about the trip will follow the below schema:

Sample stream data message

1
{
2
   "status": "Ok",
3
   "data": '{...}'
4
  }

Send a Heartbeat message

In order to keep the connection with the web-socket server alive, users can choose to make use of a heartbeat action to do so. Following is an example of a heartbeat action message:

1
{
2
  "id": "test_Subscription_1",
3
	"action": "HEARTBEAT"
4
}

Unsubscribe from a trip

Users can also unsubscribe to a trip by sending the relevant action message over the web-socket connection. The action should be set to “TRIP_UNSUBSCRIBE” to achieve it. Following is a code snippet to unsubscribe from a sample trip ID.

1
{
2
  "id": "Test Unsubscribe",
3
  "action": "TRIP_UNSUBSCRIBE",
4
  "params": {
5
    "id": "00fd9815-c482-48f6-8649-ccc134a24c79"
6
  }
7
}

Namespaces

Namespaces help users to create multiple keys under one parent organization. This feature allows users to share the capabilities of Live Tracking API with multiple consumers (customers, teams, departments etc) while ensuring isolation of underlying data - a key belonging to a namespace can access the data belonging to that namespace only. However, using namespaces is not mandatory to access the capabilities of Live Tracking services. Once a request is successfully submitted, the service responds with a unique key for the namespace along with an expiration date for the key.

Request Parameter

Response Schema

Sample API Request

Let’s create a namespace called sample_namespace for a key represented by <your_api_key>.

1
curl --location --request POST 'https://namespaces.nextbillion.io/namespaced-apikeys?key=<your_api_key>&namespace=sample_namespace'

Sample API Response

1
{
2
   "kid": "af088b64d85e4c2896034d34383deb8b",
3
   "namespace": "sample_namespace",
4
   "created_at": "2023-11-21T04:29:15.868Z",
5
   "expire": "1716805800"
6
}

API Query Limits

• Limitation for the attributes object:
  • The maximum number of key:value pairs that can be added is 100.
  • The overall size of the object should not exceed 65kb.
• For smooth tracking experience, it is recommended to keep the location service of your GPS application to always ON for a constant stream of location data.
• This page number parameter pn does not have a maximum limit per se, but would return an empty result set in case a higher value is provided when the result-set itself is smaller.
• The maximum value for page size ps parameter is 100, except in case of Track locations of an Asset method where it is 500.
• Only the updated_at or created_at fields can be used for sorting the results using the sort parameter.
• Search methods will only return active assets in the results. An asset is considered active if it has been tracked at least once in the last 7 days.
• In Around Search method, the maximum radius of the search area can not be more than 5000 meters.
• In Polygon Search and Bound Search methods, the maximum area of the “polygon” and “bound box”, respectively, can not be more than 3000 km².
• The maximum number of assets that can be created for a namespace is 10000, if namespaces are being used. If not, then the same limit applies to an organization as well.
• The maximum number of monitors that can be created for a namespace is 200, if namespaces are being used. If not, then the same limit applies to an organization as well.
• NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests.
  Note: We can increase the quota if needed, on request. Contact [email protected] for more details.

API Error Codes