Skip to main content

​
Endpoint

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

​
Authentication

HeaderRequiredValue
X-API-KeyYesYour API key (bun_...)
Content-TypeYesapplication/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

FieldTypeRequiredDescription
querystringNoFree-text address or place name (forward geocoding)
latnumberNoLatitude in decimal degrees (reverse geocoding)
lonnumberNoLongitude in decimal degrees (reverse geocoding)
Provide either query for forward geocoding, or both lat and lon for reverse geocoding.

​
Example — forward geocoding

{
  "query": "1600 Amphitheatre Parkway, Mountain View, CA"
}

​
Example — reverse geocoding

{
  "lat": 37.4224764,
  "lon": -122.0842499
}

​
Response

​
200 OK — forward geocoding

Returns a results array of up to 5 matches.
FieldTypeDescription
resultsarrayList of matching locations (up to 5)
results[].latnumberLatitude of the result
results[].lonnumberLongitude of the result
results[].display_namestringFull human-readable address string
results[].typestringOSM feature type (e.g. building, highway, city)
results[].addressobjectStructured address components (e.g. road, city, state, country, postcode, country_code)
Example 
{
  "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.
FieldTypeDescription
latnumberLatitude that was looked up
lonnumberLongitude that was looked up
display_namestringFull human-readable address string
addressobjectStructured address components (e.g. road, city, state, country, postcode, country_code)
Example 
{
  "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

{
  "detail": "Missing API key. Include X-API-Key header."
}

​
402 Payment Required

{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}

​
422 Unprocessable Entity

{
  "detail": "Provide 'query' for forward geocoding or 'lat' and 'lon' for reverse geocoding"
}

​
429 Too Many Requests

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

​
cURL example

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"}'