Jump to the following:

Search API Documentation

The Search API provides support for running keyword searches over a dataset. The API supports a flexible search syntax that allows users to query a dataset without having to know the details of data model

The API supports the following functionality:

  • Keyword searches over all literal values in the Linked Data, e.g. names, labels, codes
  • Searching for resources based on their RDF type
  • Range searches over numeric values, e.g easting and northing
  • Filtering of searches based on geographic area
  • Standard search options including relevance ranking and paging
  • Implementation of the Open Search specification

The Search API does not support querying based on relationships between resources, e.g. contains or touches relations. This type of query is already supported via the SPARQL API which is designed to support graph based queries.

The Search API is provided to support many simple data querying use cases that can be achieved with simple keyword searching and/or filtering. E.g. finding places based on their name, or within a geographical area.

The following sections provide more information on the API, beginning with details of the search fields and syntax.

API Parameters

The search API supports the following parameters. More details on the detailed search syntax are included below.

Parameter Required? Notes
easting No Specify easting for spatial search
northing No Specify northing for spatial search
lat No Specify latitude for spatial search
lon No Specify longitude for spatial search
max No Maximum number of results. Default is 10
offset No Offset in search results, to support paging
output No Used to override normal HTTP based Content Negotiation to request results in a specific response format
query Yes The text to match
r No Specify radius for spatial search

Search Syntax

Basic Search Syntax

The following examples illustrate the basic search syntax supported by the API.

Basic keyword search, terms are combined with an AND operator by default:

Vale Glamorgan

Boolean operators, including AND and OR, e.g:

Bath OR Bristol

Phrase searching using quoted terms, e.g:

"The Vale of Glamorgan"

Qualified terms, via the + and - operators, e.g match the term "vale" but exclude the term "glamorgan"

vale -glamorgan

Fielded searches require terms to be matched to specific fields. See later section for a full list of field names. E.g:

hasAreaCode:WMC

Wildcard searching is enabled within fielded searches, e.g:

label:Glamorg*

Promixity searching is also enabled within fielded searches, e.g the following will match labels in which the terms "vale" and "glamorgan" are within 2 words of one another:

label:"vale glamorgan"~2

Type Searching

The search API supports limiting search results to only match resources that have a specific RDF type. This is performed using a fielded search on the type field. URIs used as search terms MUST be quoted.

For the example the following search will return all resources that are a Westminster Constituency:

type:"http://data.ordnancesurvey.co.uk/ontology/admingeo/WestminsterConstituency"

As a fielded search, type searches can be combined with other search operators. E.g. find resources with a type of Westminister Constituency and where the label matches "Suffolk":

label:Suffolk AND type:"http://data.ordnancesurvey.co.uk/ontology/admingeo/WestminsterConstituency"

Supported Fields

The following table lists all of the fields available in the search index, with reference to the RDF property from which their values are taken. All of these fields can be used to build searches against the data.

Field Name Property Notes
easting Easting Numeric field
gssCode ONS GSS code
hasAreaCode Area coding
hasCensusCode ONS census code
hasUnitId Unique identifier for region
hectares Size in Hectares Numeric field
label RDFS label Label associated with the resource
LH NHS Health Authority Code
northing Northing Numeric field
notation SKOS notation A unique code for the resource
point GeoRSS point Latitude and longitude value, most useful via the geographical search feature
PQ Positional Quality Indicator Numeric field
prefLabel SKOS prefLabel A preferred label for a resource. May have multiple values
RH NHS Regional Health Authority Code
type RDF type Values are RDF URIs. Search terms must be quoted

Range Searches

Certain fields in the search indexes are defined as having numeric values. The search API supports performing range searches on this type of field. For example, the following will search for all geometries that are between 100 and 1000 hectares in size:

hectares:[100 TO 1000]

Because easting and northing values are defined as numeric, then it is possible to perform simple bounding box queries using the range search syntax:

easting:[373000 TO 374000] AND northing:[164000 TO 164500]

Additional geographic search features are described in the next section.

Spatial Queries

The Search API supports spatial queries based on a simple distance filter. Search results can be filtered based on whether a location is within a specific distance from an easting and northing, or latitude and longitude respectively.

A spatial search using easting and northing is specified with corresponding easting, northing and r (radius) query parameters. The easting and northing specify the centre of a circle with the specified radius.

A spatial search using latitude and longitude is specified with the lat (latitude), lon (longitude) and r (radius) query parameters. The latitude and longitude specify the centre of a circle with the specified radius.

The spatial search parameters can be used by themselves to find any location within a defined area. E.g. all points within a 5km radius of the centre of Bath (51.378190,-2.365012)

../apis/search?lat=51.378190&lon=-2.365012&r=5

The spatial search parameters can be combined with search terms to filter search results based on their location. For example, search for places called Down within 5km of the centre of Bath:

../apis/search?query=Down&lat=51.378190&lon=-2.365012&r=5

HTTP Request Methods

The Search 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 search index 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 query parameter
405 Method not allowed. Request used an unsupported HTTP method, e.g. DELETE or PUT
500 Server error when querying the search index

Response Formats

The Search API supports several different response formats, including RSS, Atom and JSON.

The following table lists the the Accept and output parameter values used to request specific formats. The following sections provide more details.

Accept header output parameter Format
application/atom+xml atom Atom with OpenSearch extensions
application/rss+xml rss RSS 2.0 with OpenSearch extensions
application/json json Custom JSON output. See below.

RSS & Atom

The Open Search specification recommends the use of existing XML formats for delivering search result in a standard format. The specification defines a number of standard OpenSearch response elements that can be used to annotate these formats to capture search specific metadata, e.g. query terms, number of results, page number and sizes, etc.

The Search API is capable of delivering results as a valid RSS 2.0 or Atom 1.0 XML feed. These feeds use the OpenSearch response elements to annotate the feeds with extra metadata.

In addition to the core metadata, the results will also contain elements from the OpenSearch Relevance extension (for relevance scores) and the Open Search Geo extension for annotating spatial search results.

The RDF properties of results are included as appropriately namespaced XML elements in the search results.

JSON

A custom JSON output format is also supported which consists of:

  • A head object that holds metadata about the search, e.g. the original search URL, search terms, page size, etc. The key names in the head element match their OpenSearch definitions.
  • A results array that holds a page of search results. Each result is a JSON object consisting of a title, a link (the resource URI) and additional keys based on the indexed fields for the resource. Multi-valued field values will be presented as JSON arrays

The following example shows an extract of a simple JSON output:

{
  "head": {
    "link": "http://osld.co.uk/datasets/combined/apis/search?query=%22Combe+Down%22&lat=51.378190&lon=-2.365012&r=5&max=10&offset=0&output=json",
    "searchTerms": "\"Combe Down\"",
    "startIndex": 0,
    "totalResults": 1,
    "lat": "51.378190",
    "lon": "-2.365012",
    "r": "5",
    "itemsPerPage": "10"
  },
  "results": [
    {
      "title": "Combe Down",
      "link": "http://data.ordnancesurvey.co.uk/id/7000000000000503",
      "gssCode": "E05001943",
      "hasAreaCode": "UTW",
      "hasCensusCode": "00HANY",
      "hasUnitID": "503",
      "easting": 375963.7,
      "northing": 162621.5,
      "point": "51.362143,-2.346616",
      "type": "http://data.ordnancesurvey.co.uk/ontology/admingeo/UnitaryAuthorityWard",
      "label": "Combe Down",
      "notation": "00HANY",
      "score": 7.942893
    }
  ]
}

Additional Features

The Search API supports a several additional features that are intended to improve performance and usability of the API.

The Search API has been written to conform to the Open Search specification. This includes:

CORS Support

The Search 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 search index 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 search 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.