Tilebelt

To use tilebelt in your project, install the package using npm:

npm install @mapbox/tilebelt

Import the library to perform tile-to-coordinate conversions. A tile is represented as an array of three integers: [x, y, z].

import * as tilebelt from '@mapbox/tilebelt';

const tile = [10, 15, 8]; // x, y, z

// Get GeoJSON representation
tilebelt.tileToGeoJSON(tile);

// Get the parent tile (one zoom level lower)
tilebelt.getParent(tile);

Convert geographic coordinates (longitude and latitude) to a tile coordinate at a specific zoom level.

• pointToTile(lon, lat, z): Returns the integer tile coordinates [x, y, z] that contain the point.
• pointToTileFraction(lon, lat, z): Returns the precise fractional tile location [x, y, z]. This is useful for determining exactly where within a tile a point lies.

// Get integer tile
const tile = pointToTile(1, 1, 20);

// Get fractional tile
const tileFraction = pointToTileFraction(30.5, 50.5, 15);

Use tileToGeoJSON to get a GeoJSON Polygon representation of a tile's boundaries. This is useful for visualizing tile boundaries on a map.

const poly = tileToGeoJSON([5, 10, 10]);
// returns a GeoJSON Polygon object

Use tileToBBOX to get the geographic bounding box (longitude/latitude) of a specific tile. The returned BBox follows the [minX, minY, maxX, maxY] format (West, South, East, North).

const bbox = tileToBBOX([5, 10, 10]);
// returns [west, south, east, north]

Use bboxToTile(bboxCoords) to find the single largest tile that completely encompasses the provided bounding box. This is useful for determining the appropriate zoom level and tile for a specific geographic area.

const tile = bboxToTile([-178, 84, -177, 85]);

Traverse the tile tree using these functions:

• getChildren(tile): Returns an array of the 4 tiles at the next zoom level (z + 1) that reside within the current tile.
• getParent(tile): Returns the single tile at the previous zoom level (z - 1) that contains the current tile.
• getSiblings(tile): Returns the 4 tiles (including the input tile) that share the same parent.

const tile = [5, 10, 10];

const children = getChildren(tile);
const parent = getParent(tile);
const siblings = getSiblings(tile);

Quadkeys are string representations of tile hierarchies used by some spatial indexing systems.

• tileToQuadkey(tile): Converts a Tile [x, y, z] to a quadkey string.
• quadkeyToTile(quadkey): Converts a quadkey string back into a Tile [x, y, z].

const quadkey = tileToQuadkey([0, 1, 5]);
const tile = quadkeyToTile('00001033');

Utility functions for managing collections of tiles:

• tilesEqual(tile1, tile2): Checks if two Tile objects are identical.
• hasTile(tilesArray, tile): Checks if a specific tile exists within an array of tiles.
• hasSiblings(tile, tilesArray): Checks if all sibling tiles of the given tile are present in the provided array.

const tiles = [[0, 0, 5], [0, 1, 5]];
const target = [0, 0, 5];

const exists = hasTile(tiles, target);
const isSame = tilesEqual(tiles[0], target);

A Tile is represented as a tuple of three numbers: [x, y, z].

• x: Column index
• y: Row index
• z: Zoom level

export type Tile = [number, number, number];