Back to Settings

GPSafe API

REST API for real-time GPS fleet tracking, geofence management, and travel monitoring.

v1.0 Last updated: March 11, 2026

Table of Contents

Authentication

All requests require a valid API key. You can generate and manage keys from Settings → API.

Include the key in the Authorization header with the Bearer prefix:

Authorization: Bearer gps_your_api_key_here

Alternatively, you may use the X-Api-Key header:

X-Api-Key: gps_your_api_key_here
Each API key is bound to a specific user account. You will only be able to access the devices and geofences that the associated user has permission to view.

Base URL

https://platform.gpsafe.io/api/v1

All endpoint paths documented below are relative to this base URL.

Error Handling

The API uses conventional HTTP status codes to indicate the outcome of each request.

CodeMeaning
200Success — response data is available in the data field
400Bad Request — invalid parameters or business rule violation
401Unauthorized — API key is missing, invalid, or expired
404Not Found — the requested resource does not exist
429Too Many Requests — rate limit exceeded (50 requests / 10 seconds)
500Internal Server Error — unexpected server-side failure

All responses share this envelope structure:

{
  "success": true | false,
  "data": { ... } | [ ... ] | null,
  "error": null | "Error description",
  "timestamp": "2026-03-10T15:30:00Z"
}

GET /api/v1/devices/status

Returns the latest status of all devices accessible by the authenticated API key, including location, speed, engine state, and connectivity information.

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer {api_key}

Query Parameters

None.

cURL Example

curl -H "Authorization: Bearer gps_your_key" \
     https://platform.gpsafe.io/api/v1/devices/status

Response 200 OK

{
  "success": true,
  "data": [
    {
      "deviceId": "350612345678901",
      "name": "TOYOTA HILUX",
      "plates": "ABC1234",
      "status": "Moving",
      "engineStatus": "On",
      "latitude": 19.432608,
      "longitude": -99.133209,
      "address": "Av. Reforma 222, CDMX",
      "speedKmh": 45,
      "heading": 270,
      "odometerKm": 128450.3,
      "satellites": 12,
      "powerVoltage": "13.8",
      "backupVoltage": "4.1",
      "signalStrength": 28,
      "connectionType": "4G",
      "lastReportUtc": "2026-03-10T15:28:44Z",
      "minutesSinceReport": 2
    }
  ],
  "timestamp": "2026-03-10T15:30:00Z"
}

Response Fields

FieldTypeDescription
deviceIdstringDevice IMEI (unique identifier)
namestringVehicle name
platesstringLicense plate number
statusstringMoving · Stopped · Inactive · Off
engineStatusstringOn · Off (ignition state)
latitudedecimal?GPS latitude
longitudedecimal?GPS longitude
addressstring?Reverse-geocoded address
speedKmhint?Current speed in km/h
headingint?Bearing in degrees (0–360)
odometerKmdouble?Odometer reading in kilometers
satellitesint?Number of GPS satellites in view
powerVoltagestring?Vehicle power supply voltage
backupVoltagestring?Backup battery voltage
signalStrengthint?GSM signal strength (0–31)
connectionTypestring?Network type (2G, 3G, 4G)
lastReportUtcdatetime?Timestamp of the last report (UTC)
minutesSinceReportint?Minutes elapsed since the last report

Try It

GET /api/v1/devices/{deviceId}/status

Returns the latest status of a single device, identified by its IMEI (deviceId). The response fields are the same as the list endpoint above.

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer {api_key}

Path Parameters

ParameterTypeRequiredDescription
deviceIdstringYesDevice IMEI

cURL Example

curl -H "Authorization: Bearer gps_your_key" \
     https://platform.gpsafe.io/api/v1/devices/350612345678901/status

Response 200 OK

{
  "success": true,
  "data": {
    "deviceId": "350612345678901",
    "name": "TOYOTA HILUX",
    "plates": "ABC1234",
    "status": "Moving",
    "engineStatus": "On",
    "latitude": 19.432608,
    "longitude": -99.133209,
    "address": "Av. Reforma 222, CDMX",
    "speedKmh": 45,
    "heading": 270,
    "odometerKm": 128450.3,
    "satellites": 12,
    "powerVoltage": "13.8",
    "backupVoltage": "4.1",
    "signalStrength": 28,
    "connectionType": "4G",
    "lastReportUtc": "2026-03-10T15:28:44Z",
    "minutesSinceReport": 2
  },
  "timestamp": "2026-03-10T15:30:00Z"
}

Error 404 — Device Not Found

{
  "success": false,
  "error": "Device not found or no access",
  "timestamp": "2026-03-10T15:30:00Z"
}

Try It

GET /api/v1/geofences

Returns all geofences belonging to the account, sorted alphabetically. Each geofence includes its center coordinates and the full list of polygon vertices.

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer {api_key}

Query Parameters

None.

cURL Example

curl -H "Authorization: Bearer gps_your_key" \
     https://platform.gpsafe.io/api/v1/geofences

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": 42,
      "name": "Central Warehouse",
      "centerLat": 19.432608,
      "centerLng": -99.133209,
      "radiusMeters": 250.0,
      "vertexCount": 4,
      "vertices": [
        { "lat": 19.433, "lng": -99.134 },
        { "lat": 19.433, "lng": -99.132 },
        { "lat": 19.432, "lng": -99.132 },
        { "lat": 19.432, "lng": -99.134 }
      ]
    }
  ],
  "timestamp": "2026-03-10T15:30:00Z"
}

Response Fields

FieldTypeDescription
idintGeofence ID
namestringGeofence name
centerLatdoubleCenter latitude
centerLngdoubleCenter longitude
radiusMetersdoubleApproximate radius in meters
vertexCountintNumber of polygon vertices
verticesarrayOrdered list of {lat, lng} polygon points

Try It

POST /api/v1/travels

Creates a new travel route for a vehicle. The starting point is always the vehicle's current GPS position at the specified startTime. Geofence names must match exactly (case-sensitive) with existing geofences in your account.

All date/time values are sent in the local timezone of the user associated with the API key. The system automatically converts to UTC for internal storage.

Request Body (JSON)

{
  "vehicle": "CC-05",
  "startTime": "11/03/2026 08:00",
  "waypoints": [
    { "geofence": "Central Office", "expectedArrival": "11/03/2026 09:30" },
    { "geofence": "North Plant",    "expectedArrival": "11/03/2026 11:00" }
  ]
}
FieldTypeDescription
vehiclestringRequired — Exact vehicle name as registered in the platform
startTimestringRequired — Start date/time in dd/MM/yyyy HH:mm format (local timezone)
waypointsarrayRequired — At least one destination waypoint
waypoints[].geofencestringExact geofence name (case-sensitive)
waypoints[].expectedArrivalstringExpected arrival time in dd/MM/yyyy HH:mm format (local timezone)

Response 200 OK

{
  "success": true,
  "data": {
    "travelId": 123,
    "vehicle": "CC-05",
    "status": "Scheduled",
    "timezone": "America/Mexico_City",
    "progress": 0,
    "totalWaypoints": 3,
    "completedWaypoints": 0,
    "startTime": { "local": "11/03/2026 08:00", "utc": "11/03/2026 14:00" },
    "waypoints": [
      { "order": 1, "geofence": "Current position",
        "status": "Pending",
        "expectedArrival": { "local": "11/03/2026 08:00", "utc": "11/03/2026 14:00" },
        "arrivedAt": null, "estimatedArrival": null,
        "delayMinutes": null, "timing": "" },
      { "order": 2, "geofence": "Central Office",
        "status": "Pending",
        "expectedArrival": { "local": "11/03/2026 09:30", "utc": "11/03/2026 15:30" },
        "arrivedAt": null, "estimatedArrival": null,
        "delayMinutes": null, "timing": "" }
    ]
  }
}

Possible Errors

ErrorCause
Vehicle not foundThe vehicle name does not exactly match any registered vehicle
Geofence not foundA geofence name does not exactly match any existing geofence
Active travel existsThe vehicle already has a scheduled or in-progress travel
Invalid date formatUse the dd/MM/yyyy HH:mm format

Try It

GET /api/v1/travels/{id}

Retrieves the full status of a travel, including all waypoints with expected times, actual arrival times, live ETA estimates, delay metrics, and timing labels. Designed for real-time monitoring via polling every few seconds.

Path Parameters

ParameterTypeDescription
idintTravel ID (returned when creating a travel or from the active travels list)

cURL Example

curl -H "Authorization: Bearer gps_your_key" \
     https://platform.gpsafe.io/api/v1/travels/123

Response 200 OK — In-progress travel

{
  "success": true,
  "data": {
    "travelId": 123, "vehicle": "CC-05",
    "status": "In progress", "progress": 33.3,
    "totalWaypoints": 3, "completedWaypoints": 1,
    "timezone": "America/Mexico_City",
    "startTime": { "local": "11/03/2026 08:00", "utc": "11/03/2026 14:00" },
    "waypoints": [
      { "order": 1, "geofence": "Current position",
        "status": "Completed",
        "expectedArrival": { "local": "11/03/2026 08:00", "utc": "11/03/2026 14:00" },
        "arrivedAt": { "local": "11/03/2026 08:01", "utc": "11/03/2026 14:01" },
        "estimatedArrival": null,
        "delayMinutes": null, "timing": "On time" },
      { "order": 2, "geofence": "Central Office",
        "status": "Pending",
        "expectedArrival": { "local": "11/03/2026 09:30", "utc": "11/03/2026 15:30" },
        "arrivedAt": null,
        "estimatedArrival": { "local": "11/03/2026 09:45", "utc": "11/03/2026 15:45" },
        "delayMinutes": 15, "timing": "+15 min late (est.)" }
    ]
  }
}

Waypoint Fields

FieldTypeDescription
orderintSequential waypoint number
geofencestringGeofence name ("Current position" for the starting point)
statusstringCompleted · Pending · Cancelled
expectedArrivalobject{local, utc} — Scheduled arrival time
arrivedAtobject|null{local, utc} — Actual arrival time (null if not yet arrived)
estimatedArrivalobject|null{local, utc} — Live ETA from the server (updated every ~30s)
delayMinutesint|nullDelay in minutes (positive = late, negative = ahead of schedule)
timingstringHuman-readable label: "On time", "+15 min late", "10 min early", etc.

Try It

DELETE /api/v1/travels/{id}

Cancels an active or scheduled travel. Only works when the travel status is Scheduled (0) or In progress (1). Completed or already cancelled travels cannot be cancelled.

cURL Example

curl -X DELETE -H "Authorization: Bearer gps_your_key" \
     https://platform.gpsafe.io/api/v1/travels/123

Response 200 OK

{
  "success": true,
  "data": {
    "travelId": 123,
    "status": "Cancelled",
    "message": "Travel cancelled successfully."
  }
}

Try It

GET /api/v1/travels

Returns a summary of all active travels (scheduled or in progress) for the account. Each entry includes progress percentage, next waypoint information, and delay metrics.

cURL Example

curl -H "Authorization: Bearer gps_your_key" \
     https://platform.gpsafe.io/api/v1/travels

Response 200 OK

{
  "success": true,
  "data": [
    {
      "travelId": 123, "vehicle": "CC-05",
      "status": "In progress", "progress": 33.3,
      "totalWaypoints": 3, "completedWaypoints": 1,
      "nextWaypoint": "Central Office",
      "delayMinutes": 5, "timing": "+5 min late",
      "startTime": { "local": "11/03/2026 08:00", "utc": "11/03/2026 14:00" }
    },
    {
      "travelId": 124, "vehicle": "CC-07",
      "status": "Scheduled", "progress": 0,
      "totalWaypoints": 2, "completedWaypoints": 0,
      "nextWaypoint": "Current position",
      "delayMinutes": null, "timing": "",
      "startTime": { "local": "11/03/2026 14:00", "utc": "11/03/2026 20:00" }
    }
  ]
}

Response Fields

FieldTypeDescription
travelIdintUnique travel identifier
vehiclestringVehicle name
statusstringScheduled · In progress
progressdoubleCompletion percentage (0–100)
totalWaypointsintTotal waypoints including the starting position
completedWaypointsintNumber of completed waypoints
nextWaypointstring|nullName of the next pending waypoint
delayMinutesint|nullDelay for the next waypoint (null if unavailable)
timingstringTiming label for the next waypoint
startTimeobject{local, utc} — Travel start time

Try It

⚠️
❓