Jump to the following:

By continuing, you agree to the use of cookies by us and third parties, which we use to improve your visit.

Using and debugging OS OpenSpace

OS OpenSpace is built upon an Open Source library called OpenLayers. The OpenLayers project provides a standard open mapping JavaScript framework, supported by the Open Source Geospatial Foundation (OSGeo).

Our API proprietary code, supporting documentation and build instructions has been released as OSGB Web Map Tools and is free to download from SourceForge.net

Although the OSGB Web Map Tools project does not provide free access to our data sets, it has been designed specifically to work with our data. To use our data you will need a data licence. We have a wide range of data licences available for businesses and other commercial requirements.

OSGB Web Map tools

This is a set of software code and installation instructions that will help organisations to use our data on the Internet. Organisations can build applications with any other type of content provided they have permission, are allowed to and are licensed to do so.

The OSGB Web map tools enable you to build the following into your web applications:

  • A map viewer.
  • Map panning, zooming and overview map controls.
  • Map styling options, including markers and vector overlays.
  • Gazetteer searching.
  • Transformation of National Grid coordinates to and from latitude and longitude.

The tools also include server side and tile cutter software to manage our data in your applications.

The OSGB Web map tools project is released under a permissive free licence, specifically a BSD-style licence.

JavaScript namespaces

The OS OpenSpace API uses the OpenSpace namespace for all its own functions and classes. The OpenLayers functions and classes remain in their own OpenLayers namespace.

For instance:




Using localhost
Localhost is used for development purposes and OS OpenSpace has been configured to work using localhost prior to go live.

Once you have completed your development you need to ensure that your registered URL is the host URL for your website. Once you have checked this you will need to add all your code to your site. To add your code to your site you can use an FTP client, most hosts/providers supply an FTP service free of charge, although some do charge. Use the ftp client to upload your html file.

Once you have uploaded your html file to a server using an FTP client you will need to add a script to your page. In your web site page, where you want the web-map to appear, insert the following script into the body of the page or blog html editor:

<iframe src="http://mysitedomain.com/oswebmap.htm" width=570" height="460" frameborder="0" scrolling="auto" name="oswebmapframe">

You’ll only need to do this once.

Calling a tile count

There is also a support service which has a function that can be called to get the current tile count and tile limit. The tile count may be a cached value, but is likely to be accurate to within a few minutes. This function is probably best called when the page is first loaded to check if there are any tiles left and then display some form of error message. The service calls a user-supplied callback function that takes two integer parameters.

To call the service:

var supportService = new OpenSpace.SupportService(); 

include the callback function:

function tileCountResults(tilesUsed, maxTiles) 
    var s = "Tiles Used: " + tilesUsed + " of " + maxTiles; 

in your code.

OS OpenSpace API versioning

Each release of the OS OpenSpace API has an associated version number. The API request automatically returns the most recent version of the API, but if you need to get an earlier version, you can explicitly request loan modification that version by including the v parameter in the API request tag.

The documentation gives details of the current version of the API and supported back versions.

HTTP Referrer Error

There are a variety of different reasons for you to experience an http referrer error when trying to display a map on your web page. Here are a few causes and possible resolutions to help you solve this error and get the mapping displayed correctly.

Host URL

Please ensure that the url that has been registered against your API Key is the host url and contains the full url address i.e www.mydomainname.co.uk. Failure to register your host url will result in an http referrer error being present.

Enabling cookies

Ensure that the cookies have been enabled for the site that you are displaying the mapping screen on.

Included in the code

<source lang="html4strict" enclose="pre" highlight="5" ordnancesurvey.co.uk/osmapapi/openspace.js

Please ensure that you include

script type="text/javascript src=</source>


in your HTML.

Firewall and Security Settings

There could be a problem for a firewall, and/or the browser's security settings. This is because some of the content in any page containing a live map which is coming from a third party site, as a result either piece of software must decide whether it can trust it or not. In general a firewall or the browser should loan modification ask whether the content should be allowed, in which case answering 'yes' will allow the map to load without problem, or if 'no' is selected it will silently block it, leading to a blank map.

Local IP

Should you start testing OS OpenSpace on different computers that connect to a local webserver running on the same network using a local ip address (eg, you will recieve the Http Referrer error. OS Openspace does not like a referring URL to be a local IP and as a result it will display the error HTTP Referrer not valid. Refreshing the page will make it work, because now the referring URL is valid.

Additional URLs

If you have added additional url's to your existing OS OpenSpace API key and get an http referrer error for these new url's this could be due to an error with the url address. Check that your url has been registered with http:// and also includes www. in the address.

Version Number

You shouldn't normally need to amend the version number and we would advise only inserting this code when you have a definite need for it. Try inserting the &v=0.8.0 at the end of the OpenSpace script load URL.

How to report a bug

To report an issue because you think that there might be a bug, announce it first in the forum because other developers will then be able to confirm whether or not there is a problem with your code. If the issue cannot be resolved, then the OS OpenSpace Team will investigate it.


You can debug using the Firebug Lite JavaScript library.

The Firebug Lite script must be included before the OS OpenSpace API script, and, depending on the browser using it, must be included from the same domain as your application.

OpenLayers.Console.log("This is a test");

This will then allow the OpenLayers.Console namespace to be used for debugging and error logging. For instance:

will display "This is a test" in either the Firebug console (where available) or the Firebug Lite console.

Back to top
© Ordnance Survey 2019