API Reference

The GeoContext API gives your AI agent a sense of place — ranked semantic POI results, neighbourhood profiles, weather, and timezone in a single call.

Authentication

Every public endpoint (except GET /health) requires a Bearer token:

Authorization: Bearer <your_api_token>

Async Job Pattern

All submit endpoints return a job_id immediately. The request is processed asynchronously by the API backend. Client polls until the result is ready.

Job statuses

Recommended polling strategy

1. Submit → receive job_id
2. Wait 500 ms
3. Poll GET /jobs/{job_id} every 1 s
4. Stop after 120 s (service may be unavailable)

POST /forward

Request body

{
  "query": "wheelchair-accessible Italian restaurant",
  "lat": 52.5200,
  "lon": 13.4050,
  "radius_m": 1000,
  "limit": 10,
  "neighborhood": false,
  "weather": false,
  "map": false
}

Response

{
  "job_id": "3f8e2a1b-4c9d-4e5f-8a1b-2c3d4e5f6a7b",
  "status": "complete",
  "result": {
    "query": "wheelchair-accessible Italian restaurant",
    "location": { "lat": 52.52, "lon": 13.405, "display_name": "Berlin, Germany" },
    "results": [
      {
        "osm_id": 123456789,
        "osm_type": "node",
        "name": "Trattoria Roma",
        "description": "Italian restaurant. Wheelchair accessible. Outdoor seating.",
        "lat": 52.5198,
        "lon": 13.4048,
        "distance_m": 45,
        "relevance_score": 0.91,
        "combined_score": 0.87,
        "tags": { "amenity": "restaurant", "cuisine": "italian", "wheelchair": "yes" },
        "opening_hours": "Mo-Su 12:00-22:00",
        "is_open": true,
        "confidence": 0.95
      }
    ],
    "neighborhood": null,
    "weather": null,
    "suggested_queries": ["nearby parking", "wheelchair route to restaurant"]
  }
}

curl example

curl -X POST https://api.YOUR_DOMAIN/forward \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "wheelchair-accessible Italian restaurant",
    "lat": 52.52, "lon": 13.405
  }'
# → { "job_id": "3f8e...", "status": "queued" }

curl https://api.YOUR_DOMAIN/jobs/3f8e2a1b-... \
  -H "Authorization: Bearer $API_TOKEN"
# → { "job_id": "...", "status": "complete", "result": { ... } }

POST /neighbourhood

Request body

{
  "lat": 52.5200,
  "lon": 13.4050,
  "radius_m": 500
}

Response result

{
  "lat": 52.52,
  "lon": 13.405,
  "radius_m": 500,
  "categories": {
    "restaurant": 12,
    "cafe": 8,
    "transit_stop": 4,
    "park": 2,
    "pharmacy": 1
  },
  "walkability": "high",
  "summary": "Dense mixed-use urban area with strong food/drink and transit presence."
}

POST /reverse

Request body

{
  "lat": 52.5200,
  "lon": 13.4050,
  "neighborhood": false,
  "weather": false,
  "map": false
}

Response result

{
  "lat": 52.52,
  "lon": 13.405,
  "display_name": "Unter den Linden 1, Mitte, Berlin, 10117, Germany",
  "address": {
    "road": "Unter den Linden",
    "house_number": "1",
    "suburb": "Mitte",
    "city": "Berlin",
    "postcode": "10117",
    "country": "Germany",
    "country_code": "de"
  },
  "neighborhood": null,
  "weather": null
}

POST /context

Request body

{
  "lat": 52.5200,
  "lon": 13.4050
}

Response result

{
  "lat": 52.52,
  "lon": 13.405,
  "address": {
    "display_name": "Mitte, Berlin, Germany",
    "country_code": "de"
  },
  "timezone": {
    "iana": "Europe/Berlin",
    "utc_offset_h": 2,
    "dst": true
  },
  "weather": {
    "current": { "temp_c": 18.5, "condition": "Partly cloudy" },
    "forecast": [ { "date": "2026-05-28", "max_c": 21, "min_c": 12 } ]
  },
  "neighborhood": {
    "categories": { "restaurant": 12, "cafe": 8 },
    "walkability": "high"
  }
}

GET /weather

Query parameters

Example

curl "https://api.YOUR_DOMAIN/weather?lat=52.52&lon=13.405" \
  -H "Authorization: Bearer $API_TOKEN"

Response result

{
  "lat": 52.52,
  "lon": 13.405,
  "timezone": "Europe/Berlin",
  "current": {
    "temp_c": 18.5,
    "feels_like_c": 17.2,
    "humidity_pct": 62,
    "wind_kph": 14,
    "condition": "Partly cloudy",
    "is_day": true
  },
  "forecast": [
    {
      "date": "2026-05-28",
      "max_c": 21,
      "min_c": 12,
      "condition": "Sunny",
      "precip_mm": 0
    }
  ]
}

GET /timezone

Query parameters

GET /timezone?lat=52.52&lon=13.405

Response result

{
  "lat": 52.52,
  "lon": 13.405,
  "iana": "Europe/Berlin",
  "utc_offset_h": 2,
  "dst": true
}

GET /changes

Query parameters

Response result

{
  "count": 3,
  "entities": [
    {
      "osm_id": 123,
      "osm_type": "node",
      "last_modified_ts": 1748390400,
      "name": "Café Berlino"
    }
  ]
}

GET /jobs/{job_id}

Responses

{ "job_id": "3f8e...", "status": "queued" }
{ "job_id": "3f8e...", "status": "processing" }
{ "job_id": "3f8e...", "status": "complete", "result": { ... } }
{ "job_id": "3f8e...", "status": "error", "error": "upstream error" }

GET /health

{ "status": "ok" }

Rate Limits

Each Bearer token is subject to a sliding-window rate limit:

When the limit is exceeded the server responds with HTTP 429:

{"detail": "rate limit exceeded"}

If the global job queue exceeds 500 pending jobs, new submissions also return HTTP 429:

{"detail": "queue full, try again later"}

Error Codes

Polling Guide

The recommended client polling loop:

import httpx, time

BASE  = "https://api.YOUR_DOMAIN"
HDRS  = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"}

def search(query: str, lat: float, lon: float) -> dict:
    # 1. Submit
    r = httpx.post(f"{BASE}/forward",
                   json={"query": query, "lat": lat, "lon": lon},
                   headers=HDRS)
    job_id = r.json()["job_id"]

    # 2. Poll
    time.sleep(0.5)
    for _ in range(120):
        r = httpx.get(f"{BASE}/jobs/{job_id}", headers=HDRS)
        data = r.json()
        if data["status"] == "complete":
            return data["result"]
        if data["status"] == "error":
            raise RuntimeError(data.get("error", "unknown error"))
        time.sleep(1.0)

    raise TimeoutError("job did not complete within 120 s")

MCP Tool Example

Wrap POST /context as a Model Context Protocol tool to give any LLM a sense of place before inference:

# MCP tool definition
{
  "name": "get_location_context",
  "description": "Get rich geospatial context for a coordinate: address, timezone, weather, POI profile.",
  "input_schema": {
    "type": "object",
    "properties": {
      "lat": { "type": "number", "description": "Latitude" },
      "lon": { "type": "number", "description": "Longitude" }
    },
    "required": ["lat", "lon"]
  }
}

# Handler: POST /context → poll /jobs/{id} → return result as tool output

Pricing

The free tier requires no credit card. Overage is billed at the per-request rate implied by the plan price after subtracting the 3,000 free requests included in all tiers.