OS OpenSpace^™ FAQ

1. General

1.1 What is OS OpenSpace?

OS OpenSpace is a free Ordnance Survey service that allows you to embed Ordnance Survey maps covering England, Scotland and Wales in your web applications using our JavaScript® application programming interface (API).

1.2 What can I do with OS OpenSpace?

You can build your own web application as long as you are acting as a private individual; it is for non-commercial purposes and it complies with the OS OpenSpace Developer Agreement.

The JavaScript API allows you to place any kind of information that has a geographic reference (such as National Grid reference or latitude/longitude) on top of Ordnance Survey maps.

1.3 I have some data which I have already geocoded. If I plot this using OpenSpace does Ordnance Survey own it?

No. When you are simply using OS Openspace to display data you have geocoded yourself by other means, your geocoded data remains yours. Provided that any data you create is not derived in any way from, and does not contain any elements of, Ordnance Survey Data, then it does not amount to 'Derived Data' which we may claim ownership of under clause 4.5 of the OS OpenSpace Developer Agreement.

1.4 I am using OS OpenSpace to create a database of location based information, does OS own this?

Yes. When you use OS OpenSpace to geocode data by adding geographical attributes to it that have been accessed from and/or made available by Ordnance Survey then the resulting data is considered to be derived from Ordnance Survey Data. OS would own such 'Derived Data but grant you a perpetual, non-exclusive, personal license to use it within your application. Please see Clause 4.5 of the OS OpenSpace Developer Agreement.

1.5 What is a JavaScript API?

The OS OpenSpace API is a piece of software code you can embed in your web application that provides you with all the necessary functionality to interact with a map, like panning, zooming in and out, and adding markers and polygons.

The advantage of using an API is that you don't need any knowledge of geographical information systems (GIS), just a bit of HTML and JavaScript.

1.6 How much data am I allowed to use?

OS OpenSpace allows your API key to access up to 30 000 tiles of data and up to 1 000 place name look-ups per day for free.

You can find more information in the Data allowance section of the FAQs.

1.7 What is a map tile?

A tile of data is a square of a digital map, with a size between 200 and 256 square pixels. Each OS OpenSpace map is displayed on your screen by joining multiple adjacent tiles.

Map demonstrating the use of map tiles

1.8 Who can I contact if I need more information?

Send us an email at openspace@ordnancesurvey.co.uk

2. Getting started

2.1 How do I start using OS OpenSpace?

It is very simple. All you need to do is register to receive your own API key and start using OS OpenSpace on your website.

Take a look at the documentation to see how to start building your first application and to get the most out of it.

When you have registered you will also be provided with examples, including code snippets, to help you get started.

2.2 What is an API key?

An API key is a unique alphanumeric code we will send you when you register. You will need to include this code in your web application when using the API.

This key will only work with the URL you need to specify when you register.

2.3 Do I need an API key to use OS OpenSpace?

Yes, if you want to use the OS OpenSpace API to display maps in your web application you will need a key. A unique key will be sent to you once you have registered.

2.4 Where can I find help if I have a problem?

If you have any problem developing your application check the documentation and the examples. You can also post a question on the forum and someone in the community may be able to help you.

3. Features

3.1 Which data layers are included in OS OpenSpace?

There is a range of Ordnance Survey digital products that are displayed at each zoom level:

outline of Great Britain (zoom level 0);
overview of Great Britain (zoom level 1-2);
MiniScale® (zoom level 3-4);
1:250 000 Scale Colour Raster (zoom level 5-6);
1:50 000 Scale Colour Raster (zoom level 7-8); and
OS Street View® (zoom level 9-10).

3.2 How can I find the location of a place?

The API has its own gazetteer look-up service that includes all the place names in the 1:50 000 Scale Gazetteer, which contains over 250 000 entries with every name featured on the 1:50 000 Scale Colour Raster product. (zoom level 7-8).

When you query the gazetteer with the name of the place you need to find, the API will return the matching place name(s) and their National Grid reference.

You can use the gazetteer to search for place name locations up to a 1 000 times every day.

3.3 How can I find the location of a postcode?

Postcode look-ups are not currently available within OS OpenSpace.

There are a number of free geocoding services available on the Internet that can provide this functionality.

3.4 Is aerial imagery included with OS OpenSpace?

The OS OpenSpace API currently provides a range of different raster maps at different zoom levels, including the detailed OS Street View. However, imagery is not available within OS OpenSpace.

3.5 What can I use to present information on top of the maps?

The OS OpenSpace API has a variety of functions to display different data on top of the maps. You can use markers (OS OpenSpace standard marker or your own one), lines, polygons and pop-up boxes with the content or media you wish.

Check the documentation if you need more information.

3.6 Which browsers are supported?

At the moment OS OpenSpace supports IE6+, Firefox® 1.5+, Safari® 2+ and Opera 8+.

3.7 Can I use National Grid references?

The OS OpenSpace API and all the data provided is in British National Grid (ESPG 27700). The API also provides the ability to convert between National Grid and latitude and longitude (ESPG 4326) and vice versa.

3.8 Can I have OS OpenSpace maps in more than one page on my website?

Yes, you can use the OS OpenSpace API on more than one page of the publicly available URL folder you register when you sign up. The available data per day will be for all pages at the registered URL folder.

3.9 Can I access the map images directly?

No, all the data in OS OpenSpace is only accessible with a valid API key and must be used within a publicly accessible application.

4. OS OpenSpace website

4.1 Who can access the forum?

Any registered developer. The forum has been set up as a place for the OS OpenSpace community to meet, share, discuss and help each other.

If you have not registered and would like to be part of this community, register to get your own API key.

5. Data allowance

5.1 How much data can I use?

OS OpenSpace allows your API key to access up to 30 000 tiles of data and up to 1 000 place name look-ups per day for free.

If at any point your application becomes so popular that this limit is not enough, please contact us.

5.2 What if I ever reach the daily allowance?

Your web application users will see a white tile displaying an appropriate message. We are working to expand the API functionality to let you check how close you are to the limit.

5.3 How do I know if I have reached my daily tile allowance?

We are working to launch a 'My OS OpenSpace' area for each developer, where you will be able to check how popular your application is and the number of tiles you've served to your users.

5.4 My site gets a lot of traffic, what can I do?

Congratulations :! Contact us to talk about the different possibilities we may be able to offer you. If you are interested in commercialising your application, take a look at point 6.2 of the FAQs.

6. Use of OS OpenSpace

6.1 Where can I find what uses I can put the OS OpenSpace API to?

Take a look at the OS OpenSpace Developer Agreement, where you will find all the information about the use of the API.

6.2 I have built an application and now I want to get some revenue from it. What can I do?

The OS OpenSpace Developer Agreement does not allow any financial gain to be derived from your application (either directly or indirectly). Depending on the type of application, you will have different options for how to progress. For all uses of data we have standard licence agreements that are fair to all, so your application will need to fit within those terms.

For more information please contact us or visit Ordnance Survey licences and agreements explained web page.

6.3 Can I have adverts like Google® Ads on my website? (is it only on the same page as the map or the whole site?)

No. There can be no advertising, paid promotional content or other revenue generating activities associate with any part of your website. Please see the definition of Purpose in Clause 1 of the OS OpenSpace Developer Agreement.

6.4 Can I build an application for Facebook®, MySpace™,or any other social networking or commercial website?

No. Your application may not interface with Facebook/MySpace because such sites carry paid for advertising and promotional content, from which third parties may accrue commercial and/or financial benefits. Doing so would be contrary to the non-commercial nature of OS OpenSpace. However you can embed your application inside websites which are non-commercial and which do not carry paid promotional content. Please see the definition of 'Purpose' in Clause 1 of the OS OpenSpace Developer Agreement.

6.5 Can I use my application on a private network or password protect it?

No, the URL folder you register and the application you build must be publicly accessible and not behind a password, internal network or other form of restriction.

6.6 Can users of my application create their own location information using OS OpenSpace?

Yes, the OS OpenSpace API provides a range of functionality to let you create different data and location information in a web application. The OS OpenSpace Developer Agreement sets out the position regarding the ownership and licensing of the copyright and other intellectual property rights in:

any data supplied to you by us; and
any data created by you.

Primarily, you cannot use any data you create for any commercial purpose.

6.7 Can I build an application for a local government, central government or other public sector organisation?

OS OpenSpace is for non-commercial use only. You cannot therefore develop an application for any organisation. This includes those operating in the public sector - many of which already make use of Ordnance Survey data under alternative licensing arrangements.

7. Technical

7.1 What is OpenLayers?

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). The website can be found here: http://www.openlayers.org and contains further API documentation and many examples.

7.2 What version of OpenLayers is used?

OpenLayers 2.5.

7.3 Including the OpenSpace API

The OpenSpace API is included as a JavaScript tag in the HEAD section of an HTML page on a developer's website.

<script src="http://openspace.ordnancesurvey.co.uk/openspace.js?key=INSERT_YOUR_KEY_HERE"></script>

7.4 Versioning of the OpenSpace API

Each release of the 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 that version by including the v parameter in the API request tag.

e.g

<script src="http://openspace.ordnancesurvey.co.uk/openspace.js?key=INSERT_YOUR_KEY_HERE&v=0.6"></script>

7.5 JavaScript Namespaces

The 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

7.6 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 OpenSpace API script, and, depending on the browser using it, must be included from the same domain as your application.

<script type="text/javascript" src="http://PATH_TO_FIREBUG/firebug/firebug.js"></script>

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.

7.7 Gazetteer search

The gazetteer service can be called via an AJAX-style call. There are currently two functions, getLocations() which returns a list of GazetteerEntry objects that contain information about matching placenames, and getLonLat(), which will get the position of the first match.

Example:

var gazetteer = new OpenSpace.Gazetteer();
function searchGazetteer(query)
{
// Query the gazetteer and call the callback function
gazetteer.getLocations(query.value, onResult);
return false;
}
function onResult(locations)
{
if (locations != null && locations.length > 0)
{
for (var i=0; i < locations.length; i++)
{
// Extract result fields
var name = locations[i].name;
var county = locations[i].county;
var location = locations[i].location
var coordStr = location.toCoordString();
// Do something with the info
……
}
// (Or optionally)
// Set centre of the map to the first point
osMap.setCenter(locations[0].location, 6);
}
}

The results of a gazetteer search are returned in order of cities, towns, others, and finally unknowns. Further information on the type can be obtained from the type field of a GazetteerEntry

where:

CITY = "C"
TOWN = "T"
OTHER = "O"
ANTIQUITY = "A"
FOREST = "F"
FARM = "FM"
HILL = "H"
ROMAN = "R"
WATER = "W"
UNKNOWN = "X"

7.8 Creating markers and InfoWindow popup custom size

This example uses a custom icon and a custom popup info window size:

// Position on the map
var position = new OpenSpace.MapPoint(438700, 114900);
// Define a custom icon
var size = new OpenLayers.Size(35, 45);
var offset = new OpenLayers.Pixel(-16, -37);
var infoWindowAnchor = new OpenLayers.Pixel(16, 16);
var icon = new OpenSpace.Icon('http://openspace.ordnancesurvey.co.uk/osmapapi/img/OS/images/markers/marker_blue.png', size, offset, null, infoWindowAnchor);
// Define the content to display in the popup
var content = "test info window content in HTML";
// Define custom size for popup
var infoWindowSize = new OpenLayers.Size(200, 300);
// Create the marker
var marker = osMap.createMarker(position, icon, content, infoWindowSize);

7.10 How to detect daily tile quota exceeded?

There is 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;
}

7.11 How to turn off map centring when markers are clicked?

The centring behaviour can be turned off by using a custom map option:

osMap = new OpenSpace.Map('map', {centreInfoWindow: false} );

7.12 Downloading custom user data

To do AJAX-style loading of custom user data while the map is being displayed, use the OpenLayers.loadURL() method, or for a more complete solution, use the XMLHttpRequest library at http://code.google.com/p/xmlhttprequest

OS OpenSpace™ FAQ