API Testing

Listed below is a brief list of available test methods for our core API endpoints.

Test requests do not require you to purchase lookups and they do not drain any existing balance.

Postcodes

Postcode to Addresses

GET /postcodes/:postcode

Postcode Parameter	Response
`ID1 1QD`	Successful postcode lookup response (`2000`)
`ID1 KFA`	Postcode does not exist error (`4040`)
`ID1 CLIP`	No lookups remaining error (`4020`)
`ID1 CHOP`	Limit breach error. Either daily or individual lookup limit has been reached (`4021`)

Addresses

Address Search

GET /addresses?query=:query

Address Query	Response
`ID1 1QD`	Successful query response (`2000`)
`ID1 KFA`	Empty query response (`2000`)
`ID1 CLIP`	No lookups remaining error (`4020`)
`ID1 CHOP`	Limit breach error. Either daily or individual lookup limit has been reached (`4021`)

UDPRN (Address ID) Lookup

UDPRN (Address ID) to Address

GET /addresses/:udprn

UDPRN Parameter	Response
`0`	Successful UDPRN lookup response (`2000`)
`-1`	UDPRN not found error (`4040`)
`-2`	No lookups remaining error (`4020`)
`-3`	Limit breach error. Either daily or individual lookup limit has been reached (`4021`)
`-10`	Successful UDPRN lookup response (`2000`)
`-11`	Successful UDPRN lookup response (`2000`)

Autocomplete

Autocomplete Address

GET /autocomplete/addresses?query=:query

Autocomplete Query	Response
`ID1 1QD`	Returns a successful autocomplete response where associated UDPRNs resolve to the test UDPRNs listed above

Test Fixtures

We also maintain a JavaScript library called api-fixtures. This package returns static test fixtures that represent genuine HTTP API responses returned by api.ideal-postcodes.co.uk.

These test fixtures can be imported to stub out internal method calls or external HTTP API requests.

This library is maintained at github.com/ideal-postcodes/api-fixtures

api-fixtures is distributed via npm (@ideal-postcodes/api-fixtures)

Example Usage

npm install @ideal-postcodes/api-fixtures

import { postcodes } from "@ideal-postcodes/api-fixtures";

// or 
// const { postcodes } = require("@ideal-postcodes/api-fixtures");

// Example for postcodes->success

console.log(postcodes.success);

{
  url: "/v1/postcodes/SW1A2AA",
  query: {
    api_key: "<VALID_API_KEY>"
  },
  headers: {},
  httpStatus: 200,
  body: {
    "code": 2000,
    "message": "success",
    "results": [
      {
        "postcode": "SW1A 2AA",
        "postcode_inward": "2AA",
        "postcode_outward": "SW1A",
        "post_town": "LONDON",
        "dependant_locality": "",
        "double_dependant_locality": "",
        "thoroughfare": "Downing Street",
        "dependant_thoroughfare": "",
        "building_number": "10",
        "building_name": "",
        "sub_building_name": "",
        "po_box": "",
        "department_name": "",
        "organisation_name": "Prime Minister & First Lord Of The Treasury",
        "udprn": 23747771,
        "umprn": "",
        "postcode_type": "L",
        "su_organisation_indicator": "",
        "delivery_point_suffix": "1A",
        "line_1": "Prime Minister & First Lord Of The Treasury",
        "line_2": "10 Downing Street",
        "line_3": "",
        "premise": "10",
        "longitude": -0.127695,
        "latitude": 51.50354,
        "eastings": 530047,
        "northings": 179951,
        "country": "England",
        "traditional_county":
        "Greater London",
        "administrative_county": "",
        "postal_county": "London",
        "county": "London",
        "district": "Westminster",
        "ward": "St James's",
        "uprn": "100023336956"
      }
    ]
  }
}

Documentation