API Documentation

Authentication
Base URL
Error Handling
GET /api/v1/devices/status
GET /api/v1/devices/{deviceId}/status
GET /api/v1/geofences
GET /api/v1/reports/geofences — Geofence report
POST /api/v1/travels — Create travel
GET /api/v1/travels/{id} — Travel status
DEL /api/v1/travels/{id} — Cancel travel
GET /api/v1/travels — Active travels

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.

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

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

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

Code	Meaning
`200`	Success — response data is available in the `data` field
`400`	Bad Request — invalid parameters or business rule violation
`401`	Unauthorized — API key is missing, invalid, or expired
`404`	Not Found — the requested resource does not exist
`429`	Too Many Requests — rate limit exceeded (50 requests / 10 seconds)
`500`	Internal 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"
}

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

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	`Bearer {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

Field	Type	Description
`deviceId`	string	Device IMEI (unique identifier)
`name`	string	Vehicle name
`plates`	string	License plate number
`status`	string	`Moving` · `Stopped` · `Inactive` · `Off`
`engineStatus`	string	`On` · `Off` (ignition state)
`latitude`	decimal?	GPS latitude
`longitude`	decimal?	GPS longitude
`address`	string?	Reverse-geocoded address
`speedKmh`	int?	Current speed in km/h
`heading`	int?	Bearing in degrees (0–360)
`odometerKm`	double?	Odometer reading in kilometers
`satellites`	int?	Number of GPS satellites in view
`powerVoltage`	string?	Vehicle power supply voltage
`backupVoltage`	string?	Backup battery voltage
`signalStrength`	int?	GSM signal strength (0–31)
`connectionType`	string?	Network type (`2G`, `3G`, `4G`)
`lastReportUtc`	datetime?	Timestamp of the last report (UTC)
`minutesSinceReport`	int?	Minutes elapsed since the last report

Try It

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

Header	Type	Required	Description
`Authorization`	string	Yes	`Bearer {api_key}`

Path Parameters

Parameter	Type	Required	Description
`deviceId`	string	Yes	Device 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

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

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	`Bearer {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

Field	Type	Description
`id`	int	Geofence ID
`name`	string	Geofence name
`centerLat`	double	Center latitude
`centerLng`	double	Center longitude
`radiusMeters`	double	Approximate radius in meters
`vertexCount`	int	Number of polygon vertices
`vertices`	array	Ordered list of `{lat, lng}` polygon points

Try It

Generates a complete geofence activity report over a date range. You can scope it to specific vehicles and/or geofences, and choose which sections to return. The report contains three sections:

summary — aggregated crossings per vehicle & geofence (count, first & last cross).
events — the chronological list of entry/exit events.
visits — paired entry/exit intervals with the time spent inside each geofence.

All dates are interpreted in the local timezone of the user associated with the API key. A date-only to value (e.g. 2026-06-30) automatically covers the entire day.

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	`Bearer {api_key}`

Query Parameters

Parameter	Type	Required	Description
`from`	string	Yes	Range start. ISO date or datetime, e.g. `2026-06-01` or `2026-06-01T08:00`
`to`	string	Yes	Range end. ISO date or datetime, e.g. `2026-06-30`
`deviceIds`	string	No	Comma-separated list of vehicle IMEIs. Omit to include all accessible vehicles
`geofenceIds`	string	No	Comma-separated list of geofence IDs. Omit to include all geofences
`include`	string	No	Comma-separated sections: `summary`, `events`, `visits`. Default: all three

cURL Example

curl -H "Authorization: Bearer gps_your_key" \
     "https://platform.gpsafe.io/api/v1/reports/geofences?from=2026-06-01&to=2026-06-30&geofenceIds=42&include=summary,visits"

Response `200 OK`

{
  "success": true,
  "data": {
    "range": { "from": "01/06/2026 00:00", "to": "30/06/2026 23:59" },
    "deviceCount": 12,
    "geofenceCount": 1,
    "included": ["summary", "events", "visits"],
    "summary": [
      {
        "deviceId": "350612345678901",
        "deviceName": "TOYOTA HILUX",
        "geofenceId": 42,
        "geofenceName": "Central Warehouse",
        "timesCrossed": 8,
        "firstCross": "02/06/2026 07:14",
        "lastCross": "28/06/2026 18:02"
      }
    ],
    "events": [
      {
        "deviceId": "350612345678901",
        "deviceName": "TOYOTA HILUX",
        "geofenceName": "Central Warehouse",
        "eventType": "Entrada",
        "dateTime": "02/06/2026 07:14"
      },
      {
        "deviceId": "350612345678901",
        "deviceName": "TOYOTA HILUX",
        "geofenceName": "Central Warehouse",
        "eventType": "Salida",
        "dateTime": "02/06/2026 09:40"
      }
    ],
    "visits": [
      {
        "deviceId": "350612345678901",
        "deviceName": "TOYOTA HILUX",
        "geofenceName": "Central Warehouse",
        "entryTime": "02/06/2026 07:14",
        "exitTime": "02/06/2026 09:40",
        "duration": "2h 26m"
      }
    ]
  },
  "timestamp": "2026-06-30T15:30:00Z"
}

Response Fields

Field	Type	Description
`range`	object	Resolved `{from, to}` range (account timezone)
`deviceCount`	int	Number of vehicles in scope
`geofenceCount`	int	Number of geofences filtered by (`0` = all)
`included`	array	Sections returned in this response
`summary[]`	array?	Aggregated crossings — present when `summary` is requested
`summary[].timesCrossed`	int	Number of crossings in the range
`summary[].firstCross` / `lastCross`	string	First / last crossing timestamp
`events[]`	array?	Chronological events — present when `events` is requested
`events[].eventType`	string	`Entrada` (enter) · `Salida` (exit)
`visits[]`	array?	Entry/exit intervals — present when `visits` is requested
`visits[].duration`	string	Time spent inside the geofence

Error `400` — Invalid Request

{
  "success": false,
  "error": "Both 'from' and 'to' query parameters are required.",
  "timestamp": "2026-06-30T15:30:00Z"
}

Try It

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" }
  ]
}

Field	Type	Description
`vehicle`	string	Required — Exact vehicle name as registered in the platform
`startTime`	string	Required — Start date/time in `dd/MM/yyyy HH:mm` format (local timezone)
`waypoints`	array	Required — At least one destination waypoint
`waypoints[].geofence`	string	Exact geofence name (case-sensitive)
`waypoints[].expectedArrival`	string	Expected 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

Error	Cause
Vehicle not found	The vehicle name does not exactly match any registered vehicle
Geofence not found	A geofence name does not exactly match any existing geofence
Active travel exists	The vehicle already has a scheduled or in-progress travel
Invalid date format	Use the `dd/MM/yyyy HH:mm` format

Try It

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

Parameter	Type	Description
`id`	int	Travel 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

Field	Type	Description
`order`	int	Sequential waypoint number
`geofence`	string	Geofence name (`"Current position"` for the starting point)
`status`	string	`Completed` · `Pending` · `Cancelled`
`expectedArrival`	object	`{local, utc}` — Scheduled arrival time
`arrivedAt`	object\|null	`{local, utc}` — Actual arrival time (`null` if not yet arrived)
`estimatedArrival`	object\|null	`{local, utc}` — Live ETA from the server (updated every ~30s)
`delayMinutes`	int\|null	Delay in minutes (positive = late, negative = ahead of schedule)
`timing`	string	Human-readable label: `"On time"`, `"+15 min late"`, `"10 min early"`, etc.

Try It

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

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

Field	Type	Description
`travelId`	int	Unique travel identifier
`vehicle`	string	Vehicle name
`status`	string	`Scheduled` · `In progress`
`progress`	double	Completion percentage (0–100)
`totalWaypoints`	int	Total waypoints including the starting position
`completedWaypoints`	int	Number of completed waypoints
`nextWaypoint`	string\|null	Name of the next pending waypoint
`delayMinutes`	int\|null	Delay for the next waypoint (`null` if unavailable)
`timing`	string	Timing label for the next waypoint
`startTime`	object	`{local, utc}` — Travel start time

GPSafe API

Table of Contents

Authentication

Base URL

Error Handling

GET /api/v1/devices/status

Headers

Query Parameters

cURL Example

Response 200 OK

Response Fields

Try It

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

Headers

Path Parameters

cURL Example

Response 200 OK

Error 404 — Device Not Found

Try It

GET /api/v1/geofences

Headers

Query Parameters

cURL Example

Response 200 OK

Response Fields

Try It

GET /api/v1/reports/geofences

Headers

Query Parameters

cURL Example

Response 200 OK

Response Fields

Error 400 — Invalid Request

Try It

POST /api/v1/travels

Request Body (JSON)

Response 200 OK

Possible Errors

Try It

GET /api/v1/travels/{id}

Path Parameters

cURL Example

Response 200 OK — In-progress travel

Waypoint Fields

Try It

DELETE /api/v1/travels/{id}

cURL Example

Response 200 OK

Try It

GET /api/v1/travels

cURL Example

Response 200 OK

Response Fields

Try It

Response `200 OK`

Response `200 OK`

Error `404` — Device Not Found

Response `200 OK`

Response `200 OK`

Error `400` — Invalid Request

Response `200 OK`

Response `200 OK` — In-progress travel

Response `200 OK`

Response `200 OK`