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

Login

  • POST /api/version/login.format

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

Song Favorites

  • GET /api/version/songs/favorites.format
  • POST /api/version/songs/favorites.format
  • DELETE /api/version/songs/favorites.format

Queue

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

Lights

  • PUT /api/version/lights.format

Plays

  • GET /api/version/plays/history.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.

Error Handling

The HTTP responses use standard HTTP status codes.

Successful responses will be 200 OK, or 201 Created.

Error responses will contain a result like:

{"error":"Description of the error","status":400}

The status code will indicate the type of error:

400 Bad Request - there is missing or invalid data in the request
401 Unauthorized - the room_code or api_key provided is incorrect
403 Forbidden - the action is not allowed right now, e.g. the queue is limited, or requires a logged-in session
404 Not Found - the URL does not correspond to a valid resource, e.g. the song_id does not exist
500 Internal Server Error - something went wrong on our end. We’ll log it and fix it
504 Gateway Timeout - the internet is unavailable between our server and the Voicebox location

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.

Sessions

Each API call may provide a session parameter, which should be a valid UUID, in the 8-4-4-4-12 hexadecimal format. This session is used to identify activity from a single user, for keeping track of play history, storing a user’s favorite songs, and other features as Voicebox grows. This parameter is usually optional, but some features require a session, such as getting your play history.

Clients may generate a session UUID themselves, and they do not need to actually call the Voicebox API in order to get a session. This session UUID should be stored client-side and sent with every request.

For testing, please use session 12345678-1234-1234-1234-123456abcdef

Login

In addition to sessions, the Voicebox API supports login to a customer profile, by supplying an email address. This finds an existing profile, or creates a new profile, which allows features such as play history to persist across sessions, or to be viewed from another device. Some features require a login, such as viewing a user’s favorite songs, and more to come.

POST /api/version/login.format

Login to the Voicebox API by email, which will or find or create a new profile if it does not already exist, and associate the current session with the profile. This is necessary for some features, such as keeping favorite songs, playlists, and more as Voicebox grows.

Parameters

  • session (optional)
    This is normally already generated by the client, and should be specified.
    When unspecified, returns a new session to be used.

  • email (required)
    A valid email address

GET /api/version/songs.format

Access songs available at Voicebox.

The intended usage is to page through songs by artist, title, popularity, or recent additions, much as you would browse songs in a printed song book.

Parameters

  • by (optional)
    one of artist, title, popularity, or recently_added 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/67277.json

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

GET /api/v1/songs/67277.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/songs/favorites.format

Get songs that have been favorited by a logged-in user.

Parameters

  • session (required)
    The user must be logged-in

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50
    maximum is 1000

POST /api/version/songs/favorites.format

Add a song to save as a favorite.

Parameters

  • session (required)
    The user must be logged-in

  • song_id (required)
    The song you love to sing!

DELETE /api/version/songs/favorites.format

Remove a song from your favorites.

Parameters

  • session (required)
    The user must be logged-in

  • song_id (required)
    The song you used to love, and now it’s just been overplayed!

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=HSCL

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=HSCL&song_id=67277

To add 3 songs at once to the queue, use

POST /api/v1/queue?room_code=HSCL&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=HSCL&song_id=67277"

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=HSCL

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=HSCL&effects=1

To set a low lighting level, use

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

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

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

GET /api/version/plays/history.format

Get the play history for the current user. This does not require a logged-in session. However, with a login, your history will be persistent across visits to Voicebox.

Parameters

  • session (required)
    See the description above about sessions

  • page (optional)
    defaults to 1

  • per_page (optional)
    defaults to 50
    maximum is 1000

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.

  • location (optional)
    The desired location for the reservation. It may be one of ‘Northwest’ or ‘Southeast’. It may also be omitted or left blank, to indicate no location preference.

  • 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&location=Northwest&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