Jump to the following:

By continuing, you agree to the use of cookies by us and third parties, which we use to improve your visit.

OS OpenSpace look-up services

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 1,000 times every day.

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.


var gazetteer = new OpenSpace.Gazetteer();
function searchGazetteer(query)
    // Query the gazetteer and call the callback 
    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"
  • FOREST = "F"
  • FARM = "FM"
  • HILL = "H"
  • ROMAN = "R"
  • WATER = "W"
  • UNKNOWN = "X"

Understanding grid references

If you look at the examples, you will see snippets of code similar to:

centrePoint = new OpenSpace.MapPoint(506040, 361635);

The numbers in it are a type of National Grid reference – this type is known as Eastings and Northings

To see how you can get from Letters to Numbers, look at our Coordinate overlay information – as you move the mouse around, you will see the numeric Eastings and Northings shown at the top right hand corner of the map.

Finding the location of a place
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)

Back to top
© Ordnance Survey 2019