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:
- Browse tags and retrieve their details (and the details of their associated videos)
- 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:
- available=n The number of tags that match the search criteria
- count=m The number of those tags delivered in this set of search results
- 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:
|
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
