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/tiles/.

• 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=<YOUR API KEY> // or for raw tiles: https://api.protomaps.com/tiles/v3/{z}/{x}/{y}.mvt?key=<YOUR API KEY>

For V2 tiles, compatible with v1 styles:

https://api.protomaps.com/tiles/v2/{z}/{x}/{y}.pbf?key=<YOUR API 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.

Examples:

https://unpkg.com/leaflet@1.7.1/dist/leaflet.css https://unpkg.com/leaflet@1.7.1/dist/leaflet.js https://unpkg.com/protomaps@1.14.1/dist/protomaps.min.js

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:

• JOSM for editing
• osm2pgsql and imposm for lossy conversion to PostgreSQL tables
• OpenTripPlanner, Valhalla, OSRM for routing
• Pelias and Photon for geocoding
• Osmium and Osmosis for general processing

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.