Using OS Maps in iShare GIS v6

This guide will explain how to set up OS Maps in iShare GIS v6.

Obtain a key from the Ordnance Survey

The maps are provided from the OS via Web Mapping Tile Services (WMTS) from https://api.os.uk. To use these services a key must be generated. Follow the guidance here from the Ordnance Survey.

MapProxy configuration

iShare GIS v6 uses MapProxy to cache requests to the OS WMTS. Configuration of MapProxy is done by editing the mapproxy.yaml file.

For the live iShare GIS application this is located here: d:\mapproxy\mapproxy.yaml.

For the test iShare GIS application this is located here: d:\mapproxytest\mapproxy.yaml.

You will need to define the following items in MapProxy:

A base grid which includes a bounding box, default resolutions and projection information. In the example below 'osgb__osmaps_epsg27700_premium__grid' is the base grid.

grids:
  webmercator:
    base: GLOBAL_WEBMERCATOR
  # OS Maps API WMTS EPSG:27700 grid with full resolutions, used as
  # a base for the other OS Maps API WMTS EPSG:27700 grids
  osgb__osmaps_epsg27700_premium__grid:
    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]

An optional grid for each base map which includes resolution overrides. More information about the native resolutions can be found here. Here we have one override for the Leisure Premium and two for open data resolutions.

  # OS Maps API WMTS EPSG:27700 grid with resolutions for open data only
  osgb__osmaps_epsg27700_open__grid:
    base: osgb__osmaps_epsg27700_premium__grid
    res: [896.0, 448.0, 224.0, 112.0, 56.0, 28.0, 14.0, 7.0, 3.5, 1.75]
  # OS Maps API WMTS EPSG:27700 grid for Leisure premium and open data resolutions
  osgb__osmaps_epsg27700_leisure_premium__grid:
    base: osgb__osmaps_epsg27700_premium__grid
    res: [896.0, 448.0, 224.0, 112.0, 56.0, 28.0, 14.0, 7.0, 3.5, 1.75]
  # OS Maps API WMTS EPSG:27700 grid for Leisure open data resolutions
  osgb__osmaps_epsg27700_leisure_open__grid:
    base: osgb__osmaps_epsg27700_premium__grid
    res: [896.0, 448.0, 224.0, 112.0, 56.0, 28.0]

A source for each base map which includes the grid and the WMTS url from https://api.os.uk. Edit the URL to use the key that you’ve generated from the Ordnance Survey.

  osgb__osmaps_road_27700__wmts:
    type: tile
    grid: osgb__osmaps_epsg27700_premium__grid
    url: https://api.os.uk/maps/raster/v1/wmts?key=<INSERT_KEY_HERE>&height=256&width=256&style=default&layer=Road_27700&version=1.0.0&service=WMTS&Request=GetTile&format=image/png&TileMatrixSet=EPSG:27700&TileMatrix=EPSG:27700:%(z)s&TileRow=%(y)s&TileCol=%(x)s
  osgb__osmaps_outdoor_27700__wmts:
    type: tile
    grid: osgb__osmaps_epsg27700_premium__grid
    url: https://api.os.uk/maps/raster/v1/wmts?key=<INSERT_KEY_HERE>&height=256&width=256&style=default&layer=Outdoor_27700&version=1.0.0&service=WMTS&Request=GetTile&format=image/png&TileMatrixSet=EPSG:27700&TileMatrix=EPSG:27700:%(z)s&TileRow=%(y)s&TileCol=%(x)s
  osgb__osmaps_light_27700__wmts:
    type: tile
    grid: osgb__osmaps_epsg27700_premium__grid
    url: https://api.os.uk/maps/raster/v1/wmts?key=<INSERT_KEY_HERE>&height=256&width=256&style=default&layer=Light_27700&version=1.0.0&service=WMTS&Request=GetTile&format=image/png&TileMatrixSet=EPSG:27700&TileMatrix=EPSG:27700:%(z)s&TileRow=%(y)s&TileCol=%(x)s
  osgb__osmaps_leisure_27700__wmts:
    type: tile
    grid: osgb__osmaps_epsg27700_leisure_premium__grid
    url: https://api.os.uk/maps/raster/v1/wmts?key=<INSERT_KEY_HERE>&height=256&width=256&style=default&layer=Leisure_27700&version=1.0.0&service=WMTS&Request=GetTile&format=image/png&TileMatrixSet=EPSG:27700&TileMatrix=EPSG:27700:%(z)s&TileRow=%(y)s&TileCol=%(x)s

The four base maps available in British National Grid are:

Name	Layer for URL	Sample
OS Maps Road	Road_27700
OS Maps Outdoor	Outdoor_27700
OS Maps Light	Light_27700
OS Maps Leisure	Leisure_27700

A cache for each base map which includes the above grid and source.

caches:
  osgb__osmaps_road_27700__cache:
    grids: [osgb__osmaps_epsg27700_premium__grid]
    sources: [osgb__osmaps_road_27700__wmts]
    meta_buffer: 0
    minimize_meta_requests: true
  osgb__osmaps_outdoor_27700__cache:
    grids: [osgb__osmaps_epsg27700_premium__grid]
    sources: [osgb__osmaps_outdoor_27700__wmts]
    meta_buffer: 0
    minimize_meta_requests: true
  osgb__osmaps_light_27700__cache:
    grids: [osgb__osmaps_epsg27700_premium__grid]
    sources: [osgb__osmaps_light_27700__wmts]
    meta_buffer: 0
    minimize_meta_requests: true
  osgb__osmaps_leisure_27700__cache:
    grids: [osgb__osmaps_epsg27700_leisure_premium__grid]
    sources: [osgb__osmaps_leisure_27700__wmts]
    meta_buffer: 0
    minimize_meta_requests: true

A layer for each base map which includes a name, a title and the above source.

layers:
  - name: osgb__osmaps_road_27700
    title: OS Maps API Road
    sources: [osgb__osmaps_road_27700__cache]
  - name: osgb__osmaps_outdoor_27700
    title: OS Maps API Outdoor
    sources: [osgb__osmaps_outdoor_27700__cache]
  - name: osgb__osmaps_light_27700
    title: OS Maps API Light
    sources: [osgb__osmaps_light_27700__cache]
  - name: osgb__osmaps_leisure_27700
    title: OS Maps API Leisure
    sources: [osgb__osmaps_leisure_27700__cache]

Check that the services section looks similar to the following.

services:
  demo:
  wmts:
  wms:
    srs: ['EPSG:3857', 'EPSG:27700']
    md:
      title: iShare Base Maps
      abstract: OS Maps API base mapping

Check that the cache base directory has been defined under the globals section and that the path exists

globals:
    cache:
        base_dir: D:\mapproxy\cache_data

Lastly we want to add an authorisation key of our own making. Add this to the end of the mapproxy.yaml file. The key value will be used in the WMTS URL in iShare GIS. Choose your own value for the key.

auth:
    keys:
      - 'somethingLongAndAlphanumeric'
      - 'somethingElseLongAndAlphanumeric'

Save the mapproxy.yaml file.

Create a .map file for the OS Base Maps.

Save the following as “E:\iShareData\LIVE\_MapServerConfig\base_osmapapi.map” if creating base maps for iShare GIS Live or “E:\iShareData\TEST\_MapServerConfig\base_osmapapi.map” if creating base maps for iShare GIS Test.

MAP
	NAME "OS MAP API"
	CONFIG "PROJ_LIB" "D:\mapserver\shared\proj\nad"
	CONFIG "MS_ERRORFILE" "logs/live_base_osmapapi_debug.log"
	PROJECTION
		"init=epsg:27700"
	END
	TEMPLATEPATTERN "."
	MAXSIZE 8192
	SIZE 512 512
	EXTENT 0 0 700000 1300000
	IMAGECOLOR 238 238 237
	DEBUG 5
	FONTSET "D:/mapserver/shared/fonts/fonts.list"
	SYMBOLSET "D:/mapserver/shared/symbols/symbolsms6.sym"
	SHAPEPATH "../"
	IMAGETYPE "png"
	OUTPUTFORMAT
		NAME "png"
		DRIVER "AGG/PNG"
		IMAGEMODE RGB
		MIMETYPE "image/png"
		EXTENSION "png"
		TRANSPARENT FALSE
		FORMATOPTION "INTERLACE=OFF"
		FORMATOPTION "QUANTIZE_FORCE=ON"
	END
	UNITS METERS
	RESOLUTION 72
	WEB
		METADATA
			"ows_title" "OS MAPS API" 
			"author" "Astun Technology" 
			"ows_enable_request" "*" 
			"ows_srs" "EPSG:27700" ## Recommended
			"ows_abstract" "OS MAPS API Demonstration" 
			"wms_srs" "epsg:27700"
		END
		IMAGEPATH "D:/mapserver/tmp/"
		TEMPPATH "D:/mapserver/tmp/"
		IMAGEURL ""
		TEMPLATE "globexml.xml"
	END
END

Create base maps in Studio

Create a new base map in Studio under Map Sources > BaseMaps.

Under Map Settings choose the above base_osmapapi.map file. Select WMTS as the Basemap Type. Projection will be EPSG: 27700 and Map Units are Meters.

Under Start up use the following boundary settings.

Name	Value
Min X	-238375.000014932
Min Y	0
Max X	900000.00000057
Max Y	1376256.00001767

Under Details use the following settings.

Name	Value
Name	The layer name in mapproxy.yaml e.g. osgb__osmaps_road_27700
Copyright	The appropriate Ordnance Survey copyright message
Type	KVP
URI	https://<isharegis_url>/mapproxy/<auth_key>/service?
WMS URL	Same as above
Tile Matrix Set Name	The grid in mapproxy.yaml e.g. osgb__osmaps_epsg27700_premium__grid
Tile Matrix Set Matrices	all

Save and add the Base Map to the chosen Map Source to view.