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.
The Lookup API has a single required parameter called
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:
||Yes||Specifies the URI of the resource to be described|
||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
The API will also respond to both
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:
|200||Request has been successful|
|304||Not Modified. In response to a conditional
|400||Invalid request. E.g. missing about parameter|
|405||Method not allowed. Request used an unsupported HTTP method, e.g.
|500||Server error when querying the triple store|
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
The following table lists the the
output parameter values
used to request specific formats. Links are provided to specifications
of the individual formats.
The following additional features improve the performance and usability of the Lookup API.
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
API responses are fully cacheable, with caching supported via the HTTP
Last-Modified date headers. When updates are made to the
underlying datasets, the values of these headers will be automatically
This means that clients can easily revalidate locally cached results
using Conditional GET requests via the
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.