# geocode.net API reference

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.

Base URL: `https://api.geocode.net/`. Send your key in the `X-API-Key` header; the remaining allowance comes back on every response in `X-Gw-Remaining`.

MCP server: `https://mcp.geocode.net/` (bearer token = the same key).

## Errors every operation can return

- `422` Validation Error

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}
```

# Geocode

## GET /v1/geocode

**Geocode one US address**

Forward geocoding. Returns the best match first with an honest accuracy_type: rooftop (an address point),
range_interpolation (placed along the street's house-number range), nearest_rooftop_match, street_center,
place, zip, county or state. Results may be stored indefinitely.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string | no | Free-form address, e.g. '1600 Pennsylvania Ave NW, Washington, DC 20500' |
| `street` | query | string | no | Structured alternative to q: house number and street |
| `city` | query | string | no | Structured: city |
| `state` | query | string | no | Structured: two-letter state code |
| `postal_code` | query | string | no | Structured: five-digit ZIP code |
| `fields` | query | string | no | Comma-separated appends: census, cd, stateleg, school, timezone, or all |
| `limit` | query | integer | no | How many candidates to return, best first Example: 1 |

### Responses

- `200` Successful Response

```json
{
  "query": "1600 Pennsylvania Ave NW, Washington, DC 20500",
  "results": [
    {
      "formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500",
      "components": {
        "number": "1600",
        "street": "Pennsylvania",
        "suffix": "Ave",
        "postdirectional": "NW",
        "city": "Washington",
        "county": "District of Columbia",
        "state": "DC",
        "zip": "20500",
        "country": "US"
      },
      "location": {
        "lat": 38.897675,
        "lng": -77.036545
      },
      "accuracy": 1.0,
      "accuracy_type": "rooftop",
      "source": "nad",
      "fields": {
        "census": {
          "state_fips": "11",
          "county_fips": "11001",
          "county": "District of Columbia",
          "county_subdivision": {
            "geoid": "1100150000",
            "name": "Washington city"
          },
          "place": {
            "geoid": "1150000",
            "name": "Washington"
          },
          "tract": "11001980000",
          "block_group": "110019800001",
          "zcta": "20006",
          "vintage": "2020 geographies, TIGER/Line 2025"
        },
        "timezone": {
          "name": "America/New_York",
          "abbreviation": "EDT",
          "utc_offset": "-04:00",
          "utc_offset_seconds": -14400,
          "observes_dst": true
        }
      }
    }
  ]
}
```

### Example

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

## POST /v1/geocode/batch

**Geocode up to 10,000 addresses**

One unit is metered per address. Results come back in the same order as the input. A batch larger than
what is left on your key is refused whole (429 allowance_exceeded) and costs nothing.

### Request body (application/json)

```json
{
  "addresses": [
    "1600 Pennsylvania Ave NW, Washington, DC 20500",
    "100 S French St, Wilmington, DE 19801"
  ],
  "fields": ""
}
```

### Responses

- `200` Successful Response

```json
{
  "results": [
    {
      "query": "1600 Pennsylvania Ave NW, Washington, DC 20500",
      "results": [
        {
          "formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500",
          "components": {
            "number": "1600",
            "street": "Pennsylvania",
            "suffix": "Ave",
            "postdirectional": "NW",
            "city": "Washington",
            "county": "District of Columbia",
            "state": "DC",
            "zip": "20500",
            "country": "US"
          },
          "location": {
            "lat": 38.897675,
            "lng": -77.036545
          },
          "accuracy": 1.0,
          "accuracy_type": "rooftop",
          "source": "nad"
        }
      ]
    },
    {
      "query": "100 S French St, Wilmington, DE 19801",
      "results": [
        {
          "formatted": "100 S French ST, Wilmington, DE 19801",
          "components": {
            "number": "100",
            "predirectional": "S",
            "street": "French",
            "suffix": "ST",
            "city": "Wilmington",
            "county": "New Castle",
            "state": "DE",
            "zip": "19801",
            "country": "US"
          },
          "location": {
            "lat": 39.7367,
            "lng": -75.550995
          },
          "accuracy": 0.9,
          "accuracy_type": "rooftop",
          "source": "nad"
        }
      ]
    }
  ]
}
```

### Example

```bash
curl -X POST "https://api.geocode.net/v1/geocode/batch" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "addresses": [
    "1600 Pennsylvania Ave NW, Washington, DC 20500",
    "100 S French St, Wilmington, DE 19801"
  ],
  "fields": ""
}'
```

# Resolve

## GET /v1/resolve

**Describe a place in words; get its address and coordinates**

A language model proposes the most likely US street address for the description and the index verifies it.
resolved.confidence is the model's own probability that the address is the place you described; resolved.verified
says whether the proposed house number exists in the index. results are ordinary geocode results for that address
with the usual accuracy_type. Slower than /v1/geocode (one model call, about a second) and metered at more than
one unit; repeat descriptions are answered from a cache. Results may be stored indefinitely.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string | no | A description of a place, e.g. 'Chiefs Stadium' or 'the Amtrak station in Wilmington DE' |
| `fields` | query | string | no | Comma-separated appends: census, cd, stateleg, school, timezone, or all |
| `limit` | query | integer | no | How many candidates to return, best first Example: 1 |

### Responses

- `200` Successful Response

```json
{
  "query": "the Amtrak station in Wilmington DE",
  "resolved": {
    "place_name": "Joseph R. Biden Jr. Railroad Station",
    "address": "100 S French St, Wilmington, DE 19801",
    "confidence": 0.88,
    "verified": true,
    "source": "model",
    "model": "claude-opus-5-5",
    "cached": false
  },
  "results": [
    {
      "formatted": "100 S French ST, Wilmington, DE 19801",
      "components": {
        "number": "100",
        "predirectional": "S",
        "street": "French",
        "suffix": "ST",
        "city": "Wilmington",
        "county": "New Castle",
        "state": "DE",
        "zip": "19801",
        "country": "US"
      },
      "location": {
        "lat": 39.7367,
        "lng": -75.550995
      },
      "accuracy": 0.9,
      "accuracy_type": "rooftop",
      "source": "nad"
    }
  ]
}
```

### Example

```bash
curl "https://api.geocode.net/v1/resolve" \
  -H "X-API-Key: YOUR_KEY"
```

# Reverse

## GET /v1/reverse

**Nearest address to a coordinate**

Reverse geocoding. The nearest address points within about 300 m, else the nearest street, else the containing place.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `lat` | query | number | yes | Latitude in decimal degrees Example: 38.8977 |
| `lng` | query | number | yes | Longitude in decimal degrees Example: -77.0365 |
| `fields` | query | string | no | Comma-separated appends: census, cd, stateleg, school, timezone, or all |
| `limit` | query | integer | no | How many candidates to return, nearest first Example: 1 |

### Responses

- `200` Successful Response

```json
{
  "query": {
    "lat": 38.8977,
    "lng": -77.0365
  },
  "results": [
    {
      "formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500",
      "components": {
        "number": "1600",
        "street": "Pennsylvania",
        "suffix": "Ave",
        "postdirectional": "NW",
        "city": "Washington",
        "county": "District of Columbia",
        "state": "DC",
        "zip": "20500",
        "country": "US"
      },
      "location": {
        "lat": 38.897675,
        "lng": -77.036545
      },
      "accuracy": 0.98,
      "accuracy_type": "rooftop",
      "source": "nad",
      "fields": {
        "distance_m": 4.8
      }
    }
  ]
}
```

### Example

```bash
curl "https://api.geocode.net/v1/reverse?lat=38.8977&lng=-77.0365" \
  -H "X-API-Key: YOUR_KEY"
```

## POST /v1/reverse/batch

**Reverse geocode up to 10,000 points**

One unit is metered per point. Results come back in the same order as the input. A batch larger than
what is left on your key is refused whole (429 allowance_exceeded) and costs nothing.

### Request body (application/json)

```json
{
  "fields": "",
  "points": [
    [
      38.8977,
      -77.0365
    ],
    [
      39.7367,
      -75.551
    ]
  ]
}
```

### Responses

- `200` Successful Response

```json
{
  "results": [
    {
      "query": {
        "lat": 38.8977,
        "lng": -77.0365
      },
      "results": [
        {
          "formatted": "1600 Pennsylvania Ave NW, Washington, DC 20500",
          "components": {
            "number": "1600",
            "street": "Pennsylvania",
            "suffix": "Ave",
            "postdirectional": "NW",
            "city": "Washington",
            "county": "District of Columbia",
            "state": "DC",
            "zip": "20500",
            "country": "US"
          },
          "location": {
            "lat": 38.897675,
            "lng": -77.036545
          },
          "accuracy": 0.98,
          "accuracy_type": "rooftop",
          "source": "nad",
          "fields": {
            "distance_m": 4.8
          }
        }
      ]
    },
    {
      "query": {
        "lat": 39.7367,
        "lng": -75.551
      },
      "results": [
        {
          "formatted": "100 S French ST, Wilmington, DE 19801",
          "components": {
            "number": "100",
            "predirectional": "S",
            "street": "French",
            "suffix": "ST",
            "city": "Wilmington",
            "county": "New Castle",
            "state": "DE",
            "zip": "19801",
            "country": "US"
          },
          "location": {
            "lat": 39.7367,
            "lng": -75.550995
          },
          "accuracy": 1.0,
          "accuracy_type": "rooftop",
          "source": "nad",
          "fields": {
            "distance_m": 0.5
          }
        }
      ]
    }
  ]
}
```

### Example

```bash
curl -X POST "https://api.geocode.net/v1/reverse/batch" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": "",
  "points": [
    [
      38.8977,
      -77.0365
    ],
    [
      39.7367,
      -75.551
    ]
  ]
}'
```

# Ip

## GET /v1/ip

**Locate an IP address**

IP geolocation: continent, country, region, city, approximate coordinates, time zone and the country's primary
languages. City-level accuracy, suitable for localisation, defaults and analytics, not for pinpointing a person.
Data: IP Geolocation by DB-IP (db-ip.com), City Lite edition, CC BY 4.0, refreshed monthly. Leave ip empty only
when calling the API directly; through the gateway the API sees the gateway's address, so pass the visitor's ip.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ip` | query | string | no | IPv4 or IPv6 address. Leave empty for the address the API sees the call from. |

### Responses

- `200` Successful Response

```json
{
  "ip": "8.8.8.8",
  "continent": {
    "code": "NA",
    "name": "North America"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "is_eu": false
  },
  "region": {
    "name": "California"
  },
  "city": "Mountain View",
  "location": {
    "lat": 37.422,
    "lng": -122.085
  },
  "timezone": {
    "name": "America/Los_Angeles",
    "utc_offset": "-07:00"
  },
  "languages": [
    "en",
    "es"
  ],
  "source": "IP Geolocation by DB-IP (https://db-ip.com), CC BY 4.0"
}
```

### Example

```bash
curl "https://api.geocode.net/v1/ip" \
  -H "X-API-Key: YOUR_KEY"
```