BellBoard API

This documentation is not very complete, and lots of functionality is not yet documented. If you wish to make use of it, we suggest you email us.

XML format

Peal data is also available in XML format. It is fetched from the same URL as the HTML version, e.g. http://www.bb.ringingworld.co.uk/view.php?id=110081. Using HTTP content negotiation, if a MIME type of application/xml is requested, the XML version is returned instead of the HTML. For example, the following HTTP request will fetch an XML version of the performance.

GET /view.php?id=110081 HTTP/1.1
Host: www.bb.ringingworld.co.uk
Accept: application/xml

The XML returned by that request is as follows.

<?xml version="1.0"?>
<performance xmlns="http://bb.ringingworld.co.uk/NS/performances#" id="P261305">
  <association>St. Martin's Guild for the Diocese of Birmingham</association>
  <place>
    <place-name type="place">Birmingham</place-name>
    <place-name type="dedication">St Paul, Jewellery Quarter</place-name>
    <place-name type="county">West Midlands</place-name>
    <ring type="tower" tenor="12-2-13" />
  </place>
  <date>2009-12-02</date>
  <duration>5h 21m</duration>
  <title><changes>10080</changes> <method>Stedman Triples</method></title>
  <details>Each change occurs once at handstroke and once at backstroke</details>
  <composer>R W Pipe (7 Part)</composer>
  <ringers>
      <ringer bell="1">Christine Mills</ringer>
      <ringer bell="2" conductor="true">Mark R Eccleston</ringer>
      <ringer bell="3">Maurice F Edwards</ringer>
      <ringer bell="4">Jonathan P Healy</ringer>
      <ringer bell="5">Richard L Jones</ringer>
      <ringer bell="6">Paul E Bibilo</ringer>
      <ringer bell="7">Michael P A Wilby</ringer>
      <ringer bell="8">Richard B Grimmett</ringer>
    </ringers>
  <footnote>Rung for the first time. This peal was originally composed in June 1980 at the request of John McDonald. John arranged a few unsuccessful attempts to ring it in the early 1980s. This completes some Birmingham unfinished business.</footnote>
  <timestamp>2013-01-04T03:34:36</timestamp>
  <source site="Campanophile" ref="0x16C81" />
</performance>

This XML format is now largely stable, as is the preferred format for those wishing to access BellBoard programmatically.

If HTTP content negotation isn't convenient, you can append &fmt=xml to the URL instead.

The search and list pages also accept a content type of application/xml and return lists of matching performances. For example, http://www.bb.ringingworld.co.uk/list.php?newest will fetch a list of links to the most recent performances. The search.php page currently needs a POST request. A similar page called export.php exists that is similar to search.php except that (i) it takes its parameters in the query string of a GET request; and (ii) that it includes details of as well as links to the performances.

Mirroring

If you maintain your own database of performances, perhaps one limited in scope, such as peals rung for an association, you can use the API to keep a local database up to date. There are several strategies for this.

The http://www.bb.ringingworld.co.uk/list.php?last_changed page is a bit like the list.php?newest page, except that it orders by date modified instead of date created.

Another possibility is the http://www.bb.ringingworld.co.uk/search?changed_since=2014-04-02 page. This gives a list of all performances modified on or after 2014-04-02. (As with all dates on BellBoard, quite a variety of date syntaxes are accepted, but YYYY-MM-DD is the one considered to be stable for the API.) This can be combined with any of the normal search parameters, such as length=peal.

In both cases, the default page size (which is 100 on the former page, and 200 on the latter) can be overriden by adding pagesize=n to the URL. If the pagesize is greater than 10,000, you'll get a HTTP 413 response. Adding page=n will select the nth page. As above, you can use HTTP content negotiation with an Accept: application/xml header, or by adding the fmt=xml parameter, to get the page in XML.

On the latter page, you can append deleted=1. This will give all deleted performances. However, what you really want is all performances deleted since a given date. Unfortunately changed_since=2014-04-02&deleted=1 doesn't do that: that searches for all performances that were edited (but not deleted) since 2014-04-02, and subsequently deleted. This is because BB doesn't record the date on which a performance is deleted. We are looking into fixing this.