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.
bells_type
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.
conductor
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.
composer
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.
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.
day
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.
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.
length
Specify the length of the performances to be found. This may be one
of the following literals:
all — meaning no restriction.
vshort — fewer than 600 changes, including no number of changes specified
eighth — between 600 and 1249 changes
e-plus — more than 600 changes
short — fewer than 1250 changes, including no number of changes specified
quarter — between 1250 and 4999 changes
qp-strict — between 1250 and 2499 changes, and where the number of changes is not equal to the year rung.
q-or-p — 1250 or more changes.
half — between 2500 and 4999 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).
compliant
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.
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 parenthetic text in the title is removed and
used as a title_suffix parameter.
title_suffix
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.
is_multi_method
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.
stages
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.
duration
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_id and direct_to_bb
The source parameter may contain the literal value
Campanophile or peals.co.uk 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 peals.co.uk. Campanophile identifiers are
in uppercase hexadecimal with a leading 0x prefix. The
identifiers in peals.co.uk 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.
rw_issue
The issue number of The Ringing World in which the
performance was printed. Note that this field is only set for recent
peals.
footnote
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.
bells
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.
strappers
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_tower,
dove_ring,
dove_id,
towerbase_id and
no_tower_id
The dove_tower and dove_ring parameters
are used to specify the tower or ring of bells by its numeric identifier in
Dove. The tower would more accurately be described as a building or structure
– St Andrew, Rugby has a single tower ID, even though the two rings are
in different physical towers. Support for dove_ring is considered
experimental and has known problems regarding former rings.
The dove_id specifies the old alphanumeric identifier in Dove (e.g.
CAMBRIDG39). These are deprecated.
The towerbase_id parameter specifies the tower’s 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 on BellBoard have these values set;
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.
composition_text
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).
composition_name
The composition_name parameter is a standard text
parameter that matches against the name (or more commonly, number)
of the composition.
event
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.
age
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.
mine
If run by a logged in user, this finds all performances that you
submitted. It does not take an argument.
liked
If run by a logged in user, this finds all performances that you
have liked. It does not take an argument.
featured
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.
deleted
Use deleted=1 to find deleted performances. The interaction
between this field and the changed_since field is ill-defined
and likely to change.
flagged_dup
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.
not_id
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.
order
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.
pagesize
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 additional result will appear first on
the next page.
page
The page number, counting from 1, which is the default.
fmt
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.
union
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.
add_cols
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.