Data Format

To assist in easy parsing of returned data, all responses from the StreetCheck API follow a common pattern:

  • The data is always returned as JSON
  • The data will always contain a top level object with result, message and success properties.

The result property contains the actual data result, and will be null for failed requests.

The message property will be OK for successful requests, and will contain debugging information that will help you if the request failed (for instance if the postcode was malformed or not found).

The success property is a boolean indicating if the returned result is from a successful request.

As well as the textual response, the API will correctly return HTTP status codes of 200 for successful requests, 400 errors for bad requests, 404 for missing information (e.g. a postcode that was not found in the system), and 500 for server errors.

All successful results include a copyrightNotice section within the result. This copyright notice must be displayed with the results on any public facing website, app or other public use. The notice varies by location and data returned (for example we retrieve data from different sources in England than Northern Ireland).

Some endpoint results will also include a apiConsumerNotes property within the result. This provides notes to developers who may be using the API as to the best way to implement the information. This information is also available in the Endpoints documentation.

Example Successful Response

{
  "result": {...data will be here...},
  "message": "OK",
  "success": true
}

Example Failed Response

{
  "result": null,
  "message": "No postcode found with code ZZ11ZZ",
  "success": false
}