Jump to the following:

SPARQL API Documentation

SPARQL is a flexible query language for interacting with RDF databases ("triple stores"). SPARQL consists of a number of specifications covering a standardised query language, query response formats, and a protocol for interacting with SPARQL endpoints using HTTP.

Every dataset published as Linked Data by the Ordnance Survey is accessible via a SPARQL endpoint that supports the full SPARQL 1.1 query language and the SPARQL 1.1 HTTP Protocol.

The API documentation on this page applies to all Ordnance Survey SPARQL endpoints. While the data available from each dataset will vary, the basic protocol, query syntax and response formats are all consistent.

API Parameters

As specified in the SPARQL 1.1 Protocol a SPARQL endpoint accepts a single query parameter whose value should be a valid, URL-encoded SPARQL query.

A request to a SPARQL endpoint without a query parameter will return a SPARQL Service Description document. This document contains metadata about the SPARQL endpoint.

The SPARQL endpoints 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
query No If a SPARQL query is not provided, then the endpoint will return a SPARQL Service Description document, otherwise the provided query will be parsed and executed.
output No Used to override normal HTTP based Content Negotiation to request results in a specific response format

HTTP Request Methods

SPARQL queries can be submitted to the endpoints using both the GET and POST methods, as documented in the SPARQL protocol.

Clients are recommended to use GET requests where possible: the responses to these requests will include caching headers that support more efficient querying.

The endpoints 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. an invalid or missing SPARQL query
405 Method not allowed. Request used an unsupported HTTP method, e.g. DELETE or PUT
500 Server error when querying the triple store
503 Query has been timed out (see below)

Response Formats

The SPARQL endpoints support a number of different response formats for serialising the responses to SPARQL queries. This allows clients to consume the data in a variety of ways.

The list of supported formats is dependent on the type of SPARQL query that is submitted to the endpoint:

  • SELECT and ASK queries return a tabular result set. These responses are available in a number of standard SPARQL formats
  • CONSTRUCT AND DESCRIBE queries return an RDF graph. These responses can be returned in a number of different RDF serialisations

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 various types of SPARQL query and the Accept and output parameter values used to request particular formats. Links are provided to specifications of the individual formats.

Query Type Accept header output parameter Format
ASK or SELECT application/sparql-results+xml xml SPARQL XML Results Format
ASK or SELECT application/sparql-results+json json SPARQL JSON Results Format
SELECT text/csv csv SPARQL CSV Results Format
SELECT text/tab-separated-values tsv SPARQL TSV Results Format
CONSTRUCT or DESCRIBE text/turtle ttl Turtle
CONSTRUCT or DESCRIBE application/rdf+xml rdf RDF/XML
CONSTRUCT or DESCRIBE application/json json RDF/JSON

Additional Features

The OS SPARQL endpoints support a number of additional features that aim to improve performance and usability of the APIs.

Query Timeouts

In order to protect the triple stores from poorly constructed or badly optimised SPARQL queries, a query timeout is enforced on all queries submitted to the SPARQL endpoints.

Queries that do not return a response within 30 seconds will be terminated, resulting in an HTTP 503 response being served to the client.

Queries that do not return all their results within 60 seconds will also be terminated. This stops large, long running queries from acquiring all server resources. If data has begun streaming, this may result in a malformed response (e.g. invalid XML or JSON). A message ("Query cancelled due to timeout during execution") is appended to the end of these responses.

To avoid this problem queries should, if possible, use the LIMIT/OFFSET feature of SPARQL to create smaller result pages. Alternatively queries should be reconstructed to return smaller amounts of data.

CORS Support

The SPARQL endpoints implement Cross-Origin Resource Sharing enabling clients to make requests directly from browsers.

All responses from the SPARQL endpoint 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

Responses from the SPARQL Endpoints are fully cacheable. Caching is 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 the 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.