Skip to content

Instantly share code, notes, and snippets.

@brainix

brainix/spool.tv-api.md

Last active August 29, 2015 14:11
Show Gist options
  • Save brainix/7e794eead28f9576639b to your computer and use it in GitHub Desktop.
Save brainix/7e794eead28f9576639b to your computer and use it in GitHub Desktop.
Download ZIP
The spool.tv Public REST API
Raw
spool.tv-api.md

Public REST API

Overview

spool.tv is a music video preview website. We aggregate a lot of data about songs, artists, and music genres. If you build anything with our API, we’d love to hear about it! Or if you need some help, please contact us: [email protected] Happy hacking!

Paths

We identify songs, artists, and genres by paths. Paths are lowercased, hyphenated, unique identifiers that correspond to the names of songs, artists, and genres. If you’d like to query for a song, artist, or genre and you don’t know its path, your best bet is to use our search API endpoint. In the search result, you’ll find the song path as path, the artist path as artist_path, and the genre path as genre_path.

Metrics (popularity and freshness)

We score each music video preview according to how popular it is cumulatively (popularity), and how trending it is today (freshness). Lastly, we normalize these scores on a scale of 1-7.

Public API endpoints

  1. GET songs/random
  2. GET songs/:artist/:song
  3. GET songs/top
  4. GET songs/search
  5. GET songs/suggest
  6. GET artists/:path/top
  7. GET artists/top
  8. GET artists/suggest
  9. GET genres/:path/top
  10. GET genres/top
  11. GET genres/suggest

GET songs/random

Returns a list of 60 random songs.

Resource URL

http://spool.tv/api/v1.0/songs/random.json

Parameters

Name Description
metric (optional) How to weight the songs, either popularity or freshness. If you omit this parameter, then we assume freshness.

Example request

GET http://spool.tv/api/v1.0/songs/random.json?metric=freshness

Example result

{
  "songs": [
    {
      "artist_name": "Big K.R.I.T.",
      "artist_path": "big-krit",
      "artwork_url": "http://a1906.phobos.apple.com/us/r30/Video5/v4/46/a8/8b/46a88b05-3f5e-a5c9-a422-8aa5ea4c7f8d/vidtrkimg_00602547052056_1_1.133x100-99.jpg",
      "genre_name": "Hip Hop/Rap",
      "genre_path": "hip-hoprap",
      "itunes_url": "https://itunes.apple.com/us/music-video/pay-attention-feat.-rico-love/id928148513?uo=2",
      "name": "Pay Attention (feat. Rico Love)",
      "path": "pay-attention-feat-rico-love",
      "preview_url": "http://a1717.v.phobos.apple.com/us/r30/Video3/v4/5e/df/20/5edf2099-aa75-2fc2-d18e-9d340954fced/mzvf_4614002185302274105.640x398.h264lc.U.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=ik_h_J7YFHk&feature=youtube_gdata_player"
    },
    {
      "artist_name": "Tim McGraw",
      "artist_path": "tim-mcgraw",
      "artwork_url": "http://a1075.phobos.apple.com/us/r30/Video3/v4/4d/93/53/4d9353b8-e8e8-a82b-d4ab-da956b405ab2/vidtrkimg_00843930010332_1_1.133x100-99.jpg",
      "genre_name": "Country",
      "genre_path": "country",
      "itunes_url": "https://itunes.apple.com/us/music-video/southern-girl/id676021395?uo=2",
      "name": "Southern Girl",
      "path": "southern-girl",
      "preview_url": "http://a1202.v.phobos.apple.com/us/r1000/032/Video4/v4/2e/97/4f/2e974f96-70cf-cc5c-8ff3-0dda5f3ff313/mzvf_9087230785766576592.640x352.h264lc.U.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=bFClhxM7LY4&feature=youtube_gdata_player"
    },

// 57 songs omitted...

    {
      "artist_name": "Elvis Presley",
      "artist_path": "elvis-presley",
      "artwork_url": "http://a644.phobos.apple.com/us/r30/Video/88/a9/2f/mzi.ntiakrye.133x100-99.jpg",
      "genre_name": "Rock",
      "genre_path": "rock",
      "itunes_url": "https://itunes.apple.com/us/music-video/love-me-ed-sullivan-show-live/id440343660?uo=2",
      "name": "Love Me (Ed Sullivan Show Live 1956)",
      "path": "love-me-ed-sullivan-show-live-1956",
      "preview_url": "http://a1060.v.phobos.apple.com/us/r1000/012/Video/09/d0/ed/mzi.zfrnjbtx..640x464.h264lc.u.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=NwWJXzobSp8&feature=youtube_gdata_player"
    }
  ]
}

GET songs/:artist/:song

Returns the song corresponding to the given artist name and song title.

Resource URL

http://spool.tv/api/v1.0/songs/:artist/:song.json

Parameters

Name Description
artist (required) The artist name. Must be a path.
song (required) The song title. Must be a path.

Example request

GET http://spool.tv/api/v1.0/songs/weezer/buddy-holly.json

Example result

{
  "song": {
    "artist_itunes_url": "https://itunes.apple.com/us/artist/weezer/id115234?uo=2",
    "artist_name": "Weezer",
    "artist_path": "weezer",
    "artwork_url": "http://a194.phobos.apple.com/us/r30/Video/d7/7f/67/mzi.bfhabttq.133x100-99.jpg",
    "blacklisted": false,
    "freshness": 3.65914546327412,
    "genre_itunes_url": "https://itunes.apple.com/us/genre/music-videos-rock/id1621?uo=2",
    "genre_name": "Rock",
    "genre_path": "rock",
    "id": 76845,
    "itunes_url": "https://itunes.apple.com/us/music-video/buddy-holly/id272450585?uo=2",
    "name": "Buddy Holly",
    "path": "buddy-holly",
    "popularity": 4.02592414786366,
    "preview_url": "http://a477.v.phobos.apple.com/us/r1000/044/Video/f6/f9/64/mzm.njrbodrr..640x464.h264lc.u.p.m4v",
    "song_suggest": {
      "input": "Buddy Holly",
      "payload": {
        "artist_path": "weezer",
        "path": "buddy-holly"
      },
      "weight": 4
    },
    "youtube_url": "https://www.youtube.com/watch?v=kemivUKb4f4&feature=youtube_gdata_player"
  }
}

GET songs/top

Returns a list of the top 7 songs.

Resource URL

http://spool.tv/api/v1.0/songs/top.json

Parameters

Name Description
metric (optional) How to rank the songs, either popularity or freshness. If you omit this parameter, then we assume freshness.

Example request

GET http://spool.tv/api/v1.0/songs/top.json?metric=freshness

Example result

{
  "songs": [
    {
      "artist_name": "Fabolous",
      "artist_path": "fabolous",
      "artwork_url": "http://a263.phobos.apple.com/us/r30/Video/fa/2f/a1/mzi.yqjrejqe.133x100-99.jpg",
      "genre_name": "Hip Hop/Rap",
      "genre_path": "hip-hoprap",
      "itunes_url": "https://itunes.apple.com/us/music-video/throw-it-in-the-bag-bonus-video/id325098557?uo=2",
      "name": "Throw It In the Bag",
      "path": "throw-it-in-the-bag",
      "preview_url": "http://a1720.v.phobos.apple.com/us/r1000/022/Video/90/b8/3f/mzm.hqztfdec..640x480.h264lc.u.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=zJOeXh6HyvU&feature=youtube_gdata_player"
    },
    {
      "artist_name": "Marvin Gaye",
      "artist_path": "marvin-gaye",
      "artwork_url": "http://a1967.phobos.apple.com/us/r30/Video/49/c6/6e/mzi.cwowudyi.133x100-99.jpg",
      "genre_name": "R&B/Soul",
      "genre_path": "rbsoul",
      "itunes_url": "https://itunes.apple.com/us/music-video/come-get-to-this-the-speek/id446225643?uo=2",
      "name": "Come Get to This (The Speek)",
      "path": "come-get-to-this-the-speek",
      "preview_url": "http://a1808.v.phobos.apple.com/us/r1000/073/Video/f3/d6/49/mzi.ncjkplqr..640x480.h264lc.u.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=ZHL6wiGUymI&feature=youtube_gdata_player"
    },

    // 4 songs omitted...

    {
      "artist_name": "Hellyeah",
      "artist_path": "hellyeah",
      "artwork_url": "http://a1605.phobos.apple.com/us/r30/Video/v4/66/c0/d8/66c0d806-c17d-a6d6-dffd-d29286cf8ed5/8864434816640101VIC.133x100-99.jpg",
      "genre_name": "Rock",
      "genre_path": "rock",
      "itunes_url": "https://itunes.apple.com/us/music-video/band-of-brothers/id525163757?uo=2",
      "name": "Band of Brothers",
      "path": "band-of-brothers",
      "preview_url": "http://a1227.v.phobos.apple.com/us/r1000/069/Video/bd/bd/e8/mzm.bohexjje..640x478.h264lc.u.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=L-PCQ0MwKLQ&feature=youtube_gdata_player"
    }
  ]
}

GET songs/search

Returns a list of (at most 7) songs matching the given search query.

Resource URLs

http://spool.tv/api/v1.0/songs/search.html
http://spool.tv/api/v1.0/songs/search.json

Parameters

Name Description
query (required) Query to search for artist names and/or song names. Must be URL encoded.
metric (optional) How to sort the songs, either popularity or freshness. If you omit this parameter, then we assume freshness.

Example request

GET http://spool.tv/api/v1.0/songs/search.html?query=weezer&metric=freshness

Example result

<li>
<a href='/weezer/back-to-the-shack'
title='Weezer &mdash; Back To the Shack'>
<em>Weezer</em> &mdash; Back To the Shack
</a>
</li>
<li>
<a href='/weezer/island-in-the-sun'
title='Weezer &mdash; Island In the Sun'>
<em>Weezer</em> &mdash; Island In the Sun
</a>
</li>

<!-- 4 search results omitted... -->

<li>
<a href='/weezer/perfect-situation'
title='Weezer &mdash; Perfect Situation'>
<em>Weezer</em> &mdash; Perfect Situation
</a>
</li>

GET songs/suggest

Returns an auto-complete suggestion for a song title matching the given query.

Resource URL

http://spool.tv/api/v1.0/songs/suggest.json

Parameters

Name Description
query (required) Query to search for a song title. Must be URL encoded.

Example request

GET http://spool.tv/api/v1.0/songs/suggest.json?query=bud

Example result

{
  "suggestion": {
    "payload": {
      "artist_path": "weezer",
      "path": "buddy-holly"
    },
    "score": 4.0,
    "text": "Buddy Holly"
  }
}

GET artists/:path/top

Returns a list of the top 7 songs by the given artist.

Resource URL

http://spool.tv/api/v1.0/artists/:path/top.json

Parameters

Name Description
path (required) The artist name. Must be a path.
metric (optional) How to rank the songs, either popularity or freshness. If you omit this parameter, then we assume freshness.

Example request

GET http://spool.tv/api/v1.0/artists/weezer/top.json?metric=freshness

Example result

{
  "songs": [
    {
      "artist_name": "Weezer",
      "artist_path": "weezer",
      "artwork_url": "http://a1626.phobos.apple.com/us/r30/Video5/v4/98/d9/e8/98d9e8e2-60cb-5e58-e766-896b7d5b0037/vidtrkimg_00602547028013_1_1.133x100-99.jpg",
      "genre_name": "Alternative",
      "genre_path": "alternative",
      "itunes_url": "https://itunes.apple.com/us/music-video/back-to-the-shack/id923675317?uo=2",
      "name": "Back To the Shack",
      "path": "back-to-the-shack",
      "preview_url": "http://a242.v.phobos.apple.com/us/r30/Video3/v4/8f/fc/a9/8ffca970-8398-78e3-d6a3-8016c1eb5d1d/mzvf_2050112508586290923.640x472.h264lc.U.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=3H89GXU9OeU&feature=youtube_gdata_player"
    },
    {
      "artist_name": "Weezer",
      "artist_path": "weezer",
      "artwork_url": "http://a1535.phobos.apple.com/us/r30/Music/ec/31/17/mzi.leqfioxz.133x100-99.jpg",
      "genre_name": "Alternative",
      "genre_path": "alternative",
      "itunes_url": "https://itunes.apple.com/us/music-video/island-in-the-sun/id81692983?uo=2",
      "name": "Island In the Sun",
      "path": "island-in-the-sun",
      "preview_url": "http://a590.v.phobos.apple.com/us/r1000/037/Video/6c/d5/6c/mzm.yccrxbux..640x480.h264lc.u.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=HVHUjzZZGQ4&feature=youtube_gdata_player"
    },

    // 4 songs omitted...

    {
      "artist_name": "Weezer",
      "artist_path": "weezer",
      "artwork_url": "http://a565.phobos.apple.com/us/r30/Music/8c/6b/30/mzi.ualsdjan.133x100-99.jpg",
      "genre_name": "Rock",
      "genre_path": "rock",
      "itunes_url": "https://itunes.apple.com/us/music-video/perfect-situation/id129579490?uo=2",
      "name": "Perfect Situation",
      "path": "perfect-situation",
      "preview_url": "http://a1380.v.phobos.apple.com/us/r1000/022/Video/23/78/2c/mzm.dbuuvkuz..640x480.h264lc.u.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=jwv-iRvyDZg&feature=youtube_gdata_player"
    }
  ]
}

GET artists/top

Returns a list of the top 7 artists.

Resource URL

http://spool.tv/api/v1.0/artists/top.json

Parameters

Name Description
metric (optional) How to rank the artists, either popularity or freshness. If you omit this parameter, then we assume freshness.

Example request

GET http://spool.tv/api/v1.0/artists/top.json?metric=freshness

Example result

{
  "artists": [
    {
      "artist_suggest": {
        "input": "Beyonce",
        "payload": {
          "path": "beyonce"
        },
        "weight": 261
      },
      "id": 19,
      "itunes_url": "https://itunes.apple.com/us/artist/beyonce/id1419227?uo=2",
      "name": "Beyonce",
      "path": "beyonce"
    },
    {
      "artist_suggest": {
        "input": "Madonna",
        "payload": {
          "path": "madonna"
        },
        "weight": 116
      },
      "id": 338,
      "itunes_url": "https://itunes.apple.com/us/artist/madonna/id20044?uo=2",
      "name": "Madonna",
      "path": "madonna"
    },

    // 4 artists omitted...

    {
      "artist_suggest": {
        "input": "Taylor Swift",
        "payload": {
          "path": "taylor-swift"
          },
          "weight": 87
          },
          "id": 77,
          "itunes_url": "https://itunes.apple.com/us/artist/taylor-swift/id159260351?uo=2",
          "name": "Taylor Swift",
          "path": "taylor-swift"
    }
  ]
}

GET artists/suggest

Returns an auto-complete suggestion for an artist name matching the given query.

Resource URL

http://spool.tv/api/v1.0/artists/suggest.json

Parameters

Name Description
query (required) Query to search for an artist name. Must be URL encoded.

Example request

GET http://spool.tv/api/v1.0/artists/suggest.json?query=wee

Example result

{
  "suggestion": {
    "payload": {
      "path": "weezer"
    },
    "score": 33.0,
    "text": "Weezer"
  }
}

GET genres/:path/top

Returns a list of the top 7 songs within the given genre.

Resource URL

http://spool.tv/api/v1.0/genres/:path/top.json

Parameters

Name Description
path (required) The genre name. Must be a path.
metric (optional) How to rank the songs, either popularity or freshness. If you omit this parameter, then we assume freshness.

Example request

GET http://spool.tv/api/v1.0/genres/alternative/top.json?metric=freshness

Example result

{
  "songs": [
    {
      "artist_name": "WALK THE MOON",
      "artist_path": "walk-the-moon",
      "artwork_url": "http://a994.phobos.apple.com/us/r30/Video3/v4/78/d0/19/78d0197d-c20d-9c0f-7d25-60a3d01de30c/8864448024060101VIC.133x100-99.jpg",
      "genre_name": "Alternative",
      "genre_path": "alternative",
      "itunes_url": "https://itunes.apple.com/us/music-video/shut-up-and-dance/id934224631?uo=2",
      "name": "Shut Up and Dance",
      "path": "shut-up-and-dance",
      "preview_url": "http://a550.v.phobos.apple.com/us/r1000/128/Video6/v4/01/33/30/013330fa-ad24-0788-8959-40996555e0d6/mzvf_4831564341052130736.640x318.h264lc.U.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=6JCLY0Rlx6Q&feature=youtube_gdata_player"
    },
    {
      "artist_name": "Azealia Banks",
      "artist_path": "azealia-banks",
      "artwork_url": "http://a1679.phobos.apple.com/us/r30/Video3/v4/9c/ae/03/9cae03c1-159f-bfc6-7d90-168af729ffd3/vidtrkimg_00813985012452_1_1.133x100-99.jpg",
      "genre_name": "Alternative",
      "genre_path": "alternative",
      "itunes_url": "https://itunes.apple.com/us/music-video/chasing-time/id943262340?uo=2",
      "name": "Chasing Time",
      "path": "chasing-time",
      "preview_url": "http://a239.v.phobos.apple.com/us/r1000/031/Video3/v4/04/8f/7d/048f7de9-d7d5-8144-f81a-edcbe751dd57/mzvf_1982185446981474121.640x472.h264lc.U.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=jtTjzDTpx8o&feature=youtube_gdata_player"
    },

// 4 songs omitted...

    {
      "artist_name": "Radiohead",
      "artist_path": "radiohead",
      "artwork_url": "http://a1519.phobos.apple.com/us/r30/Video/44/21/37/mzi.elxvkejz.133x100-99.jpg",
      "genre_name": "Alternative",
      "genre_path": "alternative",
      "itunes_url": "https://itunes.apple.com/us/music-video/bloom-live/id483049208?uo=2",
      "name": "Bloom",
      "path": "bloom",
      "preview_url": "http://a892.v.phobos.apple.com/us/r30/Video/97/65/9c/mzm.eccrwoqw..640x480.h264lc.u.p.m4v",
      "youtube_url": "https://www.youtube.com/watch?v=JHjUI7OqEWc&feature=youtube_gdata_player"
    }
  ]
}

GET genres/top

Returns a list of the top 7 genres.

Resource URL

http://spool.tv/api/v1.0/genres/top.json

Parameters

Name Description
metric (optional) How to rank the genres, either popularity or freshness. If you omit this parameter, then we assume freshness.

Example request

GET http://spool.tv/api/v1.0/genres/top.json?metric=freshness

Example result

{
  "genres": [
    {
      "genre_suggest": {
        "input": "Rock",
        "payload": {
          "path": "rock"
        },
        "weight": 6224
      },
      "id": 8,
      "itunes_url": "https://itunes.apple.com/us/genre/music-videos-rock/id1621?uo=2",
      "name": "Rock",
      "path": "rock"
    },
    {
      "genre_suggest": {
        "input": "Pop",
        "payload": {
          "path": "pop"
        },
        "weight": 5236
      },
      "id": 2,
      "itunes_url": "https://itunes.apple.com/us/genre/music-videos-pop/id1614?uo=2",
      "name": "Pop",
      "path": "pop"
    },

    // 4 genres omitted...

    {
      "genre_suggest": {
        "input": "Country",
        "payload": {
          "path": "country"
        },
        "weight": 1016
      },
      "id": 4,
      "itunes_url": "https://itunes.apple.com/us/genre/music-videos-country/id1606?uo=2",
      "name": "Country",
      "path": "country"
    }
  ]
}

GET genres/suggest

Returns an auto-complete suggestion for a genre name matching the given query.

Resource URL

http://spool.tv/api/v1.0/genres/suggest.json

Parameters

Name Description
query (required) Query to search for a genre name. Must be URL encoded.

Example request

GET http://spool.tv/api/v1.0/genres/suggest.json?query=a

Example result

{
  "suggestion": {
    "payload": {
      "path": "alternative"
    },
    "score": 3203.0,
    "text": "Alternative"
  }
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment