ngd/retrieve

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 returns the NGD record for a suggestion ID found using the ngd/find 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/retrieve?id={id}&query={query}&apikey={apikey}

Querystring parameters

Parameter	Description	Example
`apikey`	Your API key	`apikey=PCW45-12345-12345-1234X`
`id`	The ID of the suggestion to look up, found using the ngd/find API endpoint	`id=5870082467`
`query`	The URL-encoded search term which was used with ngd/find API endpoint	`query=10%20foxg`
`addtags`	Specifies the additional response fields to include within the response using a comma-delimited list, supported values: royalmailaddresses, alternateaddresses, streetaddress, metadata, planning, relatedentities, otherclassifications, fullngd	`addtags=royalmailaddresses,metadata`
`lines`	When used with `addtags=royalmailaddresses`, sets the number of address lines (1-6) to include in the response so you can mirror the layout of your existing address form; see `include` and `exclude` query parameters for further customisation options	`lines=3`
`include`	Specifies the extra address fields to include within the address lines using a comma-delimited list, supported values: posttown, postcode	`include=posttown,postcode`
`exclude`	Specifies the address fields to exclude within the address lines using a comma-delimited list, supported values: poboxnumber, organisationname, premise, departmentname, subbuildingname, buildingname, buildingnumber, dependentthoroughfare, thoroughfare, doubledependentlocality, dependentlocality	`exclude=organisationname`
`format`	Sets the format of the response, xml or json (default unless "application/xml" header is detected)	`format=json`
`identifier`	Specifies your own meaningful identifier for the request such as "websiteA" or "client123"; you can view usage for each identifier on the Identifier Usage page, which may be helpful when using your API key across multiple websites, apps or clients	`identifier=websiteA`
`callback`	Specifies the name of your JSONP callback function	`callback=jsoncallback`

Example request and response

After finding suggestions using the ngd/find API endpoint, return the NGD record with a suggestion ID of 5870082467, including the Royal Mail addresses field group with up to three address lines:

https://ws.postcoder.com/pcw/ngd/retrieve?id=5870082467&query=10%20foxg&addtags=royalmailaddresses&lines=3&apikey=PCW45-12345-12345-1234X&format=json

[
    {
        "dataset": "GB",
        "featuretype": "builtaddress",
        "uprn": "5870082467",
        "udprn": "22524732",
        "parentuprn": "5870082458",
        "rootuprn": "5870082458",
        "hierarchylevel": "2",
        "usrn": "22600558",
        "description": "Built Address",
        "fulladdress": "FLAT 10, 10, FOXGLOVE WAY, HACKBRIDGE, SM6 7JJ",
        "subname": "FLAT 10",
        "number": "10",
        "streetname": "FOXGLOVE WAY",
        "townname": "HACKBRIDGE",
        "postcode": "SM6 7JJ",
        "country": "England",
        "latitude": "51.3828568",
        "longitude": "-0.1549238",
        "easting": "528493.56",
        "northing": "166482.80",
        "geometry": "POINT(528493.56 166482.8)",
        "floorlevel": "3",
        "lowestfloorlevel": "3.0",
        "highestfloorlevel": "3.0",
        "postcodesource": "A record which is linked to a Royal Mail address",
        "royalmailaddresses": [
            {
                "udprn": "22524732",
                "uprn": "5870082467",
                "premise": "Flat 10, 10",
                "subbuildingname": "FLAT 10",
                "buildingnumber": "10",
                "thoroughfare": "FOXGLOVE WAY",
                "posttown": "WALLINGTON",
                "postcode": "SM6 7JJ",
                "postcodetype": "Small User",
                "deliverypointsuffix": "6S",
                "latitude": "51.3828568",
                "longitude": "-0.1549238",
                "easting": "528493.56",
                "northing": "166482.80",
                "geometry": "POINT(528493.56 166482.8)",
                "positionalaccuracy": "Central Internal Position",
                "geometryallocationmethod": "Matched UPRN",
                "matchedaddressfeaturetype": "Built Address",
                "matchtype": "Direct",
                "matchdate": "2012-04-23",
                "matchmethod": "Automated",
                "matchingorganisation": "GeoPlace",
                "changetype": "New",
                "theme": "Address",
                "description": "Postcode Address File",
                "versiondate": "2025-09-23",
                "versionavailablefromdate": "2025-09-24T00:00:00.000Z",
                "entrydate": "2016-01-18",
                "updatedate": "2016-01-18",
                "addressline1": "Flat 10",
                "addressline2": "10 Foxglove Way"
            }
        ]
    }
]

Response fields

The following fields, where populated, are returned by default. See additional response fields for the full list.

Field	Description	Example
`dataset`	Dataset identifier, either GB or Islands	GB
`featuretype`	Feature type, one of: builtaddress, prebuildaddress, historicaddress or nonaddressableobject	builtaddress
`uprn`	Unique Property Reference Number (UPRN) assigned by a local custodian or Ordnance Survey as a persistent identifier	200004353841
`updrn`	Comma-delimited list of Unique Delivery Point Reference Numbers (UDPRNs) assigned by Royal Mail as a persistent identifier when there are one or more Royal Mail addresses associated with the UPRN	17308537
`parentuprn`	Unique Property Reference Number (UPRN) of the parent record if a parent-child relationship exists	200004353841
`rootuprn`	In instances where an address sits in a hierarchy (for example, Child UPRN - Parent UPRN - Grandparent UPRN), the Root UPRN will display the Unique Property Reference Number (UPRN) for the top level Addressable Object in the parent-child structure, which in this example is the Grandparent UPRN	200004353841
`hierarchylevel`	In instances where an address sits in a hierarchy (for example, Child UPRN - Parent UPRN - Grandparent UPRN), the Hierarchy Level attribute describes the position of the given UPRN within the overall set of relationships. For example, FLAT 1 is the Child UPRN at the lowest level and its Hierarchy Level will be 3; its Parent UPRN is BLOCK H, which will have a Hierarchy Level of 2; BLOCK H has, in turn, a Parent UPRN of EXETER UNIVERSITY, which will have a Hierarchy Level of 1	1
`usrn`	Unique Street Reference Number (USRN), a unique and persistent identifier of a Street which is assigned by the Roads or Highway Authority	28920601
`description`	Short descriptive value that provides a summary of the feature	Postal Address
`fulladdress`	Concatenation of the following address components: Organisation (Pre-Build and Built Address Feature Types only), Sub Name and / or Name and / or Number, Street Name, Locality, Town Name, Island Name and Postcode Locator	EMMAUS HOUSE, 65, THE CLOSE, NORWICH, NR1 4DH
`organisationname`	Name of the organisation operating from the address
`poboxnumber`	Concatenation of 'PO BOX' and the Post Office Box (PO Box) number or the British Forces Post Office (BFPO) number
`subname`	Secondary description for subdivisions of properties. For example: Sub Name: 'CRYNANT LIBRARY', Name: 'CRYNANT COMMUNITY CENTRE'.
`name`	Primary description applied to an address, for example: 'SWANSEA UNIVERSITY BAY CAMPUS'. This attribute will also include numbers when the name contains non-numeric characters, such as 44A. Some descriptive names, when included with the rest of the address, are sufficient to identify the property uniquely and unambiguously, for example, MAGISTRATES COURT. Sometimes the name will be a blend of distinctive and descriptive naming, for example, RAILWAY TAVERN (PUBLIC HOUSE) or THE COURT ROYAL (HOTEL)	EMMAUS HOUSE
`number`	Gives a unique numeric identifier for addresses on a given street, for example, '11' (per Local Authority Street Naming and Numbering conventions). This includes numbers that contain a range, decimals or non-numeric characters, for example, 1-11 and 10A	65
`streetname`	Name, number or descriptor that identifies the nearest accessible Street that an Address is located on or close to	THE CLOSE
`locality`	Name of the area or geographical identifier within a town, settlement, village or hamlet that an address is located within. For example, a locality may be a suburb, housing estate or commercial estate
`townname`	Name of the settlement that the Street is located within. Where a settlement can be a City, Town, Village, Hamlet or Parish	NORWICH
`islandname`	Name of the island upon which an Address is located; only populated for addresses in the OS NGD Islands collection
`postcode`	Postcode	NR1 4DH
`country`	Name of the geographical territory that the Address is located within, where a geographical territory represents either a devolved country or an island nation	England
`latitude`	Latitude of the Address location in accordance with the ETRS89 (EPSG:4258) coordinate reference system	52.6308744
`longitude`	Longitude of the Address location in accordance with the ETRS89 (EPSG:4258) coordinate reference system	1.3009883
`easting`	X coordinate defining the position of the object in accordance with the British National Grid (EPSG:27700) coordinate reference system	623485.00
`northing`	Y coordinate defining the position of the object in accordance with the British National Grid (EPSG:27700) coordinate reference system	308793.00
`geometry`	Geometry for the feature	POINT(623485 308793)
`floorlevel`	Represents either: the access point to the Address, or the floor level or levels that the Address is located on fully occupies or represents occupiable space within the property
`lowestfloorlevel`	In cases where the Floor Level contains a list of floor levels (for example, where a commercial organisation occupies multiple levels within a building), the first value provided will be taken as the lowest floor level. For example, where Floor Level attribute values are given as -1, 0, 1, 2, 3, the Lowest Floor Level is -1. Mezzanine levels may be represented by a partial number, for example, 1.5. If the Floor Level attribute only contains one value, that value will also be used by the Lowest Floor Level attribute
`highestfloorlevel`	In cases where the Floor Level attribute contains a list of floor levels (for example, where a commercial organisation occupies multiple levels within a building), the last value provided will be taken as the highest floor level. For example, where Floor Level attribute values are given as -1, 0, 1, 2, 3, the Highest Floor Level is 3. Mezzanine levels may be represented by a partial number, for example, 1.5. If the Floor Level attribute only contains one value, that value will also be used by the Highest Floor Level attribute
`postcodesource`	Identifies the source of the postcode assigned to an address. This attribute can be used to identify properties capable of receiving mail as defined by Royal Mail for PAF matched address records, or as defined by Local Authorities for records which are not PAF matched but which are believed to be capable of receiving mail. For example, flats behind a front door with single letter box	A record which is linked to a Royal Mail address

Additional response fields

Use the addtags querystring parameter to specify a comma-delimited list of response field groups to include in the response. The following groups are supported:

royalmailaddresses
alternateaddresses
streetaddress
metadata
planning
relatedentities
otherclassifications
fullngd (includes all fields)

Royal Mail addresses

An NGD record may have zero, one or more associated Royal Mail addresses. Append ?addtags=royalmailaddresses to your request to include the following fields in the response.

Field	Description	Example
`udprn`	Unique Delivery Point Reference Number (UDPRN) assigned by Royal Mail as a persistent identifier	17308537
`uprn`	The Unique Property Reference Number (UPRN) to which a Unique Delivery Point Reference Number (UDPRN) has been matched	200004353841
`organisationname`	Name of the organisation operating from the address	THE DEAN & CHAPTER OF NORWICH CATHEDRAL
`premise`	Concatenation of the following address components: Department Name, PO Box, Sub Building Name, Building Name and Building Number	CHAPTER OFFICE, 65
`departmentname`	For some organisations, department name is indicated because mail is received by subdivisions of the main organisation at distinct delivery points
`poboxnumber`	Post Office Box (PO Box) number or the British Forces Post Office (BFPO) number
`subbuildingname`	Identifiers for subdivisions of properties	CHAPTER OFFICE
`buildingname`	Description applied to a single building or a small group of buildings, such as HIGHFIELD HOUSE. This also includes those building numbers that contain non-numeric characters, such as 44A. Some descriptive names, when included with the rest of the address, are sufficient to identify the property uniquely and unambiguously, for example, MAGISTRATES COURT. Sometimes the building name will be a blend of distinctive and descriptive naming, for example, RAILWAY TAVERN (PUBLIC HOUSE) or THE COURT ROYAL (HOTEL)
`buildingnumber`	A number given to a single building or a small group of buildings, thus identifying it from its neighbours, for example, 44. Building numbers that contain a range, decimals or non-numeric characters do not appear in this field but will be found in the Building Name or the Sub Building Name fields	65
`dependentthoroughfare`	In certain places, for example, town centres, there are named thoroughfares within other named thoroughfares, for example, parades of shops on a high street where different parades have their own identity. For example, KINGS PARADE, HIGH STREET and QUEENS PARADE, HIGH STREET
`thoroughfare`	A thoroughfare is a road, track or named access route on which there are Royal Mail delivery points, for example, HIGH STREET	THE CLOSE
`doubledependentlocality`	This is used to distinguish between similar thoroughfares or the same thoroughfare within a dependent locality. For example, Millbrook Industrial Estate and Cranford Estate in this situation: BRUNEL WAY, MILLBROOK INDUSTRIAL ESTATE, MILLBROOK, SOUTHAMPTON and BRUNEL WAY, CRANFORD ESTATE, MILLBROOK, SOUTHAMPTON
`dependentlocality`	Dependent locality areas define an area within a post town. These are only necessary for postal purposes and are used to aid differentiation where there are thoroughfares of the same name in the same locality. For example, High Street in Shirley and Swaythling in this situation: HIGH STREET, SHIRLEY, SOUTHAMPTON and HIGH STREET, SWAYTHLING, SOUTHAMPTON
`posttown`	The town or city in which the Royal Mail sorting office is located which services this record. There may be more than one, possibly several, sorting office in a town or city	NORWICH
`postcode`	Postcode	NR1 4DH
`postcodetype`	Describes the address as a small or large user as defined by Royal Mail	Small User
`deliverypointsuffix`	Two-character code uniquely identifying an individual delivery point within a postcode	1S
`welshdependentthoroughfare`	The Welsh translation of Dependent Thoroughfare
`welshthoroughfare`	The Welsh translation of Thoroughfare
`welshdoubledependentlocality`	The Welsh translation of Double Dependent Locality
`welshdependentlocality`	The Welsh translation of Dependent Locality
`welshposttown`	The Welsh translation of Post Town
`latitude`	Value defining the latitude of the Address location in accordance with the ETRS89 (EPSG:4258) coordinate reference system	52.6308744
`longitude`	Value defining the longitude of the Address location in accordance with the ETRS89 (EPSG:4258) coordinate reference system	1.3009883
`easting`	X coordinate defining the position of the object in accordance with the British National Grid (EPSG:27700) coordinate reference system	623485.00
`northing`	Y coordinate defining the position of the object in accordance with the British National Grid (EPSG:27700) coordinate reference system	308793.00
`geometry`	Geometry for the feature	POINT(623485 308793)
`positionalaccuracy`	Local Authority assigned value giving a description of the accuracy of the coordinate position allocated to the Address location, for example, 'Central Internal Position' of a building	Central Internal Position
`geometryallocationmethod`	Describes the method by which a geometry was allocated to the Royal Mail record. Where a Royal Mail record is matched to a Local Authority record, the geometry will be assigned from the matched record. Where a Royal Mail record cannot be directly matched, geometry will be assigned by reference to a parent record, a street, or records which share the postcode unit, sector, district or area – in the listed order of preference. Where none of the listed methods are available, the geometry will be allocated to an internal centre point for the Local Authority area or Island in which the Royal Mail address is located	Matched UPRN
`unmatchedreason`	Describes the reason that the Royal Mail record has not been matched to a Local Authority record
`unmatchedreasondate`	Date on which the Unmatched Reason value was captured
`matchedaddressfeaturetype`	The feature type of the Unique Property Reference Number (UPRN) to which the Unique Delivery Point Reference Number (UDPRN) has been matched	Built Address
`matchtype`	Description of the relationship assigned between the Unique Delivery Point Reference Number (UDPRN) and the Unique Property Reference Number (UPRN). Where a Postcode Address File (PAF) record relates directly to a Local Authority record, this is set to ‘Direct.’ If a ‘Direct’ match cannot be found, a PAF record may be matched to a Parent, Neighbour or Street record in Local Authority data, in order to estimate a position for the PAF record	Direct
`matchdate`	Date on which the match was made between the Unique Delivery Point Reference Number (UDPRN) and the Unique Property Reference Number (UPRN)	2012-04-23
`matchmethod`	The method by which the match was made	Unknown
`matchingorganisation`	Describes the organisation which made the match between the Royal Mail record and the Local Authority record	GeoPlace
`changetype`	The type of change that generated a new version of the feature	New
`theme`	The OS NGD theme to which this feature belongs	Address
`description`	A single descriptive value intended for a quick understanding of what the feature represents	Postcode Address File
`versiondate`	Date when the version was last updated	2025-09-23
`versionavailablefromdate`	Date this version of the feature became the latest version	2025-09-24T00:00:00.000Z
`versionavailabletodate`	Date this version of the feature was superseded by an update or ceased to exist
`entrydate`	Date of the change file that first supplied the Royal Mail record	2016-01-18
`updatedate`	Date the Royal Mail record last changed
`addressline1`	Describes the first line of the address, when address lines are requested using the `lines` query parameter	THE DEAN & CHAPTER OF NORWICH CATHEDRAL
`addressline2`	Describes the second line of the address	CHAPTER OFFICE
`addressline3`	Describes the third line of the address	65 THE CLOSE
`addressline4`	Describes the fourth line of the address
`addressline5`	Describes the fifth line of the address
`addressline6`	Describes the sixth line of the address

Alternate addresses

An NGD record may have zero, one or more associated alternate addresses. Append ?addtags=alternateaddresses to your request to include the following fields in the response.

Field	Description	Example
`alternateaddressid`	Primary key providing a unique identifier	eca05a92-7387-42fa-87ac-7689b7c6359d
`uprn`	Unique Property Reference Number (UPRN) assigned by a local custodian or Ordnance Survey as a persistent identifier	200004353841
`featuretypeversiondate`	Date of the feature version to which this related component applies	2024-05-18
`usrn`	Unique Street Reference Number (USRN), a unique and persistent identifier of a Street which is assigned by the Roads or Highway Authority	28920601
`addressstatus`	Lifecycle status of a given Address, for example, Alternative, Approved, Historic	Historical
`alternatesubname`	Provides an alternative address label to the one provided in the Sub Name. An alternative address label may be present for a number of reasons, for example, retention of an old address label or an alias address label has been recorded by the Local Authority
`alternatename`	Provides an alternative address label to the one provided in the name. An alternative address label may be present for a number of reasons, for example, retention of an old address label or an alias address label has been recorded by the Local Authority	PLOT 1
`alternatenumber`	Provides an alternative address number to the one provided in the Number attribute	1
`streetname`	Name, number or descriptor that identifies the nearest accessible Street that an Address is located on or close to	THE CLOSE
`locality`	Name of the area or geographical identifier within a town, settlement, village or hamlet that an address is located within. For example, a locality may be a suburb, housing estate or commercial estate
`townname`	Name of the settlement that the Street is located within. Where a settlement can be a City, Town, Village, Hamlet or Parish	NORWICH
`islandname`	Name of the island upon which an Address is located; only populated for addresses in the OS NGD Islands collection
`language`	The language in which the address label attribution has been captured for the alternative record	eng
`postcode`	Postcode	NR1 4DH
`fulladdress`	Concatenation of the following address components: Organisation (Pre-Build and Built Address Feature Types only), Sub Name and / or Name and / or Number, Street Name, Locality, Town Name, Island Name and Postcode Locator	PLOT 1, 65, THE CLOSE, NORWICH, NR1 4DH
`floorlevel`	Represents either: the access point to the Address, or the floor level or levels that the Address is located on fully occupies or represents occupiable space within the property
`lowestfloorlevel`	In cases where the Floor Level contains a list of floor levels (for example, where a commercial organisation occupies multiple levels within a building), the first value provided will be taken as the lowest floor level. For example, where Floor Level attribute values are given as -1, 0, 1, 2, 3, the Lowest Floor Level is -1. Mezzanine levels may be represented by a partial number, for example, 1.5. If the Floor Level attribute only contains one value, that value will also be used by the Lowest Floor Level attribute
`highestfloorlevel`	In cases where the Floor Level attribute contains a list of floor levels (for example, where a commercial organisation occupies multiple levels within a building), the last value provided will be taken as the highest floor level. For example, where Floor Level attribute values are given as -1, 0, 1, 2, 3, the Highest Floor Level is 3. Mezzanine levels may be represented by a partial number, for example, 1.5. If the Floor Level attribute only contains one value, that value will also be used by the Highest Floor Level attribute
`updatedate`	Date on which any attribute of the record was last changed	2016-02-10
`effectivestartdate`	Date on which the record was inserted into the Local Authority database	2007-03-15
`effectiveenddate`	Date on which the record ceased to exist	2009-06-04

Street address

An NGD record may have zero or one associated street address. Append ?addtags=streetaddress to your request to include the following fields in the response.

Field	Description	Example
`usrn`	Unique Street Reference Number (USRN), a unique and persistent identifier of a Street which is assigned by the Roads or Highway Authority	28920601
`versiondate`	Date when the version was last updated	2022-11-01
`versionavailablefromdate`	Date this version of the feature became the latest version	2022-11-02T00:00:00.000Z
`versionavailabletodate`	Date this version of the feature ceased to be the latest version
`changetype`	Type of change that generated a new version of the feature	New
`theme`	The OS NGD theme to which this feature belongs	Address
`description`	Short descriptive value that provides a summary of the feature	Street
`streettype`	Description of the street record type, for example, whether the Street has an official designated street name	Officially Designated Street Name
`classification`	Code for the primary street classification, for example, denoting it to be 'open to all vehicles'	All Vehicles
`operationalstate`	Description of the current state of the Street, indicating which point the street record is at within its lifecycle	Open
`operationalstatedate`	Date at which the Street achieved its current state in the world, as referenced by the 'operationalState' attribute	2003-02-07
`streetname`	Name, number or descriptor that identifies the nearest accessible Street that an Address is located on or close to	THE CLOSE
`locality`	Name of the area or geographical identifier within a town, settlement, village or hamlet that an address is located within. For example, a locality may be a suburb, housing estate or commercial estate
`townname`	Name of the settlement that the Street is located within. A settlement can be a City, Town, Village, Hamlet or Parish	NORWICH
`administrativearea`	Name of the Administrative Unit that the Address is located within	NORFOLK
`country`	Name of the geographical territory that the Address is located within, where a geographical territory represents either a devolved country or an island nation	England
`alternatelanguagestreetname`	Name, number or descriptor that identifies the nearest accessable street that an Address is located on or close to, defined in either Welsh (cym) or Gaelic / Scottish Gaelic (gla)
`alternatelanguagelocality`	Name of the area or geographical identifier within a town, settlement, village or hamlet that an address is located within, defined in either Welsh (cym) or Gaelic / Scottish Gaelic (gla). For example, a locality may be a suburb, housing estate or commercial estate
`alternatelanguagetownname`	Name of the settlement that the address is located within, defined in either Welsh (cym) or Gaelic / Scottish Gaelic (gla). A settlement can be a City, Town, Village, Hamlet or Parish
`alternatelanguageadministrativearea`	Name of the Administrative Unit that the Address is located within, defined in either Welsh (cym) or Gaelic / Scottish Gaelic (gla)
`alternatelanguage`	ISO 3166-3 Language Code for Welsh or Gaelic / Scottish Gaelic
`snnauthoritycode`	Alphanumeric code which identifies the Street Naming and Numbering Authority or the Local Highway Authority	2625
`snnauthoritydescription`	Name of the responsible Street Naming and Numbering Authority or Local Highways Authority	NORWICH
`surfacematerial`	Description indicating the type of surface finish on the Street, for example, 'Metalled'	Metalled
`starteasting`	X coordinate in metres for the position of the start point of the street defined in British National Grid (EPSG::27700) coordinate reference system	623392.00
`startnorthing`	Y coordinate in metres for the position of the start point of the street defined in British National Grid (EPSG::27700) coordinate reference system	308760.00
`endeasting`	X coordinate in metres for the position of the end point of the street defined in British National Grid (EPSG::27700) coordinate reference system	623358.00
`endnorthing`	Y coordinate in metres for the position of the end point of the street defined in British National Grid (EPSG::27700) coordinate reference system	308875.00
`startlatitude`	Value defining the Latitude of the position of the start point of the street defined in accordance with the ETRS89 (EPSG::4258) coordinate reference system	52.6300000
`startlongitude`	Value defining the Longitude of the position of the start point of the street defined in accordance with the ETRS89 (EPSG::4258) coordinate reference system	1.3000000
`endlatitude`	Value defining the Latitude of the position of the end point of the street defined in accordance with the ETRS89 (EPSG::4258) coordinate reference system	52.6300000
`endlongitude`	Value defining the Longitude of the position of the end point of the street defined in accordance with the ETRS89 (EPSG::4258) coordinate reference system	1.3000000
`geometry`	Geometry for the feature	MULTIPOINT((623392 308760),(623358 308875))
`streettolerance`	Tolerance of the Start and End Location coordinates in metres	10
`effectivestartdate`	Date on which this record was inserted into the Local Authority database	2003-02-07
`effectiveenddate`	Date on which the record ceased to exist

Meta data

Append ?addtags=metadata to your request to include the following fields in the response.

Field	Description	Example
`effectivestartdate`	Date on which this record was inserted into the Local Authority database	2003-02-25T00:00:00Z
`versiondate`	Date when the version was last updated	2024-05-24T00:00:00Z
`versionavailablefromdate`	Date this version of the feature became the latest version	2024-05-25T00:00:00Z
`changetype`	Type of change that generated a new version of the feature	Modified Attributes
`theme`	The OS NGD theme to which this feature belongs	Address
`positionalaccuracy`	Local Authority assigned value giving a description of the accuracy of the coordinate position allocated to the Address location, for example, 'Central Internal Position' of a building

Planning

Append ?addtags=planning to your request to include the following fields in the response.

Field	Description	Example
`buildstatus`	Description of the build status of the Address, for example, 'Built Complete'	Built In Use
`buildstatusdate`	Date when the address entered the lifecycle state given in Build Status	2003-02-25T00:00:00Z
`addressstatus`	Lifecycle status of a given Address, for example, 'Provisional' and 'Approved'	Approved
`classificationcode`	Alphanumeric code used to classify the object using the AddressBase Classification Scheme	CO01
`classificationdescription`	Description of the classification code as defined in the AddressBase Classification Scheme	Office / Work Studio
`primaryclassificationdescription`	Descriptive term used to describe the primary classification code for this address	Commercial
`secondaryclassificationdescription`	Descriptive term used to describe the secondary classification code for this address	Office
`tertiaryclassificationdescription`	Descriptive term used to describe the tertiary classification code for this address	Office / Work Studio
`quaternaryclassificationdescription`	Descriptive term used to describe the quaternary classification code for this address	Detached
`localcustodiancode`	Numeric code identifying the authority responsible for assigning the Unique Property Reference Number (UPRN), creating and maintaining the address record	2625
`localcustodiandescription`	Name of the authority responsible for assigning the Unique Property Reference Number (UPRN), creating and maintaining the address record	NORWICH
`lowertierlocalauthoritygsscode`	The Office for National Statistics Governmental Statistical Service (GSS) code representing the lower tier local authority	E07000148

Related entities

An NGD record may have zero, one or more associated related entities. Append ?addtags=relatedentities to your request to include the following fields in the response.

Field	Description	Example
`relatedentityid`	Primary key providing a unique identifier	1dd1906f-112a-498b-8e94-7f1dda358e04
`uprn`	Unique Property Reference Number (UPRN) assigned by a local custodian or Ordnance Survey as a persistent identifier	200004353841
`featuretypeversiondate`	Date of the feature version to which this related component applies	2024-05-24
`crossreferencefeature`	Description of the related dataset that the cross reference refers to, for example, VOA Council Tax	OSMM RoadLink
`crossreferenceid`	Identifier of the related data entity or feature type instance that is the target of the reference or link	osgb4000000027437287
`relationshiptype`	Type of relationship which has been formed between the source and target features, for example, 'Within' or 'Same As'	Accessed From
`source`	Name of the originating data provider that defined the reference or link	GeoPlace
`updatedate`	Date on which any attribute of the record was last changed	2016-02-10
`effectivestartdate`	Date on which this relationship was first added into the database	2007-12-03
`effectiveenddate`	Date on which the relationship ceased to exist

Other classifications

An NGD record may have zero, one or more associated other classifications. Append ?addtags=otherclassifications to your request to include the following fields in the response.

Field	Description	Example
`otherclassificationid`	Primary key providing a unique identifier	acbb7372-0a29-4a33-ac5c-c5dc8b9a89f2
`uprn`	Unique Property Reference Number (UPRN) assigned by a local custodian or Ordnance Survey as a persistent identifier	200004353841
`featuretypeversiondate`	Date of the feature version to which this related component applies	2025-07-08
`classificationcode`	Alphanumeric code used to classify the object using the AddressBase Classification Scheme	CO01
`classificationdescription`	Description of the classification code as defined in the AddressBase Classification Scheme	Office / Work Studio
`classificationscheme`	Name of the classification schema	VOA Primary Description
`schemeversion`	Version of the classification schema	1.0
`updatedate`	Date on which any attribute of the record was last changed	2025-07-04

Integration advice

Always provide an option for users to enter their address manually if they cannot find it using your address lookup integration
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
When using your API key across multiple websites, apps or clients, set the identifier querystring parameter to a meaningful value such as "websiteA" or "client123"; you'll then be able to view these identifiers and the number of requests made by each one on the Identifier Usage page
Treat all response fields as optional
Use these fields on your address form: addressline1, addressline2, addressline3, posttown, postcode

Credit cost

Each request costs 3.5 credits.

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