The query format

This page describes how to submit a query to the database and receive a response. For more information on the content of the response, see the XML format. The format of the query is closely related to that of the response.

The HTTP query and response

The database communicates with the outside world using HTTP, the same protocol as you are using to read this web page. This means that you can just type a query into your web browser and view the resulting XML document, which is helpful for getting to understand the system. When accessing the database from a program, you will probably want to use either one of our special libraries or a lightweight HTTP client library.

The URL used to reach the database begins like this:

For backwards compatibility, we also accept this base URL:

This should be followed by a question mark ? and the query string, which specifies which methods you want to search for.

The response to this request consists of an HTTP status code and a content document. If everything went well, the content document will be an XML document containing the results of your query. If there is an error in the query string, the status code will be 400 and the content will be a plain text document describing what was wrong.


All this may sound rather complicated, so here are some simple examples. You can select any of these links in your browser; that will actually query the database and show you the result. Depending on your browser, you may need to select View source or something similar to see the XML markup in the result document.

The query string

The query string can be made up of several parts, separated by ampersands (&). Each part is either a search criterion or another instruction to the server. For example, name=Pudsey is a search criterion asking the database to search for methods with name Pudsey; fields=title|stage|pn is an instruction specifying to the database what fields you want included in the XML for each method returned.

Each part of the query string is made up of two sections: the first selects a field, such as name or stage, or another option such as fields or page; the second section specifies something relating to that field, such as =Pudsey or =8.

Special options in the query string

Apart from search criteria, there are a few special options which can be included in the query string. We describe these first.

Search criteria in the query string

A search criterion like name=Pudsey consists of two sections: the first section name selects which field is being examined, and the second section =Pudsey specifies what criterion is to be applied to that field. The fields that may appear in the first section are listed below. What may appear as the second section, the criterion, depends on what type of field is being examined. For example, a text field such as name may be searched using wildcards such as name=Br?stol (matching both Bristol and Brystol) or even regular expressions such as name~L[oi]nd.*um (matching both Lindum and Londinium.) A numeric field such as stage might be searched using stage=6 or stage>=14.

Text fields

The following parts of the XML structure are text fields. See the XML format for more information on what information each contains.

The method’s title (name, class descriptors and stage name)
The method’s name
The method’s class descriptors (for example Surprise or Treble Place)
The first lead head of the method
The method’s classes, in the format described in the cc-class element
The method's Central Council lead head code
A reference to the method's appearance in The Ringing World

Any of these fields can be searched in three ways. As an example, we use the field name.

Numeric fields

The following parts of the XML structure are numeric fields.

The method’s unique identifier in the database, as allocated by the Central Council

Boolean fields

The following parts of the XML structure are Boolean (true or false) fields:

Whether the method is Little
Whether the method is Differential

Either of these fields can be searched by the expressions =1, =y, =yes, =true, =0, =n, =no or =false. Specifying the field's name with no further expression is the same as searching for methods where the fields is true. For example, classification/cc-class/@little=true and classification/cc-class/@little both find Little methods.

Date or date-time fields

The following parts of the XML structure are date or date-time fields.

The date of the first tower bell peal of the method
The date of the first handbell peal of the method
The date and time when the database entry for this method was last updated

Any of these fields can be searched using any of the operators =, <, <=, >= and >. The date or time you want to compare with can be specified in almost any way you can think of. For example, performances/firsttower/date<1750 selects methods whose first tower bell peal was before 1750; performances/firsthand/date>1 year ago selects methods first rung to handbell peals in the last year; and meta/db:timestamp>noon last Tuesday selects all methods whose database entry has been updated since then.

Other fields

The stage field can be searched using any of the comparisons =, <, <=, >= and >. For example, stage=8 finds Major methods; stage<5 finds methods on four bells or fewer.

If you use =, you can give a comma-separated list of values to search for: for example, stage=8,10.

The @id field contains the method's unique identifier in the database. You can search by ID either by specifying a single ID, for example @id=m8457; or by specifying a space-separated list of IDs, for example @id=m8457 m4747. Remember that, in a URI-escaped string, a space can be writted as %20 or as +.

One very good reason to search by method ID is that it is fast. Suppose that your user has already searched for a list of methods and is now choosing one or more about which to get further information. If you remember the method IDs from the first request and use them in the second request, you will get a faster response than, say, searching by title.