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:
https://methods.ringing.org/export
For backwards compatibility, we also accept this base URL:
http://methods.ringing.org/cgi-bin/simple.pl
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.
Examples
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.
- To select all methods whose name is Rutland:
https://methods.ringing.org/export?name=Rutland
- To select all Surprise Fourteen methods:
https://methods.ringing.org/export?classes=Surprise&stage=14
- To select all methods rung to (tower bell) peals before
1750:
https://methods.ringing.org/export?performances/firsttower/date<1750
- To select all methods whose database entry has been modified
in the last week:
https://methods.ringing.org/export?meta/db:timestamp>1+week+ago
- To select all plain Major methods with lead head code
c
:https://methods.ringing.org/export?stage=8&classification/cc-class/@class=plain/*&classification/lhcode/@code=c
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.
- The option
pagesize=
sets the maximum number of methods to be returned from the query and should be followed by a number. By default this is set to 100, and you cannot set it to anything greater than 100. - The option
page=
tells the server which page of results to return, when there are too many methods to fit in one page. It should be followed by a number. The
fields=
option allows you to control which parts of the XML structure are returned for each method. For example, usingfields=title
means that the resulting XML will look something like this:<?xml version="1.0"?> <methods xmlns="http://methods.ringing.org/NS/method" xmlns:db="http://methods.ringing.org/NS/database" version="0.1" db:page="0" db:pagesize="100" db:rows="4"> <method id="m3995"> <title>Pudsey Surprise Royal</title> </method> <method id="m4579"> <title>Pudsey Surprise Maximus</title> </method> <method id="m4747"> <title>Pudsey Surprise Fourteen</title> </method> <method id="m8457"> <title>Pudsey Surprise Major</title> </method> </methods>
In fact the part to the right of the equals sign is interpreted as an XPath expression which is evaluated in the context of a template method element. This means that to ask for several fields, you should combine them with a vertical bar character; for example
fields=title|stage|pn
might give the following result:<?xml version="1.0"?> <methods xmlns="http://methods.ringing.org/NS/method" xmlns:db="http://methods.ringing.org/NS/database" version="0.1" db:page="0" db:pagesize="100" db:rows="2"> <method id="4329"> <stage>12</stage> <title>Lindum Surprise Maximus</title> <pn> <symblock>-36-14-5T-16-14-3T-14-5T-14-5T-14-5T</symblock> <symblock>12</symblock> </pn> </method> <method id="5851"> <stage>8</stage> <title>Lindum Surprise Major</title> <pn> <symblock>-36-14-58-16-14-38-14-58</symblock> <symblock>12</symblock> </pn> </method> </methods>
This also means that you can select, say, the whole
classification
element and all its child elements byfields=classification
.The
order=
option specifies that the methods returned should be sorted. After the equals sign should come a list of sorting specifiers, separated by commas. Each sorting specifier is an expression selecting one or more fields, in exactly the same way as for thefields=
option above; this may be followed by one of the wordsascending
ordescending
.For example, to put the methods in alphabetical order by their title, use
order=title
. To put them in reverse order by the date and time they were last modified, useorder=meta/db:timestamp descending
. To order by class and, within that, by first tower bell peal date, useorder=classes,performances/firsttower/date
.
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.
title
- The method’s title (name, class descriptors and stage name)
name
- The method’s name
classes
- The method’s class descriptors (for example Surprise or Treble Place)
lead-head
- The first lead head of the method
classification/cc-class/@class
- The method’s classes, in the format described in the
cc-class
element classification/lhcode/@code
- The method's Central Council lead head code
refs/rwref
- 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
.
- Use an equals sign (=) to search for a given piece of text.
You can use the wildcards
*
to stand for any sequence of zero or more characters, and?
to stand for any one character. For example,name=Br?stol
matching both Bristol and Brystol;name=Camb*e
matches Cambridge, Cambridgeshire and Camborne. - Use a tilde (~) to match against a regular expression. For
example,
name~L[oi]nd.*um
matches both Lindum and Londinium. - Use just the field name on its own to search for methods
where it is not null; for example,
classification/lhcode/@code
will find all regular methods.
Numeric fields
The following parts of the XML structure are numeric fields.
@id
- 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:
classification/cc-class/@little
- Whether the method is Little
classification/cc-class/@differential
- 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.
performances/firsttower/date
- The date of the first tower bell peal of the method
performances/firsthand/date
- The date of the first handbell peal of the method
meta/db:timestamp
- 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.