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). Further information and API documentation and many examples can be found at http://www.openlayers.org/.

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

The project page on Sourceforge: http://sourceforge.net/projects/osgbwebmaptools/

Main documentation website: http://osgbwebmaptools.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.

For more information see: http://ordnancesurvey.co.uk/oswebsite/business/

OSGB Web Map tools
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:

OpenSpace.MapPoint

and

OpenLayers.LonLat 

Using Local Host
Local host is used for development purposes and OS OpenSpace has been configured to work using local host 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 however 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. 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(); 

supportService.getTileCount(tileCountResults); 

... 

The callback function

function tileCountResults(tilesUsed, maxTiles) 

{ 

    var s = "Tiles Used: " + tilesUsed + " of " + maxTiles; 

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
  Please ensure that your code includes
  
• 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 192.168.1.68), 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.

Debugging
Debugging can be done by using the Firebug Lite JavaScript library, obtained at http://www.getfirebug.com/lite.html

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.

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

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

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