# Geocode AI: full reference

> Look up any administrative boundary in the world (country, state, county, city, district, postcode) by name or point and get its polygon in one call, or describe an area in plain language and get a validated polygon back. REST, MCP, CLI and plugins for Claude and Codex.

## How to use it (also the MCP server's instructions)

Geocode AI. Boundaries and areas API for every place on Earth. Administrative boundaries come from OpenStreetMap and are cached, so repeat lookups are instant.

Workflow:
1. A named place (country, state, county, city, district, postcode): search_boundaries with the name (add the country or parent to disambiguate), pick the result whose admin level and parents match, then get_boundary with its id for the polygon. Never guess an id.
2. A coordinate: reverse_boundaries returns every boundary containing it, country down to neighbourhood.
3. Everything inside a boundary (states of a country, counties of a state): list_children with the parent's id.
4. Which zone each of many points falls in: contains_points (one batch, not one call per point).
5. Several boundaries as one shape: union_boundaries with their ids.
6. A described area that is not one named place ("the Bay Area minus San Francisco", a service area clause from a contract): create_area with the text. It runs an AI agent for 30 s to a few minutes and costs 50 units, so use it only when search + get cannot answer.
7. Missing feature or a bug: list_feedback, then upvote_feedback a match, else (with the human's OK) request_feature or report_issue. The board is public: no keys or personal data.

Boundary ids are r<OSM relation id> (r396499) or w<way id>; R62422, relation/62422 and osm.org URLs are accepted on input, the canonical form comes back. Reuse ids already in the conversation.

Costs: one unit per boundary geometry, reverse lookup or point batch; searching and browsing are free; a described area is 50 units. The Free plan includes 1,000 units a month. On a 402 (quota) stop and tell the human; never upgrade a plan. get_pricing has the current plans.

Without a key only the public tools work (20 calls a minute per IP). A free key (geo_…) from https://geo-coder-service.vercel.app/dashboard or `npx @meterapp/geocode login` unlocks the rest.

Results are GeoJSON (WGS84, lon/lat order). When you show a polygon to a human, say which boundary it is (name, admin level, parent) so they can confirm it is the right one.

Tools:
- search_boundaries (free, no key needed): Search boundaries.
- get_boundary (1 unit, no key needed): Get boundary polygon.
- export_boundary (1 unit): Export boundary file.
- reverse_boundaries (1 unit): Boundaries at a point.
- list_children (free, no key needed): List subdivisions.
- contains_points (units vary with the input): Points in boundary.
- union_boundaries (units vary with the input): Merge boundaries.
- create_area (50 units): Create area from a description.
- get_account (free): Get account.
- update_profile (free): Update profile.
- get_usage (free): Get usage.
- list_api_keys (free): List API keys.
- create_api_key (free): Create API key.
- revoke_api_key (free): Revoke API key.
- get_email_preferences (free): Get email preferences.
- update_email_preferences (free): Update email preferences.
- list_feedback (free, no key needed): List feature requests and issues.
- get_feedback (free, no key needed): Get a feature request or issue.
- request_feature (free): Request a feature.
- report_issue (free): Report an issue.
- upvote_feedback (free): Upvote a feature request or issue.
- remove_feedback_vote (free): Remove an upvote.
- comment_on_feedback (free): Comment on a feature request or issue.
- get_pricing (free, no key needed): Get plans and prices.

REST: https://geo-coder-service.vercel.app/openapi.json · Docs for agents: https://geo-coder-service.vercel.app/llms.txt

## Connect

- MCP (Claude Code): `claude mcp add --transport http geocode https://geo-coder-service.vercel.app/mcp --header "Authorization: Bearer $GEOCODE_API_KEY"`
- MCP (Claude.ai / ChatGPT connector, OAuth sign-in): https://geo-coder-service.vercel.app/mcp?auth=required
- MCP (stdio, any host): `npx -y @meterapp/geocode mcp`
- Claude Code plugin: `/plugin marketplace add MeterApp/geocode-plugins` then `/plugin install geocode@geocode`
- Codex plugin: `codex plugin marketplace add MeterApp/geocode-plugins`
- CLI: `npx @meterapp/geocode login`, then `geocode --help`; `geocode install` writes MCP config for Claude Code, Codex and Cursor

## Conventions

- Every op has an RPC route, `POST /v1/ops/{name}` with the input as JSON, and most have a resource route; both take the same input. GET routes take the input as query parameters (or `?input=<url-encoded JSON>`).
- MCP tools, CLI commands and REST ops share names: the MCP tool `get_boundary` is `POST /v1/ops/get_boundary` and `geocode get-boundary`.
- Errors are RFC 9457 `application/problem+json` with `code`, `detail` and `request_id`. 400 invalid_input, 401 unauthorized/invalid_key, 402 quota_exceeded, 404 not_found, 429 rate_limited (see `retry_after`).
- Rate limits come back as `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers.
- Coordinates are WGS84; GeoJSON is lon/lat order.

## Plans

- Free: $0, 1,000 units/month, 60 requests/minute. For prototypes and agents trying it out.
- Pro: $29/mo, 50,000 units/month, 600 requests/minute. For production apps.
- Business: $199/mo, 1,000,000 units/month, 3,000 requests/minute. For high-volume pipelines and bulk exports.
- Enterprise: custom, unlimited units, 10,000 requests/minute. Self-hosted data, SLAs and custom boundary sets.

## Ops

### search_boundaries: Search boundaries

Finds administrative boundaries (countries, states, counties, cities, districts) and postcode areas by name, in any language. Filter by country, kind or admin_level; bias toward a point with near. Free and public. Returns candidates with id, kind, admin_level, country, parents, bbox, centroid and population, but no polygon: pass the id to get_boundary for that.

Cost: free. No key needed. Read-only.
Routes: `GET /v1/boundaries/search`, `POST /v1/ops/search_boundaries`. MCP tool `search_boundaries`. CLI `geocode search-boundaries`.

Input:
- `q` (string, required): A place name, e.g. "Berlin", "Alameda County", "75011".
- `country` (string, optional): Limit to countries: ISO 3166-1 alpha-2, comma-separated (e.g. US or de,at,ch).
- `kind` ("country" | "state" | "region" | "province" | "county" | "district" | "municipality" | "city" | "borough" | "ward" | "neighbourhood" | "postal_code", optional): Only this kind (normalized across countries): country, state, region, province, county, district, municipality, city, borough, ward, neighbourhood, postal_code.
- `admin_level` (integer, optional): Only this OSM admin_level (2 = country; meaning varies by country below that).
- `near` (string, optional): lat,lon to prefer results near, e.g. 37.77,-122.42.
- `limit` (integer, optional, default 10): At most this many results (1–40, default 10).

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/boundaries/search?q=Alameda%20County&country=US"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/search_boundaries" \
  -H "Content-Type: application/json" \
  -d '{"q":"Alameda County","country":"US"}'
```

### get_boundary: Get boundary polygon

Returns one boundary as a GeoJSON Feature: its polygon at a chosen detail plus properties (name, kind, admin_level, parents, bbox, area_km2, population, wikidata). Fetched from OpenStreetMap the first time anyone asks, then served from cache. Costs 1 unit; detail=low is also public without a key (for map previews). include=parents adds the full hierarchy, include=children the direct subdivisions. If the polygon is too big for one response, geometry is null and download_url points to the file.

Cost: 1 unit. No key needed. Read-only.
Routes: `GET /v1/boundaries/{id}`, `POST /v1/ops/get_boundary`. MCP tool `get_boundary`. CLI `geocode get-boundary`.

Input:
- `id` (string, required): Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.
- `detail` ("low" | "medium" | "high" | "full", optional): Simplification relative to the boundary's size: low (~1,000 points across; the default without a key), medium (the default with a key, ~5,000), high (~25,000), full (unsimplified OSM).
- `precision` (integer, optional): Coordinate decimals (3–7). Defaults to what the detail level needs.
- `include` (array, required): Comma-separated extras: parents, children.

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/boundaries/r62422?detail=low&include=%5B%22parents%22%5D"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/get_boundary" \
  -H "Content-Type: application/json" \
  -d '{"id":"r62422","detail":"low","include":["parents"]}'
```

### export_boundary: Export boundary file

Builds a boundary's polygon as a file (geojson, kml, wkt, svg or gml) at a detail level and returns a permanent public URL on our CDN; the REST route redirects straight to it. Use it for large polygons, GIS tools and bulk downloads. Costs 1 unit; each file is built once and then shared.

Cost: 1 unit. Needs an API key or OAuth token. Read-only.
Routes: `GET /v1/boundaries/{id}.{format}`, `POST /v1/ops/export_boundary`. MCP tool `export_boundary`. CLI `geocode export-boundary`.

Input:
- `id` (string, required): Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.
- `format` ("geojson" | "kml" | "wkt" | "svg" | "gml", optional, default "geojson"): geojson (a Feature), kml, wkt, svg or gml.
- `detail` ("low" | "medium" | "high" | "full", optional, default "medium"): Simplification relative to the boundary's size: low (~1,000 points across, maps and previews), medium (default, ~5,000), high (~25,000), full (unsimplified OSM).

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/boundaries/r62422.kml?detail=medium" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/export_boundary" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"r62422","format":"kml","detail":"medium"}'
```

### reverse_boundaries: Boundaries at a point

Every administrative boundary containing a point, country first down to the smallest district, plus postcode areas. Use it to tag an address, a store or a delivery with its country, state, county and city in one call. Costs 1 unit. Returns ids you can pass to get_boundary.

Cost: 1 unit. Needs an API key or OAuth token. Read-only.
Routes: `GET /v1/boundaries/reverse`, `POST /v1/ops/reverse_boundaries`. MCP tool `reverse_boundaries`. CLI `geocode reverse-boundaries`.

Input:
- `lat` (number, required): Latitude, -90 to 90.
- `lon` (number, required): Longitude, -180 to 180.

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/boundaries/reverse?lat=52.52&lon=13.405" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/reverse_boundaries" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":52.52,"lon":13.405}'
```

### list_children: List subdivisions

The direct subdivisions of a boundary: a country's states, a state's counties, a city's districts. Without admin_level it picks the next level that exists. Free and public. Use it to build drill-down pickers or to cover a region with its parts.

Cost: free. No key needed. Read-only.
Routes: `GET /v1/boundaries/{id}/children`, `POST /v1/ops/list_children`. MCP tool `list_children`. CLI `geocode list-children`.

Input:
- `id` (string, required): Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.
- `admin_level` (integer, optional): Subdivision admin_level; default: the next level below the parent that exists.

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/boundaries/r165475/children"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/list_children" \
  -H "Content-Type: application/json" \
  -d '{"id":"r165475"}'
```

### contains_points: Points in boundary

Tests up to 10,000 points ([lon, lat] pairs) against one boundary and returns a boolean per point plus the inside count. Use it for geofencing, service-area checks and filtering customer lists. Costs 1 unit per 1,000 points.

Cost: units vary with the input. Needs an API key or OAuth token. Read-only.
Routes: `POST /v1/boundaries/{id}/contains`, `POST /v1/ops/contains_points`. MCP tool `contains_points`. CLI `geocode contains-points`.

Input:
- `id` (string, required): Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.
- `points` (array, required): Points as [lon, lat] (GeoJSON order).

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/boundaries/r62422/contains" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"points":[[13.405,52.52],[2.35,48.86]]}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/contains_points" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"r62422","points":[[13.405,52.52],[2.35,48.86]]}'
```

### union_boundaries: Merge boundaries

Merges boundaries into one polygon: the union of include minus the union of exclude (e.g. three counties minus one city). Use it for sales territories, delivery zones and service areas. Up to 50 boundaries; costs 1 unit per boundary. Returns a GeoJSON Feature with area_km2. To describe an area in words instead, use create_area.

Cost: units vary with the input. Needs an API key or OAuth token. Read-only.
Routes: `POST /v1/boundaries/union`, `POST /v1/ops/union_boundaries`. MCP tool `union_boundaries`. CLI `geocode union-boundaries`.

Input:
- `include` (array, required): Boundary ids to merge.
- `exclude` (array, optional, default []): Boundary ids to cut out.
- `detail` ("low" | "medium" | "high" | "full", optional, default "medium"): Simplification relative to the boundary's size: low (~1,000 points across, maps and previews), medium (default, ~5,000), high (~25,000), full (unsimplified OSM).

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/boundaries/union" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include":["r396499","r396479"],"exclude":["r2833530"],"detail":"low"}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/union_boundaries" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include":["r396499","r396479"],"exclude":["r2833530"],"detail":"low"}'
```

### create_area: Create area from a description

Turns a plain-language description of an area ("Alameda and Contra Costa counties excluding San Jose, plus SFO") or wording from a contract or policy into one validated land-only polygon. An AI agent plans includes/excludes from real administrative boundaries; you get GeoJSON plus each part's source, or a 422 explaining what could not be mapped. Takes 30 s to a few minutes. For a single named place use search_boundaries + get_boundary instead: it is instant and costs 1 unit.

Cost: 50 units. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/areas`, `POST /v1/ops/create_area`. MCP tool `create_area`. CLI `geocode create-area`.

Input:
- `text` (string, required): The description of the area.
- `country` (string, optional): ISO 3166-1 alpha-2 country code, if known.
- `source` (string, optional): Who wrote the description (agency, company). Optional context.
- `seed` (object, optional): A point that must be inside the area.

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/areas" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Alameda and Contra Costa counties, excluding the City of Oakland","country":"US"}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/create_area" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Alameda and Contra Costa counties, excluding the City of Oakland","country":"US"}'
```

### get_account: Get account

The signed-in account: email, plan, this month's usage against the plan's limit, and rate limit. Call it to check remaining quota before a large batch.

Cost: free. Needs an API key or OAuth token. Read-only.
Routes: `GET /v1/account`, `POST /v1/ops/get_account`. MCP tool `get_account`. CLI `geocode get-account`.

Input: none.

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/account" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/get_account" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### update_profile: Update profile

Sets the account's name, company and use case (what you are building). Send only the fields to change; an empty string clears one. Free. Returns the updated profile.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/account`, `POST /v1/ops/update_profile`. MCP tool `update_profile`. CLI `geocode update-profile`.

Input:
- `name` (string, optional): Your name, used in emails ("Hey {first name},").
- `company` (string, optional): Company or project.
- `use_case` (string, optional): What you are building with boundaries and areas.

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/account" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","company":"Analytical Engines","use_case":"Delivery zones from postcodes"}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/update_profile" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","company":"Analytical Engines","use_case":"Delivery zones from postcodes"}'
```

### get_usage: Get usage

Daily usage for the last N days (default 30), by op, with cache hit counts. Use it to explain a bill or spot a runaway client.

Cost: free. Needs an API key or OAuth token. Read-only.
Routes: `GET /v1/usage`, `POST /v1/ops/get_usage`. MCP tool `get_usage`. CLI `geocode get-usage`.

Input:
- `days` (integer, optional, default 30): How many days back.

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/usage" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/get_usage" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_api_keys: List API keys

The account's API keys (prefix, name, last use; never the secret).

Cost: free. Needs an API key or OAuth token. Read-only.
Routes: `GET /v1/keys`, `POST /v1/ops/list_api_keys`. MCP tool `list_api_keys`. CLI `geocode list-api-keys`.

Input:
- `include_revoked` (boolean, optional, default false)

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/keys" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/list_api_keys" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### create_api_key: Create API key

Creates an API key and returns the secret once. Store it in an environment variable (GEOCODE_API_KEY); it cannot be shown again.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/keys`, `POST /v1/ops/create_api_key`. MCP tool `create_api_key`. CLI `geocode create-api-key`.

Input:
- `name` (string, optional, default "Default key"): A label, e.g. the app or environment.

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/keys" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/create_api_key" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}'
```

### revoke_api_key: Revoke API key

Revokes an API key by id. Requests with it fail with 401 immediately.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `DELETE /v1/keys/{id}`, `POST /v1/ops/revoke_api_key`. MCP tool `revoke_api_key`. CLI `geocode revoke-api-key`.

Input:
- `id` (string, required): The key's id from list_api_keys.

```bash
curl -sS -X DELETE "https://geo-coder-service.vercel.app/v1/keys/%3Cid%3E" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/revoke_api_key" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_email_preferences: Get email preferences

Which automated emails the account receives: the global subscription and one switch per kind (getting-started notes, first boundary, usage milestones, quota warnings, check-ins, monthly digest). Free. Sign-in codes are always sent.

Cost: free. Needs an API key or OAuth token. Read-only.
Routes: `GET /v1/account/email-preferences`, `POST /v1/ops/get_email_preferences`. MCP tool `get_email_preferences`. CLI `geocode get-email-preferences`.

Input: none.

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/account/email-preferences" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/get_email_preferences" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### update_email_preferences: Update email preferences

Turns automated emails on or off: `subscribed: false` stops all of them (the same as the unsubscribe link), `subscribed: true` resubscribes, and `kinds` switches individual kinds. Kinds not named keep their setting. Free. Returns the preferences after the change.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/account/email-preferences`, `POST /v1/ops/update_email_preferences`. MCP tool `update_email_preferences`. CLI `geocode update-email-preferences`.

Input:
- `subscribed` (boolean, optional): false = unsubscribe from every automated email; true = resubscribe.
- `kinds` (object, optional): Per-kind switches, e.g. {"digest": false}.

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/account/email-preferences" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kinds":{"digest":false}}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/update_email_preferences" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kinds":{"digest":false}}'
```

### list_feedback: List feature requests and issues

The public feedback board: feature requests and issue reports with their status and upvotes, most upvoted first. Free and needs no key (with a key, each item says whether you voted). Call it before request_feature or report_issue to find an existing item to upvote instead of filing a duplicate, or when the human asks what is planned.

Cost: free. No key needed. Read-only.
Routes: `GET /v1/feedback`, `POST /v1/ops/list_feedback`. MCP tool `list_feedback`. CLI `geocode list-feedback`.

Input:
- `kind` ("feature" | "issue" | "all", optional, default "all"): feature = feature requests, issue = bug reports.
- `status` ("active" | "all" | "open" | "planned" | "in_progress" | "done" | "declined" | "duplicate", optional, default "active"): active = open, planned or in progress.
- `sort` ("top" | "new", optional, default "top"): top = most upvoted, new = most recent.
- `q` (string, optional): Words to find in the title.
- `mine` (object, optional): Only items you filed (needs a key).
- `limit` (integer, optional, default 20): Page size, at most 100.
- `offset` (integer, optional, default 0)

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/feedback?kind=feature&q=postcode"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/list_feedback" \
  -H "Content-Type: application/json" \
  -d '{"kind":"feature","q":"postcode"}'
```

### get_feedback: Get a feature request or issue

One feedback item with its status, upvotes and comments. Free and needs no key.

Cost: free. No key needed. Read-only.
Routes: `GET /v1/feedback/{id}`, `POST /v1/ops/get_feedback`. MCP tool `get_feedback`. CLI `geocode get-feedback`.

Input:
- `id` (integer, required): The item's id from list_feedback, request_feature or report_issue (e.g. 42).

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/feedback/1"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/get_feedback" \
  -H "Content-Type: application/json" \
  -d '{"id":1}'
```

### request_feature: Request a feature

Files a feature request on the public board and upvotes it for you. Use it when the human wants something the API cannot do yet (a boundary type, export format, op or option). Check list_feedback first and upvote an existing request instead of filing a duplicate. Free; needs a key; 10 new items per account a day. Returns the item and similar existing requests. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/feedback/features`, `POST /v1/ops/request_feature`. MCP tool `request_feature`. CLI `geocode request-feature`.

Input:
- `title` (string, required): What you want, in one line.
- `details` (string, optional, default ""): Why you need it and what you are building; concrete examples help it get planned.

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/feedback/features" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Export boundaries as Shapefile","details":"Our GIS team imports zones into ArcGIS, which wants .shp."}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/request_feature" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Export boundaries as Shapefile","details":"Our GIS team imports zones into ArcGIS, which wants .shp."}'
```

### report_issue: Report an issue

Reports a problem on the public board: a failing or wrong API call (pass its request_id from the X-Request-Id header or the error's request_id, and the op), a wrong or missing boundary, a docs error, or anything else broken. Check list_feedback with kind=issue first and upvote a matching report instead. Free; needs a key; 10 new items per account a day. Only you see the request_id. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/feedback/issues`, `POST /v1/ops/report_issue`. MCP tool `report_issue`. CLI `geocode report-issue`.

Input:
- `title` (string, required): What is wrong, in one line.
- `details` (string, optional, default ""): What you did, what you expected and what happened (status, error code, boundary id).
- `request_id` (string, optional): The request_id of the failing call, if there was one.
- `op` (string, optional): The op the failing call used, e.g. get_boundary.

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/feedback/issues" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"get_boundary returns 404 for r62422","details":"Berlin by relation id: 404 not_found since this morning.","op":"get_boundary"}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/report_issue" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"get_boundary returns 404 for r62422","details":"Berlin by relation id: 404 not_found since this morning.","op":"get_boundary"}'
```

### upvote_feedback: Upvote a feature request or issue

Adds your upvote to a feature request or issue; votes decide what gets built and fixed first. Idempotent: one vote per account. A vote on a duplicate goes to the original. Free; needs a key. Returns the item with its new vote count.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/feedback/{id}/vote`, `POST /v1/ops/upvote_feedback`. MCP tool `upvote_feedback`. CLI `geocode upvote-feedback`.

Input:
- `id` (integer, required): The item's id from list_feedback, request_feature or report_issue (e.g. 42).

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/feedback/1/vote" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/upvote_feedback" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1}'
```

### remove_feedback_vote: Remove an upvote

Takes back your upvote on a feature request or issue. Free; needs a key. Returns the item with its new vote count.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `DELETE /v1/feedback/{id}/vote`, `POST /v1/ops/remove_feedback_vote`. MCP tool `remove_feedback_vote`. CLI `geocode remove-feedback-vote`.

Input:
- `id` (integer, required): The item's id from list_feedback, request_feature or report_issue (e.g. 42).

```bash
curl -sS -X DELETE "https://geo-coder-service.vercel.app/v1/feedback/1/vote" \
  -H "Authorization: Bearer $GEOCODE_API_KEY"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/remove_feedback_vote" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1}'
```

### comment_on_feedback: Comment on a feature request or issue

Adds context to an existing feature request or issue: your use case, another failing request, a workaround. Prefer it (with upvote_feedback) over filing a near-duplicate. Free; needs a key; 50 comments per account a day. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.

Cost: free. Needs an API key or OAuth token. Changes state.
Routes: `POST /v1/feedback/{id}/comments`, `POST /v1/ops/comment_on_feedback`. MCP tool `comment_on_feedback`. CLI `geocode comment-on-feedback`.

Input:
- `id` (integer, required): The item's id from list_feedback, request_feature or report_issue (e.g. 42).
- `body` (string, required): The comment.

```bash
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/feedback/1/comments" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Same for us: we need this for French départements."}'
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/comment_on_feedback" \
  -H "Authorization: Bearer $GEOCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1,"body":"Same for us: we need this for French départements."}'
```

### get_pricing: Get plans and prices

The plans (monthly price, included units, rate limit) and what each kind of call costs in units. Free and needs no key. Call it before a large batch, or when the human asks what something costs; never quote prices from memory.

Cost: free. No key needed. Read-only.
Routes: `GET /v1/pricing`, `POST /v1/ops/get_pricing`. MCP tool `get_pricing`. CLI `geocode get-pricing`.

Input: none.

```bash
curl -sS "https://geo-coder-service.vercel.app/v1/pricing"
# RPC form, same input:
curl -sS -X POST "https://geo-coder-service.vercel.app/v1/ops/get_pricing" \
  -H "Content-Type: application/json" \
  -d '{}'
```