Marmaradar API – Usage via Gateway

All APIs are consumed through the Marmaradar gateway. This site (api.marmaradar.com) hosts documentation only — send API requests to the gateway base URL below.

Base URL (production): http://35.239.129.237:8081
Base URL (local): http://127.0.0.1:8081
Documentation URL: https://api.marmaradar.com/docs/apiusage.html
OpenAPI spec: /openapi.json — machine-readable subset; this page is the full usage guide.

1. Authentication

Most endpoints require a JWT. Send it in the header:

Authorization: Bearer <your_access_token>

Obtain a token via the Auth API (no token required). When the access token expires, call POST /v1/auth/refresh with the refresh_token.

Method	Path	Auth	Description
POST	`/v1/auth/register`	None	Register with `email` and `password` (min. 8 characters). Returns access + refresh tokens and user info.
POST	`/v1/auth/login`	None	Email/password login; returns access + refresh tokens and user info.
POST	`/v1/auth/refresh`	None	Rotate tokens. Body: `refresh_token`.
POST	`/v1/auth/oauth`	None	Google/Apple sign-in. Body: `provider` (`google` \| `apple`), `id_token`, optional `nonce` (Apple).
POST	`/v1/auth/forgot-password`	None	Request password reset email. Body: `email`. Response: `{"ok": true}`.
POST	`/v1/auth/reset-password`	None	Complete reset with `token` (from email) and `password` (min. 8). Response: `{"ok": true}`.
GET	`/reset-password`	None	HTML reset form (query: `token`). Not a JSON API.

2. API Areas (via Gateway)

All paths below are relative to the gateway base URL. Protected routes expect Authorization: Bearer <access_token>.

Route prefixes:

/v1/auth/* · /v1/users/* · /v1/drives/* · /v1/leaderboard
/v1/cameras/* · /v1/corridors/* · /v1/sync · /v1/uploads/*
/v1/reports/* · /v1/live-reports/* · /v1/eta/* · /v1/amenities/* · /v1/tts/*

2.1 Auth

/v1/auth/* — Register, login, refresh, OAuth, forgot/reset password (see table above). No Bearer token required.

2.2 Geo data (cameras, corridors, sync)

/v1/cameras/* · /v1/corridors/* · /v1/sync — Public map data. No auth.

GET /v1/cameras/nearby — Nearby speed cameras. Query: lat, lon (required), radius_m (default 1000, max 5000), region (default bursa)
GET /v1/corridors/nearby — Nearby average-speed corridors. Query: lat, lon, region
GET /v1/sync — Delta sync for a bbox. Query: bbox (west,south,east,north, required), region, optional since (RFC3339)
GET /v1/uploads/avatars/{file} — Public avatar image. No auth. Cached 24h.

2.3 Users, stats & leaderboard

/v1/users/* · /v1/leaderboard — Require Bearer token.

GET /v1/users/me — Current profile (id, email, username, profile_picture_url, vehicle_type, vehicle_color)
PATCH /v1/users/me — Partial update: username, vehicle_type, vehicle_color (see §3.2)
POST /v1/users/me/profile-picture — Upload avatar (multipart/form-data, field file; JPEG/PNG/WebP, max 2 MB)
GET /v1/users/me/stats — Lifetime stats, rank/XP, streak, achievements
GET /v1/leaderboard — Top 100 + caller rank. Query: category = distance | reports (required)

2.4 Drives

/v1/drives/* — Recorded trips. Requires Bearer token.

POST /v1/drives — Upload a drive (points + optional name). Returns id, length_m, point_count
GET /v1/drives — List my drives (summaries)
GET /v1/drives/{id} — Drive detail with points / snapped path
PATCH /v1/drives/{id} — Rename. Body: { "name": "..." }. Returns 204

2.5 Reports (crowd / mobile radar)

/v1/reports/* — Requires Bearer token.

POST /v1/reports — Create or merge a mobile radar report. Body: lat, lon, optional heading_deg, region
POST /v1/reports/{id}/votes — Vote. Body: value (1 / -1), lat, lon (voter position)

2.6 Live reports

/v1/live-reports/* — Short-lived hazards (police / accident).

GET /v1/live-reports/active — Active reports (pending + confirmed). No auth
POST /v1/live-reports — Create. Body: lat, lng, report_type (police | accident). Bearer
POST /v1/live-reports/{id}/vote — Vote. Body: is_upvote (bool). Bearer

2.7 ETA, amenities & TTS

All require Bearer token.

POST /v1/eta/cameras — Driving ETA to nearby cameras (max 3 destinations). Body: origin, destinations[]
POST /v1/amenities/cells — Gas/rest stops by grid cells (max 3). Body: cells[], optional types
POST /v1/tts/speak — Synthesize Turkish alert audio (audio/mpeg). Body: phrase_key, params
GET /v1/tts/catalog — Catalog of cacheable TTS phrase variants

3. Request & response DTOs (reference)

JSON uses snake_case property names. Date/time values are ISO 8601 (RFC3339). Errors return {"error": "human-readable message"} with an appropriate HTTP status.

3.1 Auth

Request bodies

Endpoint	Properties (JSON)
POST /v1/auth/register	`email`, `password` (min. 8)
POST /v1/auth/login	`email`, `password`
POST /v1/auth/refresh	`refresh_token`
POST /v1/auth/oauth	`provider`, `id_token`, `nonce` (optional, Apple)
POST /v1/auth/forgot-password	`email`
POST /v1/auth/reset-password	`token`, `password` (min. 8)

`AuthResult` (register / login / refresh / oauth)

{
  "access_token": "string (JWT)",
  "refresh_token": "string",
  "expires_in": 900,
  "user": { "id": "uuid", "email": "string" }
}

3.2 Users & preferences

UserProfileResponse — GET/PATCH /v1/users/me, profile-picture upload:

{
  "id": "uuid",
  "email": "string",
  "username": "string | null",
  "profile_picture_url": "/v1/uploads/avatars/{id}.jpg | null",
  "vehicle_type": "sedan | hatchback | station_wagon | kamyon | tir",
  "vehicle_color": "#RRGGBB"
}

UpdatePreferencesRequest — PATCH /v1/users/me (partial; omit unchanged fields):

{
  "username": "string (optional; a-z0-9_; 3–20; unique)",
  "vehicle_type": "sedan | hatchback | station_wagon | kamyon | tir",
  "vehicle_color": "#RRGGBB"
}

profile_picture_url is a relative path on the gateway. Display as http://35.239.129.237:8081 + path. Avatars need no Bearer token.

3.3 Leaderboard

GET /v1/leaderboard?category=distance|reports returns:

{
  "category": "distance",
  "entries": [
    {
      "rank": 1,
      "user_id": "uuid",
      "username": "string",
      "profile_picture_url": "string | null",
      "vehicle_type": "sedan",
      "vehicle_color": "#E8262D",
      "value": 152340.5
    }
  ],
  "me": { "rank": 142, "user_id": "uuid", "username": "string", "...": "...", "in_top": false }
}

value is meters for distance, contribution count for reports. Top 100 plus always the caller’s me row.

3.4 Drives

Create — POST /v1/drives:

{
  "started_at": "2026-01-01T12:00:00Z",
  "ended_at": "2026-01-01T12:30:00Z",
  "name": "string | null",
  "points": [
    { "lat": 0, "lon": 0, "speed_mps": 0, "recorded_at": "2026-01-01T12:00:00Z" }
  ]
}

List/detail include summary fields (length_m, point_count, speed stats). Detail also returns points[] and optional snapped_points[].

3.5 Reports & live reports

Create report — POST /v1/reports: lat, lon, optional heading_deg, region. Response includes id, status, votes, expires_at, merged.

Vote — POST /v1/reports/{id}/votes: value (1|-1), lat, lon.

Live report — POST /v1/live-reports: lat, lng, report_type (police|accident). Active list returns id, lat, lng, report_type, verification_state, weighted_score, timestamps.

3.6 ETA, amenities & TTS

ETA — POST /v1/eta/cameras:

{
  "origin": { "lat": 0, "lon": 0 },
  "destinations": [{ "camera_id": "string", "lat": 0, "lon": 0 }]
}

Response: [{ "camera_id", "distance_m", "duration_sec", "status" }]. Max 3 destinations. 503 if Matrix API unavailable.

Amenities — POST /v1/amenities/cells: cells[] with lat_index/lon_index; optional types (gas_station, rest_stop). Max 3 cells.

TTS speak — phrase_key examples: camera.fixed, camera.mobile, report.police, corridor.warn, corridor.over. Distance phrases need params.distance_m. Response body is raw audio/mpeg.

3.7 Errors

Validation or business errors typically return 400 with {"error": "string"}. Unauthorized: 401. Forbidden: 403. Not found: 404. Conflict (e.g. username taken, invalid vote): 409. Rate limited: 429.

4. CORS

Allowed origins include https://marmaradar.com, https://www.marmaradar.com, https://api.marmaradar.com, and localhost (e.g. http://localhost:5173). For other origins, coordinate with the API owner.

5. Health

GET {gateway}/health — Returns 200 with {"status":"ok"} if the API is up. No authentication required.

6. Checklist for integrating

Use the gateway base URL (http://35.239.129.237:8081 in production) for all API calls — not this docs host alone for data requests.
Obtain a JWT via POST /v1/auth/login, POST /v1/auth/register, or POST /v1/auth/oauth.
Refresh with POST /v1/auth/refresh when the access token expires.
Send Authorization: Bearer <token> on every protected request.
Send Content-Type: application/json for JSON bodies (except profile photo upload).
Handle 401 (re-authenticate) and 403/409/429 appropriately.
For avatars, use gateway base + relative profile_picture_url in <img src> (no Bearer on image requests).

Last updated: 2026-09 — switched docs UI to gateway usage guide. When new APIs or DTOs change, update this page and regenerate OpenAPI via backend/scripts/generate-openapi.sh for annotated endpoints.