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_addresselement 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:
- A top-level
webform_addresselement - A nested
webform_addresselement (e.g. inside a container) - A CiviCRM address field inside a
webform_cardelement (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
- Install the module in the usual way
- Register for a free API key at OS DataHub
- Navigate to Admin → Configuration → Services → Webform OSPlaces Search Settings (
/admin/config/services/webform_osplaces_search) - Enter your API key — optionally enable result caching to reduce API calls
- Add the “OSPlaces API Postcode Search” element to any webform alongside a
webform_addresselement (or CiviCRM address fields) - 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
restmodule (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.
Project information
- Project categories: Integrations
- Ecosystem: Webform
- Created by taylormadeapps on , updated
This project is not covered by the security advisory policy.
Use at your own risk! It may have publicly disclosed vulnerabilities.

