Jump to the following:

Reconciliation API Documentation

The Reconciliation API is a simple web service that supports linking of datasets to the Ordnance Survey Linked Data. The API accepts a simple text search, e.g. a label, code or other identifier for a resource and then returns a ranked list of potential matches. Client-side tools may then use these results to either build links to the Linked Data or use the returned identifiers to extract further data to enrich the original dataset.

The Reconciliation API was originally specified as part of the Google Refine tool for matching entities against Freebase and other services. The Open Refine Reconciliation API provides some additional background on the design and use of the API.

This means that all of the Ordnance Survey Linked Datasets can be used directly from Open Refine.

API Parameters

There are several ways of invoking the Reconciliation API. Several of these are supported to ensure good integration with Open Refine.

To support easier usage outside of that tool, the original API has been extended slightly to support simple query parameters rather than encoded JSON objects. The following table summarises the parameters. Their definitions match those used in the Open Refine Reconciliation API.

Parameter Required? Notes
query No If provided, this is either the text to match or a JSON literal describing the search. A request without a query parameter will return the service metadata.
queries No If provided this is must be a JSON encoded literal. Used in "Multiple Query Mode" as described in the Open Refine Reconciliation API
limit No Limit the number of candidate results returned. Default is 10
type No The URI of an RDF type to be used to filter matches
type_strict No Controls type matches. Legal values are "any", "all", or "should"
callback No A JSONP callback, indicating the client-side function to call with the results. This is provided to support Open Refine integration. New clients are recommended to use Cross-Origin Resource Sharing rather than JSONP requests.

In addition to the above usage, the API supports both the "Single Query Mode" and "Multiple Query Mode" options documented in Open Refine Reconciliation API.

These are means by which Open Refine integrates external services and are supported primarily to integrate with the tool. However they may be useful in other clients, particularly those that support bulk matching.

HTTP Request Methods

The Reconciliation API supports both GET and POST requests. Clients are encouraged to use GET requests by default as the API will return caching headers.

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 parameters
405 Method not allowed. Request used an unsupported HTTP method, e.g. DELETE or PUT
500 Server error when performing a search

Response Formats

The reconciliation API only supports JSON as output. The format matches the Open Refine Reconciliation API, e.g:

{
  "result": [
    {
      "id": "http://data.ordnancesurvey.co.uk/id/50kGazetteer/162467",
      "name": "Mill Creek",
      "score": 1,
      "match": true,
      "type": [
        "http://data.ordnancesurvey.co.uk/ontology/50kGazetteer/NamedPlace"
      ]
    },
    ...additional results...
  ]
}

The result array in the response contains one entry per match. The fields are:

  • id: URI of the matched resource
  • name: the RDFS label of the resource
  • score: a score for the match, between 0 and 1
  • match: either true or false to indicate an exact match
  • type: an array containg the RDF type properties associated with the resource

For "Multi Query Mode Requests", the JSON response format is different as results are keyed on the identifier for the original query. See the Open Refine Reconciliation API.

Additional Features

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

CORS Support

The Reconcilation 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,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.