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.
Base URL
Section titled “Base URL”https://api.gpsitalia.com/api/v2Your first request
Section titled “Your first request”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.
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.
What’s in this section
Section titled “What’s in this section”- 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.
Before you integrate
Section titled “Before you integrate”- 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.