API Reference

Reference for the HTTP requests Colota sends to your server.

Request

Method: POST (default) or GET

Configure the HTTP method in Settings > API Settings > HTTP Method.

POST (default)

Headers:

Content-Type: application/json; charset=UTF-8
Accept: application/json

Additional headers may be included based on your authentication configuration.

Body:

{
  "lat": 48.135124,
  "lon": 11.581981,
  "acc": 12,
  "alt": 519,
  "vel": 0,
  "batt": 85,
  "bs": 2,
  "tst": 1704067200,
  "bear": 180.5
}

GET

Fields are sent as URL query parameters instead of a JSON body. No Content-Type header is set. Authentication headers are still included if configured.

GET https://your-server.com:5055/?id=colota&lat=48.135124&lon=11.581981&accuracy=12&altitude=519&speed=0&batt=85&charge=2&timestamp=1704067200&bearing=180.5

Values are URL-encoded. If the endpoint URL already contains query parameters, additional parameters are appended with &.

All field names are customizable.

Field Types

Field	Type	Unit	Always present
lat	Double	Degrees	Yes
lon	Double	Degrees	Yes
acc	Integer	Meters (rounded)	Yes
alt	Integer	Meters (rounded)	No - only if device has altitude data
vel	Double	m/s (1 decimal)	No - only if device has speed data
batt	Integer	Percent (0–100)	Yes
bs	Integer	0=unknown, 1=unplugged, 2=charging, 3=full	Yes
tst	Long	Unix seconds (not milliseconds)	Yes
bear	Double	Degrees (0–360)	No - only if device has bearing data

Important: alt, vel, and bear are conditionally included. Your server should not reject payloads missing these fields.

Anchor Points

When exiting a pause zone, Colota sends a synthetic location at the geofence center. These payloads look like regular locations but have specific characteristics:

• lat/lon are the geofence center coordinates (not the actual GPS position)
• acc is set to the geofence radius in meters
• tst is set to 1 second before the first real GPS fix after leaving the zone
• alt, vel, and bear are not included
• batt and bs reflect the current battery state

Custom Fields

Custom static fields (configured in API Settings) are added to the payload first, then location fields are added. If a custom field has the same name as a location field, the location field overwrites it.

Custom field values are always sent as strings.

Batch Sync Behavior

Colota sends one location per HTTP request - not an array. During batch sync, up to 10 requests are sent concurrently, processing up to 500 queued locations per sync cycle.

Your server should handle multiple simultaneous POST requests. If you have rate limiting, some requests may fail and be retried.

Testing with curl

POST (default):

curl -X POST https://your-server.com/api/location \
  -H "Content-Type: application/json; charset=UTF-8" \
  -H "Accept: application/json" \
  -d '{"lat":48.135,"lon":11.582,"acc":12,"vel":0,"batt":85,"bs":2,"tst":1704067200}'

GET (e.g., Traccar):

curl "https://your-server.com:5055/?id=colota&lat=48.135&lon=11.582&accuracy=12&speed=0&batt=85&timestamp=1704067200"

With Basic Auth:

curl -X POST https://your-server.com/api/location \
  -H "Content-Type: application/json; charset=UTF-8" \
  -H "Authorization: Basic dXNlcjpwYXNz" \
  -d '{"lat":48.135,"lon":11.582,"acc":12,"vel":0,"batt":85,"bs":2,"tst":1704067200}'

Response

Success:

Status: 200–299
Body: Any (ignored by Colota)

Your server only needs to return a 2xx status code. The response body is not read.

Error Handling

Error Type	Behavior
Any non-2xx response	Queued for retry
Network timeout	Retried (10s connection, 10s read timeout)

There is no distinction between 4xx and 5xx in retry behavior - all failures are retried indefinitely. Failed items stay in the queue until they succeed or you clear the queue manually. Location data is never deleted.

Retry Strategy

When consecutive sync attempts fail, Colota uses exponential backoff:

Attempt 1: Immediate
Attempt 2: +30s delay
Attempt 3: +60s delay (1 minute)
Attempt 4: +300s delay (5 minutes)
Attempt 5+: +900s delay (15 minutes)

Failed items stay in the queue indefinitely until they succeed. The queue can be cleared manually in Settings > Data Management if needed.

Network Requirements

• HTTPS required for all public endpoints
• HTTP allowed for private/local addresses - enforced via DNS resolution at both sync time and Test Connection
• Non-standard ports are supported (e.g., https://my-server.com:8443/api)
• Self-signed certificates are supported - see Server Settings for setup instructions

Connectivity Check

Colota checks Android's network connectivity manager before attempting sync. This check is cached for 5 seconds. When offline, locations are queued locally and synced automatically when the network returns.