Map Configuration

There are four different groups in the map control panel:

  • map settings controlling the projection and allowed extent & zoom settings for published maps
  • map UI controls to configure map tools and colors (e.g. location pins, user drawn features)
  • background maps to configure additional background layers (e.g. OSM-like, Bing Maps)
  • advanced cache settings to fine-tune control of tiles caching

There are also two additional actions to be taken to either reconfigure cache settings (in case of some issues) and clean up of all cached tiles (for all layers).


For enabling caching for individual layers see Cache Settings section.

Map Settings



The EPSG code of the projection Mappin will use for displaying maps. British National Grid (most commonly used in the UK) is 27700, Pseudo-Mercator is 3857 and WGS 84 is 4326. You can find other EPSG codes here.

Zoom Settings

Zoom, Min Zoom and Max Zoom define the initial, closest and furthest project zoom levels respectively. Smaller zoom levels are zoomed closer (e.g. 1:1,000) and larger zoom levels are zoomed further away (e.g. 1:4,000). Zoom levels correspond with the resolutions defined in the Resolutions setting described below. A zoom level of 0 refers to the first resolution in the Resolutions list.

Custom Center

X and Y coordinates for initial center of viewport. If empty, then center is calculated as center of either panning jail (see below) or map grid.

Restrict Map Extent

Whether to restrict panning to certain area (aka. panning jail)

Xmin, Ymin, Xmax and Ymax are the Western, Southern, Eastern and Northern extents of the bounding box which users will be limited to. This bounding box should be sufficiently large as to contain all the data you wish users to see.

The get_map_bb_button button can be used to extract these values from the project’s QGIS project file. For this method to work, an Advertised extent must be specified in the QGIS project you uploaded (in QGIS, under Project > Properties > QGIS Server). Values can also be entered manually.

Map UI Controls


Marker Color Settings

Some of Mappin’s tools (e.g. Find My Nearest) use map markers to show results on the map. Marker colors are configured here. The image below shows results from a Find My Nearest query. Here the primary marker is orange and represents the search origin. The secondary markers are blue and represent results. The distances shown in search results are the straight-line distances between blue markers and the orange marker.


Zoom Slider

Whether to enable the zoom control slider.


Zoom Reset Button

Whether to enable the Zoom full button.


Background Maps


Custom Background Map Settings

The following settings can be used to include custom background mapping from a third-party provider via WMTS. The custom background tiles are fetched directly from the provider’s servers by the user’s browser and are not transferred via Mappin.

Please note that it is your responsibility to ensure you comply with the background mapping provider’s Terms of Service.

Custom Bg Url

Specified the base URL for the third-party WMTS service. An example would be OpenStreetMap’s standard tile layer at${z}/${x}/${y}.png Note that the URL needs to feature x, y and z variables.

Custom Bg Attribution

If specified, this text (e.g. Custom attribution goes here...) will be included in the attribution panel at the bottom-right of the map.


Custom Bg Attribution Url

If specified, the text in the Custom Bg Attribution setting will be hyperlinked to the URL specified here.

Include Osm Attr

If enabled, the attribution appropriate for OpenStreetMap will appear in the attribution panel.

Custom Bg Alias

The name Mappin will use to refer to these maps in the user interface.

Custom Bg On

Whether to enable custom background maps.

Bing Settings

The following settings control Mappin’s use of Microsoft’s Bing maps. When enabled, Mappin will display a Bing maps background layer. The Bing tiles are fetched directly from Bing servers by the user’s browser and are not transferred via Mappin.

Please note that it is your responsibility to ensure you comply with the Bing Terms of Service.

Bing Key

In order to make use of Bing background mapping you need to have an API key. Once you have an API key, enter it here to enable Bing maps.

Bing Style

Controls which Bing map type will be displayed.

Bing On

Whether to enable Bing maps.

Advanced Cache Settings


Custom Resolutions

Resolutions defines a comma-separated list of resolutions at which maps will be published. Each value refers to the size (in map units) of a map pixel.

When using the UK background maps supplied with Mappin, use the following settings for the best looking background maps:

  • OSBackgroundMaps: 2000,1000,500,200,100,50,25,12.5,5,2.5,2,1,0.5,0.25
  • OSZoomStack: 2048,1024,512,256,128,64,32,16,8,4,2,1,0.5,0.25,0.125,0.0625,0.03125

If left blank, default resolutions based on grid will be used.

Tile Size

The size of map tiles requested by the users’ browser in pixels. There is a trade-off between (1) spending less time rendering parts of tiles outside the visible area and (2) rendering less tiles / making less requests which can improve the total loading time due to decreased request round-trip times. 256 and 512 are common settings.

Additional SRS

If you need to access tiles in different SRS than default (e.g. as WMS source), you can add additional projections.