michaelherger/bandcamp-api

My attempt at documenting the un-documented bandcamp.com web API.

bandcamp-api's Issues

Link to old Bandcamp API documentation

Feel free to close this issue without changes if wanted, but I thought it might be nice to have a link to the old bandcamp documentation page as of the final archive:
https://web.archive.org/web/20160512171900/http://bandcamp.com:80/developer

API for searching collection /api/fancollection/1/search_items

Playing around with chrome inspect on the fan page I found the search box accesses a nice API:
POST JSON to /api/fancollection/1/search_items
request JSON:

{
  "fan_id": 1234,
  "search_key": "test",
  "search_type": "collection"
}

Response JSON:

{
  "gifts": [],
  "tralbums": [],
  "redownload_urls": {},
  "search_key": "test",
  "item_lookup": {},
  "similar_gift_ids": {},
  "track_list": []
}

More information for following_bands

Bandcamp-API/data/bandcamp.yaml

Lines 194 to 203 in 7c30cfc

	/api/fancollection/1/following_bands:
	post:
	summary: Get the bands a user is following
	tags:
	- Fan Collection
	requestBody:
	$ref: '#/components/requestBodies/FanCollectionBody'
	responses:
	'200':
	$ref: '#/components/responses/FanCollection'

The body of the request POST looks the same:

{
  "fan_id": 1234,
  "older_than_token": "1387353233:2721882214",
  "count": 3
}

Except the "older_than_token" field is very different, this time having two fields ##:##:

            "date_followed": "18 Dec 2013 07:53:53 GMT",
            "band_id": 2721882214,
            "token": "1387353233:2721882214",

Again the first field is a timestamp, and the second is an id, but this time there is no type or index variable.

Starting fields can be found from <div id="pagedata" data-blob="{JSON HERE}"> on your fan page. Inside the JSON look for .item_cache.following_bands. I believe any "token" from there can be used to start a POST request to /api/fancollection/1/following_bands

Additional information on "older_than_token" for item based endpoints

Bandcamp-API/data/bandcamp.yaml

Lines 946 to 954 in 7c30cfc

	older_than_token:
	type: string
	description: >-
	The older_than_token string's structure is still unknown to
	me. It's being used to page through results. The first part of
	it seems to be some kind of timestamp. Starting with the
	current time you'd get the last token of the result set, which
	in turn could be used to fetch more results.
	example: '1504691191:1603563167:a::'

This is merely discoveries from analysis of API responses on my own collection.
The older_than_token is broken up into 5 parts separated by :
Example partial response from api/fancollection/1/collection_items {"items": [{:

            "tralbum_type": "a",
            "purchased": "06 Feb 2017 02:16:28 GMT",
            "tralbum_id": 3314754897,
            "token": "1486347388:3314754897:a:2:",

Here's my understanding of the 5 parts:

1. Unix epoch timestamp of when fan "purchased" this item.
2. "tralbum_id" of the item in question
3. "trablum_type" of the item in question
4. Monotonically increasing index of items past initial set on users fan page (index can jump values)
5. ?Unused?

Specifically related to api/fancollection/1/collection_items:

1. The timestamp and id are not necessary and can be left blank ::...
2. The tralbum_type is required to not be empty, but any value is fine ::foo:...
3. The index value is the only important part for this handler
   3.1. Any index value that is not a positive whole number is ignored and treated as an empty value, aka start at the first value you can give. (::foo:: or ::foo:bar: says start with the first item, ::foo:50: says start with the 51st item)
   3.2. This unfortunately means you can't get the extended information about the initial 45 items set on the users fan page (apart from something like automating swapping the first and section 45 item chunks)