Voicebox API

Voicebox provides an open REST API so that web and mobile apps can integrate with the fun functionality of Voicebox. This is the guts behind our mobile app at vbsongs.com, and how our website can display the current popular songs.

We encourage experimentation and development of features which integrate Voicebox with social networking sites and other online music systems.

Please be considerate of others, and of the fact that hundreds of paying customers use our system every day. Abuse will not be tolerated.

Resource Overview

Songs

  • GET /api/version/songs.format
  • GET /api/version/songs/id.format
  • GET /api/version/songs/search.format
  • GET /api/version/songs/languages.format
  • GET /api/version/songs/stats.format

Queue

  • GET /api/version/queue.format
  • POST /api/version/queue.format
  • DELETE /api/version/queue.format

Lights

  • PUT /api/version/lights.format

Reservations

  • POST /api/version/reservations/request.format
  • GET /api/version/reservations/hdyhaus.format

Versioning

Each URL contains a version, which is something like v1, so the actual URL would be /api/v1/songs

Current Version: v1

Formats

The URLs also contain an optional format, which can be one of: .json, .txt, or .html

If the format is unspecified, it uses the Accept header in the HTTP request. Browsers will typically use Accept: text/html, so you will get back an HTML result, which is not JSON. Though this makes for convenient testing from a browser, you should use .json in your production system.

  • json should be used by production systems
  • txt is more human-readable json
  • html is a formatted response
JSONP

The Voicebox API optionally supports JSONP responses, by supplying an additional ‘callback=myFunctionName’ parameter on any of the resources below. Note that this only works with the .json format. This will cause the response to be returned as:

myFunctionName({ ... })

Error handling in JSONP is notoriously bad. See this discussion for an overview of the problem. If there is an error, the script tag will simply not be loaded by the browser, and the AJAX call will stall. To get around this, the Voicebox API will respond with an HTTP status code of 200 even if an error occurs, and the response body will be something like:

myFunctionName({"error":"Description of the error","status":400})

The status provided is the HTTP status code that would have been received, were it not a JSONP request.

Pagination

Because there are so many songs at Voicebox (over 60000 and growing), there is no single request to get all of the song data. Instead, we provide resources to browse the song database much as one would browse a song book, by artist or by title.

Large resources, like the songs resources, return only a limited set of results, and have a page parameter to control which page is returned.

There is also a per_page parameter, which can adjust how many results come back per page, though most resources will have a maximum.

Song duplicates

We often have many copies of a song. These are not simple duplicates. Rather, these are versions of the same song from different publishers, and can have radically different sound and video qualities. We may enhance the API to group these or otherwise change their formatting in the future.

GET /api/version/songs.format

Access songs available at Voicebox.

The intended usage is to page through songs by artist or by title, much as you would access songs in the song book.

Parameters

  • by (optional)
    one of artist, title or popularity defaults to artist

  • prefix (optional)
    when unspecified, returns results across all songs
    use character ‘$’ to browse all songs that begin with a non-alphabetic character

  • language (optional)
    when unspecified, returns all languages

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50 maximum is 1000

Examples

To get the first page of the English song book by title, use

GET /api/v1/songs?by=title&language=English

To get the second page, in JSON format, use

GET /api/v1/songs.json?by=title&language=English&page=2

To get just songs by title that start with ‘d’, use

GET /api/v1/songs?by=title&language=English&prefix=d

To get the third page of songs by artist that start with ‘depeche’, with a page size of 10, use

GET /api/v1/songs?by=artist&language=English&prefix=depeche&page=3&per_page=10

To get the list of popular songs, use

GET /api/v1/songs?by=popularity

GET /api/version/songs/id.format

Access information about a single song by ID.

Parameters

None

Examples

To get the JSON information for Don’t Stop Believin’, use

GET /api/v1/songs/11750.json

To get the same information using a cross-domain JSONP call, use

GET /api/v1/songs/11750.json?callback=mycallback

GET /api/version/songs/search.format

Search songs by title or artist.

Parameters

  • query (required)
    Search terms to find in the title or artist of a song
    Returns all matches, across artist and title

  • language (optional)
    when unspecified, returns all languages

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50
    maximum is 1000

Examples

To get the first page of results searching for ‘Elvis’, use

GET /api/v1/songs/search?query=Elvis

To get the second page, use

GET /api/v1/songs/search?query=Elvis&page=2

To get only English language songs with the term ‘Elvis’, use

GET /api/v1/songs/search?query=Elvis&language=English

GET /api/version/songs/languages.format

Get available languages, and information about how many songs are available in each language.

Parameters

None

Examples

To get all available languages

GET /api/v1/songs/languages

GET /api/version/songs/stats.format

Get statistics for songs, such as the top played songs and artists.
Also includes information about recently played songs, with breakdowns by day, week, and per room.

Parameters

None

Examples

To get song statistics

GET /api/v1/songs/stats

GET /api/version/queue.format

Get the song queue for a room.
Returns information about all queued songs, as well as the currently playing song.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the queue

Examples

To get the queue for a room, given that you know the 4-letter code, use

GET /api/v1/queue?room_code=MQRX

POST /api/version/queue.format

Add one or more songs to the queue for a room.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the queue

  • song_id (required)
    The numeric song id, typically found by browsing or searching for songs
    This may be a comma-separated list of song ids, to add multiple songs at once

Examples

To add Don’t Stop Believin’ to the queue, use

POST /api/v1/queue?room_code=MQRX&song_id=11750

To add 3 songs at once to the queue, use

POST /api/v1/queue?room_code=MQRX&song_id=101,102,103

Using curl, from the command-line, this can be accomplished with
curl -X POST -d "" "http://www.voiceboxpdx.com/api/v1/queue.json?room_code=MQRX&song_id=11750"

DELETE /api/version/queue.format

Delete all songs from the queue for a room.
Note, this does not stop the currently-playing song. It only removes upcoming songs.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the queue

Examples

After adding several songs, to clear them all, use

DELETE /api/v1/queue?room_code=MQRX

PUT /api/version/lights.format

Set the lighting levels and effects in a room.
Note, there is currently no way to get the current lighting levels.

Parameters

  • room_code (required)
    The 4-letter code displayed in the room at Voicebox
    Without this code, clients are not able to access the lights

  • mode (optional)
    An integer value 0 - Bright lights 1 - Medium lights 2 - Low lights

  • effects (optional)
    A boolean value, indicating whether the lighting effects should be turned on or off
    In most rooms, this controls the mirror ball

Examples

To turn on the mirror ball, given that you know the 4-letter code, use

PUT /api/v1/lights?room_code=MQRX&effects=1

To set a low lighting level, use

PUT /api/v1/lights?room_code=MQRX&mode=2

To turn off the mirror ball, and raise the lights to a bright level, use

PUT /api/v1/lights?room_code=MQRX&mode=0&effects=0

POST /api/version/reservations/request.format

Create a new reservation request. This will put a reservation request on the Voicebox calendar. The intended usage is for the “Book Your Box” form on the Voicebox website.

Parameters

  • api_key (required)
    This key is provided by Voicebox to its clients. Please contact Voicebox.
    Without this key, clients are unable to create reservation requests.

  • first_name (required)

  • last_name (required)
    The name of the customer making the request

  • phone (required)
    A valid 10-digit phone number at which the customer may be contacted
    Ignores any punctuation, so a variety of formats may be accepted
    e.g. (555) 867-5309, 555-867-5309, 5558675309
    Accepts an optional extension, after an x, e.g. 555-867-5309x123

  • email (required)
    A valid email address at which the customer may be contacted

  • business_date (required)
    The desired date of reservation.
    Accepts a variety of formats, but the following is recommended: 2012-02-14
    Even if the start_time is after midnight, use the date on which Voicebox last opened its doors for business prior to the start_time.

  • start_time (required)
    The desired starting time of the reservation. It should be on a quarter-hour boundary.
    Acceptable formats include: ‘11am’, ‘11:00am’, ‘8:15pm’, ‘11pm’, ‘12am’, ‘1:45am’
    ‘8:05pm’ would not be acceptable, because it is not on a quarter-hour boundary.

  • duration (optional)
    The desired duration of the reservation in hours. Must be in intervals of a quarter-hour.
    e.g. ‘1’, ‘1.0’, ‘1.25’, ‘3’

  • party_size (optional)
    The estimated party size. Accepts a number, a bounded range, or an unbounded range.
    e.g. ‘5’, ‘5-12’, ‘14+’

  • minors (required)
    Whether any minors under the age of 18 are expected to attend.
    One of: ‘0’, ‘1’, ‘f’, ‘t’, ‘false’, ‘true’

  • hdyhau (optional)
    “How did you hear about us?”
    One of the values returned by a call to GET /api/v1/reservations/hdyhaus

  • notes (optional)
    Any additional notes that the customer would like Voicebox be aware of.
    This may contain arbitrary text, including newlines.

  • utm_source (optional)
  • utm_medium (optional)
  • utm_term (optional)
  • utm_content (optional)
  • utm_campaign (optional)
    These optional fields indicate the corresponding Google Ad information. This is useful for tracking how customers discover Voicebox and then book reservations

Examples

To create a request, use something like the following:

POST /api/v1/reservations/request?api_key=ThisIsNotARealKey&first_name=Jenny&last_name=Tutone&phone=555-867-5309&email=jenny@columbia.net&business_date=2015-02-14&start_time=9:30pm&duration=2.5&party_size=8+&minors=false&hdyhau=friend&notes=I%20love%20Voicebox&utm_source=google&utm_medium=cpc&utm_term=karaoke&utm_content=textlink&utm_campaign=bridal

GET /api/version/reservations/hdyhaus.format

Get available HDYHAU values. HDYHAU is “How did you hear about us?”. These enumerated values are supported in the ‘hdyhau’ field of a reservation request.

Parameters

None

Examples

To get all available HDYHAUs

GET /api/v1/reservations/hdyhaus