DEVICE INTEGRATION / V1

Small payload. Clear picture.

Connect any HTTP-capable IoT device to the collection map. No registration, login, token, or API key is required. Use this server’s address as your base URL. The examples use http://localhost; on a device, replace it with the server’s reachable IP address or hostname. Devices may continue using http://193.23.126.65 on port 80. The map and these docs are also available at https://violet-koala-19661.zap.cloud. The HTTPS map uses same-origin HTTPS API requests; HTTP device requests remain supported without redirects.

Send a status first, then open the map and choose Set position. The saved status appears immediately, even if the device never sends another update. The map refreshes every second.

1. Send a bin status

POST /api/bins/status creates a bin or updates its last known status. Send JSON with Content-Type: application/json.

curl -X POST http://localhost/api/bins/status \
  -H 'Content-Type: application/json' \
  -d '{"id":"bin-001","status":"half full"}'

Field	Type	Allowed values
id	string	1–128 characters: A–Z, a–z, 0–9, underscore, hyphen. Case-sensitive.
status	string	Exactly `empty`, `half full`, or `full`

Returns 201 Created for a new bin, 200 OK for an existing bin:

{
  "id": "bin-001",
  "status": "half full",
  "latitude": null,
  "longitude": null,
  "updatedAt": "2026-11-02T12:00:00.000Z"
}

updatedAt is the server’s UTC timestamp of the most recent status report. A status update preserves the bin’s position. Devices can report repeatedly using the same ID.

2. Set or change a position

POST /api/bins/:id/position. The bin must already exist. Coordinates are decimal degrees (WGS84): latitude −90 to 90, longitude −180 to 180. This preserves the status and its timestamp. Returns 200 with the complete bin.

curl -X POST http://localhost/api/bins/bin-001/position \
  -H 'Content-Type: application/json' \
  -d '{"latitude":52.5200,"longitude":13.4050}'

You can also enter coordinates or pick a point on the map using Set position. A bin without a position stays in the list but has no map marker.

3. Read the current state

GET /api/bins returns all bins, including those awaiting a position:

curl http://localhost/api/bins

{"bins":[{"id":"bin-001","status":"half full","latitude":52.52,"longitude":13.405,"updatedAt":"2026-11-02T12:00:00.000Z"}]}

GET /api/bins/:id returns one bin in the same shape:

curl http://localhost/api/bins/bin-001

4. Remove a bin

DELETE /api/bins/:id removes its status and position. Returns 200 with {"removed":"bin-001"}. A later status POST with the same ID recreates the bin with no position. Set its position again to show its latest saved status on the map.

curl -X DELETE http://localhost/api/bins/bin-001

Response codes & device retries

Code	Meaning
200 / 201	Request succeeded.
400	Invalid JSON, ID, status, or coordinates. Correct the payload before retrying.
404	Unknown bin or route. Report a status before setting a position.
405	Method not supported on that bin route.
413	Payload exceeds 8 KB.
415	Missing or incorrect Content-Type. Use application/json.
500	Server error. Retry with a delay.

Errors return {"error":"Description"}. On connection failure or a server error, retry with increasing delays, for example 5, 10, 20, then 60 seconds. Repeating a status POST is safe: the last request received wins and refreshes the report timestamp. Statuses never expire automatically. Records survive server restarts in the SQLite database.

This is a shared, unauthenticated service: anyone who can reach the server can read reports, change positions, report statuses, or remove bins. No device identity verification is performed.

Map powered by OpenLayers and OpenStreetMap. Map tiles require internet access.