OS DataHub Maps

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.

The plugin takes over where the previous plugin, OS OpenSpace Maps, left off. Ordnance Survey will be switching off the OS OpenSpace server at the end of August 2021, having brought online the new OS Data Hub and its suite of APIs. The good news is that the OS Data Hub service 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.

The remainder of the settings have usable default values so you can come back to these later if you wish and get started with inserting a map.

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.

0. Whole UK
1. Half UK
2. 1:1M
3. 1:1M, zoom
4. 1:250,000
5. 1:250,000, zoom
6. 1:50,000 Landranger
7. 1:50,000 Landranger, zoom
8. 1:25,000 Leisure
9. 1:25,000 Leisure, zoom
10. 1:3,307 Detail
11. 1:1,654 Detail
12. 1:827 Detail
13. 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.

Note that a link will only be shown if there is one GPX or KML file selected. For multiple files you will need to add the links manually.

Inserting a Map

To insert a map into your page you need to add a shortcode. In its simplest form, you can just add [osmap] to your page. If your API key is set up correctly this will display a map with the default height and zoom level, centred on OS headquarters in Southampton. It’s a quick test, but not very useful.

There are four ways to specify what area your map is showing:

• Specify the centre point and zoom level. This will show a map with no markers. This shows a specific map scale, e.g. 1:50,000 but makes no guarantee about what area will be shown on screen due to differing screen sizes.
  [osmap centre="53.068567,-4.076072 zoom=7"]
• Specify two diagonally opposite corners of the area you want to be displayed. This differs from the first method in that the zoom level will adapt to fit the required area to the screen. On a small screen it will need to use a more zoomed out scale.
  [osmap extent="NY200200|NY260220"]
• 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 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. OS grid references must include the two letter prefix, not just the numbers.

Note that you can display a GPX file and markers on the same map. The auto-fit will accommodate them all.

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. KML files can also show polygon areas as well as linear routes, so they are useful for showing areas and boundaries. 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) 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.

Simple 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.

extent="NY200200|NY260220" Sets the map area to be covered. This requires two points, diagonally opposite corner s of the area you want to be displayed.

color=red or color=#ff0000 sets the colour of the track shown from a GPX or KML file.

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

opacity=0.8 Sets the track opacity from 0.0 to 1.0. Default value is 0.7.

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. Note that it is now possible to include multiple GPX files, so this method is less often required.

quote=^ Defines a character which will be turned into a double-quote when the shortcode is processed. This may be used in marker descriptions as described below.

Route, Marker and Layer Attributes

Defining routes and markers is a little more complicated as you can add multiple markers or route files. All of these follow broadly the same structure; individual items (markers or routes) are separated by | and there are several sub-attributes you can add to each item using $, ! and ; separators.

The location (marker) or filename (route) is required and always comes first. The other modifiers are optional.

As a simple example you could add two markers like this:
markers="SD8128299116|54.388698,-2.293453"

Or two GPX files like this:
gpx="https://www.example.com/myfile.gpx|https://www.example.com/another.gpx"

The optional parts follow after the location. None of them are required, but they must always be in this order:

1. $1 Layer specifier. If you are using switchable layers, this defines which layer to add the item to. Layers are described later. Normally you won’t need them.
2. !red Colour specifier for the item. This allows you to colour code the markers or routes on your map. For routes this can be any HTML colour or HTML # code. For markers you can only use the names colours listed below.
3. ;description Marker description. This is what appears in a bubble when you click on the marker. Normally this will be plain text. HTML is possible with limitations.

Marker Colours

For markers there are nine specific colour names you can use. If you try anything else you will get the default blue marker. Valid colours are: red, orange, yellow, green, blue, violet, gold, grey, black.

HTML in Descriptions

The problem with shortcodes is that they use quoting around the attributes. If you want to include a link, you would need to put the link destination in quotes, which messes up the shortcode. There is a way round this, albeit a little messy. You can use the quote attribute to define a character that you want to be converted into a double quote.

If your description text is <a href="https://example.com/crib-goch-walk/">Crib Goch Walk</a> then you could define your quote character as ^ and use <a href=^https://example.com/crib-goch-walk/^>Crib Goch Walk</a> in your shortcode.

If you have a lot of markers, or if the HTML is more complex, you may want to use the markerfile option instead.

A fully populated example

Putting all these optional parts together you might specify a marker like this, which specifies a grid reference, layer 1, marker colour red and marker text Glyder Fach:
markers="SH6564658285$1!red;Glyder Fach"

List Files

If you have a lot of markers or routes, or if the descriptions are long, you may be better putting the definitions into a text file. This works for markers, GPX and KML files. Instead of using | to separate items, you put them in the text file one item per line. In this case you just include the information you would otherwise have put inside the markers="" attribute, e.g.:

SH6099054380!red;Snowdon
SH6564658285!green;Glyder Fach

Upload the text file to your WordPress media library and refer to the file instead.

markerfile="http://example.com/markers.txt"
gpxfile="http://example.com/gpx_routes.txt"
kmlfile="http://example.com/kml_overlays.txt"

Using Layers

If your map includes a lot of overlays or markers, you may want a way of turning groups of them on or off to show or hide detail on the map using layers. When you specify layer names, a new icon appears in the top right corner of the map allowing you to toggle the individual layers on and off. There are two parts to setting this: defining the layer names, and assigning markers and routes to the layers.

layers="Civil Parish|-Ecclesiastical Parish|-School Catchment"

This defines three layers, in this case showing different boundaries. The first one is initially on and the second two are initially not shown, indicated by the leading - sign.

When adding the KML files which define these boundaries, we need to specify which layer number to assign them to. The first is layer 1, etc. We may also want to use different colours.

kml="https://example.com/civil_parish.kml$1!red|https://example.com/ecc_parish.kml$2!purple| https://example.com/school_catch.kml$3!#804467"

This has assigned the three KML files to the three different layers. You can of course assign multiple items to a layer, such as a group of markers, and you can mix markers and routes within a layer. Items not assigned to a layer are always shown.

Additional Shortcode for Markers

If you want to add a legend below your map referring to the markers, you may want to include an image of the marker so your readers can see which one you mean. There’s a shortcode for that which you can embed in your text.
[osmap_marker color=red]

The colours supported are the same as the marker colours.

Summit of Snowdon
Glyder Fach

Deprecated and Removed 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. Or for marker descriptions you can use the quote attribute to define a substitute in order to work around this.

Examples

The simplest possible map

Ordnance Survey headquarters is the E-shaped building in the middle.

[osmap]

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" color="darkgreen" track="4" profile="175"]

Map with multiple GPX tracks

This example combines six different GPX tracks onto one map, assigning a different colour to each.

[osmap height=750 gpx="https://skirridsystems.co.uk/wp-content/uploads/ranger-track1.gpx!#800080|https://skirridsystems.co.uk/wp-content/uploads/watkinpath.gpx!#000080|https://skirridsystems.co.uk/wp-content/uploads/south_ridge.gpx!#FF0000|https://skirridsystems.co.uk/wp-content/uploads/llanberis-path11.gpx!#008000|https://skirridsystems.co.uk/wp-content/uploads/miners-path.gpx!#008080|https://skirridsystems.co.uk/wp-content/uploads/cribgoch_GPS.gpx!#808000"]

Thanks to mudandroutes for these GPX files.

Map with layers

This map is used to show three different boundaries and the differences between them. Click on the layers button in the top right corner to switch layers on and off.

[osmap kml="https://skirridsystems.co.uk/wp-content/uploads/ComptonandShawfordOSM.kml$1!#00ff88|https://skirridsystems.co.uk/wp-content/uploads/HCCSchoolCatchmentOSM.kml$2!#8800ff|https://skirridsystems.co.uk/wp-content/uploads/ChurchParishBoundaryOSM.kml$3!#ff8800" layers="Civil Parish Boundary|-School catchment - HCC version|-Ecclesiastical parish boundary"]

Thanks to Compton and Shawford Parish Council for these KML files. Ecclesiastical boundary reproduced by permission of the Church Commissioners

Printing maps

If you enable printing in the settings, the map will include a print icon which offers 4 options:

• Portrait
• Landscape
• Auto
• Custom

The first 3 work as you expect, but if you want to print from the fullscreen view then you have to use Auto, otherwise the print window will not show the extended area. I’m not sure why this is. Auto is generally the best choice but it may not work in all browsers.

Custom initially appears to do nothing, but a crosshair appears allowing you to select an area of the map. Once you’ve dragged out a rectangle, the print dialog appears showing only the selected area. I may drop this option later as it seems of limited use.

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.