yellowcab/docs

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

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

Other Parameters

Parameters	Meaning	Available settings
force-theme	Forces the theme of your widget	dark, lite
autorefresh	Autorefreshes widget to keep it up to date	30, 60
js-refresh	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

Examples

A call for "tacohitbox" on Last.fm

Response Example

This is what a successful call looks like for Last.fm

{
  "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
  }
}

Here's a successful request for Listenbrainz.

{
  "success": true,
  "response": {
    "scrobbler": {
      "name": "ListenBrainz",
      "user_url": "https://listenbrainz.org/user/tacohitbox/"
    },
    "cover": "https://coverartarchive.org/release/5ee8b734-e29a-36d9-9913-3319e21b5444",
    "track": {
      "name": "Fight Test",
      "stream": null,
      "url": "https://musicbrainz.org/recording/1b8e706a-454e-4466-9a8b-75214b5965f7"
    },
    "artist": {
      "name": "The Flaming Lips",
      "url": "https://musicbrainz.org/artist/1f43d76f-8edf-44f6-aaf1-b65f05ad9402"
    },
    "album": {
      "name": "Yoshimi Battles the Pink Robots",
      "url": "https://musicbrainz.org/release/5ee8b734-e29a-36d9-9913-3319e21b5444"
    },
    "est-timestamp": "9 minutes ago",
    "timestamp": 1643079696000
  }
}