Geocode AI

View saved version →

---
name: geocode-api
description: Write code that calls the Geocode AI API - REST (fetch, curl, Python requests) with the OpenAPI spec, the @meterapp/geocode CLI in scripts and CI, or the hosted MCP server from an agent framework. Covers auth with geo_ keys kept server-side, the resource and RPC routes, reading the op catalog, RFC 9457 errors, rate limit headers, batching points, caching polygons you already fetched, and the device sign-in for tools. Use when implementing or reviewing code that talks to Geocode AI; do not use for answering a boundary question in chat (geocode-boundaries) or building a described area (geocode-areas).
---

# Geocode AI from code

Base URL: `https://geocodeai.dev` (read `GEOCODE_BASE_URL` in
your code so it can change). Machine-readable references, always current:

- `GET /v1`: every op with its input JSON Schema, cost and routes.
- `/openapi.json`: OpenAPI 3.1 (generate a client from it).
- `/llms-full.txt`: every op with curl examples.

## Auth

`Authorization: Bearer geo_…` (or `X-Api-Key: geo_…`). Create keys in the
dashboard or with `npx @meterapp/geocode keys create <name>`. Keep keys in an
environment variable (`GEOCODE_API_KEY`) on the server; never ship one to a
browser or commit it. Public ops work without a key at a low per-IP rate.

## Routes

Every op has two equivalent routes with the same input:

- Resource route from the catalog (`http` field), e.g. `GET /v1/account`,
  `POST /v1/areas`. GET inputs are query parameters (or `?input=<json>`).
- RPC route `POST /v1/ops/{name}` with the input as a JSON body. Simplest to
  generate: one function for every op.

```ts
async function geocode<T>(op: string, input: object): Promise<T> {
  const res = await fetch(`${process.env.GEOCODE_BASE_URL ?? "https://geocodeai.dev"}/v1/ops/${op}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.GEOCODE_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify(input),
  });
  if (!res.ok) {
    const problem = await res.json(); // RFC 9457: { code, detail, request_id, ... }
    throw new Error(`${problem.code}: ${problem.detail} (request ${problem.request_id})`);
  }
  return res.json() as Promise<T>;
}
```

## Errors and limits

Errors are `application/problem+json` with `code`, `detail` and `request_id`:
400 `invalid_input` (with `issues`), 401 `unauthorized`/`invalid_key`, 402
`quota_exceeded` (stop and explain the current entitlement limit; do not promote an upgrade), 404 `not_found`, 422 `could_not_map` (areas), 429
`rate_limited` (wait `retry_after` seconds). Responses carry `RateLimit-Limit`,
`RateLimit-Remaining` and `RateLimit-Reset`; back off on 429 instead of
retrying hot. Retry 5xx once with jitter; never retry 4xx unchanged.

## Doing it efficiently

- Store boundary ids (`r396499`) in your data, not names; fetch by id.
- Cache polygons you fetched; boundaries change rarely.
- Test many points with one `contains_points` call, not a loop.
- `create_area` is slow (up to minutes) and costs much more than a lookup: run
  it once, store the polygon, re-run only when the description changes. Use only the connected account’s existing entitlements.

## CLI in scripts and CI

```bash
export GEOCODE_API_KEY=geo_…
npx @meterapp/geocode search "Alameda County" --json | jq '.'
npx @meterapp/geocode call get_boundary --input '{"id":"r396499"}' > alameda.json
```

Exit codes: 2 usage, 3 auth, 4 quota or rate limit, 1 anything else. For a
tool that signs a person in, use the device flow the CLI uses:
`POST /v1/auth/device`, have them open `verification_uri_complete`, then poll
`POST /v1/auth/device/token` every `interval` seconds until it returns the key.

## Feature requests and issue reports

The feedback board is part of the API, so an app or agent can file from where
the problem happens. `GET /v1/feedback` (public; `kind`, `status`, `sort`,
`q`) lists requests and issues by upvotes; `POST /v1/feedback/features` and
`POST /v1/feedback/issues` file one (`title`,

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: geocode-areas
description: Turn a plain-language description of an area into one validated polygon with Geocode AI's create_area - "Alameda and Contra Costa counties excluding Oakland", "the Bay Area minus San Francisco, plus SFO", a delivery or service area, or wording pasted from a contract, policy, license or regulation. An AI agent composes includes and excludes from real administrative boundaries and returns GeoJSON plus where each part came from, or explains what it could not map. Use when the area is not a single named place; for one named place use geocode-boundaries (instant and far cheaper).
---

# Geocode AI: natural-language areas

`create_area` (MCP tool, `POST /v1/areas`, or `geocode area "<text>"`) runs an
AI agent that plans the area from real boundaries, builds it, and validates the
result (land only, the parts it names, nothing it excludes).

## When to use it

- The area combines or subtracts places: "A and B counties except the city of C".
- The text comes from a document: a contract's territory clause, a regulator's
  service area, a franchise or license region. Pass the wording verbatim.
- One named place is **not** a reason: `search_boundaries` + `get_boundary` is
  instant and costs one unit.

## How to call it

- `text`: the description, verbatim (up to a few thousand characters).
- `country`: ISO alpha-2 code when known (`"US"`). It removes ambiguity.
- `source`: who wrote the text (agency, company), when it helps.
- `seed`: `{ "lat": …, "lon": … }`, a point that must be inside the area, when
  the human gave one.

It takes 30 seconds to a few minutes. Tell the human it is running; do not
retry while it runs. It consumes more account resources than a lookup. Confirm with the human before running several; use only existing entitlements.

## Results

- Success: a GeoJSON polygon plus the parts used (each boundary included or
  excluded and why). Summarize the parts so the human can check the
  interpretation, and save the GeoJSON to a file rather than pasting it.
- `could_not_map` (422): the detail says which phrase could not be resolved or
  was ambiguous. Ask the human to clarify that phrase, then run it again. Never
  return a partial or guessed shape as if it were the answer.
- `quota_exceeded` (402): stop and tell the human.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: geocode-boundaries
description: Look up administrative boundaries anywhere in the world with Geocode AI and work with their polygons - find a country, state, county, city, district or postcode by name, get its polygon as GeoJSON, find every boundary containing a coordinate (reverse), list what is inside a boundary (children), check which zone each of many points falls in (contains), and merge several boundaries into one shape (union). Use for "get the boundary/polygon/shape of X", "which county is this point in", "list the counties of Y", "is this address inside Z", service areas built from named places, and map data for a page or a notebook; do not use for a described area that is not one named place (geocode-areas) or for writing code against the API (geocode-api).
---

# Geocode AI: boundaries

Tools come from the `geocode` MCP server (or the `geocode` CLI). Boundaries are
OpenStreetMap administrative areas, cached by Geocode AI, so repeat lookups are
instant.

## Workflow

1. **Named place → search, then get.** Call `search_boundaries` with the name.
   Add the country or a parent to the query when the name is ambiguous
   ("Alameda County, California", "Paris, France"). Pick the result whose admin
   level and parents match what the human meant, then call `get_boundary` with
   its `id` for the polygon. Never guess or construct an id.
2. **A coordinate → reverse.** `reverse_boundaries` with `lat` and `lon`
   returns every boundary containing the point, from country down to
   neighbourhood. Use it for "which city/county/state is this in".
3. **Inside a boundary → children.** `list_children` with the parent's id
   (states of a country, counties of a state, districts of a city).
4. **Many points → contains.** `contains_points` takes a batch of points in one
   call. Never loop one call per point.
5. **Several boundaries as one shape → union.** `union_boundaries` with the ids
   you got from search or children.
6. **Files.** `export_boundary` (or `get_boundary` with a `format`) returns other
   formats when the human wants a file.

## Ids

Ids are `r<OSM relation id>` (`r396499`) or `w<way id>`. `R62422`,
`relation/62422`, `-62422` and osm.org URLs are accepted; the canonical form
comes back. Reuse ids already in the conversation instead of searching again.

## Costs and limits

Searching and browsing (search, children) are free. A polygon, a reverse lookup
or a point batch costs one unit. Use the connected account’s existing entitlements; do not display plans or pricing. Without a key only public tools work. If a call
returns `unauthorized`, tell the human to connect their account (the MCP
server's sign-in, or `npx @meterapp/geocode login`). On `quota_exceeded` stop
and tell the human. Do not create checkout links, promote upgrades, or initiate subscriptions.

## Presenting results

- Say which boundary you used: name, admin level and parent ("Alameda County,
  California, United States, admin level 6"), so the human can catch a wrong
  match before using it.
- GeoJSON is WGS84 in lon/lat order. Do not paste a huge polygon into chat
  unless asked; save it to a file (`alameda.geojson`) or summarize it (bbox,
  area, number of parts).
- If no result matches, say so and show the closest candidates. Never
  substitute a different place silently.

## When the API falls short

If the human needs something the tools cannot do, or a call fails in a way
that looks like our bug (a 5xx, a boundary that is wrong or missing), use the
public feedback board. `list_feedback` first; if a matching item exists,
`upvote_feedback` it and add the use case with `comment_on_feedback`.
Otherwise, with the human's go-ahead, `request_feature` or `report_issue`
(pass the failing call's `request_id` and `op`). All free; the board is
public, so never include keys, personal or customer data.

## CLI equivalents

```bash
npx @meterapp/geocode search "Alameda County"
npx @meterapp/geocode get r396499 --format geojson > alameda.geojson
npx @met

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: geocode-feedback
description: Report a Geocode AI bug with the failing request attached, request a missing feature, upvote or comment on what others asked for, follow up on what the human filed, and post or read reviews - report_issue (with the request_id from the failed call), request_feature, upvote_feedback, comment_on_feedback, list_feedback, get_feedback, list_my_feedback, submit_review, list_reviews. Use after a Geocode AI call fails in a way that looks like our bug (5xx, a wrong or missing boundary), when the human wishes the API did something it cannot, asks what is planned, or wants to rate the product; do not use for ordinary lookups (geocode-boundaries), described areas (geocode-areas) or purchases.
---

# Feedback, issues and reviews

Everything here is free. Filing, voting and commenting need a key (or a
connected account) so each vote is one account; reading needs none. Ask the
human before you file anything on their behalf, and never invent a review.

## A call failed and it looks like our bug

Every response carries `X-Request-Id`; every error body and every MCP tool
error has a `request_id`, and tool errors say when a report is worth filing.

1. Tell the human what failed.
2. `report_issue` with:
   - `title`: what went wrong, in one line;
   - `details`: what you did, expected and got;
   - `request_id` and `op` of the failing call;
   - `context`: `boundary_id`, `query`, `error` (`{code, status, message}`),
     `client` and `version` when you have them. A request id must be one of the
     human's own calls (`not_your_request` otherwise).
3. If the result has `filed: false`, it found `similar` issues: if one is the
   same problem, `upvote_feedback` it and `comment_on_feedback` with the new
   request id; otherwise call again with `force: true`.

Issues are private to the reporter and the Geocode AI team. The human gets an
email with the reference number and another on every status change.

From a terminal: `npx @meterapp/geocode feedback report "<title>" --last`
attaches the last failed CLI call (request id, op, error).

## The human wants something the API cannot do

1. `list_feedback` with `kind: "feature"` and a few words in `q`.
2. A match: `upvote_feedback` (and `comment_on_feedback` with their use case).
3. No match: `request_feature` with `title` and `details` (what they are
   building). It also checks for similar requests and files nothing when it
   finds some; pass `force: true` when theirs is different.

Feature requests and comments are public (shown with a first name, never an
email): no keys, personal data or customer data in them.

## Following up

- `list_my_feedback`: what the human filed (with private issues), what they
  follow, and their review, each with its status.
- `get_feedback` with an id: comments (official team responses are marked),
  and the timeline of status changes (`open → planned → in_progress → done`,
  or `declined`, or `duplicate` with the item it was merged into).
- `remove_feedback_vote` takes a vote back and stops that item's emails.

## Reviews

- `list_reviews`: the average, the distribution and published reviews with
  the team's replies (`sort`: `new`, `helpful`, `highest`, `lowest`).
- `submit_review` only with the human's own rating (1-5) and words: `title`,
  `likes`, `dislikes`, `body`, `use_case`, `display_name`, and
  `marketing_consent: true` only if they agree to be quoted. One review per
  account; submitting again edits it (once an hour). A review with links, or
  from an account under a day old, waits for a check (`status: pending`).

## Errors

- `401 unauthorized`: filing needs a key or a connected account.
- `429 rate_limited`: 10 new items and 50 comments a day per account; one
  review edit an hour.
- `404 not_found`: no such item, or a private issue that is not the human's.
- `403 not_your_request`: the request id was made with another account.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: geocode-teams
description: Work inside a Geocode AI organization - tell which organization a key or connection acts in and the caller's role (get_account, list_orgs), who is in it and which teams exist (list_members, list_teams), save a boundary export to the organization's shared file library (save_file), find files teammates saved (list_files, get_file) and share a file with a team or a person at read, write or admin access (share_file, unshare_file, update_file). Use for "share this boundary with the GIS team", "what files has my team saved", "who is in our account", "which org am I in", a 403 forbidden; do not use for looking boundaries up (geocode-boundaries), purchases, or inviting and removing people, which a human does on the dashboard.
---

# Organizations, teams and the file library

Every Geocode AI account is an organization. A key, the CLI or a connected
app acts in one organization: its plan, monthly units, API keys and file
library are shared by everyone in it. Each person has a role:

| role | can |
| --- | --- |
| viewer | read files shared with the whole organization; nothing that costs units |
| member | use every API op, save files, create teams and their own API keys |
| admin | also invite and remove people, manage every key and team, billing |
| owner | also make admins and owners, transfer or delete the organization |

An API key acts with its creator's role (at most admin) and keeps working if
they leave. A solo account is a personal organization with one owner, so for
most people nothing changes.

## Where am I

- `get_account`: `org` (id, slug, name, personal), `role`, and the plan and
  units of that organization.
- `list_orgs`: every organization the person is in (with a key: just the key's).
  To act in another, the human approves a new key there (`geocode login`
  asks which organization) or connects the app again and picks it.

## Handing a boundary to the team

1. Find the boundary as usual (`search_boundaries`, then its id).
2. `list_files` first: someone may have saved it already; reuse that entry.
3. `save_file` with `{"boundary_id": "r62422", "format": "geojson",
   "detail": "medium"}` (1 unit). `visibility: "org"` (default) lets every
   member see it; `"restricted"` keeps it to the creator, admins and shares.
4. `list_teams` for the team's slug, then `share_file` with `{"id": "<file
   id>", "team": "gis", "access": "read"}` (or `"user": "<email>"` for one
   member from `list_members`). Sharing again changes the access.
5. Give the human the file's `url` (a permanent CDN link) and say who can see it.

`get_file` shows a file's shares when you can manage it; `unshare_file` removes
one by its grant id; `update_file` renames it or changes its visibility.

## When something is refused

- `403 forbidden` carries `required_role` or `required_access`: tell the human
  which role or share they need and that an admin changes it at
  `/dashboard/org`. Do not retry with another key.
- Inviting, removing members, changing roles, teams, transferring or deleting
  the organization are done by a person on the dashboard (`/dashboard/org`).
  No tool does them; never try to work around that.
- `list_invites` and `list_audit_log` are for admins: who was invited, and who
  changed what (members, roles, keys, billing, shares) and when.

From a terminal: `geocode whoami` names the organization and role;
`geocode orgs`, `geocode members`, `geocode teams`, `geocode files`,
`geocode save <id>` and `geocode share <file id> --team <slug>`.

Referenced files: 1 — file references are metadata, not package contents.