Working with API requests

API (Application Programming Interface) is a set of rules and tools for software to interact with each other. In PILOT, the API is used to exchange data between systems, services, applications, and the platform.
An API request consists of:
  • URL — the address of the API server and the command
  • Request parameters — the data sent to the server
  • Request method — the way the server is accessed
     

How API works in PILOT

PILOT uses a distributed infrastructure that includes multiple servers, for example, BLADE, KSA, AFRICA, USA. Each server can have several nodes, each with its own number.
When you send an API request to the system, specify the server (for example, BLADE) and the specific node within that server — the node. This ensures the request is processed directly on the selected server and node, minimizing extra routing and response time.
Example request:
https://blade.pilot-gps.com/api/api.php?cmd=list&node=14 
blade.pilot-gps.com — server name
node=14 — specifies the node on the server where the request should be processed
For more details on how to authorize and send requests to the PILOT server, see the next article.
 

API request methods

GET

Used to retrieve data, for example, requesting a list of objects or account information.
In a GET request, the command and parameters are passed directly in the URL. Parameters are added after the ? and separated by &.
Example
https://<server_address>/api/api.php?cmd=bindControl&uid=123&imei=456&lineuid=789
cmd=bindControl — command
uid=123, imei=456, lineuid=789 — parameters

POST

Used to send data, for example, creating a new object or generating a report.
In a POST request, the command and parameters can be sent in the request body, or the command can be specified in the URL while parameters are in the body.
Example 1
URL: https://<server_address>/api/api.php?cmd=bindControl
Request body
 {
    "uid": "123",
    "imei": "456",
    "lineuid": "789"
  }
Example 2
URL: https://<server_address>/api/api.php
Request body
{
    "cmd": "bindControl",
    "uid": "123",
    "imei": "456",
    "lineuid": "789"
  }

PUT

Used to update data, for example, changing parameters of an object or account.
PUT is typically used to update a specific resource, so the identifier is usually included in the URL, and the updated data in the body.
Example
URL: https://<server_address>/api/api.php/123
Request body
{
  "cmd": "updateControl",
  "uid": "123",
  "imei": "456",
  "lineuid": "789",
  "status": "active"
}

DELETE

Used to delete data, for example, to remove an object or account.
In a DELETE request, the command and parameters are usually passed in the URL.
Example
https://<server_address>/api/api.php?cmd=bindControl&uid=123&imei=456&lineuid=789
 

Data formats

The API supports different formats for both requests and responses.
JSON:
{
  "cmd": "bindControl",
  "uid": "123",
  "imei": "456",
  "lineuid": "789"
}
Form-encoded:
cmd=bindControl&uid=123&imei=456&lineuid=789
XML:
<request>
  <cmd>bindControl</cmd>
  <uid>123</uid>
  <imei>456</imei>
  <lineuid>789</lineuid>
</request>
 

Data types

The API uses different data types to transfer information between the client and the server. Here are the main types you may encounter in API requests and responses.
  Data type
  Description
  Example in JSON
  Purpose
  String
  Text in quotes
 "name": "Route #9"
  For textual data: names, descriptions, identifiers
  Number
  Numeric value, integer or decimal
  "price": 15.35
For numeric data: prices, identifiers, coordinates, time
  Array
  Ordered list of elements of any type
"points": [{"lat": "53.352142", "lon": "83.758749"},  {"lat": "52.534012", "lon": "85.178777"}]
  For lists of data: stops, items, users
  Object
  Set of key-value pairs
  "uid": "1", "lat": "53.352142", "lon":"83.758749"}
  For structured data: stop info, user info,
  order info
  Boolean
Logical value true/false or 1/0
  "bidirectional": 1
  For flags or states: active/inactive, available/unavailable