This project is not covered by Drupal’s security advisory policy.

Adds a UK postcode address lookup element to Webform, powered by the Ordnance Survey OS Places API. Users type a postcode; matching addresses appear in a dropdown and populate address fields automatically.

Features

  • Adds an “OSPlaces API Postcode Search” element to the Webform element library, available under the “Address” category
  • Users type a UK postcode — matching addresses appear in a dropdown and populate address fields automatically, no page reload required
  • Uses the Ordnance Survey OS Places API — the UK government’s authoritative address and property dataset
  • Free API tier available via OS DataHub — no commercial subscription required
  • Supports both Webform’s native webform_address element and CiviCRM address fields
  • Optional result caching to reduce API calls
  • Admin settings page at /admin/config/services/webform_osplaces_search

Technical Details

Element structure

The module registers a composite Webform element (webform_osplaces_search_element) containing three sub-elements: a postcode text input, a loading spinner, and a results dropdown. The JavaScript library (postcode_search_popup) is attached via hook_form_alter only to forms that contain the element.

Address field detection

hook_form_alter scans the form for a compatible address target in this order:

  1. A top-level webform_address element
  2. A nested webform_address element (e.g. inside a container)
  3. A CiviCRM address field inside a webform_card element (identified by _address_ in the field key)

The detected field key is passed to JavaScript via drupalSettings.

Client-side behaviour

Postcode format is validated client-side using regex before any API call is made. On a valid postcode, an AJAX GET request hits the local REST endpoint (/api/webform-osplaces-search-resource?search_text={postcode}). Results are filtered to residential (R) and commercial (C) OS classification codes only. On selection, OS Places LPI fields are mapped to address lines using a formatting algorithm that handles organisations, sub-buildings, building names/numbers, thoroughfares, and dependent localities across up to three address lines.

REST endpoint

/api/webform-osplaces-search-resource (GET) accepts search_text, proxies to https://api.os.uk/search/places/v1/postcode, and returns filtered JSON. Authenticated via Drupal session cookie. Caching is opt-in via admin settings, using a custom url_param cache context keyed on search_text.

Address field mapping — webform_address

OS Places LPI field Webform field
POSTCODE_LOCATOR Postal code
TOWN_NAME City
ORGANISATION, SAO_TEXT, PAO_TEXT, PAO_START_NUMBER, STREET_DESCRIPTION etc. Address lines 1–3
Hardcoded Country → “United Kingdom”

CiviCRM field mapping

Targets street-address, supplemental-address-1, supplemental-address-2, city, and postal-code selectors within the webform_card container.

Installation & Configuration

  1. Install the module in the usual way
  2. Register for a free API key at OS DataHub
  3. Navigate to Admin → Configuration → Services → Webform OSPlaces Search Settings (/admin/config/services/webform_osplaces_search)
  4. Enter your API key — optionally enable result caching to reduce API calls
  5. Add the “OSPlaces API Postcode Search” element to any webform alongside a webform_address element (or CiviCRM address fields)
  6. The module auto-detects the associated address fields and wires up the lookup automatically

Requirements

  • Drupal 10 or 11
  • Webform contrib module
  • An OS Places API key — free registration at OS DataHub
  • Drupal core rest module (enabled automatically via dependency)

Similar Projects

Several modules offer address lookup or address field functionality for Drupal, but none combine Webform integration with the Ordnance Survey dataset:

  • Webform Address Autocomplete — Webform address lookup using Google Maps or Mapbox. No OS Places support.
  • Loqate — International address lookup with Webform support. Requires a paid commercial subscription.
  • Address — International address field storage and validation. No lookup functionality.
  • UK Postcode — Abandoned since 2016. Postcode validation only, no lookup, not compatible with Drupal 10/11.
Supporting organizations: 
Authors and Maintainers

Project information

Releases