Mapumental API

Accessibility mapping as a service

Getting Started

You need an account to use the API. Please register or log in.

Mapumental API


The Mapumental API allows travel time maps to be created for one or more places of interest (POIs) with the output represented as either a PNG image file or a GRASS ASCII grid raster suitable for use with GIS software.

The API is based around a single HTTPS endpoint, which accepts various arguments to create maps of varying formats with the POIs specified as postcodes or latitude/longitude coordinates.

Example Maps & Usage

View examples of maps generated by the API.

Creating Maps

The API exposes a single endpoint, which can be called in various ways to generate maps.

Maps can be created with POIs specified as postcodes, latitude/longitude coordinates, or a combination of both.

Synchronous/Asynchronous Creation

Maps are created in one of two modes: synchronous or asynchronous.

Synchronous creation means that the map will be generated and returned as the response to the creation request, i.e. a PNG or GRASS ASCII grid file will form the response to the HTTP request.

A request for an asynchronous map will return immediately with a unique id for this map creation request and the map will be created in the background by Mapumental's map server. The end result will then be delivered to an email address or URL depending on which was specified in the map creation request. This process will usually happen within a couple of minutes for smaller/single-POI maps, but may take longer depending on server load and the size of the map and number of POIs being shown.

Generally you may choose asynchronous or synchronous creation depending on your application, however there are certain situations where asynchronous creation will be required by the API. Maps must be created asynchronously if any of the following criteria are met:

Requests to the API that require asynchronous map creation must include the callback parameter. Those that do not will receive an HTTP 400 response. For the format of the callback parameter, see below.

API Specification

/static_map/ accepts requests with HTTP GET or POST methods. All requests must be made over HTTPS.

View examples of maps generated by the API.

Requesting Maps

Specifying POI locations

POIs are identified by UK postcode or WGS84 lat/lon coordinate.

Creating a map with a single POI specified by postcode takes the form:

A map with a single POI specified by lat/lon takes the form:

An arbitrary number of POIs can be displayed on a map. POIs can be specified as a mixture of postcodes and lat/lons on a single map.

Some examples of how to specify POI locations:

Shapefile Upload

You can also specify POIs by uploading an ESRI point shapefile. All POIs in the shapefile will be processed and shown on the map. This file must be zipped and include the .shp and .dbf parts of the shapefile. See below for the necessary parameters.

Request Parameters
Shapefile Upload Parameters

When specifying POIs by uploading a shapefile, an HTTP POST request must be used. The following parameters must be given:

Response Format

Successful Requests
Failure Modes

Map Limits

Map Costs

Mapumental API credits are required to generate maps from the API. Credits are debited from your account when maps are requested, and if your balance is not sufficient for a map request an error will be shown.

You can view your balance and purchase credits on your account page on