GeoDojo: UK Grid Web Service

Introduction

The UK Grid web service provides an interface to various polygonal and point-based geographic datasets, provided by the Ordnance Survey and others. It also provides location conversion to and from WGS84 latitude and longitude, OSGB36 National Grid references, eastings and northings, and postcodes.

The datasets are processed offline into a form which allows online queries to be efficiently handled in realtime by the web server. Polygonal datasets are organised into a hierarchical structure based on national grid references and the spatial redundancy is reduced by storing only information for the coarsest grid squares which are completely contained within the same polygon, up to an accuracy of 100m. The point-based datasets are stored in a binary-space-partition (BSP) tree which allows fast calculation of the nearest points to the input location. These tree-based data structures allow query results to be calculated by the server without the need to access the whole data-set, significantly accelerating response time.

The query results can be returned in JSON or XML formats. Client-side cross-domain queries are handled via JSONP, allowing access to the data from your own Javascript code.

Query Parameters

location

The location used to define the results: a OSGB36 easting/northing pair, a OSGB36 National Grid reference, a WGS84 latitude/longitude pair or a postcode.

Conversions between WGS84 and OSGB36 latitude and longtitude is performed via the data defined in the document NATO Helmert Datum Transformation Parameters; the apparent reported accuracy is roughly seven metres. Conversion between OSGB36 latitude and longitude and eastings and northings is handled via the equations from the document The Universal Grids and the Transverse Mercator and Polar Stereographic Map Projections.

Conversion to and from postcodes is handled via the OS Code-Point Open dataset; this defines each postcode by a central point for its area, rather than a true polygon, and so a location may be reported as closest to a given postcode but actually inside the area for another.

dataset (optional)

The dataset used to define the results: boundary_line | code_point | gazetteer | vice_county | diva_gis.

sub_data (optional)

A data subset identifier. Used with the boundary_line, gazetteer and diva_gis datasets.

n (optional)

An integer for the number of nearby results to return. Used with the code_point and gazetteer point-based datasets. The default value is 1.

encoding (optional)

The encoding for the results: json | jsonp | xml. The default value is json.

callback (optional)

The callback function used for the jsonp encoding.

Query Results

location

The input location converted to a easting/northing pair, a national grid reference, a WGS84 latitude/longitude pair and a postcode.

Fields: east, north, grid, lat, lng, postcode.

result

The result of the operation.

Fields: boundary_line | code_point | gazetteer | vice_county | diva_gis.

status

The status of the operation.

Fields: flag (ok | fail).

time

The time spent calculating the result by the server.

Fields: ms.

Datasets

OS Boundary Line

A polygonal dataset of administrative boundaries provided by the Ordnance Survey. The results are correct to the nearest 100 metres to the original data.

Parameters

location: location of query

data_set: boundary_line

sub_data: county_electoral_division_region | county_region | district_borough_unitary_region | district_borough_unitary_ward_region | european_region_region | greater_london_const_region | high_water_polyline | parish_region | scotland_and_wales_const_region | scotland_and_wales_region_region | unitary_electoral_division_region | westminster_const_region

OS Code-Point Open

A point-based dataset including postcodes provided by the Ordnance Survey. The nearest data points to the input location are returned.

Parameters

location: location of query

data_set: code_point

n: The number of nearest results to the input location

OS 1:50 000 Scale Gazetteer

A point-based dataset of places provided by the Ordnance Survey. The nearest data points to the input location are returned.

Parameters

location: location of query

data_set: gazetteer

sub_data: antiquity | city | farm | forest | hill | town | other | water | all_other

n: The number of nearest results to the input location

NBN Watsonian Vice County

A polygonal dataset of Watsonian vice counties provided by the National Biodiversity Network. The results are correct to the nearest 100 metres to the original data.

Parameters

location: location of query

data_set: vice_county

Diva-GIS UK Administrative Areas

A polygonal dataset of UK administrative areas. The results are correct to the nearest 100 metres to the original data.

Parameters

location: location of query

data_set: diva_gis

sub_data: adm0 | adm1 | adm2

Query Examples

URLs

http://www.geodojo.net/uk/grid/?location=PE27+5JL
http://www.geodojo.net/uk/grid/?location=PE27+5JL&dataset=boundary_line&sub_data=district_borough_unitary_ward_region&encoding=xml
http://www.geodojo.net/uk/grid/?location=TL322723&dataset=diva_gis&sub_data=adm2&encoding=xml
http://www.geodojo.net/uk/grid/?location=TL322723&dataset=vice_county&encoding=xml
http://www.geodojo.net/uk/grid/?location=52.332867+-0.061269&dataset=gazetteer&sub_data=city&n=5&encoding=xml
http://www.geodojo.net/uk/grid/?location=532200+272300&dataset=code_point&n=5&encoding=xml

jQuery

$.ajax(
{
	url: 'http://www.geodojo.net/uk/grid', 
	dataType: 'jsonp',
	data:
	{
		encoding: 'jsonp',
		location: 'PE27 5JL',
		dataset: 'boundary_line',
		sub_data: 'district_borough_unitary_ward_region' 
	},   
	success: function (result) 
	{
		console.log(JSON.stringify(result)) ;
	}
}) ;

PHP

$fields = array
(
	'encoding' => 'json',
	'location' => 'PE27 5JL',
	'dataset' => 'boundary_line',
	'sub_data' => 'district_borough_unitary_ward_region'
) ;

$url = 'http://www.geodojo.net/uk/grid?' . http_build_query($fields) ;

$ch = curl_init() ;

curl_setopt($ch, CURLOPT_URL, $url) ;
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true) ;
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true) ;

$result = json_decode(curl_exec($ch), true) ;

curl_close($ch) ;

print_r($result) ;

Licence Statements

Contains OS data © Crown copyright and database right 2015.
Contains Royal Mail data © Royal Mail copyright and database right 2015.
Contains National Statistics data © Crown copyright and database right 2015.

Contact

hello@geodojo.net