The National Library of Scotland (NLS) publish a number of historic base maps of the United Kingdom via MapTiler. MapProxy can be used to make these base maps available for use within iShare Maps and GIS.

Overview

The historic base maps provided by NLS are made available in an OpenStreetMap compatible XYZ format in Web Mercator (EPSG:3857).

iShare Maps and GIS support WMS and WMTS (v6 and above) base maps in the same projection as the MapSource which is commonly British National Grid (EPSG:27700).

MapProxy can be used to request the tiles from NLS, reproject them to British National Grid and provide a WMS and WMTS service compatible with iShare.

Example - NLS - Great Britain, Ordnance Survey (1:1 million-1:10,560), 1900s

This example will guide you though configuring MapProxy and iShare to make use of the NLS - Great Britain, Ordnance Survey (1:1 million-1:10,560), 1900s base map.

Create a MapTiler API key

In order to make use of the NLS historic maps you need to sign-up for a MapTiler account and create an API key which will be used in all API requests to MapTiler.

Sign up for a MapTiler accounts via https://www.maptiler.com/cloud/pricing/
Login and navigate to https://cloud.maptiler.com/account/keys/
to create an API key

Tileset information

Each MapTiler tileset has an information page which provides a preview and various metadata URLs.

The tileset for the NLS - Great Britain, Ordnance Survey (1:1 million-1:10,560), 1900s base map can be found here: https://cloud.maptiler.com/tiles/uk-osgb1888/

We are interested in the TileJSON URL which provides us with the information required to configure MapProxy.

The TileJSON URL is https://api.maptiler.com/tiles/uk-osgb1888/tiles.json?key=MAPTILER_API_KEY (replace MAPTILER_API_KEY with your MapTiler API key).

From the TileJSON document below we are interested in:

attribution - the copyright statement to use in the iShare BaseMap MapSource
crs - this confirms that the tiles are in Web Mercator EPSG:3857
extent - the bounding box of the data in EPSG:3857 (metres)
minzoom and maxzoom - the supported zoom levels
tiles - The URL pattern for requesting tiles

{
    "attribution": "<a href=\"http://maps.nls.uk/projects/subscription-api/\">National Library of Scotland</a>",
    "bounds": [
        -14.169172000000001,
        49.20588199999999,
        4.393046,
        61.48378600000002
    ],
    "center": [
        -4.888063,
        55.82580299999999,
        15
    ],
    "color": "#DED8C2",
    "crs": "EPSG:3857",
    "crs_wkt": "PROJCS[\"WGS 84 / Pseudo-Mercator\",GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563,AUTHORITY[\"EPSG\",\"7030\"]],AUTHORITY[\"EPSG\",\"6326\"]],PRIMEM[\"Greenwich\",0,AUTHORITY[\"EPSG\",\"8901\"]],UNIT[\"degree\",0.0174532925199433,AUTHORITY[\"EPSG\",\"9122\"]],AUTHORITY[\"EPSG\",\"4326\"]],PROJECTION[\"Mercator_1SP\"],PARAMETER[\"central_meridian\",0],PARAMETER[\"scale_factor\",1],PARAMETER[\"false_easting\",0],PARAMETER[\"false_northing\",0],UNIT[\"metre\",1,AUTHORITY[\"EPSG\",\"9001\"]],AXIS[\"Easting\",EAST],AXIS[\"Northing\",NORTH],EXTENSION[\"PROJ4\",\"+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 +x_0=0 +y_0=0 +k=1 +units=m +nadgrids=@null +wktext +no_defs\"],AUTHORITY[\"EPSG\",\"3857\"]]",
    "description": "A set of five different scales of seamless Ordnance Survey map layers from around 1900, which display the different scales at different zoom levels:",
    "extent": [
        -1577305.01200231,
        6309867.739012304,
        489031.6437514273,
        8737763.75100255
    ],
    "format": "hybrid",
    "format_arguments": "",
    "generator": "MapTiler Desktop Pro 10.3-0934099ad7 Merge MBTiles",
    "legend": "",
    "logo": "https://api.maptiler.com/resources/logo.svg",
    "maxzoom": 17,
    "minzoom": 1,
    "name": "UK Great Britain, Ordnance Survey (1:1 million-1:10,560), 1900s",
    "profile": "mercator",
    "scale": "1.000000",
    "tilejson": "2.0.0",
    "tiles": [
        "https://api.maptiler.com/tiles/uk-osgb1888/{z}/{x}/{y}?key=MAPTILER_API_KEY"
    ],
    "type": "baselayer",
    "version": "1"
}

MapProxy configuration

Configuring MapProxy involves editing a YAML file in a text editor (like Notepad++).

Before making changes it is recommended to take a back up of mapproxy.yaml.

Pay particular attention to indentation as whitespace indentation is used for denoting structure. Tools such as https://onlineyamltools.com/validate-yaml are helpful for validating that mapproxy.yaml is valid.

On an iShare Maps or GIS server MapProxy is installed at D:\MapProxy (LIVE) and D:\MapProxyTest (TEST).

The LIVE MapProxy is available at https://maps.example.gov.uk/mapproxy (replace maps.example.gov.uk with your iShare domain) while the TEST MapProxy is available at http://localhost:82/mapproxy.

This example will assume updating the configuration under D:\MapProxyTest.

MapProxy configuration is saved in mapproxy.yaml and is comprised of the following sections:

services
- We are going to enable the wmts service, enable the EPSG:27700 spatial reference system (British National Grid) under the wms service and add image/png as an output format
layers: the layers that are available in the service
- We require a single uk_osgb1888 layer
caches: the tile caches used to store map tiles
- To reproject the MapTiler tileset we need two caches, one in EPSG:3857 to match the MapTiler tileset and another in EPSG:27700 which uses the EPSG:3857 cache as a source
sources: the source of the data to be cached
- We require a tile source that will fetch tiles from MapTiler
grids: the spatial reference system, resolutions and extent of a tile grid, used by layers and caches
- We require a EPSG:3857 grid to match the MapTiler tileset for the tile source and the cache plus a grid for the EPSG:27700 cache

grids

We require an EPSG:3857 grid (called uk_osgb1888__3857__grid) which is based on the built-in GLOBAL_WEBMERCATOR grid. The only change we’re making is to limit the zoom levels to 0 to 17 via the num_levels property to match the MapTiler tileset. This grid will be used for the source and the cache which we will define below.

We also need an EPSG:27700 grid (called EPSG:27700) which will be used with a cache of tiles in EPSG:27700. This grid matches the grid used by the OS Maps API WMTS EPSG:27700 service.

grids:
  # Grid used by uk_osgb1888__27700__cache ompatible with OS Maps API
  # EPSG:27700 grid, used by uk_osgb1888__27700 layer
  'EPSG:27700':
    origin: nw
    srs: 'EPSG:27700'
    bbox: [-238375.0000149319, 0.0, 900000.00000057, 1376256.0000176653]
    bbox_srs: 'EPSG:27700'
    res: [896.0, 448.0, 224.0, 112.0, 56.0, 28.0, 14.0, 7.0, 3.5, 1.75, 0.875, 0.4375, 0.21875, 0.109375]
  # Grid to use with the uk_osgb1888 tile source and cache. Based on Web Mercator
  # (OSM tiling scheme).
  uk_osgb1888__3857__grid:
    base: GLOBAL_WEBMERCATOR
    # The source only supports requests down to level 17 (zero based) so limit
    # the number of levels. The maxzoom can be found in
    # https://api.maptiler.com/tiles/uk-osgb1888/tiles.json?key=MAPTILER_API_KEY
    num_levels: 18

sources

We require a tile source (called uk_osgb1888) that will fetch tiles from MapTiler, we use the tiles URL pattern from the TileJSON with MapProxy style placeholders for the z, x and y components (for example %(z)s instead of {z}). We use the extent in the coverage.bbox which tells MapProxy to only request tiles within those bounds.

sources:
  uk_osgb1888:
    type: tile
    grid: uk_osgb1888__3857__grid
    # TODO Replace with appropriate MapTiler API key
    url: https://api.maptiler.com/tiles/uk-osgb1888/%(z)s/%(x)s/%(y)s?key=MAPTILER_API_KEY
      # Coverage extents in EPSG:3857 (which matches uk_osgb1888__3857__grid) taken from
      # https://api.maptiler.com/tiles/uk-osgb1888/tiles.json?key=MAPTILER_API_KEY
    coverage:
      bbox: [-1577305.01200231, 6309867.739012304, 489031.6437514273, 8737763.75100255]
      srs: 'EPSG:3857'

caches

To reproject the tileset we need two caches, one in EPSG:3857 (called uk_osgb1888__3857__cache) to match the MapTiler tileset and another in EPSG:27700 (called uk_osgb1888__27700__cache) which uses the uk_osgb1888__3857__cache as a source.

The cache uk_osgb1888__27700__cache uses the grid 'EPSG:27700' and the cache uk_osgb1888__3857__cache as a source which causes the tiles to be reprojected.

The cache uk_osgb1888__3857__cache uses the grid uk_osgb1888__3857__grid and the tile source uk_osgb1888.

The cache uk_osgb1888__3857__cache sets disable_storage: true to avoid storing the tiles on disk while uk_osgb1888__27700__cache will store the tiles in a file cache.

caches:
  uk_osgb1888__27700__cache:
    grids: ['EPSG:27700']
    sources: [uk_osgb1888__3857__cache]
    format: image/png
    image:
      # Avoid black edges when reprojecting from EPSG:3857
      transparent: true
    meta_buffer: 0
    minimize_meta_requests: true
    cache:
      type: file
  uk_osgb1888__3857__cache:
    grids: [uk_osgb1888__3857__grid]
    sources: [uk_osgb1888]
    format: image/png
    meta_buffer: 0
    minimize_meta_requests: true
    disable_storage: true

layers

We create a uk_osgb1888 layer which makes use of the cache uk_osgb1888__27700__cache in British National Grid (EPSG:27700).

layers:
  - name: uk_osgb1888
    title: UK Great Britain, Ordnance Survey (1:1 million-1:10,560), 1900s
    sources: [uk_osgb1888__27700__cache]

services

The services section is shared with all layers defined in mapproxy.yaml. We have enabled the wmts (Web Map Tile Service) and wms (Web Map Service) services and enable the EPSG:27700 spatial reference system (British National Grid) under the wms service and added image/png as an output format.

services:
  demo:
  tms:
    use_grid_names: true
    # origin for /tiles service
    origin: 'nw'
  kml:
    use_grid_names: true
  wmts:
  wms:
    srs: ['EPSG:3857', 'EPSG:27700']
    image_formats: ['image/jpeg', 'image/png']
    max_output_pixels: [6000, 6000]
    md:
      title: Base mapping
      abstract: Base mapping via MapProxy

Full example

services:
  demo:
  tms:
    use_grid_names: true
    # origin for /tiles service
    origin: 'nw'
  kml:
    use_grid_names: true
  wmts:
  wms:
    srs: ['EPSG:3857', 'EPSG:27700']
    image_formats: ['image/jpeg', 'image/png']
    max_output_pixels: [6000, 6000]
    md:
      title: Base mapping
      abstract: Base mapping via MapProxy

layers:
  - name: uk_osgb1888
    title: UK Great Britain, Ordnance Survey (1:1 million-1:10,560), 1900s
    sources: [uk_osgb1888__27700__cache]

caches:
  uk_osgb1888__27700__cache:
    grids: ['EPSG:27700']
    sources: [uk_osgb1888__3857__cache]
    format: image/png
    image:
      # Avoid black edges when reprojecting from EPSG:3857
      transparent: true
    meta_buffer: 0
    minimize_meta_requests: true
    cache:
      type: file
  uk_osgb1888__3857__cache:
    grids: [uk_osgb1888__3857__grid]
    sources: [uk_osgb1888]
    format: image/png
    meta_buffer: 0
    minimize_meta_requests: true
    disable_storage: true

sources:
  uk_osgb1888:
    type: tile
    grid: uk_osgb1888__3857__grid
    # TODO Replace with appropriate MapTiler API key
    url: https://api.maptiler.com/tiles/uk-osgb1888/%(z)s/%(x)s/%(y)s?key=MAPTILER_API_KEY
      # Coverage extents in EPSG:3857 (which matches uk_osgb1888__3857__grid) taken from
      # https://api.maptiler.com/tiles/uk-osgb1888/tiles.json?key=MAPTILER_API_KEY
    coverage:
      bbox: [-1577305.01200231, 6309867.739012304, 489031.6437514273, 8737763.75100255]
      srs: 'EPSG:3857'

grids:
  # Grid used by uk_osgb1888__27700__cache ompatible with OS Maps API
  # EPSG:27700 grid, used by uk_osgb1888__27700 layer
  'EPSG:27700':
    origin: nw
    srs: 'EPSG:27700'
    bbox: [-238375.0000149319, 0.0, 900000.00000057, 1376256.0000176653]
    bbox_srs: 'EPSG:27700'
    res: [896.0, 448.0, 224.0, 112.0, 56.0, 28.0, 14.0, 7.0, 3.5, 1.75, 0.875, 0.4375, 0.21875, 0.109375]
  # Grid to use with the uk_osgb1888 tile source and cache. Based on Web Mercator
  # (OSM tiling scheme).
  uk_osgb1888__3857__grid:
    base: GLOBAL_WEBMERCATOR
    # The source only supports requests down to level 17 (zero based) so limit
    # the number of levels. The maxzoom can be found in
    # https://api.maptiler.com/tiles/uk-osgb1888/tiles.json?key=MAPTILER_API_KEY
    num_levels: 18

Testing

If you are not seeing changes to mapproxy.yaml reflected then try recycling the MapProxy or MapProxyTest Applications Pool in IIS

Assuming the demo service is enabled (as in the example above) the base map can be tested via the MapProxy demo service. The MapProxy TEST demo is available at http://localhost:82/mapproxy/demo/ while on the iShare server. Clicking one of the highlighted links will open a map view displaying the layer.

If the layer doesn’t display or you get an error then check the log files mapproxy.log and source-requests.log under D:\MapProxyTest.

Create an iShare BaseMap MapSource

To display the base map in iShare, create a new BaseMap MapSource based on an existing OS Maps API BaseMap MapSource which will be configured with a suitable projection, bounds and mapfile.

MapProxy service URL

When using MapProxy TEST the URL that iShare will send requests to is http://localhost:82/mapproxy/service?

When using MapProxy LIVE the URL will match your iShare Maps/GIS domain, for example https://maps.example.gov.uk/mapproxy/service? (replace maps.example.gov.uk with your domain). It’s possible that you might need an API key in the path if you have an auth.keys section in mapproxy.yaml; if this is the case the URL will be along the lines of https://maps.example.gov.uk/mapproxy/68ec347d9a63/service? (replace maps.example.gov.uk with your domain and 68ec347d9a63 with a key from mapproxy.yaml)

iShare v6

Create a new WMTS BaseMap MapSource based on an existing OS Maps API MapSource.
On the Details page, update:
1. Name to match the MapProxy layer name uk_osgb1888
2. Copyright: © National Library of Scotland
3. URI and WMS URI: see note above about MapProxy service URL
4. Under Tile Matrix Set > Matrices choose all

iShare v5

Create a new WMS BaseMap MapSource based on an existing OS Maps API MapSource .
On the Details page, update:
1. Name to match the MapProxy layer name uk_osgb1888
2. Copyright: © National Library of Scotland
3. URI: see note above about MapProxy service URL
4. The scales can remain unchanged

Once a MapSource has been created, add it to the list of Selected BaseMap Sources of a MyMaps MapSource to allow you to test in iShare.

Publish a NLS Historic Map as WMS/WMTS for use in iShare Maps and GIS