Hex Tile Functions

The Data SDK contains a variety of endpoints for the Hex Tile system.

Hex Tiles is Studio's analytic tiling system for geospatial data that combines the ability of tiling systems to handle massive datasets with the power of the H3 hierarchical grid system, enabling a tabular data view with full data integrity at all resolutions.


Create Hex Tiles

Process a geospatial dataset into Hex Tiles using the Studio Data SDK. Pass a source UUID ordataset record to convert to Hex Tiles. Requires either a hex (H3) column or latitude and longitude columns.

# Import the HexTileOutputColumn Model from Studio Data SDK
from unfolded.data_sdk.models import HexTileOutputColumnConfig
# Import enum members from Studio Data SDK
from unfolded.data_sdk.enums import (
    AggregationMethod,
    Dtype
)
# Create Hex Tiles
hextile_dataset = data_sdk.create_hextile(
    source="tree_data_set_hex10",
    source_hex_column="hex10",
    output_columns=(
      # Use HexTileOutputColumnConfig
      # to format source and target columns
      # aggregation method, and data type
      HexTileOutputColumnConfig(
          source_column="TreeID",
          target_column="TreeID_sum",
          agg_method=AggregationMethod.SUM,
          dtype=Dtype.UINT16
      ),
    )
)
curl -X POST https://data-api.foursquare.com/internal/v1/datasets/hextile \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "source": "<source_dataset_id>",
    "sourceHexColumn": "hex",
    "sourceTimeColumn": "datestr",
    "timeIntervals": ["DAY"],
    "targetResOffset": 4,
    "outputColumns": [
        {
        "sourceColumn": "metric",
        "targetColumn": "metric_sum",
        "aggMethod": "sum",
        "dtype": "uint16"
        }
    ]
}'

You can also process temporal datasets into Hex Tiles. To do this, you must specify the source time column and time intervals.

# Import TimeInterval enum from Studio Data SDK
from unfolded.data_sdk.enums import TimeInterval

# Create Hex Tiles
hextile_dataset_time = data_sdk.create_hextile(
    source='sample_dataset_hex6',
    source_hex_column="hex6",
    source_time_column="time",
    time_intervals=(TimeInterval.DAY,)
)

create_hextile reference


Enrich Dataset with Hex Tiles

You can enrich a dataset with Hex Tiles. Enriching refers to the process of joining Hex Tiles with another datasets to enrich them with contextual information. Requires a dataset to enrich with, which can be a UUID, dataset object, or dataframe.

# Enrich dataset with Hex Tiles
data_sdk.enrich(
    dataset="my-dataset-uuid",
    source_id="my-hex-tile-uuid",
    source_column="some_value",
    lat_column="lat",
    lng_column="lng",
    time_column="date",
)
curl -X POST https://data-api.foursquare.com/internal/v1/datasets/hextile \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-H 'Accept: text/csv' \
--data-raw '{
    "type": "enrich",
    "input": [
        {
            "type": "dataset",
            "uuid": "my-target-uuid"
        }
    ],
    "sourceId": "my-hex-tile-uuid",
    "sourceColumn": "some_value",
    "timeColumn": "date",
    "targetType": "LATLNG",
    "latColumn": "lat",
    "lngColumn": "lng"
}'

enrich_dataset reference.

Extract Hex Tiles

You may specify an area of Hex Tiles (represented by a GeoJSON geometry) for extraction. This function returns a geopandas H3 dataframe containing all fields from the Hex Tile dataset at the specified resolution.

# Extract Hex Tiles within a specified GeoJSON geometry
extracted_dataset = data_sdk.extract(
    source_id="<UUID>",
    geojson="
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [0, 0],
            [0, 10],
            [10, 0],
            [0, 0]
          ]
        ]
      }
    };,
    source_column="hextile_column",
    res=8,
    h3_column = "h3_8",
    time_column = "year",
    time_interval = "YEAR"
)
POST https://data-api.foursquare.com/internal/v1/query HTTP/1.1
    Note: Extracting Hextiles makes use of Studio's Query API.
    Please contact us if you wish to use the Query API to extract Hex Tiles.

tile_extract reference.


Sign In