Skip to main content

Ingest Location

POST 
/api/v1/locations

Ingest a single location point.

This endpoint accepts location updates from external systems and queues them for asynchronous processing with GPS jitter reduction filters.

Devices must already be registered and active. API keys require devices:write. A 202 response means durable admission, including during broker outages; pending work is recovered automatically without charging retries again. Each admitted fix counts toward the monthly event quota. Usage past the quota never refuses a fix.

A shift pause is enforced as on the device location routes. While the device's shift is paused, a fix is rejected with 400 and error_code SHIFT_PAUSED. A fix timestamped inside a pause is rejected with 400 and error_code PAUSED_INTERVAL, also after that shift has ended or a newer one has started. Each shift keeps only its last resume, so everything in it before that resume counts as paused, and a shift that ended while paused counts as paused until its end. A rejected fix is not stored, charged or evaluated. If a pause begins before an admitted fix is processed, the fix is dropped instead and an exact retry returns the same error. A fix outside any shift is admitted as usual.

Authentication: API Key (Bearer token) Rate Limit: 1000 requests/minute per API key

Returns: 202 Accepted: Location queued for processing 400 Bad Request: Invalid location data, or a fix from a paused shift 401 Unauthorized: Missing or invalid API key 429 Too Many Requests: Rate limit exceeded

Example:

curl -X POST https://api.spatialflow.io/api/v1/locations \
  -H "Authorization: Bearer sf_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '\{
    "device_id": "truck-005",
    "lat": 40.7589,
    "lon": -73.9851,
    "ts": "2025-10-01T14:30:00Z",
    "accuracy": 8.5
  \}'

Request​

Responses​

Accepted