GET /addresses/paf

Search for UK addresses by text query or return the nearest address to a given coordinate, returning the full Royal Mail PAF (Postcode Address File) breakdown of each result.

Base URL: https://api.geocerta.io

Sandbox URL: https://api-staging.geocerta.io

Authentication required. Include your API key in the api-key header. See Authentication.

Endpoint

GET /addresses/paf

Query Parameters

Field	Type	Required	Description
`address`	string	Yes	Address text to search for. Min 3, max 200 characters. Alternatively, pass an Easting/Northing coordinate pair (e.g. `530000 180000` or `530000,180000`) to find the nearest address to that point.

Response

200 OK — returns an array of matching address results, each enriched with PAF fields.

Response Fields

Field	Type	Description
`address`	string	Concatenated address.
`uprn`	string \| undefined	The Unique Property Reference Number.
`x`	number	Easting in metres, defining the location in the British National Grid spatial reference system.
`y`	number	Northing in metres, defining the location in the British National Grid spatial reference system.
`lat`	number	Latitude (WGS84).
`lng`	number	Longitude (WGS84).
`postcode`	string \| undefined	The postcode.
`department`	string \| null	In a few organisations, department name is indicated because mail is received by subdivisions of the main organisation at distinct delivery points.
`organisation`	string \| null	The organisation name is the business name given to a delivery point within a building or small group of buildings. This field could also include entries for churches, public houses and libraries.
`sub_building`	string \| null	The sub-building name and/or number are identifiers for subdivision of properties.
`building`	string \| null	The building name is a description applied to a single building or a small group of buildings.
`building_number`	string \| null	The building number, or postal number, is a number given to a single building or a small group of buildings.
`dependent_thoroughfare`	string \| null	In certain places, for example, town centres, there are named thoroughfares within other named thoroughfares.
`thoroughfare`	string \| null	A road, track or named access route on which there are Royal Mail delivery points.
`double_dependent_locality`	string \| null	To distinguish between similar or same thoroughfares within a dependent locality.
`dependent_locality`	string \| null	Dependent locality areas may define an area within a post town.
`post_town`	string \| null	The town or city in which the Royal Mail sorting office is located.
`po_box`	string \| null	Post Office Box (PO Box) number.

Returns an empty array [] when no results are found.

Errors

Status	Message	Cause
`400`	Bad Request	`address` is missing, under 3, or over 200 characters
`401`	Unauthorized	Missing or invalid API key

Example

curl "https://api.geocerta.io/addresses/paf?address=10+Downing+Street+London" \
  -H "api-key: YOUR_API_KEY"

Coordinate lookup (returns nearest PAF result within 25m):

curl "https://api.geocerta.io/addresses/paf?address=530047,179951" \
  -H "api-key: YOUR_API_KEY"