yellowcab/docs/API.md

Yellowcab API

This is the documentation of the APIs you can use for YellowCab.

Embed

The base URL is <base domain>/embed/<service>/<username>.

Parameters	Meaning	Available settings
base-domain	The domain of your instance	yc.tacohitbox.com
services	Service you want to use for YellowCab	last (Last.fm), listenbrainz (ListenBrainz)
username	Your (or anyone's, really) username on the scrobbling site	any

An example for this would be: yc.tacohitbox.com/embed/last/tacohitbox.

Other Parameters

Parameters	Meaning	Available settings
force-theme	Chooses the theme of your widget	dark, light, auto
autorefresh	Autorefreshes widget to keep it up to date	30, 60
js-refresh (not implemented)	Determines how the data on the page is refreshed. 0 for HTML only, 1 to refresh the data via calling the API with JS.	0, 1

Examples

An auto-refreshing (30 seconds, via HTML) dark mode widget for tacohitbox on Last.fm An auto-refreshing (60 seconds, via JS) widget for hazysu on Last.fm

JSON

The base URL is <base domain>/api/<service>/<username>.

Parameters	Meaning	Available settings
base-domain	The domain of your instance	yc.tacohitbox.com
services	Service you want to use for YellowCab	last (Last.fm), listenbrainz (ListenBrainz)
username	Your (or anyone's, really) username on the scrobbling site	any

Examples

A call for "tacohitbox" on Last.fm

Response Example

This is what a successful response looks like

{
	"success": true,
	"response": {
		"scrobbler": {
			"name": "Last.fm",
			"user_url": "https://www.last.fm/user/tacohitbox/"
		},
		"cover": "https://lastfm.freetls.fastly.net/i/u/200s/94b19046bd55a54b1387d6bae2ea1e04.jpg",
		"track": {
			"name": "Late Bloomer",
			"url": "https://www.last.fm/music/GoldFlame/_/Late+Bloomer",
			"stream": "https://www.youtube.com/watch?v=Blr1_pJTdPo"
		},
		"artist": {
			"url": "https://www.last.fm/music/GoldFlame",
			"name": "GoldFlame"
		},
		"album": {
			"url": "https://www.last.fm/music/GoldFlame/Late+Bloomer",
			"name": "Late Bloomer"
		},
		"est-timestamp": "live",
		"timestamp": 1643079697000
	}
}