Jump to the following:

OS OpenSpace [logo]

Technical FAQs

This page contains tecnical FAQs, for the OS OpenSpace API. For information on; getting started, features, forum, data allowance and use then please visit the general FAQs page.

1 Questions

1.1 What is OpenLayers?

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

1.2 What version of OpenLayers is used?

OpenLayers 2.7.

1.3 How to include the OS OpenSpace API

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

  1. <scriptsrc="http://openspace.ordnancesurvey.co.uk/osmapapi/openspace.js?key=INSERT_YOUR_KEY_HERE"></script>
1.4 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 that version by including the v parameter in the API request tag.

e.g

  1. <scriptsrc="http://openspace.ordnancesurvey.co.uk/openspace.js?key=INSERT_YOUR_KEY_HERE&v=0.6"></script>
1.5 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:

  1. OpenSpace.MapPoint

and

  1. OpenLayers.LonLat
1.6 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.

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

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

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

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

1.9 Can I find the location of a postcode?

Yes, a postcode look-up service is available with the OS OpenSpace API.

The API will accept a postcode e.g. SO16 4GU and return a single corresponding easting and northing which is the nominal centre of that postcode area.

The API will accept a postal districte.g.SO16 and return a single corresponding easting and northing calculated from the average of the postcodes that relate to the given postal district.

The API will not allow a postal district search of postal districts from Northern Ireland, Jersey, Guernsey or Isle Of Man (postal areas "BT", "JE", "GY", "IM" respectively)

1.10 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:

  1. var gazetteer = new OpenSpace.Gazetteer();
  2. function searchGazetteer(query)
  3. {
  4.     // Query the gazetteer and call the callback function
  5.     gazetteer.getLocations(query.value, onResult);
  6.     return false;
  7. }
  8. function onResult(locations)
  9. {
  10.     if (locations != null && locations.length > 0)
  11.     {
  12.         for (var i=0; i < locations.length; i++)
  13.         {
  14.             // Extract result fields
  15.             var name = locations[i].name;
  16.             var county = locations[i].county;
  17.             var location = locations[i].location
  18.             var coordStr = location.toCoordString();
  19.             // Do something with the info
  20.             ……
  21.         }
  22.         // (Or optionally)
  23.         // Set centre of the map to the first point
  24.         osMap.setCenter(locations[0].location, 6);
  25.     }
  26. }

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"
1.11 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.

1.12 Creating markers and InfoWindow popup custom size

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

  1. // Position on the map
  2. var position = new OpenSpace.MapPoint(438700, 114900);
  3. // Define a custom icon
  4. var size = new OpenLayers.Size(35, 45);
  5. var offset = new OpenLayers.Pixel(-16, -37);
  6. var infoWindowAnchor = new OpenLayers.Pixel(16, 16);
  7. var icon = new OpenSpace.Icon('http://openspace.ordnancesurvey.co.uk/osmapapi/img/OS/images/markers/marker_blue.png', size, offset, null, infoWindowAnchor);
  8. // Define the content to display in the popup
  9. var content = "test info window content in HTML";
  10. // Define custom size for popup
  11. var infoWindowSize = new OpenLayers.Size(200, 300);
  12. // Create the marker
  13. var marker = osMap.createMarker(position, icon, content, infoWindowSize);
1.13 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:

  1. ...
  2. var supportService = new OpenSpace.SupportService();
  3. supportService.getTileCount(tileCountResults);
  4. ...

The callback function

  1. function tileCountResults(tilesUsed, maxTiles)
  2. {
  3.     var s = "Tiles Used: " + tilesUsed + " of " + maxTiles;
  4. }
1.14 How to turn off map centring when markers are clicked?

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

  1. osMap = new OpenSpace.Map('map', {centreInfoWindow: false} );
1.15 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

Introduction to Ordnance Survey data derived from the Boundary-Line™ product

Ordnance Survey data derived from the Boundary-Line™ product are administrative and electoral boundaries for England, Scotland and Wales. These include counties, unitary authorities, Westminster constituencies, wards and many more. They have been derived from Boundary-Line to ensure compatibility and good performance with web applications built using OS OpenSpace API. The geometry information is represented as vector digital data, supplied in GeoJSON format.

With Ordnance Survey data derived from the Boundary-Line™ product you can:

  • Customise and style boundaries for your web site.
  • Design thematic maps using your own or third party data.
  • Inspire and amaze people with environmental, political and other social statistics.
  • Experiment and innovate.
1.16 What is a boundary feature?

Ordnance Survey data derived from the Boundary-Line™ product are made up of boundaries are made up of 11,773 individual boundary areas known as features. Each feature has a unique ADMIN_UNIT_ID is made up of the following attributes:

  • Boundary Line Name (NAME)
  • Administrative boundary area (AREA_CODE)
  • Census code (CENSUS_CODE)
  • Geometry as XMIN YMIN XMAX YMAX (BOUNDING_BOX) This geometry information attribute is optional.
  • Centroid of the feature as easting and northing as x,y (CENTROID)
  • Resolution of data (RESOLUTION)
  • Description of the boundary type (DESCRIPTION)
  • Administrative Unit ID (ADMIN_UNIT_ID)
  • Area of the feature in Hectares (HECTARES)
  • Type Code (TYPE_CODE)
  • Type Definition (TYPE DESCRIPTION)
1.17 Which Ordnance Survey data derived from the Boundary-Line™ product is available?

The following list shows:

OS OpenSpace boundary DESCRIPTION, (AREA_CODE) and feature count (number of boundary areas of this type)

  • County, (CTY) 27
  • County Electoral Division, (CED) 1739
  • District, (DIS) 201
  • District Ward, (DIW) 4585
  • European Region, (EUR) 11
  • Greater London Authority, (GLA) 1
  • Greater London Authority Assembly Constituency, (LAC) 14
  • London Borough, (LBO) 33
  • London Borough Ward, (LBW) 649
  • Metropolitan District, (MTD) 36
  • Metropolitan District Ward, (MTW) 815
  • Scottish Parliament Electoral Region, (SPE) 8
  • Scottish Parliament Constituency, (SPC) 73
  • Unitary Authority, (UTA) 110
  • Unitary Authority Electoral Division, (UTE) 1334
  • Unitary Authority Ward, (UTW) 1464
  • Welsh Assembly Electoral Region, (WAE) 5
  • Welsh Assembly Constituency, (WAC) 40
  • Westminster Constituency, (WMC) 628
1.18 Are there high level administration relationships in Ordnance Survey data derived from the Boundary-Line™ product?

In England;

A County (CTY) is divided into Districts (DIS) which is divided into District Wards (DIW). For voting purposes a County is divided into Electoral Divisions (CED)

Unitary Authorities (UTA) are, for voting purposes, divided into Unitary Authority Wards (UTW) - except in the Isle of Wight, where it is the Unitary Authority Electoral Division (UTE)

England also has Metropolitan Districts (MTD); these have no County administration. These Districts are divided for voting purposes into Metropolitan District Wards (MTW).

With the introduction of the regional government for London, in this document called the Greater London Authority (GLA); the proportional representation voting area for this new administration is the Greater London Authority Assembly Constituency (LAC). The existing London Borough (LBO) structure also has a relationship with the new Greater London Authority and each London Borough is divided for voting purposes into London Borough Wards (LBW).

In Scotland;

Unitary Authorities (UTA) are, for voting purposes, divided into Unitary Authority Wards (UTW).

The Scottish Parliamentary Electoral Region (SPE) is divided into Scottish Parliamentary Constituencies (SPC). Scotland is divided into Parliamentary Constituencies for voting purposes; to elect Members of the Scottish Parliament.

In Wales;

Unitary Authorities (UTA) are, for voting purposes, divided into Unitary Authority Electoral Divisions (UTE).

The Welsh Assembly Electoral Region (WAE) is divided into Welsh Assembly Constituencies (WAC). Wales is divided into Welsh Assembly Constituencies for voting purposes; to elect Assembly Members to the Welsh Assembly.

In Great Britain;

Great Britain is divided into European Regions (EUR) (Scotland, Wales and nine English regions) for voting purposes to elect members to the European Parliament.

England, Scotland, and Wales are divided into Westminster Constituencies (WMC) for voting purposes to elect members to the Westminster Parliament. Westminster Constituencies are made up of combinations of Wards (or Unitary Authority Electoral Divisions (UTE) in Wales), but they don't have consistent common boundaries.

1.19 Is there a lookup table of all the boundary features?

A lookup table (csv) is available to download from the forum with the following attributes:

NAME | CENSUS_CODE | ADMIN_UNIT_ID | AREA_CODE | DESCRIPTION | CENTROID

The NAME is the distinctive name of the boundary area.

The CENSUS_CODE data is created by the Office of National Statistics allows you to link Ordnance Survey data derived from the Boundary-Line™ product with census statistics. It can be used to identify a logical structure between certain boundary areas. For example District Wards nests into Districts which nests into Counties:

  • County (CTY) - Hampshire, 24
  • District (DIS) - Basingstoke and Deane District, 24UB
  • District Ward (DIW) - Basing Ward, 24UBJX

The census codes are present as attributes for the following AREA_CODEs:

  • CTY, DIS, DIW, LBO, LBW, MTD, MTW, UTA, UTE, UTW,
  • The ADMIN_UNIT_ID is a unique identifier created by Ordnance Survey.
  • The AREA_CODE is the name of the feature area type e.g. CTY
  • The DESCRIPTION is the type description of the AREA_CODE e.g. County.
  • The CENTROID is an x,y nominal centre coordinate of the feature
1.20 What is the meaning of Ordnance Survey data derived from the Boundary-Line™ product RESOLUTION?

Ordnance Survey data derived from the Boundary-Line™ product has been generalised at six different resolutions (RESOLUTION) to ensure that the vector data is appropriately scaled and maintains performance at different zoom levels.

The following data resolution by zoom level is detailed in a table (csv) in the forum and shows the resolutions available for all boundary areas by AREA_CODE.

Zoom Level Raster data shown boundaries Resolution
10 & 9 Streetview 5m
8 & 7 1:50 000 20m
6 & 5 1:250 000 200m
4 & 3 MiniScale (1:1M) 500m
2 Overview 1000m
1 Overview 2000m
0 Overview 5000m
1.21 Are there any special characteristics of Ordnance Survey data derived from the Boundary-Line™ product?

Ordnance Survey data derived from the Boundary-Line™ product is derived from Ordnance Survey's dataset Boundary-Line and will still show the following characteristics:

Extent of the Realm (EOR)

This is where a boundary area is digitised on the alignment of the mean low water for the seaward extent. This is prevalent particularly around the estuaries of Great Britain. All Ordnance Survey data derived from the Boundary-Line™ product that extends into the sea include the EOR extent.

Area Values

The area values attribute (HECTARES) quoted is retained from the source data. Area values of each ADMIN_UNIT_ID in Ordnance Survey data derived from the Boundary-Line™ product include the Extent of the Realm (EOR).

Treatment of boundaries in estuaries

The extent of the realm (EOR) follows mean low water and crosses the estuaries at the level of the sea at low water. In this example showing Westminster Constituencies, an adjoining boundary also extends into the estuary.

Map showing Westminster Constituencies

Seaward extensions

These are artificial extensions to the realm. They extend the local government and parliamentary areas seaward.

Map showing seaward extensions

Structures in the sea

Breakwaters are structures of wood, stone, metal or other material built to break the force of waves. They can be separate from, or joined to, the mainland. If joined, they are generally included in the local government and parliamentary areas. If separate, they are not part of the local government and parliamentary area unless they are placed therein by legislation of some kind, for example, Plymouth breakwater is included in the local government area whilst the centre portion of the Portland Harbour breakwater is not.

Permanent or solid structures in the sea, such as the forts in the Solent off Portsmouth Harbour and Brighton Marina, are usually included in local government and parliamentary areas.

Islands and rocks in the sea

The following rules govern the representation in Boundary-Line of offshore islands and rocks in the sea:

  • If an offshore island or rock is shown, it will be contained within all the relevant administrative unit collections.

In this example, the Islands of Flat Holm and Steep Holm in the Mouth of the river Severn are contained within the Bristol North West Westminster Constituency.

Map showing islands contained within constituency boundary-line

Features with multi-part polygons

Where multiple polygons occur as part of the same feature then the CENTROID will be located at the nominal centre of the largest polygon in that feature.

1.22 Is the technology used to build OS OpenSpace available for me to host my own application?

Yes, the OS OpenSpace API created by Ordnance Survey is built using freely available third party open source software including the Ordnance Survey API, all of which are detailed in the Open Source Software and Licences page.

The Ordnance Survey 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 Ordnance Survey data sets, it has been designed specifically to work with Ordnance Survey data. To use Ordnance Survey data you will need a data licence. Ordnance Survey has a wide range of data licences available for businesses and other commercial requirements.

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

1.23 What is OSGB Web Map tools?

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

The OSGB Web map tools enable customers to build the following into their 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 Ordnance Survey data in their applications.

1.24 Are there any restrictions using OSGB Web Map Tools?

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