Unit management
A 'Unit' is a fundamental entity created within a client's account to which the tracker is connected. Consequently, all messages transmitted by the tracker to a specific IP and port are directly associated with the unit.
The IP and port can be obtained using GET /partner/units/{id}/channel method.
When creating unit, it is essential to specify a unique ID along with an appropriate hardware ID.
In our applications, the hardware ID represents the type of device selected during unit creation. This allows the tracker to connect to the platform seamlessly. The list of all devices with their hardware IDs can be retrieved using the GET /client/hardware/devices method.
Create unit
This endpoint is used to create a unit and attach it to the account.
POST /partner/units
The mandatory field for this request:
- name: (string) name of the unit.
- ident: (string) identifier of the unit. Must be unique. It is typically the IMEI or ID of the tracker.
- hw_id: (number) hardware ID of the unit. This value can be obtained using the GET/client/hardware/devices method.
- app_id: (string) application ID:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
- account_id: (number) account ID to which the unit belongs.
Request example:
curl -X 'POST' \
'https://api.gps-trace.com/partner/units' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>' \
-H 'Content-Type: application/json' \
-d '{
"description": "Unit description",
"name": "Unit_name",
"ident": "string",
"hw_id": 40372386,
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
"account_id": <account id>
}'
201 Response example:
{
"data": {
"name": "Unit_name",
"device_type_id": 725,
"cid": number,
"protocol_id": 13,
"channel_id": number,
"id": number,
"hw_id": number,
"tls": false,
"last_active": null,
"messages_ttl": number,
"messages_rotate": number,
"description": "123Unit description",
"extra_data": [],
"tokens": {},
"created_at": number,
"updated_at": number,
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
"b_type": null,
"completed": null,
"ready": null,
"account_id": number,
"ident": "string"
}
}
- id: (string) unit ID
- cid: (string) account ID to which the unit belongs
- device_type_id: (string) unit device type ID
- channel_id: (string) unit channel ID
- hw_id: (string) unit hardware ID
- account_id: (number) related account ID
- name: (string) unit name
- description: (string) unit description (maximum length 100)
- tls: (boolean) indicates the use of encrypted Flespi protocol
- last_active: (object) description of when a new data piece is received from the connected device
- messages_ttl: (number) duration for storing messages
- messages_rotate: (number) number of messages to store
- extra_data: (array of strings) data for displaying additional fields
- tokens: (object) tokens for locator and toolbox
- created_at: (number) unit creation date
- updated_at: (number) unit update date
- app_id: (string) application ID:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
- b_type: (object) description of the unit billing type
- completed: (object) indicates if the unit is configured with errors (e.g., in calcs link or plugins)
- ready: (object) indicates if the unit is ready to work (True for ready, False if not all settings were done)
- ident: (string) Unique unit identifier. It is typically the IMEI or ID of the tracker.
Get the list of units
This endpoint lets you get the list of units.
GET /partner/units
200 Response example:
{
"data": [
{
"name": "test_unit",
"device_type_id": 725,
"cid": number,
"channel_id": number,
"id": number,
"hw_id": 40372386,
"tls": false,
"last_active": null,
"messages_ttl": number,
"messages_rotate": number,
"description": "Test_description",
"extra_data": null,
"tokens": null,
"created_at": number,
"updated_at": number,
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
"b_type": null,
"completed": null,
"ready": null,
"account_id": number,
"ident": "string"
},
- id: Unique identifier for the unit.
- cid: Account ID to which the unit belongs
- device_type_id: ID representing the device type of the unit.
- protocol_id: ID representing the protocol used by the unit.
- channel_id: ID representing the communication channel used by the unit.
- hw_id: Hardware ID of the unit.
- account_id: ID of the related account.
- name: Name of the unit.
- description: Description of the unit (maximum length 100 characters).
- tls: Boolean indicating whether the unit uses encrypted flespi protocol.
- last_active: Timestamp indicating when new data was last received from the connected device (nullable).
- messages_ttl: Time-to-live for messages (how long to store messages).
- messages_rotate: Number of messages to store.
- extra_data: Additional data for displaying additional fields. It's an array of objects with the following properties:
- value: Value of the additional field.
- icon: Icon for the additional field.
- label: Label for the additional field.
- showOnCard: An array of values indicating where to show the additional field.
- tokens: Description of tokens for locator and toolbox (nullable).
- created_at: Timestamp indicating when the unit was created.
- updated_at: Timestamp indicating when the unit was last updated.
- app_id: ID of the application to which the unit belongs. It can have one of the following enumerated values:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
- b_type: Billing type of the unit (nullable).
- completed: Indicates whether the unit is configured with errors. Possible values are "true" or "false" (nullable).
- ready: Indicates the readiness status of the unit. Possible values are "true" or "false" (nullable).
- ident: Unique identifier of the unit. It is typically the IMEI or ID of the tracker.
Get unit information by ID
This endpoint lets you get unit information by ID.
GET /partner/units/{id}
The mandatory fields for this request are as follows:
- id - unit ID
200 Response example:
{
"data": {
"name": "My Queclink GV75",
"device_type_id": 147,
"cid": number,
"channel_id": number,
"id": number,
"hw_id": 862684660,
"tls": false,
"last_active": null,
"messages_ttl": number,
"messages_rotate": number,
"description": "",
"extra_data": [
{
"label": "My SIM",
"showOnCard": true,
"value": "88888888888",
"icon": "t-icon-telephone"
}
],
"tokens": null,
"created_at": number,
"updated_at": number,
"app_id": "b901da51-ce00-4af2-b978-8d0fca8ae1ea",
"b_type": null,
"account_id": number,
"ident": "string"
}
}
- id: Unique identifier for the unit.
- cid: Account ID to which the unit belongs
- device_type_id: ID representing the device type of the unit.
- protocol_id: ID representing the protocol used by the unit.
- channel_id: ID representing the communication channel used by the unit.
- hw_id: Hardware ID of the unit.
- account_id: ID of the related account.
- name: Name of the unit.
- description: Description of the unit (maximum length 100 characters).
- tls: Boolean indicating whether the unit uses encrypted flespi protocol.
- last_active: Timestamp indicating when new data was last received from the connected device (nullable).
- messages_ttl: Time-to-live for messages (how long to store messages).
- messages_rotate: Number of messages to store.
- extra_data: Additional data for displaying additional fields. It's an array of objects with the following properties:
- value: Value of the additional field.
- icon: Icon for the additional field.
- label: Label for the additional field.
- showOnCard: An array of values indicating where to show the additional field.
- tokens: Description of tokens for locator and toolbox (nullable).
- created_at: Timestamp indicating when the unit was created.
- updated_at: Timestamp indicating when the unit was last updated.
- app_id: ID of the application to which the unit belongs. It can have one of the following enumerated values:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
- b_type: Billing type of the unit (nullable).
- completed: Indicates whether the unit is configured with errors. Possible values are "true" or "false" (nullable).
- ready: Indicates the readiness status of the unit. Possible values are "true" or "false" (nullable).
- ident: Identifier of the unit. It is typically the IMEI or ID of the tracker.
Update unit by ID
This endpoint is used to update unit by ID.
PATCH /partner/units/{id}
The mandatory fields for this request are as follows:
- id - unit ID
It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners cannot update activated Ruhavik/Petovik units.
On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.
When using this method, you can modify the following fields:
- description: this field represents the description of the unit.
- name: name of the unit.
- ident: unique identifier for the unit. It is typically the IMEI or ID of the tracker.
- hw_id: this field represents the Hardware ID of the unit. This value can be obtained using the GET/client/hardware/devices method.
- password: some types of devices require a password for connection. This is particularly relevant for devices that require authentication during the connection process.
Request example:
curl -X 'PATCH' \
'https://api.gps-trace.com/partner/units/<unit id>' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>' \
-H 'Content-Type: application/json' \
-d '{
"description": "new_description",
"name": "new_unit_name",
"ident": "string",
"hw_id": 19671936
}'
200 Response example:
{
"data": {
"name": "new_unit_name",
"device_type_id": 122,
"cid": number,
"channel_id": number,
"id": number,
"hw_id": 19671936,
"tls": false,
"last_active": null,
"messages_ttl": number,
"messages_rotate": number,
"description": "new_description",
"extra_data": null,
"tokens": null,
"created_at": number,
"updated_at": number,
"app_id": "5a5ca87f-7cbe-4540-ab5d-77bf4bf69884",
"b_type": null,
"completed": null,
"ready": null,
"account_id": number,
"ident": "string"
}
}
- id: (string) unit ID
- cid: (string) account ID to which the unit belongs
- device_type_id: (string) unit device type ID
- channel_id: (string) unit channel ID
- hw_id: (string) unit hardware ID
- account_id: (number) related account ID
- name: (string) unit name
- description: (string) unit description (maximum length 100)
- tls: (boolean) indicates the use of encrypted Flespi protocol
- last_active: (object) description of when a new data piece is received from the connected device
- messages_ttl: (number) duration for storing messages
- messages_rotate: (number) number of messages to store
- extra_data: (array of strings) data for displaying additional fields
- tokens: (object) tokens for locator and toolbox
- created_at: (number) unit creation date
- updated_at: (number) unit update date
- app_id: (string) application ID:
- 5a5ca87f-7cbe-4540-ab5d-77bf4bf69884 - Ruhavik,
- 962e19f0-6b4a-4f81-a3fe-4b657689b6f9 - Petovik,
- b901da51-ce00-4af2-b978-8d0fca8ae1ea - Forguard
- b_type: (object) description of the unit billing type
- completed: (object) indicates if the unit is configured with errors (e.g., in calcs link or plugins)
- ready: (object) indicates if the unit is ready to work (True for ready, False if not all settings were done)
- ident: (string) unit identifier. It is typically the IMEI or ID of the tracker.
Delete unit by ID
This endpoint allows to remove unit by ID.
It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners cannot update activated Ruhavik/Petovik units.
On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.
DELETE /partner/units/{id}
- id: - unit ID
Request example:
curl -X 'DELETE' \
'https://api.gps-trace.com/partner/units/<unit id>' \
-H 'accept: */*' \
-H 'X-AccessToken: <your token>'
Upon successful deletion, a response with status code 200 will be returned.
Get units count
This method allows you to retrieve the count of units based on the filtering conditions specified in the request (e.g., all units, units with access to a specific application, active units or no, units of attached or unattached accounts)
GET/partner/units/count
Request body example:
curl -X 'GET' \
'https://api.gps-trace.com/partner/units/count?ack_active=true&app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
In the provided example request, units from activated accounts (ack_active=true) in the Forguard application (app_id=b901da51-ce00-4af2-b978-8d0fca8ae1ea) are counted.
The response includes the total count of units according to the specified filter conditions.
200 Response example:
{
"data": {
"all": 4,
"active": 3
}
}
- all: total count of units according to the specified filter conditions
- active: the number of active units, which are those that have been connected to the platform.
Get unit messages
This method allows you to retrieve messages from a device (unit).
GET /partner/units/{id}/messages
- id - unit ID
The maximum number of messages that can be retrieved is 10,000. You can also specify the number of recent messages you want to obtain.
It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners cannot get messages from units on activated Ruhavik/Petovik accounts.
On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.
Request example (get the last 10 messages)
curl -X 'GET' \
'https://api.gps-trace.com/partner/units/<unit id>/messages?count=10' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
Example of success response:
{
"data": [
{
"ain.12": 14765,
"ain.2": 55.5867,
"channel.id": 10664,
"custom.0g": 16,
"custom.battery.level": 100,
"custom.gsm_lvl": 96,
"custom.in1": 1,
"custom.in5": 1,
"custom.in6": 1,
"custom.in7": 1,
"custom.in8": 1,
"custom.odo": 535.546997,
"custom.ta": 10,
"custom.wln_brk_max": 0.05,
"device.id": 5459437,
"device.name": "HG-3365",
"device.type.id": 14,
"engine.ignition.status": true,
"gsm.lac": 18508,
"gsm.mcc": 262,
"gsm.mnc": 1,
"ident": "string",
"peer": "string",
"position.altitude": 46,
"position.direction": 320,
"position.hdop": 1,
"position.latitude": number,
"position.longitude": number,
"position.satellites": 15,
"position.speed": 76,
"protocol.id": 15,
"server.timestamp": number,
"timestamp": number
},...
]
}
The fields in the response will depend on the parameters sent by the tracker.
Get telemetry data
This endpoint lets you get latest unit telemetry data.
It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners can get information of unit messages on activated Ruhavik/Petovik accounts only if the client has enabled Service mode.
On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.
GET /partner/units/{id}/telemetry
- id - unit ID
Request example:
curl -X 'GET' \
'https://api.gps-trace.com/partner/units/<unit id>/telemetry' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
200 Response example:
{
"data": {
"channel.id": {
"ts": 1713977017.812001,
"value": number
},
"device.id": {
"ts": 1713977017.812001,
"value": number
},
"device.name": {
"ts": 1713977017.812001,
"value": "string"
},
"device.type.id": {
"ts": 1713977017.812001,
"value": number
},
"ident": {
"ts": 1713977017.812001,
"value": "string"
},
"position.altitude": {
"ts": 1713977016,
"value": number
},
"position.direction": {
"ts": 1713977016,
"value": number
},
"position.latitude": {
"ts": 1713977016,
"value": number
},
"position.longitude": {
"ts": 1713977016,
"value": number
},
"position.satellites": {
"ts": 1713977016,
"value": number
},
"position.speed": {
"ts": 1713977016,
"value": number
},
"protocol.id": {
"ts": 1713977017.812001,
"value": number
} ...
}
}
- ts: timestamp. The 'ts' element is included by default in every object within the 'data' object
The fields in the response will depend on the parameters sent by the tracker.
Get unit channel data
This endpoint lets you get unit communication channel data.
It is important to note that Ruhavik/Petovik accounts, once activated by the client, become fully owned by the client. Therefore, partners get information of unit channel data on activated Ruhavik/Petovik accounts only if the client has enabled Service mode.
On the other hand, Forguard accounts are fully managed by the partner and do not have any restrictions on actions from the partner's side.
GET /partner/units/{id}/channel
- id - unit ID
Request example:
curl -X 'GET' \
'https://api.gps-trace.com/partner/units/<unit id>/channel' \
-H 'accept: application/json' \
-H 'X-AccessToken: <your token>'
200 Response example:
{
"data": {
"id": string,
"configuration": null,
"host": "string",
"port": "string",
"ip": "string",
"shortLink": null
}
}
- id: ID of the channel.
- configuration: Channel configuration.
- host: Channel host.
- port: Channel port.
- ip: Channel IP address.
- shortLink: Channel short link.