Overview
This plugin allows maps to be inserted into a page or post using the new Ordnance Survey Data Hub platform which launched in 2020. It displays OS maps with their legendary level of topographical detail, making them ideal for walking, cycling, riding, and just about anything outdoors-related. You can add routes from GPX files, elevation profiles, and markers for points of interest.
This plugin takes over where our previous plugin, OS OpenSpace Maps, leaves off. Ordnance Survey is expecting to switch off the OpenSpace server altogether in August 2021, having replaced it with their new Data Hub. The good news is that the Data Hub service which replaces it is superior in every way. You now have access to the full 1:25,000 Explorer mapping as well as the 1:50,000 Landranger series. And the free allowances are a lot more generous, offering typically 2,000,000 map views per month.
The plugin has been rewritten too, and now uses Leaflet.js to display the maps, giving a cleaner interface and a much more responsive feel. Other goodies include full screen view, colour markers and elevation profiles, one of our most requested features.
The new plugin aims to take over seamlessly from the old one, allowing all your existing pages with to display the same maps without changing the shortcode.
API Key Registration
In order to use this plugin you must first register with the Ordnance Survey for an API key. Head over to the Data Hub website and signup for a free account. Once you’ve signed in, follow the instructions on the Getting Started page to generate a Maps API key. You will need this key after you have installed the plugin.
The other thing you will want to do, assuming you want to show Landranger and Explorer maps, is to upgrade your OS account to Premium. This gives you permission to access their premium data, which includes these maps styles and also the highly detailed scales beyond 1:25,000.
There is no monthly cost associated with a premium account. The pricing page does show a charge per map tile but there is a free monthly allowance. This is large enough that most smaller sites will not even come close to using. It’s counted in map tiles, but OS estimates that it equates to about 2,000,000 map views per month.
You don’t have to provide any credit card details when you opt for premium, and if you don’t and you exceed your allowance, your maps will simply stop being shown, so there is no chance of receiving a huge unexpected bill. There are other settings which we’ll come to later which can help with controlling access.
Note also that there is no premium version of the plugin. The standard free plugin covers everything you need.
Installation
The easiest way to install the plugin is directly from your WordPress dashboard. Go to the Add New Plugin page and search for DataHub, then click on Install. Alternatively you can go to the plugin page on wordpress.org and download it.
After installing you will need to Activate the plugin. Once activated, you will be prompted to enter your API key on the settings page.
Settings Page
You can find the settings page under Settings in the WordPress dashboard, listed as OS Maps.
The first and most important setting is the API key obtained previously from the OS registration process. Copy this from Data Hub project page.
Default Settings
The next few settings relate to the defaults used with all maps, namely the height and width of the map, the elevation profile height, the initial zoom level. You can also set defaults for track colour and width used for displaying GPX or KML route files.
You can override these defaults for individual maps using shortcode attributes (see below).
Global Settings
These settings will affect all maps on your site and cannot be overridden with shortcode attributes.
Premium data use
You can choose who gets to see maps with premium data: Everyone (default), logged-in users, or no-one. Users who do not have access to premium data will see instead the Open Data maps which still offer a good level of detail but not to the same standard as the Landranger and Explorer maps.
If you have a membership site, you might allow only logged-in users to see the premium data. If you don’t need the full colour OS maps for your purpose, you can select no-one to get just the Open Data maps.
Full screen
Maps can now have a full screen button, great for seeing maximum map area. You can also enable this for the user levels shown above.
When the map is not shown full screen, mouse-wheel zoom also requires Ctrl to be pressed and on mobile devices, touch dragging requires two-finger drag. This ensures that the map doesn’t break the page navigation. In full screen mode you can zoom with the mouse-wheel and drag with one finger on mobile devices.
Open data style
There are three available styles for Open Data: Road, Outdoor and Light. Choose the style which suits your needs. If you’re using premium data, this style will only be used for the high detail zoom levels beyond 1:25,000. If you’re not using premium maps, this style will be used for all displays beyond 1:100,000.
Map zoom
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 Global Settings section you can select the maximum and minimum zoom levels you want to allow.
Several map styles are shown in 2 resolutions, the resampled version just being a zoomed-out version of the same map.
This is the list of available zoom levels, along with the number used to identify each one in the shortcode attributes if required.
- Whole UK
- Half UK
- 1:1M
- 1:1M, zoom
- 1:250,000
- 1:250,000, zoom
- 1:50,000 Landranger
- 1:50,000 Landranger, zoom
- 1:25,000 Leisure
- 1:25,000 Leisure, zoom
- 1:3,307 Detail
- 1:1,654 Detail
- 1:827 Detail
- 1:413 Detail
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!red;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.
Note that you can display a GPX file and markers on the same map. The auto-zoom will work on the GPX file and not the markers. If your markers are just showing waypoints on the route then this will not be a problem, but if they lie outside the route then you may not see them all.
[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. The easiest way is simply to upload as a media file and then copy and paste the URL from your media library.
Elevation Profiles
This was one of the most-requested features in OpenSpace maps, and thanks to the power of Leaflet maps we can now provide them. They only work with GPX files (not KML at present) and the elevation data must be included in the GPX file. To see the profile you need to set a height, either by setting the default profile height on the plugin settings page or by using the shortcode attribute.
Shortcode Attributes
Note that the order in which you list attributes is unimportant.
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
profile="200" Sets the elevation profile height, overriding the default on the settings page
zoom="5" Sets the initial map zoom level using the zoom selection value described above in Map Zoom.
centre="SD8128299116" Sets the map centre point, to override the default centre point, or if not using markers or track files. This can be an OS grid reference or a comma-separated latitude/longitude pair.
markers="SD8128299116;Marker 1|54.388698,-2.293453!red;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.
If you want to override the default blue marker colour you can add a colour after the position, separated by a !. Valid colours are: red, orange, yellow, green, blue, violet, gold, grey, black.
Text defined in the markers attribute must be simple text. You cannot reliably use any HTML formatting within a shortcode. If you want to use more complex formatting, or if you have a long list of markers, you can instead define them in a file as described next.
markerfile="http://example.com/markers.txt" Specifies a text file containing the list of markers, one per line. The format is the same as for markers; position and text are separated by ; with optional colour before the text part. The text can include any characters including quotes, so you can use HTML content in your markers, e.g. should you require a link to another page within the marker. A line within the markerfile might look like this:
NY194124!green;Black Sail Hut<br /><a href="yha.org.uk/hostel/yha-black-sail" target="_blank">Youth Hostel</a>
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.
gpxstyle=1 Tells the GPX file processor to take the track colour from the GPX file rather than from the OS maps settings. This is useful for GPX files which contain multiple tracks.
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.
scale=5 Sets the map scale using the mapping from the OpenSpace maps plugin. The new OS API uses a zoom setting instead, so the plugin now also uses the zoom= attribute. This attribute is retained for backward compatibility with existing shortcodes on your pages, but is not recommended for adding new shortcodes.
Removed attributes
grid=SD8128299116 and ll=-2.293453,54.388698 were originally used to specify a single marker as an OS grid reference or longitude, latitude pair in conjunction with label=Wasdale Head. These were deprecated in later versions of the OpenSpace plugin and have now been removed entirely.
Attribute quoting
Like any other shortcode in WordPress, you can use quotes around shortcode attributes of the attribute includes a space or an apostrophe. But be careful that you’re using plain old ASCII straight quotes like ” or ‘. Don’t use “curly quotes” as they won’t work and you may just get a blank map, or you may get an error message to say that the position is not valid.
If you need to use a quotation mark within an attribute value, you must use the alternate quote style, e.g. if you are quoting shortcode attributes using double quotes, you can include single quotes within an attribute.
Examples
Map showing Landranger data
This map of Ambleside is the one OS uses on their own demo pages. You can zoom in to show street level detail, including house numbers. This map is using the defaults from the settings page. Height is set to 400 pixels and zoom to 7. All I have provided here is the centre point as an OS grid reference. In this case it’s a 6-figure reference but you can use 6, 8 or 10. You can also use latitude/longitude if you prefer.
[osmap centre="NY375040"]
Map with three markers, auto-zoomed
This shows how maps with multiple markers will automatically zoom to show all markers. I’ve used a different colour for each of the three peaks.
[osmap markers="SH609543;Snowdon|SH656582!red;Glyder Fach|SH705546!green;Carnedd Moel Siabod"]
Overriding the default settings
If you want to override the defaults for a particular map, just specify the values in the attributes.
[osmap centre="SH6099054380" height="600" zoom="9"]
Map with GPX track and elevation profile
This uses a GPX track to show a walking route on the map. As with multiple markers, the map will auto-scale to show the whole route.
The GPX file also includes elevation data, allowing us to show the elevation profile of the route below the map. If you hover over the profile it will show a marker on the map, and an info box with the height and distance data.
[osmap gpx="https://skirridsystems.co.uk/wp-content/uploads/2018/01/horseshoe.gpx" colour="blue" track="2" profile="175"]
Map with multiple GPX tracks
Unfortunately there is no simple way to show multiple GPX files on one map, but you can combine several tracks into a single GPX file. You can do this manually by editing GPX files in a text editor to include the <trk> sections from several routes into one file.
You can also assign a colour to each track using the GPX extensions tag.
<extensions><line xmlns="http://www.topografix.com/GPX/gpx_style/0/2"><color>FF0000</color></line></extensions>
Place this after the opening <trk> tag. The colour is defined as a hex colour, 3 hex bytes for RGB, so the example above is pure red. You can find the appropriate hex code using this tool. The hex code is the first one shown, labelled #. However you should not include the # in the XML, just the 6 hex digits.
The example below shows several different routes up Snowdon, each in a different colour, which I created by editing several separate GPX files together into this one. Note also that the elevation profile is disabled because it tries to combine the separate tracks into one profile.
[osmap height="750" gpx="https://skirridsystems.co.uk/wp-content/uploads/snowdon.gpx" gpxstyle=1 profile=0]
Thanks to mudandroutes for these GPX files.
Map in a popup window
I’ve been asked whether it is possible to have a map appear in a popup window when a button or link is clicked, to avoid needing a separate page for each map. Sadly the answer appears to be no at the present time. I have tried several different WordPress popup makers and I cannot find a popup which works with OS maps.
I tried other Leaflet maps plugins too and they don’t work in popups either, so it’s not a problem specific to this plugin.