Complete API integration guide for REST and SOAP services. Real-time UK address lookup, postcode search, and geocoding.
ePostcode offers two robust API integration methods to suit your development needs
Modern, high-speed JSON API with simple HTTP requests. Perfect for web applications, mobile apps, and microservices.
XML-based SOAP web service for enterprise systems and legacy applications requiring WSDL integration.
Modern JSON API for high-speed UK address lookups
https://wsp.epostcode.com/uk/v1/
All REST API endpoints require authentication via an API key passed as a URL parameter:
?key=YOUR_API_KEY_HEREGet your API key from the ePostcode Portal → Manage Keys section.
Search for premises by building name, street, town, business name, or postcode.
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Required | Your API key (obtain from ePostcode Portal) |
| query | string | Required | Search term (postcode, street name, business name, or building) |
| maxresults | integer | Optional | Maximum number of results to return (default: 100) |
curl -X GET "https://wsp.epostcode.com/uk/v1/Search?key=YOUR_API_KEY_HERE&query=SW1A%201AA"fetch('https://wsp.epostcode.com/uk/v1/Search?key=YOUR_API_KEY_HERE&query=SW1A 1AA')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));import requests
url = "https://wsp.epostcode.com/uk/v1/Search"
params = {
"key": "YOUR_API_KEY_HERE",
"query": "SW1A 1AA"
}
response = requests.get(url, params=params)
data = response.json()
print(data){
"results": [
{
"id": "12345678",
"address": "10 Downing Street, Westminster, London, SW1A 2AA",
"buildingName": "",
"buildingNumber": "10",
"street": "Downing Street",
"locality": "Westminster",
"town": "London",
"county": "Greater London",
"postcode": "SW1A 2AA",
"country": "England"
}
],
"totalResults": 1
}Get complete address details for a specific premise by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Required | Your API key (obtain from ePostcode Portal) |
| id | string | Required | Premise ID from Search results |
curl -X GET "https://wsp.epostcode.com/uk/v1/GetPremise?key=YOUR_API_KEY_HERE&id=12345678"{
"premise": {
"id": "12345678",
"uprn": "10001234567",
"buildingName": "",
"buildingNumber": "10",
"subBuildingName": "",
"dependentStreet": "",
"street": "Downing Street",
"doubleDependentLocality": "",
"dependentLocality": "",
"locality": "Westminster",
"town": "London",
"county": "Greater London",
"postcode": "SW1A 2AA",
"postcodeInward": "2AA",
"postcodeOutward": "SW1A",
"country": "England",
"latitude": 51.503396,
"longitude": -0.127764,
"eastings": 530047,
"northings": 179951
}
}Get geographic coordinates and grid references for a specific premise.
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Required | Your API key (obtain from ePostcode Portal) |
| id | string | Required | Premise ID from Search results |
{
"geoData": {
"premiseId": "12345678",
"latitude": 51.503396,
"longitude": -0.127764,
"eastings": 530047,
"northings": 179951,
"gridReference": "TQ 300 799"
}
}Monitor your available API credits in real-time.
curl -X GET "https://wsp.epostcode.com/uk/v1/GetCredits?key=YOUR_API_KEY_HERE"{
"credits": {
"remaining": 9850,
"used": 150,
"total": 10000,
"expiryDate": "2026-12-31"
}
}XML-based web service for enterprise and legacy systems
https://ws.epostcode.com/uk/postcodeservices19.asmx?WSDL
The SOAP API uses WSDL (Web Services Description Language) for service definition. Most enterprise development tools can automatically generate client code from the WSDL.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<PostcodeLookup xmlns="http://ws.epostcode.com/">
<ApiKey>YOUR_API_KEY_HERE</ApiKey>
<Postcode>SW1A 1AA</Postcode>
</PostcodeLookup>
</soap:Body>
</soap:Envelope><?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<PostcodeLookupResponse xmlns="http://ws.epostcode.com/">
<PostcodeLookupResult>
<Address>
<BuildingNumber>10</BuildingNumber>
<Street>Downing Street</Street>
<Locality>Westminster</Locality>
<Town>London</Town>
<County>Greater London</County>
<Postcode>SW1A 2AA</Postcode>
<Latitude>51.503396</Latitude>
<Longitude>-0.127764</Longitude>
</Address>
</PostcodeLookupResult>
</PostcodeLookupResponse>
</soap:Body>
</soap:Envelope>// Add Service Reference to: https://ws.epostcode.com/uk/postcodeservices19.asmx
using PostcodeServiceReference;
var client = new PostcodeServices19SoapClient();
var result = await client.PostcodeLookupAsync("YOUR_API_KEY", "SW1A 1AA");
foreach (var address in result.Addresses)
{
Console.WriteLine($"{address.BuildingNumber} {address.Street}");
Console.WriteLine($"{address.Town}, {address.Postcode}");
}Our technical support team is here to help you integrate ePostcode into your application.