# Geocode AI

> 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.

Base URL: https://geo-coder-service.vercel.app/. Auth: `Authorization: Bearer geo_…` (free key at https://geo-coder-service.vercel.app/dashboard). Public ops work without a key, 20 calls a minute per IP. One unit = one boundary geometry, reverse lookup or point batch; search and browsing are free; a described area costs 50 units.

## 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

## Reference

- [Full reference for agents](https://geo-coder-service.vercel.app/llms-full.txt): every op with input fields, costs and curl examples
- [OpenAPI 3.1](https://geo-coder-service.vercel.app/openapi.json): the REST API, generated from the same registry
- [Op catalog (JSON)](https://geo-coder-service.vercel.app/v1): every op with its input JSON Schema
- [MCP server card](https://geo-coder-service.vercel.app/.well-known/mcp.json)

## Boundaries

- search_boundaries (GET /v1/boundaries/search; free; no key): 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.
- get_boundary (GET /v1/boundaries/{id}; 1 unit; no key): 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.
- export_boundary (GET /v1/boundaries/{id}.{format}; 1 unit): 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.
- reverse_boundaries (GET /v1/boundaries/reverse; 1 unit): 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.
- list_children (GET /v1/boundaries/{id}/children; free; no key): 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.
- contains_points (POST /v1/boundaries/{id}/contains; units vary with the input): 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.
- union_boundaries (POST /v1/boundaries/union; units vary with the input): 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.

## Areas

- create_area (POST /v1/areas; 50 units): 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.

## Account

- get_account (GET /v1/account; free): 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.
- update_profile (POST /v1/account; free): 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.
- get_email_preferences (GET /v1/account/email-preferences; free): 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.
- update_email_preferences (POST /v1/account/email-preferences; free): 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.
- get_pricing (GET /v1/pricing; free; no key): 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.

## Usage

- get_usage (GET /v1/usage; free): 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.

## Keys

- list_api_keys (GET /v1/keys; free): The account's API keys (prefix, name, last use; never the secret).
- create_api_key (POST /v1/keys; free): Creates an API key and returns the secret once. Store it in an environment variable (GEOCODE_API_KEY); it cannot be shown again.
- revoke_api_key (DELETE /v1/keys/{id}; free): Revokes an API key by id. Requests with it fail with 401 immediately.

## Feedback

- list_feedback (GET /v1/feedback; free; no key): 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.
- get_feedback (GET /v1/feedback/{id}; free; no key): One feedback item with its status, upvotes and comments. Free and needs no key.
- request_feature (POST /v1/feedback/features; free): 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.
- report_issue (POST /v1/feedback/issues; free): 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.
- upvote_feedback (POST /v1/feedback/{id}/vote; free): 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.
- remove_feedback_vote (DELETE /v1/feedback/{id}/vote; free): Takes back your upvote on a feature request or issue. Free; needs a key. Returns the item with its new vote count.
- comment_on_feedback (POST /v1/feedback/{id}/comments; free): 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.

## 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.