OS OpenSpace Maps

Overview

This plugin allows maps to be inserted into a page or post using the Ordnance Survey OpenSpace platform. This displays the OS maps which give a much greater level of topographical detail than Google or Bing maps, which focus mainly on roads and urban features.

API Key Registration

In order to use this plugin you must first register with the Ordnance Survey for an API key. Your key will be linked to your domain name and there will be a limit to the number of map tiles served to your API key each day. If you wish to use OpenSpace on multiple domains you can add them to your key, but you should note that the daily limit applies to all tiles served using that key, so it may be better to get a separate key for each domain.

Go to the OS OpenSpace Registration page to register for a free key. You have to specify whether your site uses http:// or https:// and if it uses both then you need to add both domains to your key. The API will check for an exact match between the source URL and the registered URL, so if your maps appear anywhere other than on the home page you should use a wildcard, e.g. https://example.com/*

The API key will be generated and emailed to you, and also added to the OS database. The OS database is particularly slow to sync and normally takes at least an hour and sometimes a day. If you make a change to your API key, the database will need to sync again and until it does your access will not work, even if it was working previously. This will cause a warning message saying http referer not valid or Invalid API key whenever you try to display a map on your site. Unfortunately there is nothing you can do about this apart from wait. If it doesn’t sort itself out you will need to contact OS directly on their forums, where you will notice this issue arising relatively frequently.

Update June 2018: I am getting reports that the OS database sync is taking up to 2 weeks to happen. This is really annoying but unfortunately there is nothing I can do about it. The problem lies at the OS end.

Installation

The easiest way to install the plugin is directly from wordpress.org. Go to the plugins page on your WordPress dashboard and search for OpenSpace, then click on Install. After installing you will need to Activate the plugin. Once activated, a new menu entry for OpenSpace Maps appears under the Settings menu of your WordPress Dashboard.

Settings

The first and most important setting is the API key obtained previously from the OS registration process. Copy this from the email your received and paste it here.

The next few settings relate to the defaults used with all maps, namely the height and width of the map, the initial map scale and track colour and width used for displaying GPX or KML route files.

You can override these defaults for individual maps using shortcode attributes.

Map scales

The mapping engine supports a wide range of scales from whole UK right through to street level views. In many cases you will not need the extreme zoom out – if your site is about walks in the Brecon Beacons then you probably only need enough zoom out to show that part of South Wales, not the whole UK. On the Admin Settings page you can see the full range of available scales, each with a checkbox to indicate whether you want to use that scale in your maps.

Several map styles are shown in 2 resolutions, the resampled version just being a zoomed-out version of the same map.

The 1:50,000 Landranger maps show exactly what you hope they will, with the full level of detail available on the printed LandRanger maps. The 1:25,000 maps show more details, but unfortunately not the contour information.

This is the list of available scales, along with the number used to identify each one in the shortcode attributes if required.

• 2500 = Whole UK
• 1000 = Whole UK zoomed in a bit
• 500 = Whole UK zoomed in a bit more
• 200 = 1:1M Overview resampled
• 100 = 1:1M Overview
• 50 = 1:250,000 resampled
• 25 = 1:250,000
• 10 = 1:50,000 Landranger resampled
• 5 = 1:50,000 Landranger
• 4 = 1:25,000 VectorMap District resampled
• 2.5 = 1:25,000 VectorMap District
• 2 = 1:10,000 Street View resampled
• 1 = 1:10,000 Street View

Disable mousewheel zoom

By default when the mouse is over the map then the mousewheel can be used to zoom in and out. However this can lead to unexpected zoom when using the mousewheel to scroll down the page; when the mouse enters the map area the action changes from scrolling to zooming. Check this box to prevent the mousewheel from zooming. You can still use the zoom control embedded in the map.

Add download link

Check this box to add a download link to the associated GPX or KML file immediately below the map. This can be useful for sites offering walking and cycling routes. The link just follows the same styling as other links on your site. If you want to change the styling you can do that in the Additional CSS section of the WordPress customizer by setting a style for a.osmap_download.

Inserting a Map

To insert a map into your page you need to add a shortcode. There are three ways to specify what area your map is showing:

• Specify one or more markers to display on the map. For multiple markers the map will automatically zoom and centre to show all markers, unless you give an explicit centre point to override this behaviour.
  [osmap markers="SH6099054380;Snowdon|SH6564658285;Glyder Fach"]
• Specify the centre point and zoom level. This will show a map with no markers.
  [osmap centre="53.068567,-4.076072"]
• Specify a GPX or KML track file to load. The map will automatically zoom and centre to show the entire track.
  [osmap gpx="https://example.com/MyRoute.gpx"]

Markers and centre points can be specified either as a latitude, longitude pair or as an OS 6, 8 or 10 figure grid reference.

The OS mapping engine is very picky about URLs and the domain name of the GPX file must match the domain name of your installation. This can be a problem if your site is accessed as https://example.com/ and also as https://www.example.com/. To work around this you can use site-relative URLs for your GPX files, e.g.

[osmap gpx="/wp-content/uploads/2018/01/MyRoute.gpx"]

GPX and KML files

GPX (GPS Exchange format) and KML (Keyhole Markup Language) files are used to record a route, typically recorded live on a walk by a GPS system. The OS mapping engine allows you to import these as layers on your map, which is useful for showing a route and marking significant features. The file must be on the same WordPress domain as your site, otherwise OpenSpace will reject it. The easiest way is simply to upload as a media file and then copy and paste the URL from your media library.

Unfortunately WordPress 4.7.1 introduced a bug which prevents upload of these files due to over-zealous MIME type checking, resulting in a message “Sorry, this file type is not permitted for security reasons”. This is still not working for GPX and KML as of WordPress 5.0.3 (this is because the correct MIME type for these files begins with application/ and requires explicit whitelisting). It is slated to be fixed at some point in WordPress 5.x but as a temporary workaround around you can install the Lord of the Files plugin, which was created by one of the core WP contributors working on this problem. That plugin requires PHP 7. If you are still running an older PHP version then another (less secure) workaround is the Disable Real MIME Check plugin.

These files can contain waypoint markers as well as the route track itself. These are displayed as small circles.

Shortcode Attributes

height="400" Sets the height of the map in pixels, overriding the default on the settings page

width="600"  Sets the width of the map in pixels, overriding the default on the settings page

scale="5"  Sets the initial map scale using the scale selection value described above in Map Scales.

centre="SD8128299116"  Sets the map centre point, to override the default centre point, or if not using markers or track files.

markers="SD8128299116;Marker 1|54.388698,-2.293453;Marker 2"  This is a list of one or more positions with optional labels. Markers are separated by |, with a ; between the position and label. Markers labels can only include simple text. If you want to use HTML formatting or if you have a long list of markers you can instead define them in a file.

markerfile="http://example.com/markers.txt" Specifies a text file containing the list of markers, one per line. The position and text are separated by ; and the text can include any characters including HTML, should you require a link to another page within the marker.

gpx="http://www.example.com/myfile.gpx"  Specifies a GPX file to be displayed, showing route information.

kml="http://www.example.com/myfile.kml"  Specifies a KML file to be displayed, showing route information.

color="red" or color="#ff0000"  (colour is also acceptable) sets the colour of the track shown from a GPX or KML file.

track="3"  Sets the width of the track in pixels.

Deprecated attributes

As this plugin has developed, a number of improvements have been made leading to some shortcode attributes which are still supported but no longer recommended.

zoom=5 Sets the map scale using an index into the list of scales selected for display where 0 represents the most zoomed out option ticked on the Admin screen. This is not recommended because if you ever change the list of supported zoom levels then you may also have to change the shortcode for every map on your site to get it to display at the same zoom level as it did previously. Superseded by the scale= attribute.

grid=SD8128299116 and ll=-2.293453,54.388698 were previously used to specify a single marker as an OS grid reference or longitude, latitude pair (note the order is reversed from what is conventionally used) in conjunction with label=Wasdale Head. These have been superseded by the markers= attribute.

Examples

Map with two markers, auto-zoomed to show all markers.

[osmap markers="SH6099054380;Snowdon|SH6564658285;Glyder Fach"]

Map with no markers, specified by centre point. Default scale overridden.

[osmap centre="SH6099054380" scale="10"]

Map with GPX track and waypoints (thanks to mudandroutes for the GPX file).

[osmap gpx="https://skirridsystems.co.uk/wp-content/uploads/2018/01/horseshoe.gpx" colour="blue" track="2"]