API Reference

REST API for reading and writing location data

https://geolocateme.guleki.com

All responses include CORS headers and use JSON format. Error responses follow the format: { "error": "message" }

Geolocate Me uses a two-token system:

• Client Token — used by the iOS app to write location pings (X-Client-Token header)
• Bot Token — used by external consumers to read location data (X-Bot-Token header)

Write endpoints also require the X-Device-Id header. Both tokens are generated at device registration and returned once. Only SHA-256 hashes are stored server-side.

Get the most recent location ping for a device.

Headers:
  X-Bot-Token: <your-bot-token>

Query Parameters:
  deviceId (required) — your device UUID

Example:
  curl -H "X-Bot-Token: YOUR_TOKEN" \
    "https://geolocateme.guleki.com/api/location/latest?deviceId=YOUR_ID"

Response:
  {
    "location": {
      "lat": -33.8829,
      "lng": 151.2167,
      "accuracy": 5,
      "timestamp": "2026-04-02T10:00:00.000Z"
    }
  }

Returns { "location": null } if no pings exist.

Get location history with optional time filtering. Returns up to 100 entries, newest first.

Headers:
  X-Bot-Token: <your-bot-token>

Query Parameters:
  deviceId (required) — your device UUID
  hours (optional) — return pings from the last N hours
  from (optional) — ISO 8601 start timestamp
  to (optional) — ISO 8601 end timestamp

Examples:
  # Last 24 hours
  curl -H "X-Bot-Token: TOKEN" \
    "https://geolocateme.guleki.com/api/location/history?deviceId=ID&hours=24"

  # Date range
  curl -H "X-Bot-Token: TOKEN" \
    "https://geolocateme.guleki.com/api/location/history?deviceId=ID&from=2026-04-01T00:00:00Z&to=2026-04-02T00:00:00Z"

Response:
  {
    "pings": [
      { "lat": -33.8829, "lng": 151.2167, "accuracy": 5, "timestamp": "..." }
    ],
    "count": 42
  }

Send a single location ping.

Headers:
  Content-Type: application/json
  X-Device-Id: <your-device-id>
  X-Client-Token: <your-client-token>
  X-Retention-Days: <30|90|365> (optional, default: 30)

Body:
  { "lat": -33.8829, "lng": 151.2167, "accuracy": 5 }

Response:
  { "status": "ok", "timestamp": "2026-04-02T10:00:00.000Z" }

Send up to 100 queued location pings in a single request.

Headers:
  Content-Type: application/json
  X-Device-Id: <your-device-id>
  X-Client-Token: <your-client-token>
  X-Retention-Days: <30|90|365> (optional, default: 30)

Body:
  {
    "pings": [
      { "lat": -33.8829, "lng": 151.2167, "accuracy": 5, "timestamp": "..." },
      { "lat": -33.8830, "lng": 151.2168, "accuracy": 10 }
    ]
  }

Response:
  { "status": "ok", "count": 2 }

Pings are automatically deleted based on your subscription tier:

• Basic ($1.99/mo) — 30 days
• Standard ($2.99/mo) — 90 days
• Pro ($4.99/mo) — 365 days

Retention is set per-ping via the X-Retention-Days header. The iOS app sends this automatically based on your subscription.

No application-level rate limiting is enforced. AWS service limits apply:

• API Gateway: 10,000 requests/second
• Lambda: 1,000 concurrent executions
• DynamoDB: on-demand scaling