Authentication

Authentication uses the “key” parameter followed by the customer’s API key. All requests must be made over HTTPS.

📘

Use your own API Key

Throughout our documentation you can use your own API key wherever you read YOUR_APP_KEY to run the examples we provide. Simply sign up for a free trial and enter the key when prompted. The key automatically populates the examples, so you only need to do this once.

Currently your app key is set to: [[app:key]]

Encryption

As a user of our APIs you are currently free to use encrypted (https) or unencrypted (http) requests. We always advocate using encrypted connections where possible, though acknowledge that there are legitimate and justified use cases for not using encryption.

🚧

SSL/TLS

Ordnance Survey APIs no longer support calls made using SSL v2/v3 or TLS v1.0/v1.1.
All calls made to any of our APIs must support TLS v1.2 as of 24th October 2018 in line with current cyber security recommendations.
More information can be found on our dedicated support page.

Encoding

All requests must be encoded correctly according to standard percent-encoding procedures for a URI.

What are the response codes?

Code

Official description

Explanation in context of the API

200

OK

Request has been successful.

304

Not Modified

In response to a conditional GET request this response indicates that the underlying data has not changed since the previous request, and cached results may be re-used.

400

Bad Request

E.g. missing query parameter, malformed syntax.

401

Unauthorized

The client has not provided authentication or incorrect authentication.

404

Not Found

The server has not found anything matching the Request-URI.

405

Method not allowed

Request used an unsupported HTTP method, e.g. DELETE or PUT.

500

Internal Server Error

Generic internal server error.

503

Service unavailable

E.g. due to overloading or maintenance.

Service Checks

🚧

Before you Check the Service

In order to check the Os Places API service you will need an API key with a valid Os Places package plan. This can be purchased through your account portal.

To check that the service is running correctly, copy one of the below URL's and paste it into your browser along with your API key;

Match/Find

https://api.ordnancesurvey.co.uk/places/v1/addresses/postcode?postcode=so160as&key=[[app:key]]

Polygon

https://api.ordnancesurvey.co.uk/places/v1/addresses/polygon?offset=0&referencepoint=437318.00%2C115539.00&maxresults=100&key=[[app:key]]