Introduction

Our API allows you to easily generate Mapbox vector tiles from your geodata, making it a powerful tool for integrating interactive maps into your applications. This documentation will guide you through the process of using our API, from getting started to advanced features.

Vector tiles make huge maps fast while offering full design flexibility. They are the vector data equivalent of image tiles for web mapping, applying the strengths of tiling — developed for caching, scaling and serving map imagery rapidly — to vector data.

---

Getting Started

It's quick and easy, and with just a few steps you'll have vector tiles on there way to clients.

• Drag and drop on the upload page
• Collate Datasets as layers into a Tileset
• Set zoom levels for each layer
• Determine a White List of accepted Referers who can have access
• Embed a mapping library into your website

---

File Uploads & Processing

We currently accept Geopackage or Geojson filetypes (.gpkg .geojson file extensions), these are chunked and uploaded. Partial uploads can be resumed by dropping/selecting the same file.

Once uploaded the files are verified and any geometry issues rectified. The geometries are then reprojected to webmercator projection before being spatially indexed and made ready for tile generation.

---

API Endpoints & Requests

Each endpoint is unique to a Tileset and follows the below format:

https://{subdomain}.tile.stream/{unique path}/{zoom level}/{x}/{y}.mvt

We run several subdomains which can all be used for the same purpose and allow parallel requests for several tiles at once. Requests must come from a White List domain.

---

Response Format

The API response is delivered in a structured format, typically in JSON. Understanding this format is crucial for processing the data returned by the API. We provide an example response structure to help you work with the data effectively.

---

Authentication and Security

Our end points will normally be used in client side code and so authentication is done by reviewing the headers on incoming requests.

This is done on our edge network which will cross check the unique path against a the White List of domains to see if the incoming request is permitted.

---

Data Formats

Upload Files

Data that is going to be uploaded needs to be in either Geopackage or Geojson filetypes (.gpkg .geojson file extensions).

Tile Files

Requested files will come in a Google Protobufs (PBF) format with the Mapbox Vector Tiles .mvt file suffix.

---

Caching

Tiles are cached on the browser and content delivery network for 30 days. After this a request to the origin will occur and any changes will be propagated then.

To push changes to the client as soon as possible the url path for that Tileset can be rotated and new tiles will be pulled from the origin server.

---

Tile Configuration & Optimisation

Tiles are optimised along several points but all start with the original data uploaded.

Upload Files

Less is more - only upload the data that is absolutely necessary for the end user, unnecessary meta data and over complex geometries can result in large tiles.

Layer Zoom Levels

When layering up the Datasets to form a Tileset, select the zoom levels at which those layers are incorporated, this can help reduce superfluous data from a tile.

Simplification

Geometries are simplified prior to the tiles being encoded to reduce size without any visual effects.

Compression

Tiles are zipped to reduce their size and transmission time.

Content Delivery Network

Following the initial request for a tile, all subsequent request will come from a nearer edge server on a CDN making all subsequent requests faster.