Search Parameters

This page documents the search parameters available for use when searching via the API. This page will not be helpful to most users of BellBoard.

Use the literal value tower or hand to restrict the search to just tower or just handbell performances. The value all may be used to explicitly request both tower and handbell performances.
ringer and ringer2
Search for performances including a ringer of the given name. This is a standard text parameter. If both ringer and ringer2 are given the performance must include a ringer that matches the former and a different ringer that matches the latter. If the search is positive (i.e. it does not being !), then the performance much include at least one ringer matching the search; if it is negative (i.e. starting with !), then no ringer must match.
ringer_bell and ringer2_bell
Used in conjunction with ringer and ringer2 respectively, these parameters are used to specify that the given ringer rang a particular bell. This may either be an integer (the bell number) or an expression like N-2, meaning two bells away from the tenor (e.g. the 10th to a 12-bell peal). A ! prefix inverts the sense of the test.
ringer_is_conductor and ringer2_is_conductor
Used in conjunction with ringer and ringer2 to require that the ringer named was the conductor. Usually the conductor parameter is a better way of achieving this, but this can be combined with, say, ringer_bell to locate performances where the conductor rang a specific bell.
ringer_is_strapper and ringer2_is_strapper
Used in conjunction with ringer and ringer2 to require that the ringer was not the first listed ringer of the bell.
Search for performances where the conductor (or one of the conductors in the case of jointly conducted performances) matches the given name. It is a standard text parameter.
Search for performances where the composer maches the given name. Compositions described as arranged by or generated by are found just as if they were composed by. It is a standard text parameter.
date, from and to
Specify the exact date of the performances to the found, or the first or last days included in the results. A wide variety of date formats are supported, but YYYY-MM-DD is recommended. Dates of the form nn/nn/nnnn are treated in the British style (DD/MM/YYYY) rather than the American style (MM/DD/YYYY). If just a year is given (as YYYY) then the whole of the year is included in the search. The literal values today and yesterday are supported, as are certain phrases such as 7 days ago. All dates up to and including 1752-09-02 are assumed to be in the Julian calendar; other dates are assumed to be Gregorian. For backwards compatibility, year is accepted as a synonym for date.
Find performances rung on a particular day, but in any year. The parameter's argument must be written MM-DD (or MM/DD, though this is deprecated).
changed_since, changed_before, submitted_since and submitted_before
Finds only those performances that have changed (for changed_…) or were first submitted (for submitted_…) on or since the given date (for …_since), or before it (for …_before). The date may be specified in any of the formats accepted by the date parameter.
place, region and address
Search only for performances in the matching place. The region field typically contains a county, state or province name, while for churches the address field usually contains its dedication. They are standard text parameters.
Specify the length of the performances to be found. This may be one of the following literals:
  • all — meaning no restriction.
  • short — meaning fewer than 1250 changes.
  • quarter — between 1250 and 4999 changes, inclusive.
  • q-or-p — 1250 or more changes.
  • half — 2500 or more changes.
  • peal — 5000 or more.
  • long — 10000 or more.
  • date — where changes rung equals the year in which it was rung.
  • record — meaning it has been flagged on BellBoard as a record performance by the CC Peal Records Committee.
Note that date touches are considered a type of quarter peal, and long lengths a type of peal. The peal length filter does necessary imply the performance is recognised or claimed as a peal by the band. Alternatively an integer can be given, in which case exactly that number of changes is required. A range separated by a hyphen (e.g. 2000-2015) may also be given and is treated inclusively. Either end of the range may be omitted to denote an open range (e.g. 15000- for touches of 15,000 or more).
If the compliant parameter is set to 0, only performances that have been flagged as non-compliant by the CC Peal Records Committee are found. If set to 1 or used without an argument only performances not flagged as non-compliant are found. As quarter peals and other shorter touches are outwith the remit of the CC Peal Records Committee, they should never be flagged as non-compliant.
title and details
Specifies the title and composition details of the performance. The composition details field typically contains the number of changes of each method, whether it is all the work, etc. They are standard text parameters, except that if no title_suffix parameter is given, any panenthetic text in the title is removed and used as a title_suffix parameter.
Specifies the suffix part of the title — the bit usually placed at the end in parentheses, such as 8m. This is a standard text parameter.
A value of 1 will search for performances with a recognised multi-method title (e.g. Spliced Surprise Major), and a value of 0 will search for performances without a multi-method title. A value of or will search for a performance that either matches the title parameter, or has a mutli-method title.
The stage or stages (in ascending order) of the performance, as an integer or space-separated sequence of them. It is a standard text parameter, so 12 will match both 12, meaning maximus, and 11 12, meaning spliced cinques and maximus; quoting (e.g. "12") can be used to find just that one stage. Note that the stage does not include any covering bells, this triples is found by 7 regardless of whether there is a covering bell.
Specifies the duration of the performance. This must be written in a recognised duration format, examples of which include 4h, 3h23 = 3h23m = 3:23, 47 = 47m, 4m15 = 4m15s, and 35s. Spaces between components are optional. A range separated by a hyphen (e.g. 2h25-2h30) may be given and is treated inclusively. Either end of the range may be omitted to denote an open range (e.g. -2h denotes a performance rung in two hours or less).
weight, tenor_size and tenor_note
Specifies the tenor weight (or size, for handbells) or tenor note. Currently weight and tenor_size are synonymous, but for forwards compatibility, the former should be preferred for tower bells, and the latter for hand bells. At present these are standard text parameters, but the behaviour of these parameters is extremely likely to change in the near future.
source, source_id and direct_to_bb
The source parameter may contain the literal value Campanophile or to find only performances imported from those systems respectively. The source_id field may be used to find a specific performance imported from Campanophile or Campanophile identifiers are in uppercase hexadecimal with a leading 0x prefix. The identifiers in consist of a T or H, followed by a four-digit year and a slash, and then a four-digit identifier, padded with zeros if necessary. Both source and source_id are standard text parameters. The direct_to_bb parameter does not take a value. When specified it tests for those performances that were entered directly on BellBoard. Use of these parameters is discouraged and they are subject to change without notice.
The issue number of The Ringing World in which the performance was printed. Note that this field is only set for recent peals.
Match a footnote to the performance. It is a standard text parameter but will not match across multiple paragraphs.
association and association_id
The association parameter is a standard text parameter that will match the name of the association for which a performance was rung. The association_id parameter takes an integer which matches exactly one form of the association name; it is rather more efficient than using the association parameter. The literal value 0 in the association_id parameter searches for non-association performances. BellBoard does not distinguish performances that are explicitly tagged as non-association from those that are implicitly non-association by virtue of not having an association specified.
Searches for number of bells rung in the given performance. Specifically, it searches for the highest number bell with a ringer associated. If no ringers are given, this will be zero.
If used without a value, this parameter is used to find all performanes in which a bell is rung by more than one ringer. It can also be used with an integer value, optionally prefixed with a > or < sign, to find all performances where there were exactly, more than, or less than the specified number of strappers. For example, >1 will search for performances with more than one strapper, such as when the back two bells both have strappers.
dove_id, towerbase_id and no_tower_id
The dove_id and towerbase_id parameters are used to specify the tower by its alphanumeric identifier in Dove (e.g. CAMBRIDG39) or its TowerBase identifier (e.g. 923). The TowerBase identifier may but needn't be padded to four digits with leading zeros. Note that not all performances in the BellBoard database have these values set correctly; the no_tower_id parameter (which does not take an argument) can be used to find such performances.
with_composition and machine_comp
To find only performances with compositions use the with_composition=1 parameter, and to find just those with a machine-readable composition, use machine_comp=1.
The composition_text parameter is a standard text parameter that matches against the human-readable version of the composition (which may be automically generated from a machine-readable version).
The composition_name parameter is a standard text parameter that matches against the name (or more commonly, number) of the composition.
Find performances associated with a particular event. The value of the parameter is the event id on BellBoard. If the value is prefixed by a !, then all performances not associated with that event are found.
The age parameter is an integer that can be used to hide performances submitted (or copied) to BellBoard a long time after they were rung. Its value is the maximum number of days permitted between the performance and it appearing on BellBoard.
If run by a logged in user, this finds all performances that you submitted. It does not take an argument.
If run by a logged in user, this finds all performances that you have liked. It does not take an argument.
Finds all performances that have been BellBoard's featured performance. It does not take an argument. Note that BellBoard users who have selected a default length in their account preferences will not always see the featured performance on the front cover, and will instead see the highest rated performance of their preferred length. This search parameter only shows the principal featured performance.
Use deleted=1 to find deleted performances. The interaction between this field and the changed_since field is ill-defined and likely to change.
Finds all performances that have been flagged by users as potential duplicates, but not yet resolved by a BellBoard administrator. It does not take an argument.
The not_id parameter takes a comma-separated list of performance identifiers to exclude from the search. For backwards compatibility, this parameter may also be spelt not-id.
Specify the order of the results. The parameter value should be one of the following:
  • date_rung (the default) — chronologically by date rung, newest first.
  • newest — chronologically by date submitted, newest first.
  • last_changed — chronologically by date last modified, newest first.
  • place — alphabetically by place name.
  • changes — numerically by increasing number of changes, and then by place.
  • title — alphabetically by performance title, and then by place.
Any order tag may have reverse or rev appended (with an intervening space, e.g. place reverse), to reverse the order.
The maximum number of results to return from a search. This may not be greater than 10000, or an error will be generated. For most types of search, the default page size is 200. In fact, the API returns one more result than requested, which can be used by applications to determine whether there is a further page of results. This addiional result will appear first on the next page.
The page number, counting from 1, which is the default.
This parameter overrides HTTP content negotiation. At present the only supported value on the search page is xml for BellBoard XML. Export pages (i.e. those with an export.php URL) also allow txt and csv for plain text and comma-separated values. Those formats are less well defined. The plain text format, in particular, is subject to change without notice.
The union parameter takes a comma- or space-separated list of saved search IDs. Each search is run and the results combined with duplicates matches removed. Each constituent search must either be owned by you or have the Publish as RSS check box checked. They must each be sorted by the same criteria.
This parameter takes a comma-separated list of extra columns to append to the search results table. The following column names are accepted:
  • association — the association name.
  • conductor — the name of the conductor.
  • composer — the name of the composer.
  • ringer — the name of the ringer that matched the ringer search parameter; or if that parameter was omitted or was negative, an ampersand-separated list of all the ringers.
  • ringer_bell — the bell or bells rung by the ringer or ringers matched by the ringer parameter, as above. When more than one bell is listed, they are separated by dashes.
  • ringer2 and ringer2_bell — as for the ringer and ringer_bell columns, but for the ringer2 search parameter.
  • stages — the stage or stages rung in the performance, as described for the stages search parameter. The stages are separated by an ampersand for multi-stage performances.
  • bells — the number of bells rung in the performance, as described for the bells search parameter.
  • duration — the duration of the performance. For half peals and longer, providing they last an hour or more, this is formatted 4h or 3h 23; for all other performances it is formatted 47m or 4m 15s. currently in an unstructured format.
  • peal_speed — the length of time a performance of 5000 changes would take, if rung at the same speed as this performance.
  • tenor_size or weight — the size or weight of the tenor, including the note if given; currently in an unstructured format. The two column names are currently synonyms.
  • sent_to_rw — the date on which it was sent for print in The Ringing World.
  • donation — the value of the donation (if any) associated with the performance.
  • score — the current performance score: i.e. the number of likes after their daily decay.
  • likes — the number of likes the performance has received.
  • views — the number of page views the performance has had.
  • details — the composition details.

Standard text parameters

Many search parameters are used to search text, and they share a common syntax. The search text is split on whitespace and each word matched in order in the text. Use an * as a wild card. (A percent sign is also permitted but deprecated.) N* Pitstow will match entries for N Pitstow or Nathan John Pitstow, as well as a fictional Malcolm N Pitstow or M Nathan Pitstow.

Enter a search term enclosed in double quotes to return entries matching that exact search term only: "Nathan Pitstow" will match entries for Nathan Pitstow only, but will exclude entries for Nathan John Pitstow and any other variations on the exact search term. The empty double-quoted string "" can be used to search for an when that field is absent.

Prefix the search term with a ! to invert the sense of the search. A | can be used to separate two or more alterative values.