Dispositivi

Un “device” è un dispositivo o veicolo tracciato, nello scope del proprietario della chiave: una chiave vede solo i dispositivi a cui il suo owner ha accesso.

Modello

Campo	Tipo	Note
id	string	coincide con imei
imei	string
name	string | null
plate	string | null	targa
device_model	string | null	modello hardware
odometer_km	number | null
status	enum	moving | parked | offline | unknown
groups	string[]	gruppi di appartenenza
location	object | null	null se nessuna posizione nota
location.latitude / location.longitude	number
location.speed_kmh	number
location.recorded_at	string (ISO 8601) | null
updated_at	string (ISO 8601) | null

GET /api/v2/devices

Elenco dei dispositivi a cui la chiave ha accesso. Permesso: read_devices.

Parametro	Default	Range	Note
limit	50	1–200	clampato ai bordi, mai rifiutato
offset	0	≥ 0

cURL

curl https://api.aitrack.it/api/v2/devices?limit=10 \
  -H "X-API-Key: $AITRACK_API_KEY"

Node.js

const res = await fetch('https://api.aitrack.it/api/v2/devices?limit=10', {
  headers: { 'X-API-Key': process.env.AITRACK_API_KEY },
});
const { data, meta } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v2/devices",
    headers={"X-API-Key": api_key},
    params={"limit": 10},
    timeout=10,
)
data = res.json()["data"]

{
  "data": [
    {
      "id": "352093081452312",
      "imei": "352093081452312",
      "name": "Furgone 1",
      "plate": "AB123CD",
      "device_model": "FMB920",
      "odometer_km": 84213,
      "status": "moving",
      "groups": ["Consegne"],
      "location": {
        "latitude": 45.4642,
        "longitude": 9.19,
        "speed_kmh": 52,
        "recorded_at": "2026-07-14T09:00:00.000Z"
      },
      "updated_at": "2026-07-14T09:00:03.000Z"
    }
  ],
  "meta": { "pagination": { "limit": 10, "offset": 0, "count": 1 } }
}

GET /api/v2/devices/nearest

Il dispositivo più vicino a una coordinata, e quanto dista. Permesso: read_locations.

Parametro	Obbligatorio	Valore
lat	sì	latitudine, da -90 a 90
lng	sì	longitudine, da -180 a 180
limit	no	quanti restituirne, 1–50. Predefinito 1
max_km	no	scarta chi è oltre questo raggio (km)

Distanza in linea d'aria

distance_km è la distanza in linea d’aria (haversine), non su strada: il dispositivo più vicino in linea d’aria può essere il più lontano da guidare (un fiume in mezzo, un’uscita autostradale dalla parte sbagliata). Se ti serve il tempo di percorrenza reale, questo numero è un punto di partenza, non una risposta. I dispositivi senza una posizione nota non compaiono: non sono “lontani”, sono ignoti.

cURL

curl -H "X-API-Key: $AITRACK_API_KEY" \
  "https://api.aitrack.it/api/v2/devices/nearest?lat=45.4642&lng=9.19&limit=3"

Node.js

const url = new URL('https://api.aitrack.it/api/v2/devices/nearest');
url.searchParams.set('lat', '45.4642');
url.searchParams.set('lng', '9.19');
url.searchParams.set('limit', '3');

const res = await fetch(url, { headers: { 'X-API-Key': process.env.AITRACK_API_KEY } });
const { data, meta } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v2/devices/nearest",
    headers={"X-API-Key": api_key},
    params={"lat": 45.4642, "lng": 9.19, "limit": 3},
    timeout=10,
)
nearest = res.json()["data"]

{
  "data": [
    {
      "id": "359000000000001",
      "imei": "359000000000001",
      "name": "Furgone 1",
      "plate": "AB123CD",
      "status": "moving",
      "location": {
        "latitude": 45.4642,
        "longitude": 9.19,
        "speed_kmh": 52,
        "recorded_at": "2026-07-14T09:00:00.000Z"
      },
      "distance_km": 0.412
    }
  ],
  "meta": {
    "query": { "lat": 45.4642, "lng": 9.19, "limit": 3, "max_km": null },
    "distance": "straight_line_km"
  }
}

Coordinate mancanti → 400 COORDINATES_REQUIRED. Coordinate fuori dai limiti o non numeriche → 400 INVALID_COORDINATES. Nessun dispositivo con posizione nota (o nessuno entro max_km) → data è una lista vuota, non un errore.

GET /api/v2/devices/{imei}

Un dispositivo. Permesso: read_devices. IMEI inesistente — o non tuo — → 404 DEVICE_NOT_FOUND (le due situazioni non si distinguono, per non rivelare l’esistenza di un IMEI fuori dal tuo scope).

cURL

curl https://api.aitrack.it/api/v2/devices/352093081452312 \
  -H "X-API-Key: $AITRACK_API_KEY"

Node.js

const res = await fetch('https://api.aitrack.it/api/v2/devices/352093081452312', {
  headers: { 'X-API-Key': process.env.AITRACK_API_KEY },
});
const { data } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v2/devices/352093081452312",
    headers={"X-API-Key": api_key},
    timeout=10,
)
device = res.json()["data"]

GET /api/v2/devices/{imei}/location

Ultima posizione nota. Permesso: read_locations. 404 LOCATION_NOT_FOUND se il dispositivo non ha ancora inviato nulla.

cURL

curl https://api.aitrack.it/api/v2/devices/352093081452312/location \
  -H "X-API-Key: $AITRACK_API_KEY"

Node.js

const res = await fetch(
  'https://api.aitrack.it/api/v2/devices/352093081452312/location',
  { headers: { 'X-API-Key': process.env.AITRACK_API_KEY } },
);
const { data } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v2/devices/352093081452312/location",
    headers={"X-API-Key": api_key},
    timeout=10,
)
location = res.json()["data"]

{
  "data": {
    "latitude": 45.4642,
    "longitude": 9.19,
    "altitude_m": 122,
    "speed_kmh": 52,
    "recorded_at": "2026-07-14T09:00:00.000Z"
  }
}

GET /api/v2/devices/{imei}/history

Storico delle posizioni. Permesso: read_history.

Parametro	Default	Range	Note
from	—	ISO 8601	inizio finestra
to	—	ISO 8601	fine finestra
limit	500	1–1000	clampato

La finestra effettivamente leggibile dipende dal piano: il server taglia le richieste che vanno più indietro di quanto il piano conservi.

cURL

curl -H "X-API-Key: $AITRACK_API_KEY" \
  "https://api.aitrack.it/api/v2/devices/352093081452312/history?from=2026-07-14T00:00:00Z&to=2026-07-14T23:59:59Z&limit=500"

Node.js

const url = new URL('https://api.aitrack.it/api/v2/devices/352093081452312/history');
url.searchParams.set('from', '2026-07-14T00:00:00Z');
url.searchParams.set('to', '2026-07-14T23:59:59Z');
url.searchParams.set('limit', '500');

const res = await fetch(url, { headers: { 'X-API-Key': process.env.AITRACK_API_KEY } });
const { data, meta } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v2/devices/352093081452312/history",
    headers={"X-API-Key": api_key},
    params={
        "from": "2026-07-14T00:00:00Z",
        "to": "2026-07-14T23:59:59Z",
        "limit": 500,
    },
    timeout=10,
)
points = res.json()["data"]

{
  "data": [
    {
      "latitude": 45.4642,
      "longitude": 9.19,
      "speed_kmh": 52,
      "heading": 91,
      "satellites": 11,
      "recorded_at": "2026-07-14T09:00:00.000Z"
    }
  ],
  "meta": { "pagination": { "limit": 500, "offset": 0, "count": 1 } }
}

GET /api/v2/devices/{imei}/commands

Coda dei comandi, in sola lettura. Permesso: send_commands.

Parametro	Default	Valori	Note
status	pending,sent	csv di pending | sent | canceled	filtro stato
limit	50	1–100	clampato

Note

L’invio comandi (blocco/sblocco motore, ecc.) non è esposto in API v2: qui si legge solo lo stato della coda. type è semantico (engine_lock / engine_unlock / other): la stringa di protocollo hardware interna non è esposta.

cURL

curl -H "X-API-Key: $AITRACK_API_KEY" \
  "https://api.aitrack.it/api/v2/devices/352093081452312/commands?status=pending,sent&limit=50"

Node.js

const url = new URL('https://api.aitrack.it/api/v2/devices/352093081452312/commands');
url.searchParams.set('status', 'pending,sent');

const res = await fetch(url, { headers: { 'X-API-Key': process.env.AITRACK_API_KEY } });
const { data } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v2/devices/352093081452312/commands",
    headers={"X-API-Key": api_key},
    params={"status": "pending,sent"},
    timeout=10,
)
commands = res.json()["data"]

{
  "data": [
    { "id": 91, "type": "engine_lock", "status": "pending", "queued_at": "2026-07-14T09:00:00.000Z", "sent_at": null }
  ],
  "meta": { "pagination": { "limit": 50, "offset": 0, "count": 1 } }
}

Vedi anche Errori e limiti per il significato completo dei codici HTTP e degli error.code.