ngd/find

Postcoder NGD autocomplete for the OS National Geographic Database (NGD) provides free real-time suggestions as users start to type their address, and a chargeable lookup to retrieve full details of a selected NGD record.

This API endpoint accepts a partial address query (e.g. 10 foxg) and returns a list of suggestions. Each suggestion includes a unique ID and a summary (e.g. FLAT 10, 10, FOXGLOVE WAY, HACKBRIDGE).

Results can be refined by making sequential autocomplete/find requests - for example, '10 fo' followed by '10 fox' and then '10 foxg'. The NGD record for a suggestion can be retrieved by passing its ID to the chargeable ngd/retrieve API endpoint.

Try the sample code for NGD autocomplete.

NGD: Enable access on your API key using the Features page or by contacting us.

Request URL

https://ws.postcoder.com/pcw/ngd/find?query={query}&apikey={apikey}

Querystring parameters

Parameter	Description	Example
`apikey`	Your API key	`apikey=PCW45-12345-12345-1234X`
`query`	The URL-encoded search term (minimum of three characters required, returns empty list otherwise)	`query=10%20foxg`
`featuretype`	Filters by one or more comma-delimited feature types, supported values: builtaddress (default), royalmailaddress, prebuildaddress, historicaddress, nonaddressableobject, all. See feature types below	`featuretype=royalmailaddress`
`format`	Sets the format of the response, xml or json (default unless "application/xml" header is detected)	`format=json`

Feature types

Use the featuretype querystring parameter to filter results by one or more comma-delimited feature types.

If the featuretype parameter is not included in a request, builtaddress is used as the default.

Feature type	Description
`builtaddress`	Local authority addresses that are currently built and live and can typically receive mail, deliveries, or services. For example, homes, shops, schools and hospitals
`royalmailaddress`	Royal Mail delivery point addresses, a point geometry and information describing the relationship they have with Local Authority addresses
`prebuildaddress`	Local authority addresses that will be able to receive mail, deliveries or services, where the property is either yet to be built but has been granted planning permission, or is under construction. Pre-build addresses can take the format of a development site, a plot number, or a definitive address for property units
`historicaddress`	Local authority addresses that are no longer in existence. This can occur as a result of demolition or the merging of two built properties to become one new single address, or the splitting of a single property into multiple flats for example
`nonaddressableobject`	Local authority and Ordnance Survey captured features that are currently live but are objects that would not be expected to be able to receive mail or deliveries. These objects typically represent structures or sites rather than buildings that somebody could conceivably live, work or engage in leisure activities within. For example, ponds and static water sites, public parks and telephone boxes
`all`	All of the above

Example requests and responses

Return NGD record suggestions for "10 foxg" that have an associated PAF address:

https://ws.postcoder.com/pcw/ngd/find?query=10%20foxg&featuretype=royalmailaddress&apikey=PCW45-12345-12345-1234X&format=json

[
    {
        "id": "5870082467",
        "summaryline": "FLAT 10, 10, FOXGLOVE WAY, HACKBRIDGE"
    },
    {
        "id": "100031821060",
        "summaryline": "10, FOXGLOVE CLOSE, FEATHERSTONE"
    },
	...
	...
]

Response fields

Field	Description	Example
`id`	The ID of the suggestion	5870082467
`summaryline`	The summary of the suggestion	FLAT 10, 10, FOXGLOVE WAY, HACKBRIDGE

Integration advice

Always provide an option for users to enter their address manually if they cannot find it using your address lookup integration
For best performance, implement debouncing to wait for a pause in user activity (e.g. 50ms) before making a request, and consider using a JavaScript AbortController (or an equivalent in other languages) to cancel in-flight requests when a new query is triggered
URL encode all special characters (including /) in your request parameters with %xx encoding
Verify your request was successful by checking for an HTTP status code of 200; see all HTTP status codes with descriptions
Treat all response fields as optional
Use the autocomplete="xyz" attribute in your input tag if Chrome's autofill blocks your suggestions
Requests to this API endpoint are not logged within your usage history
Use the ngd/retrieve API endpoint to retrieve the full address for a suggestion

Credit cost

This API endpoint is free to use providing you use it with the chargeable ngd/retrieve API endpoint.

Buy a credit pack or set up a monthly plan to use with all Postcoder features.