BNG Reference#

Provides functionality to manipulate British National Grid (BNG) references.

BNGReference Object#

The BNG index system uses BNG references, also known more simply as grid or tile references, to identify and index locations across Great Britain (GB) into grid squares at various resolutions.

The BNGReference object is a custom class that encapsulates a BNG reference string, providing properties and methods to access and manipulate the reference.

British National Grid Index System#

The Ordnance Survey (OS) BNG index system, also known as the OS National Grid, is a rectangular Cartesian 700 x 1300km grid system based upon the transverse Mercator projection. In the BNG, locations are specified using coordinates, eastings (x) and northings (y), measured in meters from a defined origin point (0, 0) southwest of the Isles of Scilly off the coast of Cornwall, England. Values increase to the northeast, covering all of mainland GB and surrounding islands.

The BNG is structured using a hierarchical system of grid squares at various resolutions. At its highest level, the grid divides GB into 100km by 100km squares, each identified by a two-letter code. Successive levels of resolution further subdivide the grid squares into finer detail, down to individual 1-meter squares.

https://raw.githubusercontent.com/OrdnanceSurvey/osbng-py/main/docs/_static/images/osbng_grids_100km.png

BNG Reference Structure#

Each BNG reference string consists of a series of alphanumeric characters that encode the easting and northing at a given resolution.

A BNG reference includes a 2-letter prefix that identifies the 100km grid square. This is followed by an easting and northing value, and optionally, a suffix indicating an ordinal (intercardinal) direction (NE, SE, SW, NW). These suffixes represent a quadtree subdivision of the grid at the ‘standard’ resolutions (100km, 10km, 1km, 100m, and 10m), with each direction indicating a specific quadrant.:

<prefix><easting value><northing value><suffix>

There are two exceptions to this structure:

At the 100km resolution, a BNG reference consists only of the prefix.
At the 50km resolution, a BNG reference includes the prefix and the ordinal direction suffix but does not include easting or northing components.

A BNG reference can be expressed at different scales, as follows:

Resolution	Description	Example
100km	Identified by a two-letter code	TQ
50km	Subdivides the 100km grid into four quadrants. The grid reference adds an ordinal direction suffix (NE, NW, SE, SW) to indicate the quadrant within the 100km square.	TQ SW
10km	Adds one-digit easting and northing values	TQ 2 3
5km	Subdivides the 10km square adding an ordinal suffix	TQ 23 SW
1km	Adds two-digit easting and northing values	TQ 23 34
500m	Subdivides the 1km square adding an ordinal suffix	TQ 23 34 NE
100m	Adds three-digit easting and northing values	TQ 238 347
50m	Subdivides the 100m square adding an ordinal suffix	TQ 238 347 SE
10m	Adds four-digit easting and northing values	TQ 2386 3472
5m	Subdivides the 10m square adding an ordinal suffix	TQ 2386 3472 NW
1m	Adds five-digit easting and northing values	TQ 23863 34729

BNG Reference Formatting#

BNG reference strings passed to a BNGReference object must adhere to the following format:

Whitespace may or may not separate the components of the reference (i.e. between the two-letter 100km grid square prefix, easting, northing, and ordinal suffix).
If whitespace is present, it should be a single space character.
Whitespace can be inconsistently used between components of the reference.
The two-letter 100km grid square prefixes and ordinal direction suffixes (NE, SE, SW, NW) should be capitalised.

EPSG:27700 (OSGB36 / British National Grid)#

The BNG system is a practical application of the EPSG:27700 (OSGB36 / British National Grid) coordinate reference system which provides the geodetic framework that defines how locations defined by easting and northing coordinates and encoded as BNG references (e.g. ‘ST 569 714’) are projected to the grid.

BNG Reference Application#

The BNG index system is widely used by the geospatial community across GB. At each resolution, a given location can be identified with increasing detail, allowing for variable accuracy depending on the geospatial application, from small-scale mapping to precise survey measurements.

`BNGReference`#

The BNGReference class supports the conversion of a BNG reference string into a BNGReference object, ensuring type consistency across the package. All functions accepting or returning BNG references enforce the use of this class.

These functions are available both as instance methods of the class and as standalone functions, providing users with the flexibility to either:

Create a BNGReference object and pass it to a function.
Create a BNGReference object and use one of its instance methods.

BNGReference objects can be compared and ordered. Ordering considers both the grid resolution and the reference string. They are also hashable, so can be used as keys or set elements.

class osbng.bng_reference.BNGReference(bng_ref_string: str)[source]#: Initialises a BNGReference from a BNG reference string.

Properties#

`BNGReference.bng_ref_compact`	The BNG reference string of this `BNGReference` with whitespace removed.
`BNGReference.bng_ref_formatted`	The BNG reference string of this `BNGReference` in pretty format.
`BNGReference.resolution_metres`	The resolution of this `BNGReference` in meters.
`BNGReference.resolution_label`	The resolution of this `BNGReference` expressed as a string label.
`BNGReference.__geo_interface__`	A GeoJSON-like mapping of this `BNGReference`.

Methods#

`BNGReference.bng_to_xy`(*[, position])	Returns easting and northing coordinates of this `BNGReference`.
`BNGReference.bng_to_bbox`()	Returns grid square bounding box coordinates of this `BNGReference`.
`BNGReference.bng_to_grid_geom`()	Returns a grid square as a `Shapely Polygon` of this `BNGReference`.
`BNGReference.bng_to_children`(*[, resolution])	Returns a list of child `BNGReference` objects of this `BNGReference`.
`BNGReference.bng_to_parent`(*[, resolution])	Returns the `BNGReference` that is the parent of this `BNGReference`.
`BNGReference.bng_kring`(k, *[, return_relations])	Returns a hollow ring of BNGReference objects around this `BNGReference`.
`BNGReference.bng_kdisc`(k, *[, return_relations])	Returns a filled disc of BNGReference objects around this `BNGReference`.
`BNGReference.bng_distance`(bng_ref2, *[, ...])	Returns the euclidean distance between bng_ref2 and this `BNGReference`.
`BNGReference.bng_neighbours`()	Returns the four BNGReference object neighbours to this BNGReference.
`BNGReference.bng_is_neighbour`(bng_ref2)	Tests whether `bng_ref2` is a neighbour of this `BNGReference`.
`BNGReference.bng_dwithin`(d)	Returns all BNGReference objects within distance `d` of this BNGReference.
`BNGReference.__eq__`(other)	Determines whether this `BNGReference` is equal to `other`.
`BNGReference.__lt__`(other)	Determines whether this `BNGReference` is ordered before `other`.
`BNGReference.__hash__`()	Returns a hash value of this `BNGReference`.
`BNGReference.__repr__`()	Returns the string representation of this `BNGReference`.