Working with H3
H3 is a hexagonal global grid system. It's a good fit when you need to:
- Build heatmaps of events (populations, counts, etc.)
- Compare datasets across resolutions and scale
- Work with sparse datasets, like point or location data
You can try all of the basics of H3 on this Canvas →
A typical H3 workflow has five steps: get your data into H3, pick a resolution, aggregate, join with other H3 datasets, and visualize. This page is the map; each step links to the page in H3 Analytics that covers it.
1. Get your data into H3
| Your data | Go to |
|---|---|
| Small (under about 100 MB): points, polygons or raster tiles | Convert on the fly: hexagonify inside a UDF on every run |
| Large: points, vectors, tables, or multi-dimensional data such as weather | Ingest: Partition, Index & Query: write it once, then read back only the part you need |
| Large rasters where you want aggregation and overviews built in | Ingest: Raster Pipeline: pixels to hexes, aggregated, with zoomed-out overviews |
Not sure which one fits? Get your data into H3 compares them.
If your dataset doesn't fit the patterns above (hundreds of GB, tens of thousands of files, or a custom ingestion shape), reach out to info@fused.io. We can help you scale the ingestion.
2. Pick a resolution
The resolution (res) controls hex size, and it drives everything downstream: conversion fidelity, how much data you store, and the granularity available for aggregation and joins.
| Resolution | Avg edge length | Typical use case |
|---|---|---|
| 3 | 59.81 km | Regional |
| 7 | 1.22 km | Neighborhood |
| 9 | 174.38 m | Block |
| 12 | 10.8 m | Building |
See the Resolution Guide for the full table and how Fused infers resolution from raster pixel size.
3. Aggregate
Once data is in H3, roll it up to coarser (parent) resolutions to make it fast to render and analyze at different zoom levels. Two datasets also need to share a resolution before they can be joined.
- Numerical (temperature, elevation, population): sum, mean, max, min, or stddev per cell.
- Categorical (land use, crop type): count occurrences, or take the mode, per cell.
See Aggregations.
4. Join datasets
Two H3 datasets with the same hex column and resolution merge with a standard SQL join on hex, with no spatial join. This makes it easy to combine datasets in different projections, sparse location data, or raster and vector sources.
See Joining.
5. Visualize
Return your H3 table from a UDF, then connect it to a fused-map widget: add an H3 layer that points at the UDF, set h3Column to your hex column, and the widget renders the hexagons on a map. You can also render hexagons in the Workbench Map Viewer, or link several UDFs into an interactive view in Canvas.
Query over HTTP
An indexed H3 dataset is also a REST endpoint. GET /h3/query takes a bounding box, point, cell, time window or partition as query parameters and returns the matching rows as a Parquet file. Any language can call it, and public data needs no credentials:
curl -G "https://www.fused.io/server/v1/h3/query" \
--data-urlencode "path=s3://fused-asset/data/ais/ais_week_h3_v2/" \
-d min_lng=-74.10 -d min_lat=40.55 -d max_lng=-73.90 -d max_lat=40.72 \
-d time_min=2024-07-03T12:00:00 -d time_max=2024-07-03T12:59:59 \
-o harbor.parquet
This returns all 6,214 ship position reports in New York Harbor between 12:00 and 13:00 UTC on July 3, 2024. Because every filter is a URL parameter, a web page can query the dataset directly: the AIS map sends one request per map tile as you pan.
See H3 datasets in the REST API reference for every parameter, paging and the index format.
Reference
fused.h3: Python SDK reference for H3 ingestion and query functions- H3 datasets REST API:
GET /h3/queryparameters, paging and the index format - H3 Analytics: full walkthroughs with runnable code for every step above
- Need help with a large or unusual dataset? Contact info@fused.io