Skip to main content

H3 datasets

Once a dataset is partitioned and indexed with fused.h3, any HTTP client can read it with GET /h3/query: a point, a bounding box, a polygon, an H3 cell or a time window comes back as a Parquet file, without running a UDF. fused.h3.query() is a client of this endpoint.

A public dataset needs no credentials, so a browser page can call the endpoint directly. The AIS map loads every ship position report on screen this way, one /h3/query request per map tile.

Query a dataset​

GET /h3/query

Scope: public or authorized. With no credentials, only a public dataset at a literal s3:// path whose files are publicly readable can be read (403 otherwise). With credentials, path resolves to your environment's own dataset, else to the public one.

Returns the matching rows as a Parquet file.

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 \
-d columns=MMSI -d columns=VesselName -d columns=BaseDateTime \
-d columns=LAT -d columns=LON -d columns=SOG \
-o harbor.parquet

This reads the 6,214 position reports in New York Harbor between 12:00 and 13:00 UTC on July 3, 2024, from the public AIS dataset.

Query parameters

ParameterTypeRequiredDescription
pathstringYesThe indexed dataset, as passed to fused.h3.index()
min_lng, min_lat, max_lng, max_latnumberNoA bounding box. Give all four.
lat, lngnumberNoA point. Give both.
cellstringNoAn H3 cell id as a hex string. Returns every row in that cell, or in its descendants when cell is coarser than the dataset.
hex_min, hex_maxstringNoAn inclusive range of raw H3 cell ids, each as a hex string
polygonstringNoA GeoJSON Polygon or MultiPolygon geometry, or a Feature holding one, as a JSON string. At most 50,000 vertices. See Query by polygon.
polygon_wktstringNoThe same polygon as WKT POLYGON or MULTIPOLYGON
containstringNoWhich cells a bounding box or polygon selects: center (default) a cell whose center is inside or on the edge, full a cell wholly inside, overlap a cell sharing any point with it
kintegerNoAlso return every cell within k grid steps of a selected cell, for a point, bounding box or polygon. From 0 to 25. Default 0.
time_min, time_maxstringNoAn inclusive ISO datetime window. Omitted, the whole time range is read.
partitionstringNoJSON object mapping a partition column to a value, or a list of values that any may match. See Filter by partition.
partition_rangestringNoJSON object mapping a partition column to an inclusive [min, max], with null for an open end
columnsstringNoA column to return. Repeat the parameter for several. Omitted, every column is returned.
formatstringNoWhat to return. Leave it out to get the matching rows. Use files to inspect a query without downloading any rows: files returns JSON listing the files the query would read, with their row counts. See Files format.
max_row_groupsintegerNoRow groups (blocks of rows in a file) per page, from 1 to 4,096. Default 1,024.
cursorstringNoThe cursor from the previous page. See Page through large results.

Pass at most one spatial selector: the bounding box, the point, polygon, polygon_wkt, cell, or hex_min and hex_max. With none, the query reads the whole dataset, narrowed only by time and partition.

Query by polygon​

polygon and polygon_wkt take longitude/latitude degrees on a flat plane, as in GeoJSON. Split a polygon that crosses the antimeridian into a MultiPolygon at ±180. A polygon too long for a URL can go in the JSON body of POST /h3/query, which takes the same parameters as fields and accepts polygon, partition and partition_range as JSON objects:

curl -X POST "https://www.fused.io/server/v1/h3/query" \
-H "Content-Type: application/json" \
-d '{
"path": "s3://fused-asset/data/ais/ais_week_h3_v2/",
"polygon": {"type": "Polygon", "coordinates": [[[-74.10, 40.55], [-73.90, 40.55], [-73.90, 40.72], [-74.10, 40.72], [-74.10, 40.55]]]},
"time_min": "2024-07-03T12:00:00",
"time_max": "2024-07-03T12:59:59",
"columns": ["MMSI", "VesselName", "BaseDateTime", "LAT", "LON", "SOG"]
}' \
-o harbor.parquet

This returns the same 6,214 reports as the bounding box example above. A field the GET form does not have is a 422.

Filter by partition​

partition and partition_range select folders written with partition_by in fused.h3.partition(), for example partition={"date": "2024-07-03"} or partition_range={"date": ["2024-07-01", "2024-07-07"]}. A folder must match every column named. A date column matches a folder whose period (YYYY, YYYY-MM or YYYY-MM-DD) overlaps the value or range.

Page through large results​

A large result comes back one page at a time. When more remain, the response carries a cursor: the X-Fused-Next-Cursor header. Send it back as cursor, with the same query, until a response has none. format=files always answers in one page.

Files format​

format=files returns JSON describing the indexed files that overlap the query, without opening any. The body has level ("file"), h3_resolution (the resolution of the data cells), cell_resolution (the resolution of the H3 cells that name the files), cells (the H3 cell, in lowercase hex, that names each file) and row_counts: parallel arrays total (each file's rows in the matched folders) and window (only the rows in folders the time window overlaps). max_row_groups and cursor are ignored, and columns is not accepted. time_min and time_max narrow the answer only when the time column is a date partition column.

Errors​

StatusWhen
400More than one spatial selector, an incomplete one (for example lat without lng), an invalid cell id, or an invalid polygon
400k with a selector other than a point, bounding box or polygon, contain with a selector other than a bounding box or polygon, or a k buffer too costly to compute
400time_min or time_max on a dataset with no time column
400partition or partition_range that is not a JSON object, names a column that is not a partition column, or holds a value of the wrong type
400format=files with columns, or selecting more than 2,048 folders
400A malformed cursor, or one from a different query
403No credentials, and path is not a public s3:// dataset
404You can read no dataset at path
409The dataset has never finished indexing, or the cursor predates a re-index
422A name in columns is missing from the indexed files, max_row_groups is above 4,096, k is outside 0 to 25, format is not a supported value, or (format=files) an indexed file is not named by an H3 cell

See also​