The BarbershopTags.com API

Application Programming Interface - version 1.7

An API (Application Programming Interface) has been developed for the BarbershopTags.com website, to allow programmers to develop applications for other platforms, such as the iPhone, Android smartphones, and the like.

Currently, there are two ways to interact with the API:

  1. Browse tags and retrieve their details (and the details of their associated videos)
  2. Rate a tag

The API receives HTTP GET requests, queries our online database and returns the requested data in the format specified below
 

Note for all iOS/MacOS developers

Carson Greene has developed a reusable package for interfacing with the API, so that other app developers can easily develop new apps on Apple platforms without having to do all the hard work of manually parsing the API data.  It's currently under active development, but doesn't yet support all features.  The project can be found here: https://github.com/pianogamer5/barbershoptagsapi-swift


1. Browse Tags

Specify on the HTTP GET line the details of the tag(s) you are interested in, and the system will return the tag details in XML format.

A typical browse request looks like this:

http://www.barbershoptags.com/api.php?PARAMETERS

The PARAMETERS listed above are optional.  If they are omitted, the API will return all tags in the system (well, the first 10, anyway).

The parameters that can be specified are as follows:

q Words to search for in the tags' title, alternative title, or arranger's name.  Use %20 for spaces.  If omitted, all tags are returned.  Note:  If you specify the "q" parameter, you should not specify the "id" parameter (see below).  Searches are case-insensitive.
e.g.  q=sweet%20adeline
n The maximum number of tag results required.  If omitted, the default of 10 is used.  Not required when the "id" parameter is specified (see below).
e.g.  n=20
start The index number of the first tag to return.  If omitted, the default of 1 is used.  Note that tags start at index 1, not index 0.  Note that the "index" is NOT the same as the tag's id field.  The index is simply the position of the tag in the list of tags that are returned.
e.g. start=21
id When a specific tag is required, it should be referenced by its "id" number.  Note that if you specify the "id" parameter, you should not specify any of the following parameters:  q, n, start, Parts, Learning, SheetMusic, Collection, MinRating, MinDownloaded or Sortby.
e.g.  id=345
Parts Specify tags that are written for a specific number of voice parts.  Not required with the "id" parameter.
e.g.  Parts=4
Type Specify tags that are written in a particular style.
e.g.  Type=sai
The following types are currently available:
Type=bbs (Barbershop)
Type=sai (Sweet Adelines)
Type=satb (SATB)
Type=male (Other male)
Type=female (Other female)
Type=mixed (Other mixed)
Note that it's possible to request tags from more than one type simultaneously:
e.g.  Type=sai|female|mixed
Learning Specify whether you want tags with learning tracks or not.  Not required with the "id" parameter.
e.g.  Learning=Yes   (tags with at least one learning track)
or
Learning=No   (tags with no learning tracks at all)
SheetMusic Specify whether you want tags with sheet music or not.  Not required with the "id" parameter.
e.g.  SheetMusic=Yes  or  SheetMusic=No
Collection Only return tags that are part of a particular collection.  Not required with the "id" parameter.  At present, there are three tag collections in the system:
Collection=classic (David Wright's "Classic Tags")
Collection=easytags (The "Easy Tags" collection)
Collection=100 (The "100 Days: 100 Tags" collection)
MinRating Filter the tags returned so that the only tags returned are the ones that have their "Rating" field (see below) greater than or equal to the number you specify.  This number can be an integer (e.g. MinRating=3) or a decimal number (e.g. MinRating=3.6).  Not required with the "id" parameter.
MinDownloaded Filter the tags returned so that the only tags returned are the ones that have their "Downloaded" field (see below) greater than or equal to the number you specify. This number must be an integer (e.g. MinDownloaded=300). Not required with the "id" parameter.
Minstamp Filter the tags returned so that the only tags returned are ones that have their "stamp" field later than or equal to the value you specify.  This value can be either a date or a date/time.  Use the following formats:  either YYYY-MM-DD or YYYY-MM-DD HH:MM:SS where a %20 must be used for the space between the day and the hour.  e.g.  Minstamp=2011-06-28 or Minstamp=2011-06-28%2018:04:30
Sortby How to order the tags that are returned.  Not required with the "id" parameter.  The options are:
Sortby=Title (the default) - sort alphabetically by the tag's title
Sortby=Posted - sort by the date the tag was posted to the site (newest first)
Sortby=stamp - sort by the date the tag was last updated (newest first)
Sortby=Rating - sort by the tags' 5-star rating (highest first)
Sortby=Downloaded - sort by the tags' "downloaded" count (most downloaded first)
Sortby=Classic - sort by the tag's "Classic Tags" number (the order in which the tags appear in David Wright's "Classic Tags" booklet).  Should only be used with the Collection=classic parameter.
fldlist A list of the fields that you want returned in the XML, comma-separated (no spaces). If you omit this parameter, then all fields are returned. e.g. fldlist=id,Title,Parts,videos.  The full list of available fields is given below.
client The name of the application or website accessing this data (optional). e.g. client=MyTagsApp

Note that all parameters are case-sensitive (except for the search query term used with the "q" parameter)

For example, consider the following query:

http://www.barbershoptags.com/api.php?q=love&Learning=Yes&SheetMusic=No&start=41&n=20

This means:  Search all tags...

  • That have the word "love" in the title, alternative title or arranger's name (case-insensitive)
  • That have at least one learning track
  • That have no sheet music
  • Starting with the 41st tag in the result set
  • Returning at most 20 tags

Or, to find the first 20 tags from the "Classic Tags" booklet, use the following:

http://www.barbershoptags.com/api.php?Collection=classic&n=20&Sortby=Classic

And then to find the next 20...

http://www.barbershoptags.com/api.php?Collection=classic&n=20&Sortby=Classic&start=21

The query results will look something like this:

<?xml version="1.0" ?>

<tags available="125" count="10" stamp="2011-06-28 18:04:30">

	<tag index="1">

		<id>31</id>

		<Title>After Today</Title>

		<AltTitle />

		<Version />

		<WritKey>Major:F</WritKey>

		<Parts>4</Parts>

		<Type>Barbershop</Type>

		<Recording>stereo - one part on one side, the other three parts on the other side</Recording>

		<TeachVid />

		<Notes />

		<Arranger>Jay Giallombardo</Arranger>

		<ArrWebsite />

		<Arranged>1971</Arranged>

		<SungBy>Acoustix</SungBy>

		<SungWebsite />

		<SungYear />

		<Quartet>Daniel Gillis</Quartet>

		<QWebsite>http://www.vocalharmonies.com</QWebsite>

		<Teacher />

		<TWebsite />

		<Provider>Daniel Gillis</Provider>

		<ProvWebsite>http://www.vocalharmonies.com</ProvWebsite>

		<Posted>Sat, 13 Dec 2008</Posted>

		<Classic>110</Classic>

		<Collection>classic</Collection>

		<Rating>3.1490384615385</Rating>

		<RatingCount>291</RatingCount>

		<Downloaded>434</Downloaded>

		<SheetMusic type="gif">http://www.barbershoptags.com/dbaction.php?action=DownloadFile&dbase=tags&id=31&fldname=SheetMusic</SheetMusic>

		<Notation />

		<AllParts type="mp3">http://www.barbershoptags.com/dbaction.php?action=DownloadFile&dbase=tags&id=31&fldname=AllParts</AllParts>

		<Bass type="mp3">http://www.barbershoptags.com/dbaction.php?action=DownloadFile&dbase=tags&id=31&fldname=Bass</Bass>

		<Bari type="mp3">http://www.barbershoptags.com/dbaction.php?action=DownloadFile&dbase=tags&id=31&fldname=Bari</Bari>

		<Lead type="mp3">http://www.barbershoptags.com/dbaction.php?action=DownloadFile&dbase=tags&id=31&fldname=Lead</Lead>

		<Tenor type="mp3">http://www.barbershoptags.com/dbaction.php?action=DownloadFile&dbase=tags&id=31&fldname=Tenor</Tenor>

		<Other1 />

		<Other2 />

		<Other3 />

		<Other4 />

		<videos available="1" count="1">

			<video index="1">

				<id>83</id>

				<Desc />

				<SungKey>Major:Ab</SungKey>

				<Multitrack>Yes</Multitrack>

				<Code>uxzJHrj0-eI</Code>

				<SungBy>Ronnie Spann (aka BBSTENOR419)</SungBy>

				<SungWebsite />

				<Posted>Mon, 30 Mar 2009</Posted>

			</video>

		</videos>

	</tag>

	<tag index="2">

		....

	</tag>

	....

</tags>

There will be one XML block labelled  "tags".  It will have three attributes:

  1. available=n  The number of tags that match the search criteria
  2. count=m  The number of those tags delivered in this set of search results
  3. stamp=s  The date/time stamp that the XML was generated

Inside that "tags" block, there will be m XML blocks, each labelled "tag".  Each represents all the details from one tag in the database.  Each has a single attribute:  index=i, representing the position of this tag in the total search results.

Each "tag" block will have the following fields:

id The tag's internal database ID
Title The tag's primary title
AltTitle The tag's alternative title
Version The tag's version (e.g. "Realtime version")
WritKey The key the tag was written in
Parts The number of voice parts the tag was written for
Type Either "Barbershop", "Sweet Adelines", "SATB", "Other male", "Other female" or "Other mixed"
Recording The method by which the learning tracks (if any) were recorded
TeachVid The YouTube video ID of the learning video - http://www.youtube.com/watch?v=[video ID here]
Notes Any notes or comments made by the person who uploaded the tag
Arranger The name of the tag's arranger
ArrWebsite The arranger's website
Arranged The year the tag was arranged
SungBy The artist that made the tag famous
SungWebsite The website of the artist that made the tag famous
SungYear The year the tag was made famous
Quartet The quartet or person that sung the learning tracks
QWebsite The website of the quartet or person that sung the learning tracks
Teacher The quartet or person that sung the learning video
TWebsite The website of the quartet or person that sung the learning video
Provider The person that provided the tag or learning tracks
ProvWebsite The website of the person that provided the tag or learning tracks
Posted The date the tag was added to the BarbershopTags.com website
Classic If the tag is part of David Wright's "Classic Tags" booklet, this is the tag number within that booklet
Collection     Which collection of tags this tag is a part of (see above for possible values)
Rating The average of all the tag's 5-star ratings, as a decimal number (e.g. 3.451104)
RatingCount The number of people that have rated the tag
Downloaded The number of times the tag has been downloaded
stamp The date and time the tag was last updated, in the format YYYY-MM-DD HH:MM:SS.  Note that when a tag's rating or download count changes, this updates the tag's stamp value.  Note also that when a video is added to the list of videos available for a tag, the tag's stamp does not change.
SheetMusic URL of the tag's sheet music
Notation URL of the tag's music notation file
AllParts URL of the tag's "All parts" recording (usually MP3)
Lyrics The lyrics to the tag
Bass
Bari
Lead
Tenor
Other1
Other2
Other3
Other4
URLs of each of the tag's learning tracks

Note that the type/extension of the file is returned as a "type" attribute
e.g.  <Bass type="mp3">....</Bass>
videos Set of XML blocks, each representing one tag video, arranged in descending order of the date the video was added to BarbershopTags.com. Each sub-block is called <video>. The <videos> block will be present whether there are <video> sub-blocks or not. There will always be two attributes to the videos field: "available" and "count". Each will contain an identical number - the number of videos available for this tag. There is no way to control how many videos are returned for each tag - you always get all of them. The only thing you can do is specify a fldlist parameter that doesn't include the "videos" field, and then the entire videos XML block will be omitted.

The fields contained in each video block are:
  • id: The video's unique ID
  • Desc: The uploader's description of the video
  • SungKey: The key the video is sung in
  • Multitrack: "Yes" or "No"
  • Code: The YouTube video ID - http://www.youtube.com/watch?v=[Code here]
  • SungBy: Name of singer or quartet in the video
  • SungWebsite: Website of the above singer or quartet
  • Posted: Date the video was added to BarbershopTags.com

2. Rate Tags

Specify on the HTTP GET line the tag that you would like to rate, and its rating, and the system will return either an error message or "ok".

A rating request looks like this:

http://www.barbershoptags.com/api.php?action=rate&id=[tag ID]&rating=[Your rating]

Each rating request must contain exactly three parameters:

action Must always be set to rate
i.e.  action=rate
id The tag ID of the tag you wish to rate.
e.g.  id=21
rating The rating you wish to give the tag. Must be an integer between 1 and 5 (inclusive). 0 is not a valid rating, nor is 3.5.
e.g. rating=4

If all parameters validate correctly, the system will output the word ok onto the page - nothing more.
Otherwise a descriptive error message will be output (e.g. Tag 123456 does not exist).

A working example would look like this:

http://www.barbershoptags.com/api.php?action=rate&id=23&rating=4

Please contact us!

We would love to hear from you....

  • If you have any questions about this API, or you can't get it to work for you
  • If you have developed an application - we can advertise it for you on our site
  • If you have any suggestions about new features for the API

If any of the above applies to you, please contact us!


Swift/iOS API Client

Antonio Cabezuelo Vivo, from Spain, created an API client in Swift, to help with the development of iOS apps.

You can find it here:  https://github.com/tapsandswipes/BarbershopTagsAPIClient