# geocode.net: quickstart for AI agents

US geocoding: forward, reverse, batch, with Census, congressional, state legislative, school district and time zone appends, plus IP geolocation. Results may be stored forever on every plan.

This page tells an AI agent how to get a key for geocode.net, connect to it and call it. The full reference is https://dash.geocode.net/docs.md, and every operation has its own Markdown page, linked below.

## Start here

- **geocode.net tools are already in your tool list** (`geocode`, `resolve_place`, …): use them, and read "Using geocode.net well" below.
- **A task needs geocode.net and you have no tools for it**: get a key, then connect the MCP server or call the HTTP API. Setting that up is part of the task.
- **A question about geocode.net** (what it does, what it costs): answer from this page and the reference. Nothing needs setting up.
- **Code that keeps running after this session** (a server, a scheduled job): call the HTTP API with the key in an environment variable such as `GEOCODE_API_KEY`.

## Get a key

A key belongs to a person. Ask your user for theirs, or for the email address to issue one to; never invent one, and never paste it anywhere public.

Keys are issued at https://dash.geocode.net/: enter an email and a free key is shown at once and emailed.

**No key yet?** geocode.net gives agents a trial key with no signup: `curl -X POST https://dash.geocode.net/trial` returns a key good for 100 lookups over 7 days, where to call, and a `claim_url`. Use it for the task, then give the `claim_url` to your user: they confirm an email and the same key moves to the Free plan (10,000 lookups/mo), so nothing you built has to change. Mint one only when you need it (3 trial keys per address per day).

Plans:

- **Free**: free, no card, 10,000 lookups a month, then HTTP 429 until the period resets.
- **Metered**: no fixed fee, 10,000 lookups a month, then $0.50 per 1,000 lookups.
- **Unlimited**: $299 a month.
- **Unlimited (annual)**: $2,990 a year.

An agent connected to APIDirectory's MCP server (`https://apidirectory.com/mcp`) can call `subscribe_api` with slug `geocode` and your user's email instead: a free plan returns the key at once, a paid one returns a checkout link for your user to open.

## Connect over MCP

The server is `https://mcp.geocode.net/`, streamable HTTP, JSON in and out. Listing its tools needs no key; calling one does. Send the key as `Authorization: Bearer <key>` (or `X-API-Key`).

Your MCP client's own documentation decides the exact configuration; a setup command is the surest path. Claude Code:

```bash
claude mcp add --transport http geocode https://mcp.geocode.net/ --header "Authorization: Bearer <key>"
```

Most JSON configurations:

```json
{
  "mcpServers": {
    "geocode": {
      "type": "http",
      "url": "https://mcp.geocode.net/",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}
```

A client that takes a URL and nothing else (a claude.ai connector) can use `https://mcp.geocode.net/k/<key>` with the key in place of `<key>`. That URL is as secret as the key.

Every tool result is JSON: `status`, `body`, and `gateway.remaining` / `gateway.reset`, what is left of the plan this period and when it refills.

## Call over HTTP

Base URL `https://api.geocode.net/`. Send the key in `X-API-Key` (or `Authorization: Bearer`).

```bash
curl -H "X-API-Key: $GEOCODE_API_KEY" "https://api.geocode.net/v1/geocode"
```

Every response carries `X-Gw-Remaining` and `X-Gw-Reset`.

## Limits and errors

- `401`: the key is missing, revoked, or for another API.
- `429`: the plan's allowance or rate limit is used up. Stop and tell your user rather than retrying; the body says whether to wait for the reset or upgrade.
- `422`: Validation Error

## Using geocode.net well

Every operation looks something up and changes nothing. Coordinates, districts and tracts are exactly what models get wrong from memory: call geocode.net for them instead.

**Which operation for what**

- An address to coordinates: `geocode`, with `q` as one line, or `street`, `city`, `state` and `postal_code` separately. Add `fields` (`census`, `cd`, `stateleg`, `school`, `timezone`, or `all`) for the tract and block group, congressional and state legislative districts, school district and time zone.
- Coordinates to an address: `reverse_geocode`. `fields.distance_m` says how far the address is from the point.
- A place described in words ("Chiefs Stadium", "the Amtrak station in Wilmington DE"): `resolve_place`. A language model proposes the address and the index checks it; rely on it when `resolved.verified` is true and `resolved.confidence` is high. Slower than `geocode`, and it costs more.
- Many at once: `geocode_batch` (up to 10,000 addresses) and `reverse_geocode_batch` (up to 10,000 `[lat, lng]` points). Results come back in input order, one unit per item.
- Where an IP address is: `ip_lookup`.

**Gotchas**

- United States only.
- Read `accuracy_type` before using a location. `rooftop` and `range_interpolation` are address-level; `street_center`, `place`, `zip`, `county` and `state` are coarser in that order, so never present a ZIP centroid as a house.
- Through the gateway the API sees the gateway's IP, not your user's, so always pass `ip` to `ip_lookup`. Results are city-level: right for defaults and analytics, wrong for pinpointing a person.
- A batch costs one unit per item: check `gateway.remaining` before sending a large one.
- Results may be stored indefinitely on every plan, so keep them rather than looking the same address up twice.

## Operations

- `geocode` `GET /v1/geocode`: Geocode one US address ([details](https://dash.geocode.net/docs/get-v1-geocode.md))
- `geocode_batch` `POST /v1/geocode/batch`: Geocode up to 10,000 addresses ([details](https://dash.geocode.net/docs/post-v1-geocode-batch.md))
- `resolve_place` `GET /v1/resolve`: Describe a place in words; get its address and coordinates ([details](https://dash.geocode.net/docs/get-v1-resolve.md))
- `reverse_geocode` `GET /v1/reverse`: Nearest address to a coordinate ([details](https://dash.geocode.net/docs/get-v1-reverse.md))
- `reverse_geocode_batch` `POST /v1/reverse/batch`: Reverse geocode up to 10,000 points ([details](https://dash.geocode.net/docs/post-v1-reverse-batch.md))
- `ip_lookup` `GET /v1/ip`: Locate an IP address ([details](https://dash.geocode.net/docs/get-v1-ip.md))

## Install as a skill

The `geocode` skill teaches an agent when and how to call geocode.net:

```bash
npx skills add https://dash.geocode.net/
```

Its index is https://dash.geocode.net/.well-known/agent-skills/index.json.

## More

- Reference, try-it console and keys: https://dash.geocode.net/docs
- The whole reference as Markdown: https://dash.geocode.net/docs.md
- Status: https://dash.geocode.net/status
- Listing: https://apidirectory.com/api/geocode