Building with the Match API - Part 2 Mapping Address Points

In Part 1 of this series I demonstrated how to perform an address search using Addresscloud's Match API. The API provides an easy to use geocoding service, which returns address data including location coordiantes. In this post I'm going to combine this with the Ordnance Survey's new Vector Tile Service to create a detailed map showing an address location and UPRN within its building footprint.

This tutorial builds on the material covered in Part 1. If you'd like an Addresscloud API key for testing please email support@addresscloud.com

Need an "out the box" solution? Addresscloud provides a fully-fledged and globally-available map service to its customers for property searches and risk assessments. Contact sales@addresscloud.com for more details.

Quickstart

1. Sign-up for an OS Data Hub account (you'll need a Premium account for the most detailed building footprints).
2. Download the tutorial repository from here.
3. Unzip the folder and navigate to the workspace for this tutorial: interactive/match/02_geocoding.
4. Add your Addresscloud API credentials to api.js.
5. Using the OS Data Hub, create an API key for the OS Vector Tile API (instructions here) and add to map.js.
6. Open index.html.

Initializing the Map

The requests to Addresscloud's Match API are the same as in Part 1. This tutorial extends the code-base to generate a map showing address locations. The map.js code is adapted from the excellent examples from the OS' GitHub repository and uses the Mapbox GL JS library. Setting up the map is done by the initMap() function in map.js. This function sets the OS Vector Tiles API, and centres the map on the UK ready to receive address points.

const OS_API_KEY = '<YOUR OS VECTOR TILE API KEY>'

let map
function initMap() {

    const serviceUrl = "https://api.os.uk/maps/vector/v1/vts";
    map = new mapboxgl.Map({
        container: 'map',
        style: serviceUrl + '/resources/styles?key=' + OS_API_KEY,
        center: [-4.7,54.5],
        zoom: 5,
        maxZoom: 20,
        transformRequest: url => {
            url += '&srs=3857';
            return {
                url: url
            }
        }
    });

// function continues...

Coordinate Systems

The OS Vector Tile API provides tiles in two coordinate systems, either British National Grid (EPSG 27700) or WGS 84 / Pseudo-Mercator (EPSG 3857). To support global geocoding requests Addresscloud provides coordinates in WGS 84 ("GPS coordinates"), the map tiles therefore need to be in 3857 so that the address points and basemap align properly.

Address to Building Footprint

I've extended the setOuput() function in app.js so that once an address is retrived from the Match API, the mapAddress() function in map.js is called.

function setOutput(address) {
    let output = `<p>${address.description}</p>`

    output += `<p><table><tr><td>coordinates</td>	   
    <td>${address.geometry.coordinates.lon}, 
    ${address.geometry.coordinates.lat}</td></tr>`
    
    for ([key, value] of Object.entries(address.properties)){
        output += `<tr><td>${key}</td><td>${value}</td></tr>`
    }
    output += `</table></p>`

    document.getElementById('results').innerHTML = output
    console.log(address)
    mapAddress(address) // <-- new mapAddress call
}

The mapAddress() function takes in an address object - that is the address details returned from the Match API which are used to generate the properties table. This object contains the address coordinates (longitude and latitude) which are used to create a Mapbox marker for the address, and trigger the map to zoom to that location.

If you signed up for a premium OS Data Hub account then at zoom levels of 12 or greater the Vector Tiles service switches from the OS Open Zoomstack tiles to using OS MasterMap, which is the OS' most detailed topographic data-source for Great Britain. MasterMap topography is a very rich data-set and includes building outlines, down to the resolution of individual garages and outhouses. Combining these with Addresscloud's high-precision geocoding provides a powerful way to quickly visualise address and building locations across the country.

MasterMap is commercial data which means that the OS charge for access in production environments. For the purposes of this tutorial I recommend you set your API Project to "Development mode" to avoid being billed for Vector Tile transactions whilst you're developing your app. Every OS Data Hub account also includes £1,000 of free usage credits per month to allow developers to get up and running.

Displaying A UPRN Pop-Up

The UPRN is a key attribute in the British address system and is used to link address and property data. Addresscloud allows customers to query and search by UPRNs in both the Match and Intelligence APIs.

As a final task in this tutorial we're going to modify the existing map code to display the address UPRN as a pop-up on the map. To do this we can remove the existing "hello world" text from the .setPopup() method of the address marker in  map.js. Because mapAddress() accepts the whole address object as input we have easy access to the address attributes, specifically "address.properties.uprn". For reference your mapAddress() function should now look like the snippet below.

function mapAddress(address){
    // Extract address coordinates
    const coordinates = address.geometry.coordinates

    // Create the marker
    new mapboxgl.Marker()
        .setLngLat(coordinates)
        .setPopup(new mapboxgl.Popup().setHTML(`<p>UPRN: 
        ${address.properties.uprn}</p>`)) // <-- Added UPRN here.
        .addTo(map);

    // Zoom to address point
    map.flyTo({
            center: coordinates,
            zoom: 18,
            essential: true
        });
}

Once complete, refresh index.html and enter an address. When you click on the map pin the pop-up should open to show the UPRN.

Summary

In this tutorial I've demonstrated how to add a simple web-map to show address locations returned from the Addresscloud Match API. Using these precise locations from Addresscloud's geocoding service we can overlay our results on the OS' new Vector Tiles API to show address locations within building footprints, and display the address' UPRN in a pop-up on the map. In the next post I'll demonstrate using the map to perform reverse-geocoding queries against the Match API.