/postcode request

This request is used to get a list of addresses with their details for a specified postcode.

Request

GET https://api.yespostcodesearch.co.uk/api/VERSION/postcode/POSTCODE.FORMAT?key=YOUR_API_KEY

The requests should be sent using the GET method. A valid request should contain the API version, your key, a valid postcode and the selected response format.

Request Parameters

ParameterDescriptionExample
VERSIONThe API version that you intend to use. Currently only version 1 is available.1
YOUR_API_KEYThe API key that have been assigned to you. The key contains 40 alphanumeric characters. Each user can have multiple API keys for use in separate projects. Each key needs to be topped up separately.12345...67890
POSTCODEA postcode to be checked. A valid postcode contains outward code, space and inward code.PA3 4DB
FORMATThe expected response format. Currently XML and JSON responses available. New response types can be added on request.xml

Sample Request

GET https://api.yespostcodesearch.co.uk/api/1/postcode/PA3 4DB.json?key=12345...67890
GET https://api.yespostcodesearch.co.uk/api/1/postcode/PA3 4DB.xml?key=12345...67890

Sample Response

{
   "addresses":[
      {
         "postcode":"G40 1AT",
         "outward_code":"G40",
         "inward_code":"1AT",
         "post_town":"GLASGOW",
         "dependent_locality":"",
         "double_dependent_locality":"",
         "thoroughfare_and_descriptor":"Glasgow Green",
         "dependent_thoroughfare_and_descriptor":"",
         "building_number":" ",
         "building_name":"",
         "sub_building_name":"",
         "po_box":"",
         "department_name":"",
         "organisation_name":"Peoples Palace Museum",
         "udprn":9434444,
         "postcode_type":"S",
         "su_organisation_indicator":"Y",
         "delivery_point_suffix":"1A",
         "latitude":55.85120709,
         "longitude":-4.23698488,
         "county":"Glasgow City",
         "country":"Scotland",
         "openstreetmap_url":"https://www.openstreetmap.org/#map=18/55.85120709/-4.23698488",
         "googlemaps_url":"https:[email protected],-4.23698488,19z",
         "here_url":"https://wego.here.com/?map=55.85120709,-4.23698488,18,normal"
      }
   ],
   "code":200,
   "message":"Success"
}

Response Values

ParameterDescriptionExample
postcodePostcode, the same that was specified in the request.G40 1AT
outward_codeOutward code of the postcode. The postcode part to the left from the space character.G40
inward_codeInward code of the postcode. The postcode part to the right from the space character.1AT
post_townCity / town.GLASGOW
dependent_localityDependent locality.Blantyre
double_dependent_localityDouble dependent locality.Tyre Industrial Estate
thoroughfare_and_descriptorThoroughfare and descriptor. This is the field where you should look for the address street name.Glasgow Green
dependent_thoroughfare_and_descriptorDependent thoroughfare and descriptor.Cheshunt Court
building_numberBuilding number.6
building_nameBuilding name.Abercorn House
sub_building_nameSub building name. Flat number can be stored here.Flat 1
po_boxPO Box.61
department_nameDepartment name.
organisation_nameOrganisation name.Peoples Palace Museum
udprnUDPRN (Unique Delivery Point Reference Number).9434444
postcode_typePostcode type. It is 'S' for Small User and 'L' for Large Users.S
su_organisation_indicatorSmall User Organisation Indicator. Can have the values 'Y' or space. A value of 'Y' indicates that there is a Small User Organisation present at this address.Y
deliver_point_suffixDelivery Point Suffix (DPS). This is a unique Royal Mail 2-character code, which - after added to the postcode - enalbes each live Delivery Point to be uniquely identified. It is a 2-character code, first numberic and second alphabetical, eg. 2B. The DPS for a Large User is always '1A' as each Large User has its own Postcode.1A
latitudeLatitude of the postcode.55.85120709
longitudeLongitude of the postcode.-4.23698488
countyCounty or Region.Glasgow City
countryCountry.England
Scotland
Wales
Northern Ireland
openstreetmap_urlURL to www.openstreetmap.org with the postcode location pointed.https://www.openstreetmap.org/...
googlemaps_urlURL to Google Maps with the postcode location pointed.https://www.google.co.uk/maps/...
here_urlURL to Here Maps (Nokia) with the postcode location pointed.https://wego.here.com/...