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

Header	Description
`Content-Type`	Must be `application/json`. This header is required.

Body

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

Parameter	Type	Description
`source`	`string`	Required. `Dataset` record or UUID of the dataset to convert to Hex Tile.
`target`	`string`	`Dataset` record or UUID of an existing Hex Tile dataset to overwrite.
`sourceHexColumn`	`string`	Name of the hex (h3) column in the source dataset. Hex column must contain hex indexes as `string`.
`sourceLatColumn`	`string`	Name of the latitude column in the source dataset.
`sourceLngColumn`	`string`	Name of the longitude column in the source dataset.
`finestResolution`	`int`	Finest resolution for the data hexes within a tile (when creating a tileset from lat/lng columns)
`sourceTimeColumn`	`string`	Name of the time column in the source dataset, or null if non-temporal data.
`timeIntervals`	`string array`	Array of time intervals to generate for temporal datasets. Accepted intervals: `["YEAR"]`, `["MONTH"]`, `["DAY"]`, `["HOUR"]`, `["MINUTE"]`, `["SECOND"]`.
`outputColumns`	`object array`	Object array used to aggregate a new data column during Hex Tile generation.
`outputColumns.sourceColumn`	`string`	Column name in the source dataset.
`outputColumns.targetColumn`	`string`	Column name in the target hex tile dataset.
`outputColumns.aggMethod`	`string`	Method 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.dtype`	`string`	Data type to encode the column in the Hex Tile dataset. Example values include `"float32"`, `"uint8"`, `"int64"`.
`targetResOffset`	`int`	Optional integer controlling the depth of the tile hierarchy.
`tileMode`	`string`	Experimental. `"dense"`, `"sparse"`, or `"auto"`. Defaults to `"auto"`.
`positionalIndexes`	`boolean`	Experimental. 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 code	Description
`pending`	The tiling process is still running.
`ready`	The tiling process is complete and the Hex Tiles can be used.
`error`	The 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"
        }
    ]
}