Skip to content

API & integrations

The GPS Italia public API exposes read access to your fleet — devices, positions, history, events — so you can connect it to your back office, CRM or internal dashboard. For real-time events without polling, use webhooks.

This page covers v2, stable. There’s also an API v3, in beta, which adds area/geofence management (read and write) alongside v2 — see From v2 to v3 for what changes.

https://api.gpsitalia.com/api/v2

Every call carries the key in the X-API-Key header. Create a key from the app, under Settings → API Keys, and it is shown in clear text only once, at creation time.

Finestra del terminale
curl https://api.gpsitalia.com/api/v2/devices \
-H "X-API-Key: $GPSITALIA_API_KEY"

If the key is valid but missing the required permission, or the path doesn’t accept API keys (v1 routes used by the app), the request is rejected: see Authentication and Errors.

  • Authentication — header, permissions (scopes), IP restriction, rate limits, a key’s lifecycle.
  • Devices — list, detail, location, history, command queue, nearest device.
  • Events — fleet events (geofence, alerts, movement…) read via polling.
  • Errors & limits — response shape, error codes, pagination, rate limiting.
  • Versioning — v1/v2/v3 differences, deprecation, compatibility.
  • API v3 (beta) — read and write areas/geofences, alongside v2.
  • Webhooks — receive events via POST instead of polling the API, with a verifiable HMAC signature.

The canonical reference at the bottom of the menu carries the full text of the source documents this section is derived from, for anyone who wants the complete detail or to cite a stable version.

  • API keys stay on your server, never in the code of a public website or in a repository.
  • One key per integration: revoking one doesn’t break the others.
  • Restrict access by IP when you can (up to 50 entries, IPv4/CIDR or exact IPv6).
  • The v2 API is read-only for commands: sending commands (engine cut, etc.) stays inside the app by security design.