Jump to the following:

Lookup API Documentation

The Lookup API provides a simple way to extract an RDF description of a single resource from an Ordnance Survey dataset.

The URI of the resource to be described is provided as a parameter to the API. All RDF statements about that resource will be extracted from the underlying triple store and used to build the response.

This means the API provides a simple, efficient way to extract descriptions of resources without the need to use a SPARQL query.

API Parameters

The Lookup API has a single required parameter called about whose value should be a URL-encoded URI.

The API also support an optional output parameter that may be used to request a specific response format without using HTTP Content Negotiation. Details on the legal values of that parameter are provided in the section on Response Formats later in this document.

The following table summarises the API parameters:

Parameter Required? Notes
about Yes Specifies the URI of the resource to be described
output No Used to override normal HTTP based Content Negotiation to request results in a specific response format

HTTP Request Methods

The Lookup API only supports GET requests.

The API will also respond to both OPTIONS and HEAD requests. OPTIONS is supported as part of implementing the Cross-Origin Resource Sharing specification. Whereas support for HEAD requests enables conditional HTTP requests, e.g. to check whether data held in the endpoint's triple store has been updated.

HTTP Response Codes

Clients should be prepared to deal with any valid HTTP response code. However the following table summarises the response codes that may be most frequently encountered:

Code Description
200 Request has been successful
304 Not Modified. In response to a conditional GET or HEAD request this response indicates that the underlying data has not changed since the previous request, and cached results may be re-used.
400 Invalid request. E.g. missing about parameter
405 Method not allowed. Request used an unsupported HTTP method, e.g. DELETE or PUT
500 Server error when querying the triple store

Response Formats

The Lookup API returns an RDF graph contains statements about the specified resource. That RDF graph can be serialised in a number of different ways.

The primary method of selecting a response format is using the HTTP Accept header. This can be overridden using the output parameter.

The following table lists the the Accept and output parameter values used to request specific formats. Links are provided to specifications of the individual formats.

Accept header output parameter Format
text/turtle ttl Turtle
application/rdf+xml rdf RDF/XML
application/json json RDF/JSON

Additional Features

The following additional features improve the performance and usability of the Lookup API.

CORS Support

The Lookup API implements Cross-Origin Resource Sharing enabling clients to make requests directly from browsers.

All responses from the API include the following HTTP headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,OPTIONS,HEAD
Access-Control-Allow-Headers: X-Requested-with, Content-Type

Response Caching

API responses are fully cacheable, with caching supported via the HTTP ETag and Last-Modified date headers. When updates are made to the underlying datasets, the values of these headers will be automatically updated.

This means that clients can easily revalidate locally cached results using Conditional GET requests via the If-None-Match and/or If-Modified-Since headers.

A Conditional GET request will return a 304 status to indicate that no changes have been made to the underlying data and previously cached results are still valid. If the triple store has been updated then a 200 response will be served along with the requested results.

Conditional GET requests are faster to serve than the alternative, which involves re-running a query on the server and then re-processing the full results on the client. Clients are therefore encouraged to make use of this facility to improve overall performance.