Skip to main content

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 ParameterResponse
ID1 1QDSuccessful postcode lookup response (2000)
ID1 KFAPostcode does not exist error (4040)
ID1 CLIPNo lookups remaining error (4020)
ID1 CHOPLimit breach error. Either daily or individual lookup limit has been reached (4021)

Addresses#

Address Search#

GET /addresses?query=:query
Address QueryResponse
ID1 1QDSuccessful query response (2000)
ID1 KFAEmpty query response (2000)
ID1 CLIPNo lookups remaining error (4020)
ID1 CHOPLimit 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 ParameterResponse
0Successful UDPRN lookup response (2000)
-1UDPRN not found error (4040)
-2No lookups remaining error (4020)
-3Limit breach error. Either daily or individual lookup limit has been reached (4021)
-10Successful UDPRN lookup response (2000)
-11Successful UDPRN lookup response (2000)

Autocomplete#

Autocomplete Address#

GET /autocomplete/addresses?query=:query
Autocomplete QueryResponse
ID1 1QDReturns 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"      }    ]  }}