Create Hex Tiles

Data can be processed into Hex Tiles using the Studio Data SDK.

POST https://data-api.foursquare.com/internal/v1/datasets/hextile HTTP/1.1

HTTP API

You can access the Studio Data SDK through the HTTP REST API to process your dataset into Hex Tiles.

Headers

HeaderDescription
Content-TypeMust be application/json. This header is required.

Body

The body of the request should be the parameters encoded as a JSON blob.

ParameterTypeDescription
sourcestringRequired. Dataset record or UUID of the dataset to convert to Hex Tile.
targetstringDataset record or UUID of an existing Hex Tile dataset to overwrite.
sourceHexColumnstringName of the hex (h3) column in the source dataset. Hex column must contain hex indexes as string.
sourceLatColumnstringName of the latitude column in the source dataset.
sourceLngColumnstringName of the longitude column in the source dataset.
finestResolutionintFinest resolution for the data hexes within a tile (when creating a tileset from lat/lng columns)
sourceTimeColumnstringName of the time column in the source dataset, or null if non-temporal data.
timeIntervalsstring arrayArray of time intervals to generate for temporal datasets. Accepted intervals: ["YEAR"], ["MONTH"], ["DAY"], ["HOUR"], ["MINUTE"], ["SECOND"].
outputColumnsobject arrayObject array used to aggregate a new data column during Hex Tile generation.
outputColumns.sourceColumnstringColumn name in the source dataset.
outputColumns.targetColumnstringColumn name in the target hex tile dataset.
outputColumns.aggMethodstringMethod to aggregate the data column with when generating coarser tile resolutions. Accepted methods: "sum", "count", "min", "max", "mean", "median", "mode". Defaults to "sum" for numeric columns.
outputColumns.dtypestringData type to encode the column in the Hex Tile dataset. Example values include "float32", "uint8", "int64".
targetResOffsetintOptional integer controlling the depth of the tile hierarchy.
tileModestringExperimental. "dense", "sparse", or "auto". Defaults to "auto".
positionalIndexesbooleanExperimental. Enables the positional indexes encoding feature.

Response

Upon completion, you will receive a response containing the metadata of your dataset.

{
  "id": "string",
  "name": "string",
  "createdAt": "2021-02-04T00:17:38.652Z",
  "updatedAt": "2021-02-04T00:17:38.652Z",
  "description": "string",
  "isValid": true
}

Dataset Location

Once processed, your dataset will be stored on your Unfolded Cloud account. You may download it using the download dataset function in the Data SDK.

Check Hex Tiling Status via API

You can find the status of the Hex Tile dataset in the API.

Retrieve the dataset's metadata, then find one of three codes in the dataStatus field:

Status codeDescription
pendingThe tiling process is still running.
readyThe tiling process is complete and the Hex Tiles can be used.
errorThe tiling process has failed.

Examples

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"
        }
    ]
}
Sign In