Sign Up | Sign In

Chat with fellow tag singers and discuss the tags on our Facebook group

Developing this site has cost a great deal of money, and it costs still more to keep it alive (hosting, domain names, etc). Any help you can offer in offsetting these costs is greatly appreciated.

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

---

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
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 only two tag collections in the system: Collection=classic (David Wright's "Classic Tags") Collection=easytags (The "Easy 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> 

		<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
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)
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!

Copyright information

Website developed and hosted by Virtual Creations