Skip to content

API

Overview

The Protomaps Map API is a hosted, CDN-accelerated web service for interactive maps on the web. The Map API serves square Web Mercator tiles based on the MVT Vector Tiles specification : vector-tile-spec

Endpoints

The Protomaps hosted tile API is available at https://api.protomaps.com/.

  • Access requires an API key.
  • Requests made from a web browser are subject to Cross-Origin Resource Sharing (CORS) limitations. The list of allowed sites can be set per API key at the Dashboard.
  • Requests made from localhost with a valid API key are not subject to CORS restrictions; this is useful for local development. For domain names used in development and staging environments, set them to allowed on the Dashboard.

The URL for accessing map tiles is:

https://api.protomaps.com/tiles/v3.json?key=<KEY>
// or for raw tiles:
https://api.protomaps.com/tiles/v3/{z}/{x}/{y}.mvt?key=<KEY>

For V2 tiles, compatible with v1 styles:

https://api.protomaps.com/tiles/v2/{z}/{x}/{y}.pbf?key=<KEY>

Other assets such as JavaScript Libraries, map styles, and fonts, can be loaded from content delivery networks and do not need an API key.

For hosted versions of the styles through the API:

https://api.protomaps.com/styles/v2/light.json?key=<KEY>
https://api.protomaps.com/styles/v2/dark.json?key=<KEY>
https://api.protomaps.com/styles/v2/white.json?key=<KEY>
https://api.protomaps.com/styles/v2/grayscale.json?key=<KEY>
https://api.protomaps.com/styles/v2/black.json?key=<KEY>

MapLibre GL glyphs can be loaded at this URL:

glyphs: "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf"

Renderers

A map rendering library is needed to display interactive maps on the web. The Protomaps Map API is designed to work with any renderer that supports MVT format tiles, including:

Minutely Extracts is an on-demand downloader for raw OpenStreetMap data, built from minute-level planet snapshots. It's a simple web frontend to a Protomaps-hosted OSM Express database.

Downloads are provided in PBF format, which is interoperable with most tooling, such as:

Try Geofabrik Downloads if you need less frequently updated data clipped to administrative boundaries.

Programmatic API

Access to the API is enabled on request: please contact support@protomaps.com to request access.

Usage is free for non-commercial, academic research and OSM community applications.

Your application should make a POST request to the endpoint https://protomaps.com/api/v1/extracts with a JSON payload.

The JSON payload should include:

  1. a key token with your API token from the Dashboard.

  2. a key region with a JSON object having keys type and data:

    • if type is bbox, data is an array of numbers: [min_lat,min_lon,max_lat,max_lon]

    • if type is geojson, data is a GeoJSON Geometry object with a single Polygon feature.

A successful API response will have a key uuid and another key url which returns a progress endpoint. It should be polled until the key Complete appears.

Finally, the download URL can be retrieved via POST to https://protomaps.com/api/v1/extracts/<UUID> with token again in the JSON payload.

The result object will have a url key with a temporary link to download the file.

© 2022 Protomaps LLC