Tracking API — GPS pings and geofences

The Tracking API covers two concerns: GPS pings recorded by drivers during active assignments, and geofences that define delivery corridors or restricted zones. Pings are stored in the gps_tracking MongoDB collection with a 2dsphere index on location. Geofences are stored in the geocercas collection and can be queried for spatial containment.

All endpoints require a valid Bearer token. GPS endpoints use the tracking resource; geofence endpoints use the geocercas resource.

GPS endpoints

Record GPS ping

POST /tracking/ping Stores a single GPS position emitted by a driver’s device. If timestamp is omitted, the server time is used. Permission: tracking:write

asignacion_id

integer

required

Active assignment ID this ping belongs to.

conductor_id

integer

required

Driver (conductor) ID.

vehiculo_placa

string

required

Vehicle licence plate.

lon

number

required

Longitude (-180 to 180).

lat

number

required

Latitude (-90 to 90).

speed_kmh

number

Current speed in km/h.

heading

number

Bearing in degrees (0–360).

accuracy_m

number

GPS accuracy radius in metres.

timestamp

string

ISO 8601 datetime. Defaults to server time when omitted.

curl -X POST "https://api.rappi2.com/tracking/ping" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "asignacion_id": 101,
    "conductor_id": 5,
    "vehiculo_placa": "ABC-123",
    "lon": -77.0282,
    "lat": -12.0432,
    "speed_kmh": 35.5,
    "heading": 180.0,
    "accuracy_m": 4.2
  }'

{
  "id": "664f1a2b3c4d5e6f7a8b9c0d",
  "asignacion_id": 101,
  "conductor_id": 5,
  "vehiculo_placa": "ABC-123",
  "location": {
    "type": "Point",
    "coordinates": [-77.0282, -12.0432]
  },
  "speed_kmh": 35.5,
  "heading": 180.0,
  "accuracy_m": 4.2,
  "timestamp": "2026-05-22T14:00:00Z"
}

List pings for assignment

GET /tracking/asignacion/{asignacion_id} Returns up to limit pings for an assignment, ordered by timestamp descending. Permission: tracking:read

asignacion_id

integer

required

Assignment ID.

desde

string

ISO 8601 datetime — return only pings at or after this time.

hasta

string

ISO 8601 datetime — return only pings at or before this time.

limit

integer

default:"500"

Maximum number of pings to return (max 2000).

curl -X GET "https://api.rappi2.com/tracking/asignacion/101?limit=100&desde=2026-05-22T12:00:00Z" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "664f1a2b3c4d5e6f7a8b9c0d",
    "asignacion_id": 101,
    "conductor_id": 5,
    "vehiculo_placa": "ABC-123",
    "location": {"type": "Point", "coordinates": [-77.0282, -12.0432]},
    "speed_kmh": 35.5,
    "heading": 180.0,
    "accuracy_m": 4.2,
    "timestamp": "2026-05-22T14:00:00Z"
  }
]

Get most recent ping

GET /tracking/asignacion/{asignacion_id}/ultimo Returns the single most recent GPS ping for an assignment. Permission: tracking:read

asignacion_id

integer

required

Assignment ID.

curl -X GET "https://api.rappi2.com/tracking/asignacion/101/ultimo" \
  -H "Authorization: Bearer <token>"

{
  "id": "664f1a2b3c4d5e6f7a8b9c0d",
  "asignacion_id": 101,
  "conductor_id": 5,
  "vehiculo_placa": "ABC-123",
  "location": {"type": "Point", "coordinates": [-77.0282, -12.0432]},
  "speed_kmh": 35.5,
  "heading": 180.0,
  "accuracy_m": 4.2,
  "timestamp": "2026-05-22T14:00:00Z"
}

Assignment statistics

GET /tracking/asignacion/{asignacion_id}/estadisticas Computes total distance (via the Haversine formula over sequential pings), duration, and average speed for an assignment. Permission: tracking:read

asignacion_id

integer

required

Assignment ID.

curl -X GET "https://api.rappi2.com/tracking/asignacion/101/estadisticas" \
  -H "Authorization: Bearer <token>"

{
  "asignacion_id": 101,
  "pings": 48,
  "distancia_total_m": 9830.45,
  "distancia_total_km": 9.830,
  "duracion_segundos": 1350.0,
  "duracion_minutos": 22.5,
  "velocidad_promedio_kmh": 26.21,
  "primer_ping": "2026-05-22T13:37:30Z",
  "ultimo_ping": "2026-05-22T14:00:00Z"
}

asignacion_id

integer

required

Assignment ID.

pings

integer

required

Total number of pings recorded.

distancia_total_m

number

required

Distance in metres.

distancia_total_km

number

required

Distance in kilometres.

duracion_segundos

number

required

Elapsed time in seconds between the first and last ping.

duracion_minutos

number

required

Elapsed time in minutes.

velocidad_promedio_kmh

number

Average speed in km/h. null when duration is zero.

primer_ping

string

Timestamp of the first recorded ping.

ultimo_ping

string

Timestamp of the most recent recorded ping.

Find nearby drivers

GET /tracking/conductores-cerca Uses a MongoDB $geoNear aggregation over the gps_tracking collection to return the most recent ping of each driver within radio_m metres whose last ping falls within the ventana_min time window. Permission: tracking:read

lon

number

required

Centre longitude (-180 to 180).

lat

number

required

Centre latitude (-90 to 90).

radio_m

integer

default:"2000"

Search radius in metres (10–50000).

ventana_min

integer

default:"5"

Only consider drivers whose last ping is within this many minutes (1–60).

curl -X GET "https://api.rappi2.com/tracking/conductores-cerca?lon=-77.03&lat=-12.04&radio_m=3000&ventana_min=10" \
  -H "Authorization: Bearer <token>"

[
  {
    "conductor_id": 5,
    "ultimo_ping_id": "664f1a2b3c4d5e6f7a8b9c0d",
    "asignacion_id": 101,
    "vehiculo_placa": "ABC-123",
    "location": {"type": "Point", "coordinates": [-77.0282, -12.0432]},
    "speed_kmh": 35.5,
    "timestamp": "2026-05-22T14:00:00Z",
    "distance_m": 412.7
  }
]

Geofence endpoints

Create geofence

POST /geocercas Creates a polygon geofence stored in the geocercas MongoDB collection. Geometry must be a valid GeoJSON Polygon coordinate array. Permission: geocercas:write

tipo

string

required

Geofence type: ruta_buffer, zona_entrega, or prohibida.

coordinates

array

required

GeoJSON Polygon coordinates: an array of rings, each ring being an array of [lon, lat] pairs. The first and last positions of each ring must be identical (closed ring).

ruta_id

integer

Route ID to link this geofence to.

orden_id

integer

Order ID to link this geofence to.

tolerance_m

integer

Buffer tolerance in metres used when generating this geofence programmatically.

activa

boolean

default:"true"

Whether the geofence is active.

curl -X POST "https://api.rappi2.com/geocercas" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "zona_entrega",
    "ruta_id": 7,
    "activa": true,
    "coordinates": [[
      [-77.030, -12.040],
      [-77.025, -12.040],
      [-77.025, -12.045],
      [-77.030, -12.045],
      [-77.030, -12.040]
    ]]
  }'

{
  "id": "664e9f1a2b3c4d5e6f7a8b9c",
  "ruta_id": 7,
  "orden_id": null,
  "tipo": "zona_entrega",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[-77.030,-12.040],[-77.025,-12.040],[-77.025,-12.045],[-77.030,-12.045],[-77.030,-12.040]]]
  },
  "tolerance_m": null,
  "activa": true,
  "created_at": "2026-05-22T14:05:00Z"
}

List geofences

GET /geocercas Returns all geofences, optionally filtered by route or active status. Permission: geocercas:read

ruta_id

integer

Filter by route ID.

activa

boolean

Filter by active status.

curl -X GET "https://api.rappi2.com/geocercas?ruta_id=7&activa=true" \
  -H "Authorization: Bearer <token>"

Geofences containing a point

GET /geocercas/contiene Returns all active geofences whose polygon contains the given point. Uses MongoDB $geoIntersects. Permission: geocercas:read

lon

number

required

Longitude of the point to test (-180 to 180).

lat

number

required

Latitude of the point to test (-90 to 90).

curl -X GET "https://api.rappi2.com/geocercas/contiene?lon=-77.0282&lat=-12.0432" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "664e9f1a2b3c4d5e6f7a8b9c",
    "ruta_id": 7,
    "orden_id": null,
    "tipo": "zona_entrega",
    "geometry": {"type": "Polygon", "coordinates": [[...]]},
    "tolerance_m": null,
    "activa": true,
    "created_at": "2026-05-22T14:05:00Z"
  }
]

Get geofence

GET /geocercas/{geocerca_id} Retrieve a single geofence by its MongoDB ObjectId. Permission: geocercas:read

geocerca_id

string

required

MongoDB ObjectId of the geofence.

curl -X GET "https://api.rappi2.com/geocercas/664e9f1a2b3c4d5e6f7a8b9c" \
  -H "Authorization: Bearer <token>"

Update geofence

PATCH /geocercas/{geocerca_id} Partially update a geofence’s type, coordinates, tolerance, or active status. Permission: geocercas:write

geocerca_id

string

required

MongoDB ObjectId of the geofence.

tipo

string

New type: ruta_buffer, zona_entrega, or prohibida.

coordinates

array

Replacement GeoJSON Polygon coordinates.

tolerance_m

integer

Updated buffer tolerance in metres.

activa

boolean

Enable or disable the geofence.

curl -X PATCH "https://api.rappi2.com/geocercas/664e9f1a2b3c4d5e6f7a8b9c" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"activa": false}'

Delete (deactivate) geofence

DELETE /geocercas/{geocerca_id} Sets activa = false on the geofence. The document is retained in MongoDB. Permission: geocercas:delete

This is a soft delete — the geofence is deactivated, not removed from the database.

geocerca_id

string

required

MongoDB ObjectId of the geofence.

curl -X DELETE "https://api.rappi2.com/geocercas/664e9f1a2b3c4d5e6f7a8b9c" \
  -H "Authorization: Bearer <token>"

Geofence response schema

string

required

MongoDB ObjectId as a hex string.

ruta_id

integer

Route linked to this geofence.

orden_id

integer

Order linked to this geofence.

tipo

string

required

One of ruta_buffer, zona_entrega, prohibida.

geometry

object

required

GeoJSON Polygon object with type and coordinates.

tolerance_m

integer

Buffer tolerance applied when the geofence was generated automatically.

activa

boolean

required

Whether the geofence is currently active.

created_at

string

required

ISO 8601 creation timestamp.

Auth & Users

Operations

Logistics

Analytics

Tracking API — GPS pings and geofences

GPS endpoints

Record GPS ping

List pings for assignment

Get most recent ping

Assignment statistics

Find nearby drivers

Geofence endpoints

Create geofence

List geofences

Geofences containing a point

Get geofence

Update geofence

Delete (deactivate) geofence

Geofence response schema

Build docs developers (and LLMs) love

Auth & Users

Operations

Logistics

Analytics

Documentation Index

​GPS endpoints

​Record GPS ping

​List pings for assignment

​Get most recent ping

​Assignment statistics

​Find nearby drivers

​Geofence endpoints

​Create geofence

​List geofences

​Geofences containing a point

​Get geofence

​Update geofence

​Delete (deactivate) geofence

​Geofence response schema

Build docs developers (and LLMs) love

GPS endpoints

Record GPS ping

List pings for assignment

Get most recent ping

Assignment statistics

Find nearby drivers

Geofence endpoints

Create geofence

List geofences

Geofences containing a point

Get geofence

Update geofence

Delete (deactivate) geofence

Geofence response schema