REST API Documentation - ePostcode Developer Guide

REST API Overview

Modern JSON API for high-speed UK address lookups, postcode search, and geocoding services.

Base URL: https://wsp.epostcode.com/uk/v1/

Key Features

JSON Responses: Easy to parse and integrate
RESTful Design: Predictable resource-based URLs
High Performance: Optimized for speed and reliability
Real-time Data: Access to the latest UK PAF dataset
Comprehensive Geocoding: Latitude, longitude, UPRN, and UDPRN

Authentication

All REST API endpoints require authentication via an API key passed as a URL parameter.

URL Parameter

?key=YOUR_API_KEY_HERE

Get your API key: Sign up at the ePostcode Portal and navigate to the Manage Keys section.

API Key Security

The master key issued to you is for managing available credits and account administration only. It is not used for consuming the web services themselves.

Create API keys securely within your portal's Manage API Keys tab
Configure security restrictions (IP/domain whitelisting)
Set rate limiting to control usage
Never expose API keys in client-side code or public repositories

Search for UK Addresses

GET /Search

Performs high-speed searches to identify UK postcodes, business names, or addresses based on a phrase. Supports open searches (matching keywords) or exact postcode matches.

Query Parameters

Parameter	Type	Required	Description
key	string	Required	Your API key (obtain from ePostcode Portal)
phrase	string	Required	The search phrase (e.g., "Mossland Road" or "G524XZ")
opensearch	boolean	Optional (default: true)	If true, searches keywords across address fields; if false, matches exact postcodes

Search Modes Comparison

Mode	Description	Example Phrase	Matches
`opensearch=true`	Searches keywords across all fields	"Mossland Road G5"	Addresses containing "Mossland", "Road", and "G5"
`opensearch=false`	Matches exact postcode only	"G524XZ"	All addresses at postcode "G524XZ"

Example Request (Open Search)

cURL

curl -X GET "https://wsp.epostcode.com/uk/v1/Search?key=YOUR_API_KEY_HERE&phrase=mossland%20road&opensearch=true"

JavaScript (Fetch)

fetch('https://wsp.epostcode.com/uk/v1/Search?key=YOUR_API_KEY_HERE&phrase=mossland%20road&opensearch=true')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Python

import requests

url = "https://wsp.epostcode.com/uk/v1/Search"
params = {
    "key": "YOUR_API_KEY_HERE",
    "phrase": "mossland road",
    "opensearch": "true"
}

response = requests.get(url, params=params)
data = response.json()
print(data)

Response Fields

Field	Type	Description
items	Array	List of matching premises or groups
items[].key	String	Postcode (for "Group" type) or premise ID (for "Premise" type)
items[].text	String	Summary of the premise or group (e.g., address and count)
items[].type	String	Type of match: "Premise" (single address) or "Group" (multiple addresses)

Example Response (Open Search)

JSON Response

{
  "items": [
    {
      "key": "ST3 5AB",
      "text": "Mossland Road, Stoke-on-Trent, ST3 5AB - 26 Addresses",
      "type": "Group"
    },
    {
      "key": "ST3 5AF",
      "text": "Mossland Road, Stoke-on-Trent, ST3 5AF - 10 Addresses",
      "type": "Group"
    },
    {
      "key": "L36 8FA",
      "text": "Mossland Road, Liverpool, L36 8FA - 22 Addresses",
      "type": "Group"
    },
    {
      "key": "G52 4XZ",
      "text": "Mossland Road, Hillington Park, Glasgow, G52 4XZ - 24 Addresses",
      "type": "Group"
    }
  ]
}

Example Request (Exact Postcode)

cURL

curl -X GET "https://wsp.epostcode.com/uk/v1/Search?key=YOUR_API_KEY_HERE&phrase=G50JE&opensearch=false"

Example Response (Exact Postcode)

JSON Response

{
  "items": [
    {
      "key": "9269651",
      "text": "2 Jane Place, Glasgow, G5 0JE",
      "type": "Premise"
    },
    {
      "key": "9269652",
      "text": "4 Jane Place, Glasgow, G5 0JE",
      "type": "Premise"
    },
    {
      "key": "27783162",
      "text": "6 Jane Place, Glasgow, G5 0JE",
      "type": "Premise"
    },
    {
      "key": "27783163",
      "text": "8 Jane Place, Glasgow, G5 0JE",
      "type": "Premise"
    }
  ]
}

Retrieve Detailed Premise Data

GET /GetPremise

Get complete address details for a specific premise by ID.

Query Parameters

Parameter	Type	Required	Description
key	string	Required	Your API key (obtain from ePostcode Portal)
id	string	Required	The ID of the premise to retrieve
uprn	boolean	Optional (default: false)	If true, includes UPRN (deducts 1 extra credit)

Example Request

cURL

curl -X GET "https://wsp.epostcode.com/uk/v1/GetPremise?key=YOUR_API_KEY_HERE&id=52502003&uprn=true"

Example Response

JSON Response

{
  "item": {
    "id": "52502003",
    "domesticId": "52502003",
    "adminAreaName": "Renfrewshire",
    "barcode": "",
    "buildingName": "Merlin House",
    "buildingNumber": 20,
    "city": "Glasgow",
    "company": "Etellect Ltd",
    "countryIso2": "",
    "countryIso3": "",
    "countryIsoNumber": 0,
    "countryName": "Scotland",
    "district": "Hillington Park",
    "line1": "Merlin House",
    "line2": "20 Mossland Road",
    "line3": "",
    "line4": "",
    "line5": "",
    "poBox": "",
    "postalCode": "G52 4XZ",
    "province": "Renfrewshire",
    "secondaryStreet": "",
    "street": "Mossland Road",
    "subBuilding": "",
    "department": "",
    "lat": "55.863168",
    "long": "-4.379078",
    "uprn": "123105666",
    "udprn": "52502003"
  }
}

Note: Latitude and longitude are now included by default. Setting uprn=true includes the UPRN field. Setting uprn=true deducts 1 extra credit per request.

Retrieve Geodata for Premise

GET /GetPremiseGeoData

Retrieves geodata for a premise by its ID.

Query Parameters

Parameter	Type	Required	Description
key	string	Required	Your API key (obtain from ePostcode Portal)
id	string	Required	The ID of the premise to retrieve

Example Request

cURL

curl -X GET "https://wsp.epostcode.com/uk/v1/GetPremiseGeoData?key=YOUR_API_KEY_HERE&id=52502003"

Example Response

JSON Response

{
  "item": {
    "id": "52502003",
    "lat": "55.863168",
    "long": "-4.379078",
    "uprn": "123105666",
    "udprn": "52502003"
  }
}

Check Remaining API Credits

GET /GetCredits

Monitor your available API credits in real-time.

Example Request

cURL

curl -X GET "https://wsp.epostcode.com/uk/v1/GetCredits?key=YOUR_API_KEY_HERE"

Example Response

JSON Response

{
  "credits": 29
}

API Versioning & Changelog

Track changes and updates to the ePostcode REST API.

Current Version: v1

Base URL: https://wsp.epostcode.com/uk/v1/

Changelog

February 2026

Breaking Change: Removed includeGeoData parameter from /GetPremise
Enhancement: Latitude and longitude (lat, long) now included by default in /GetPremise response
New Parameter: Added uprn boolean parameter to /GetPremise (default: false)
Credit Change: Setting uprn=true now deducts 1 extra credit per lookup (returns UPRN field)
Note: UDPRN continues to be included by default at no extra cost

May 2025

Added includeGeoData parameter to /GetPremise endpoint
Geodata (lat, long, UPRN, UDPRN) available when includeGeoData=true (1 extra credit)

Migration Guide: If you're currently using includeGeoData=true, update your code:

Latitude and longitude are now always included (no parameter needed)
To get UPRN, use uprn=true instead of includeGeoData=true
UDPRN is always included at no extra cost

Credit Usage Summary

Understand how API credits are consumed for different operations.

Endpoint	Base Cost	Additional Costs	Notes
`/Search`	1 credit	—	Per search request
`/GetPremise`	1 credit	+1 if `uprn=true`	Includes lat, long, udprn by default
`/GetPremiseGeoData`	1 credit	—	Returns lat, long, uprn, udprn
`/GetCredits`	0 credits	—	Free to check balance

Tip: Use the /GetCredits endpoint to monitor your usage and avoid service interruptions.

Need Help with Integration?

Our technical support team is here to help you integrate ePostcode into your application.

Email Support Developer Portal Contact Us

REST API Overview

Key Features

Authentication

API Key Security

Search for UK Addresses

Query Parameters

Search Modes Comparison

Example Request (Open Search)

Response Fields

Example Response (Open Search)

Example Request (Exact Postcode)

Example Response (Exact Postcode)

Retrieve Detailed Premise Data

Query Parameters

Example Request

Example Response

Retrieve Geodata for Premise

Query Parameters

Example Request

Example Response

Check Remaining API Credits

Example Request

Example Response

API Versioning & Changelog

Current Version: v1

Changelog

February 2026

May 2025

Credit Usage Summary

Need Help with Integration?

Cookie Settings