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 distibuted 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"
      }
    ]
  }
}