---
name: geolith-geocoding
description: Geocode with geolith — turn place names and addresses into coordinates, coordinates into addresses, and fetch place outlines, over REST or MCP. Use when a task needs latitude/longitude for a place, the address at a point, or a place's polygon.
---

# Geocode with geolith

geolith answers forward geocoding, autocomplete, structured address search, reverse geocoding and place lookup over OpenStreetMap and Overture Maps data. Answers are GeoJSON FeatureCollections (`features[].geometry.coordinates` is `[lon, lat]`; `properties.label` is a display string; `properties.gid` identifies the place).

## 1. Get a credential

Either:

- **API key** — sign up at https://console.geolith.app/signup, then create a key at https://console.geolith.app/dashboard/keys. Send it as `Authorization: Bearer gc_sk_…` or `?api_key=gc_sk_…`.
- **OAuth 2.1** — register as a client and get an access token for resource `https://api.geolith.app/mcp` (MCP) or `https://api.geolith.app` (REST) with scope `geocode`. The steps are in https://console.geolith.app/auth.md.

The Free plan allows 100,000 requests a month. Every geocoding call or tool call counts as one request. `X-Quota-Remaining` reports what is left.

## 2a. REST

| Task | Request |
| --- | --- |
| Search | `GET https://api.geolith.app/v1/search?text=gateway+of+india&size=3` |
| Autocomplete | `GET https://api.geolith.app/v1/autocomplete?text=koramang` |
| Structured | `GET https://api.geolith.app/v1/search/structured?locality=pune&country=IN` |
| Reverse | `GET https://api.geolith.app/v1/reverse?point.lat=18.5195&point.lon=73.8553` |
| Place + outline | `GET https://api.geolith.app/v1/place?ids=<gid>&geometry=true` |

Common filters: `size` (1–40), `layers` (venue, address, street, neighbourhood, locality, county, region, country…), `boundary.country` (ISO alpha-2), `focus.point.lat` / `focus.point.lon`. Full reference: https://docs.geolith.app/search/openapi.json (OpenAPI 3.1) and https://docs.geolith.app/search.

```bash
curl -H "Authorization: Bearer $GEOLITH_KEY" "https://api.geolith.app/v1/search?text=india+gate&size=1"
```

## 2b. MCP

Remote MCP server (Streamable HTTP): `https://api.geolith.app/mcp`. Authenticate with the same API key (`Authorization: Bearer gc_sk_…`) or an OAuth access token; an unauthenticated request gets a 401 whose `WWW-Authenticate` header points at the OAuth metadata.

Tools: `search`, `autocomplete`, `structured_search`, `reverse`, `place` (set `geometry: true` for outlines). Each returns the FeatureCollection as `structuredContent` and as JSON text.

## 2c. A2A

A2A 1.0 agent (JSON-RPC): `https://api.geolith.app/a2a`, card at `https://api.geolith.app/.well-known/agent-card.json`. Send `SendMessage` with a text part (a place name, or `"lat, lon"` to reverse-geocode) or a data part `{ "operation": "search", "params": { "text": "…" } }`.

## Rules

- Show "© OpenStreetMap contributors, Overture Maps Foundation" wherever results appear.
- Storing results permanently is allowed on every plan.
- Errors: 401 missing or invalid credential, 403 origin not allowed (publishable keys) or missing scope, 429 rate limit (`Retry-After`) or monthly quota used up.