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.
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.
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
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:
||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.|
||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
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 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. an invalid or missing SPARQL query|
|405||Method not allowed. Request used an unsupported HTTP method, e.g.
|500||Server error when querying the triple store|
|503||Query has been timed out (see below)|
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
The following table lists the various types of SPARQL query and the
output parameter values used to request particular
formats. Links are provided to specifications of the individual formats.
||SPARQL XML Results Format|
||SPARQL JSON Results Format|
||SPARQL CSV Results Format|
||SPARQL TSV Results Format|
The OS SPARQL endpoints support a number of additional features that aim to improve performance and usability of the APIs.
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
OFFSET feature of SPARQL to create smaller result pages. Alternatively queries should be reconstructed to return smaller amounts of data.
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
Responses from the SPARQL Endpoints are fully cacheable. Caching is
supported via the HTTP
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
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.