> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /geocoding

> Convert addresses to coordinates (forward geocoding) or coordinates to addresses (reverse geocoding).

## Endpoint

```
POST https://api.bunny.build/api/v1/geocoding
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Perform forward geocoding (address to coordinates) by passing a `query`, or reverse geocoding (coordinates to address) by passing `lat` and `lon`. Returns structured location data including formatted address, country, city, and precise latitude/longitude.

## Use cases

* Geocode user-entered addresses for map display
* Reverse-geocode GPS coordinates to human-readable addresses
* Validate and normalize delivery addresses
* Enrich location data in analytics pipelines

## Details

Forward geocoding accepts free-text queries in any language and returns up to 5 results in a `results` array. Reverse geocoding requires decimal degree coordinates and returns a single flat object with the nearest address. Provide either `query` or both `lat` and `lon` — not both.

## Request body

| Field   | Type   | Required | Description                                         |
| ------- | ------ | -------- | --------------------------------------------------- |
| `query` | string | No       | Free-text address or place name (forward geocoding) |
| `lat`   | number | No       | Latitude in decimal degrees (reverse geocoding)     |
| `lon`   | number | No       | Longitude in decimal degrees (reverse geocoding)    |

Provide either `query` for forward geocoding, or both `lat` and `lon` for reverse geocoding.

### Example — forward geocoding

```json theme={null}
{
  "query": "1600 Amphitheatre Parkway, Mountain View, CA"
}
```

### Example — reverse geocoding

```json theme={null}
{
  "lat": 37.4224764,
  "lon": -122.0842499
}
```

## Response

### 200 OK — forward geocoding

Returns a `results` array of up to 5 matches.

| Field                    | Type   | Description                                                                                         |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------------- |
| `results`                | array  | List of matching locations (up to 5)                                                                |
| `results[].lat`          | number | Latitude of the result                                                                              |
| `results[].lon`          | number | Longitude of the result                                                                             |
| `results[].display_name` | string | Full human-readable address string                                                                  |
| `results[].type`         | string | OSM feature type (e.g. `building`, `highway`, `city`)                                               |
| `results[].address`      | object | Structured address components (e.g. `road`, `city`, `state`, `country`, `postcode`, `country_code`) |

**Example**

```json theme={null}
{
  "results": [
    {
      "lat": 37.4224764,
      "lon": -122.0842499,
      "display_name": "1600, Amphitheatre Parkway, Mountain View, Santa Clara County, California, 94043, United States",
      "type": "building",
      "address": {
        "house_number": "1600",
        "road": "Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "California",
        "postcode": "94043",
        "country": "United States",
        "country_code": "us"
      }
    }
  ]
}
```

### 200 OK — reverse geocoding

Returns a single flat object for the nearest address.

| Field          | Type   | Description                                                                                         |
| -------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `lat`          | number | Latitude that was looked up                                                                         |
| `lon`          | number | Longitude that was looked up                                                                        |
| `display_name` | string | Full human-readable address string                                                                  |
| `address`      | object | Structured address components (e.g. `road`, `city`, `state`, `country`, `postcode`, `country_code`) |

**Example**

```json theme={null}
{
  "lat": 37.4224764,
  "lon": -122.0842499,
  "display_name": "1600, Amphitheatre Parkway, Mountain View, Santa Clara County, California, 94043, United States",
  "address": {
    "house_number": "1600",
    "road": "Amphitheatre Parkway",
    "city": "Mountain View",
    "state": "California",
    "postcode": "94043",
    "country": "United States",
    "country_code": "us"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Provide 'query' for forward geocoding or 'lat' and 'lon' for reverse geocoding"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/geocoding \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "1600 Amphitheatre Parkway, Mountain View, CA"}'
```