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. https://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: bb.ringingworld.co.uk
Accept: application/xml

The XML returned by that request is as follows.



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, https://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 with a list of search parameters. 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.

There is an example PHP script and and an example perl script showing how to drive the API from these languages.

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 https://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 https://bb.ringingworld.co.uk/search.php?changed_since=2024-03-14 page. This gives a list of all performances modified on or after 2024-03-14. (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=2024-03-14&deleted=1 doesn't do that: that searches for all performances that were edited (but not deleted) since 2024-03-14, and subsequently deleted. This is because BB doesn't record the date on which a performance is deleted. We are looking into fixing this.