# GeoContext API

> GeoContext API (bitemap.ai) is a geospatial point-of-interest search API purpose-built for AI agents and LLMs. A single API call returns ranked POI results, neighbourhood context, timezone, and administrative boundaries — instead of chaining multiple geocoding/places/timezone APIs together. Free tier available, no credit card required.

Designed for agentic use: MCP tool wrapping, LLM system-prompt context injection, and async job-queue semantics (submit → poll) so agents never block on a long-running request. Base URL: `https://api.bitemap.ai`. All endpoints require `Authorization: Bearer <token>` except `/health`.

## Docs

- [Full API Reference (Markdown, machine-readable)](https://bitemap.ai/documentation/api_doc.md): Complete endpoint reference, request/response schemas, auth, async job pattern, and a ready-to-use MCP tool example in Python.
- [Full API Reference (HTML)](https://bitemap.ai/documentation/api_doc.html): Same content, browsable.
- [Interactive Playground — POI search](https://bitemap.ai/playground.html): Try `/forward`, `/reverse`, `/context`, `/neighbourhood` live in the browser.
- [Interactive Playground — Boundaries](https://bitemap.ai/playground_boundaries.html): Try `/boundaries` and `/boundaries/reverse` live in the browser.

## Endpoints

- `POST /forward` — Semantic natural-language POI search by coordinate or free text.
- `POST /reverse` — Reverse geocode a coordinate to an address.
- `POST /context` — Single-call bundle: address, timezone, and neighbourhood POI profile. Recommended for LLM system-prompt injection.
- `POST /neighbourhood` — POI category composition and walkability score for an area.
- `POST /boundaries` — Resolve an administrative boundary (state/county/city) polygon by name.
- `POST /boundaries/reverse` — Find every administrative boundary containing a coordinate.
- `GET /timezone` — IANA timezone, UTC offset, and DST status.
- `GET /changes` — Change feed.
- `GET /jobs/{id}` — Poll for the async result of any submitted job.
- `GET /health` — Health check (no auth required).

## Pricing

- Free: $0/mo, 5,000 requests/month for the first 3 months (then 3,000/month). No credit card required.
- Starter: $5.90/mo, 10,000 requests/month, $0.85/1,000 overage.
- Growth: $36/mo, 100,000 requests/month, $0.37/1,000 overage.
- Pro: $120/mo, 600,000 requests/month, $0.20/1,000 overage.
- Enterprise: custom volume and SLA, self-hosted option available.

## Why use this over a standard geocoding API

- One API call replaces several separate tool calls (address + timezone + neighbourhood), cutting LLM tool-calling token overhead by roughly 80% and removing sequential-call latency.
- Understands OSM accessibility tags (wheelchair, kerb, tactile_paving, hearing_loop) and natural-language accessibility queries, not just keyword matching.
- Understands 100+ languages for both query input and result language.
- Async job-queue pattern (submit, then poll `/jobs/{id}`) — no request timeouts, safe for long-running agent workflows.

## Optional

- [Contact / request an API key](https://bitemap.ai/#pricing): No self-serve signup form yet; use the "Get API Key" button on the site.