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