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, 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 (application/vnd.apache.parquet).

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
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.
formatstringNoparquet (default) returns rows. index returns the matching row groups as JSON. See Index format.
max_row_groupsintegerNoRow groups 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, cell, or hex_min and hex_max. With none, the query reads the whole dataset, narrowed only by time and partition.

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 for format=parquet, or the next_cursor field of the body for format=index. Send it back as cursor, with the same query, until a response has none.

Index format​

format=index returns JSON describing the matching row groups without reading any rows, for a client that reads the Parquet files itself: each row group's file path, row_group_index and byte offsets, the files' base64-encoded Parquet footers, and next_cursor for the next page.

Errors​

StatusWhen
400More than one spatial selector, an incomplete one (for example lat without lng), an invalid cell id, a partition naming a column that is not a partition column, or a cursor 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, or max_row_groups is above its maximum

See also​