Skip to main content

Ingest Location Batch

POST 
/api/v1/v1/locations/batch

Ingest a batch of location points.

Accepts up to 5000 locations per batch (PRD §3.4). Each location is validated and processed asynchronously as a single batch task.

Idempotency: If idempotency_key is provided, duplicate requests with the same key within 24 hours will return the original response without reprocessing.

Authentication: API Key (Bearer token) Rate Limit: 100 batches/minute per API key

PRD Reference: §3.4 Public Ingest API

Returns: 202 Accepted: Locations queued (includes counts of accepted/rejected) 400 Bad Request: Invalid batch data 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/batch \
  -H "Authorization: Bearer sf_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '\{
    "locations": [
      \{"device_id": "truck-005", "lat": 40.7589, "lon": -73.9851, "ts": "2025-10-01T14:30:00Z"\},
      \{"device_id": "truck-005", "lat": 40.7590, "lon": -73.9850, "ts": "2025-10-01T14:31:00Z"\}
    ],
    "idempotency_key": "batch-20251001-001"
  \}'

Request​

Responses​

Accepted