Skip to main content
GET
/
v1
/
h3
H3 Utility
curl --request GET \
  --url https://api.bookovia.com/v1/h3 \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "h3_cell": "<string>",
  "resolution": 123,
  "centroid": {
    "latitude": 123,
    "longitude": 123
  }
}

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 H3 Utility endpoint provides bidirectional conversion between latitude/longitude coordinates and Uber’s H3 hexagonal spatial index. H3 is used throughout the geocoding system for fast spatial queries and proximity searches.
Uses Uber H3 hierarchical spatial index with resolutions from 0 (continent-scale) to 15 (meter-scale). Default resolution is 11 (~25m cell size).

​
Authentication

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

​
Request

​
Convert Coordinates to H3

​
lat
number
Latitude coordinate (-90 to 90)Required for coordinate → H3 conversion
​
lon
number
Longitude coordinate (-180 to 180)Required for coordinate → H3 conversion
​
resolution
integer
H3 resolution level (0 to 15)
  • Resolution 7: ~5km cells (admin boundaries)
  • Resolution 11: ~25m cells (places, addresses)
  • Resolution 15: ~1m cells (high precision)
Default: 11

​
Convert H3 to Coordinates

​
h3
string
H3 cell identifier (e.g., “8928308280fffff”)Required for H3 → coordinate conversion

​
Request Example

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

​
Response

​
success
boolean
Indicates whether the request was successful
​
h3_cell
string
H3 cell identifier (15-character hexadecimal string)
​
resolution
integer
H3 resolution level (0-15)
​
centroid
object
Center coordinates of the H3 cell

​
Response Example (Coordinates to H3)

{
  "success": true,
  "h3_cell": "8928308280fffff",
  "resolution": 11,
  "centroid": {
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

​
Response Example (H3 to Coordinates)

{
  "success": true,
  "h3_cell": "8928308280fffff",
  "resolution": 11,
  "centroid": {
    "latitude": 40.71280234,
    "longitude": -74.00599876
  }
}

​
H3 Resolution Reference

ResolutionAvg Cell AreaAvg Edge LengthUse Case
04,357,449 km²1,107 kmContinental
312,393 km²59.8 kmRegional
5252.9 km²8.5 kmCity
75.16 km²1.22 kmAdmin boundaries
90.105 km²174 mNeighborhood
1143 m²25 mPlaces/addresses
130.9 m²4.2 mBuilding
150.0009 m²0.5 mHigh precision

​
Use Cases

Index geographic data for fast proximity searches. H3 cells enable O(1) lookup for nearby locations.
Define service areas or restricted zones using H3 cells instead of complex polygons.
Aggregate data by H3 cells to create density visualizations (e.g., trip origins, popular locations).
Share approximate location using H3 cell instead of exact coordinates for privacy.
Group and analyze geographic data at different resolutions (city, neighborhood, street level).

​
Error Handling

Status CodeErrorDescription
400provide either lat/lon or h3 parameterMissing required parameters
400invalid H3 cellMalformed H3 identifier
401API key requiredMissing authentication

​
Performance

  • Average Response Time: <10ms
  • Computation: In-memory (no database lookup)
  • Library: Uber H3 (official Go implementation)

​
Best Practices

Choose the right resolution: Use resolution 7 for large areas, 11 for POIs, 13-15 for precise building-level indexing.
Cache conversions: H3 cells are deterministic. Cache the conversion for frequently used coordinates.
Use for proximity queries: Query by H3 cell prefix for fast radius searches (e.g., all places in cell 892830*).

​
Example: Finding Neighbors

H3 cells have a hierarchical structure. To find all cells within a radius:
  1. Convert center point to H3 cell at resolution 11
  2. Get neighbor cells using H3’s gridDisk function (k=1 for adjacent, k=2 for 2-ring)
  3. Query your database for records with H3 cells in this set
JavaScript
// This logic is built into Places Nearby endpoint
// For custom implementation:
const centerH3 = '8928308280fffff'; // from /v1/h3
const neighbors = h3.gridDisk(centerH3, 1); // Get 1-ring neighbors
// Query database: WHERE h3_cell IN (neighbors)

​
Learn More