Skip to main content
GET
/
v1
/
boundaries
/
lookup
Lookup Boundaries
curl --request GET \
  --url https://api.bookovia.com/v1/boundaries/lookup \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "boundaries": {
    "city": "<string>",
    "county": "<string>",
    "state": "<string>",
    "state_code": "<string>",
    "country": "<string>",
    "country_code": "<string>",
    "region": "<string>",
    "h3_cell": "<string>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.bookovia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Boundaries Lookup endpoint returns administrative division information for a given coordinate. It provides hierarchical location context from city level up to country level, useful for address normalization, regional analytics, and location-based services.
Built on Overture Maps divisions data with 63,909 administrative boundaries covering the United States.

​
Authentication

This endpoint requires authentication via API key in the X-API-Key header. Required permissions: geocoding:read

​
Request

​
lat
number
required
Latitude coordinate (-90 to 90)
​
lon
number
required
Longitude coordinate (-180 to 180)

​
Request Example

curl -X GET "https://api.bookovia.com/v1/boundaries/lookup?lat=40.7128&lon=-74.0060" \
  -H "X-API-Key: bkv_test_your_api_key_here"

​
Response

​
success
boolean
Indicates whether the request was successful
​
boundaries
object
Hierarchical boundary information

​
Response Example

{
  "success": true,
  "boundaries": {
    "city": "New York",
    "county": "New York County",
    "state": "New York",
    "state_code": "US-NY",
    "country": "United States",
    "country_code": "US",
    "region": "US-NY",
    "h3_cell": "872a100b5ffffff"
  }
}

​
Use Cases

Complete partial addresses by filling in missing city, state, or country information from coordinates.
Aggregate data by administrative divisions for reports and dashboards (e.g., trips by state, sales by county).
Determine if a location is within a specific city or state boundary for service area validation.
Calculate location-based taxes using state and county information.
Route emergency calls to correct jurisdictions based on precise location.

​
Error Handling

Status CodeErrorDescription
400lat and lon are requiredMissing coordinates
400Invalid coordinatesCoordinates out of valid range
401API key requiredMissing authentication
500search errorInternal search error
Some locations (e.g., water bodies, remote areas) may return partial or empty boundary data.

​
Performance

  • Average Response Time: <100ms
  • H3 Resolution: 7 (~5km cell size)
  • Lookup Method: Bounding box containment check
  • Coverage: United States

​
Best Practices

Cache results: Boundary lookups are expensive. Cache results by H3 cell or lat/lon (rounded to 3-4 decimals) to reduce API calls.
Handle missing data: Not all fields will be populated for every location. Always check for empty strings or missing keys.