Bandcamp API

Bandcamp provides data and functionality through its API to you, the developer. The API is free to use, but before you start you need to 0) familiarize yourself with the API terms of use, and 1) get your own developer key, which is required in order to make API calls.

The spirit of the API is to help artists thrive (come to think of it, that goes for all of Bandcamp). If you're an artist, we encourage you to use the API to make your own players, track lists, Buy buttons, etc. If you're a developer thinking about putting together a mobile app or website that's going to feature Bandcamp artists, we require you to include prominent links in your UI back to the individual artists' Bandcamp pages, Buy buttons when artists have music for sale, and so on. Again, be sure to read the terms of use for the full list of requirements. The gist is to be good to artists. Let this guide your efforts, and we look forward to seeing what you make!

Getting Started

The API is based on HTTP GET requests. The URL you request is the full specification of the function call, including the name of the function and all of the function's parameters. The HTTP response is the data you asked for, in JSON format. It's pretty simple.

Let's get into the details by way of a few examples. Here's a search:

  http://api.bandcamp.com/api/band/3/search?key=<key>&name=amanda%20palmer

Clicking on the example will open a new window with the results.

Looking at the response you'll see that you've got a top-level JSON object named results. It's an array of matches, and each match is a hash containing basic information about the matching band: its id and Bandcamp URL, and so on. In Ruby you can use the response in pretty standard ways:

  response["results"].each do |match|
    puts match["url"]
  end

And in JavaScript it would look something like this:

  for (var i = 0; i < response.results.length; ++i) {
    var match = response.results[i];
    console.log(match.url);
  }

The point we're trying to make is that the result is a simple JSON object, which you can turn into your language's equivalent of hashes (objects), arrays, numbers, strings, etc. If you've used an HTTP-based API before this should all be familiar.

If you haven't used an API like this, you'll want to get good at constructing query strings, learn the techniques in your language to fetch a URL, and bone up on JSON, including how to convert data from JSON format.

Here's another example. This one fetches a band's discography:

  http://api.bandcamp.com/api/band/3/discography?key=<key>&band_id=203035041

In this example you're getting back an object named discography that's made up of an array of albums. Each album in the discography is a hash with basic information such as the album's id, title, Bandcamp URL, etc.

Let's look at how the URL is constructed. Every API URL begins with

  api.bandcamp.com/api/

All of the functions are grouped into modules (more on this in the reference) which is part of the URL. First comes the module name and version number, followed by the function name.

  api.bandcamp.com/api/band/3/search

Together these pieces uniquely identify the function you're calling. Functions typically have parameters, and these are included in the URL in the normal query format. That is, they're prefixed with ?, they're made up of name/value pairs, and multiple parameters are separated with &.

  api.bandcamp.com/api/band/3/search?name=amanda%20palmer
  api.bandcamp.com/api/band/3/info?band_id=3463798201&key=jokull

The values are typically numbers and strings, and all strings must be URL-encoded. Strings don't have quotes around them. Note that it's not enough simply to replace spaces with %20 in strings — you must use the URL-escaping methods of your language.

  name=dan%C3%ADel%20bjarnason
  band_id=3463798201

Not all parameters need a value. For these it's enough just to have the parameter's name in the URL. Some parameters can take a list of values, in which case the values are separated by commas. The search function works this way.

  name=dan%C3%ADel%20bjarnason,cults,mountain%20man

You can use a browser like we're doing now to explore all of the API calls. These are, after all, just HTTP requests and responses. For example, take the search URL we used in the first example and modify it to search for other names. Try using one name and a list of names. How many bands do you think are named "Si"?

  http://api.bandcamp.com/api/band/3/search?key=<key>&name=cults,mountain%20man

By now you may've noticed that we've been secretly including the debug parameter in the examples. This instructs the API to return the JSON response in a more human-readable form with spacing and newlines. This is what it looks like with debug:

  {
    "subdomain": "amandapalmer",
    "name": "Amanda Palmer",
    "offsite_url": "http:\/\/www.amandapalmer.net",
    "url": "http:\/\/music.amandapalmer.net",
    "band_id": 3463798201
  },

And this is what it's like without:

  {"subdomain":"amandapalmer","name":"Amanda Palmer","offsite_url":"http:\/\/www.amand... etc.

It's great to use while you're exploring but be sure to leave it out of your finished product.

Developer keys

Sorry, we're not handing out new developer keys at the moment. Follow @bandcamp to be notified when we start doing so again.

Reference

Here you'll find an overview of the Bandcamp API and details of every function available.

Modules. All of the API functions are grouped into modules. The functions that have to do with bands, for example, are grouped together in the "band" module. When talking about functions we include both the function's module and the function's name, like "band/search" and "album/info".

Modules are versioned individually and independently — there’s no overall "Bandcamp API" version number. The version number of the module is included in every call, like this:

  api.bandcamp.com/api/band/3/search?...

Which means "band module, version 3". And this:

  api.bandcamp.com/api/url/1/info?...

is version 1 of the "url" module. Version numbers are plain ol' integers that we increment with each new revision of a module. This makes it easy for us to extend the API (that is, make new versions of modules) while maintaining backwards compatibility with older modules (and the programs that use them). In the sections below the version number is listed under the module's name, and of course the version numbers are included in all the examples.

Data Types. The only primitive data types used in the API are numbers and strings. When a number is used as an "id" it'll be an unsigned 32-bit integer. There's no fixed upper limit on the lengths of strings. Dates are expressed as integer epoch seconds (unsigned 32-bit). Bandcamp lives on the Faroe Islands and consequently all times are GMT.

Parameters. There are three parameters that apply to every function call:

  • key – Your developer key must be included in every call.
  • debug – Optional parameter that instructs the API to return the text of the JSON blob in a more human-readable format.
  • callback – If you include this parameter the response will use the JSONP format with the specified callback function name.

All strings must be URL-encoded, and the parameters follow the normal format of URL query strings.

The Response. Every response is a JSON blob. JSON is a simple data-interchange format with basic support for numbers, strings, hashes (also called objects, dictionaries, structs, etc.) and arrays. It also supports the values true, false and null. The API always responds with a single hash. The contents of the hash are particular to each function call, as described below. However there are some common conventions:

  • Search results will always be an array of matches named "results".
  • If a property is null or false it may be absent from the hash.

If there's an error the hash will be empty except for one or two properties. The error property will always be present and will always be true. (If there's no error the property is missing; that is, false). There may also be an error_message property which contains more information about the error. The error_message is not meant to be parsed and the format may change.

  http://api.bandcamp.com/api/band/3/info?key=<key>
  {
    "error": true,
    "error_message": "band_id required"
  }

Some of the calls support batch mode, where you can make multiple requests in a single call. For example, you can get info for several bands in one call by providing a list of band_ids.

  http://api.bandcamp.com/api/band/3/info?key=<key>&band_id=203035041,3463798201

Take a look at the response. Notice that it's two objects, one for each band_id. In the non-batch form of this call you'll get a single object-full of info without the band_id association. Try the call again removing one of the band_id numbers to see the difference. (Notice that the band_ids in the hash are actually strings. This is unfortunately a limitation of JSON.) If a function supports batch mode it'll be indicated in the description below. You should use this whenever you can — it’s faster for you and it keeps our servers from going to the zoo.

URLs. You can append ?action=<xxx> onto the URL of an album or track page, as returned by an API function. The actions are:

  • buy or download – Display the digital item’s Purchase dialog.
  • package – Display a package’s Purchase dialog. The package number is specified by the param no=<n>, starting with 0. (Note: I know that there’s no API for getting info on an album’s packages. That’s coming.)

For example:

  http://sufjanstevens.bandcamp.com/album/enjoy-your-rabbit?action=buy

Band module

version 3

search

Searches for bands by name. The names must match exactly, except that case is ignored.

You can search for more than one name at a time by separating the URL-encoded names with commas. See the second example below. There’s a limit of 12 names in a single request.

URL

http://api.bandcamp.com/api/band/3/search

Examples

Parameters

  • name – one or more band names to search for, comma separated. There is currently a maximum of 12 names at a time.

Response

  • results – array of matching bands. Each item in the array is the same info hash you get with the info call.

discography

Returns a band’s discography. This is the “top level” discography, meaning all of the band’s albums and tracks that aren’t on an album. To get an album’s tracks you use the album/info function.

This call can be used in batch mode, where you can specify multiple band ids separated by commas. All the discographies for the bands are fetched in one call and returned to you in a hash, mapping the band ids to individual discography blobs. Click on the examples to see what this looks like.

URL

http://api.bandcamp.com/api/band/3/discography

Examples

Parameters

  • band_id – the numeric id of the band, or a list of band ids for batch mode.

Response

For a single band id the response is a single discography item. For batch mode, the response is a hash mapping the requested band ids to their discographies.

  • discography – array of albums and tracks. The info for each item is the same as what you get with the info functions (below), except there won’t be credits, about text or the array of tracks for albums. The intention is that you’d use this function to populate a playlist picker, and then make an additional band or track info call when an item is selected. You can tell if an item’s a track or an album by the existence of a track_id or album_id property.

info

Returns information about a band.

This call can be used in batch mode, where you can specify multiple band ids separated by commas. The info for all the bands is fetched in one call and returned to you in a hash, mapping the band ids to individual info blobs. Click on the examples to see what this looks like.

URL

http://api.bandcamp.com/api/band/3/info

Examples

Parameters

  • band_id – the numeric id of the band, or a list of band ids for batch mode.

Response

For a single band id the response is a hash with the following items. For batch mode, the response is a hash mapping the requested band ids to their blobs of info.

  • band_id – the numeric id of the band.
  • name – the band’s name. This may not be unique, especially if the band is shy about their name.
  • subdomain – the band’s subdomain. This will be unique across all the bands.
  • url – the band’s home page.
  • offsite_url – the band’s alternate home page, not on Bandcamp.

Album module

version 2

info

Returns information about an album.

URL

http://api.bandcamp.com/api/album/2/info

Examples

Parameters

  • album_id – the numeric id of the album you want info about.

Response

  • title – the album’s title.
  • release_date – the album’s release date, expressed as an integer of epoch seconds.
  • downloadable – 1 if the album is free, 2 if paid.
  • url – the album’s URL.
  • tracks – array of tracks, the info for each track is the same as you get from the track/info function.
  • about – the album’s “about” text, if any.
  • credits – the album’s credits, if any.
  • small_art_url – URL to the album’s cover art, 100×100, if any.
  • large_art_url – 350×350.
  • artist – the album’s artist, if different than the band’s name.
  • album_id – the album’s numeric id.
  • band_id – the band’s numeric id.

Track module

version 3

info

Returns information about one or more tracks.

This call can be used in batch mode, where you can specify multiple track ids separated by commas. The info for all the tracks is fetched in one call and returned to you in a hash, mapping the track ids to individual info blobs. Click on the examples to see what this looks like.

URL

http://api.bandcamp.com/api/track/3/info

Examples

Parameters

  • track_id – the numeric id of the track, or a list of track ids for batch mode.

Response

  • title – the track’s title.
  • number – the track number on the album.
  • duration – the track’s duration, in seconds (float).
  • release_date – the track’s release date if it’s different than the album’s release date, expressed as an integer of epoch seconds.
  • downloadable – 1 if the track is free, 2 if paid.
  • url – the relative URL of the track. Note that this is relative, as opposed to the album info URL that’s absolute. This is a bug and will be fixed in future versions.
  • streaming_url – the URL to the track’s mp3-128 audio.
  • lyrics – the track’s lyrics, if any.
  • about – the track’s “about” text, if any.
  • credits – the track’s credits, if any.
  • small_art_url – URL to the track’s art, 100×100, only present if it’s different than the album’s cover art.
  • large_art_url – 350×350.
  • artist – the track’s artist, if different than the album’s artist.
  • track_id – the track’s numeric id.
  • album_id – the album’s numeric id.
  • band_id – the band’s numeric id.

URL module

version 1

info

Resolves a Bandcamp URL to its band, album or track.

URL

http://api.bandcamp.com/api/url/1/info

Examples

Parameters

  • url – the Bandcamp URL of a band, album or track that you want to resolve. The scheme (“http://”) is optional. It must be URL encoded.

Response

  • band_id – the band’s numeric id.
  • album_id – the album’s numeric id.
  • track_id – the track’s numeric id.