API Guide - laughly/external-docs GitHub Wiki

Introduction

This is a detailed guide on using the Laughly API. Everything you need to know.
Response formats are detailed at the end by example.
Questions or comments can be directed to [email protected].

Domain name

The API server is located at laughly.herokuapp.com.

General Rules

  • Unique users need to be signed into Laughly with unique accounts. Don't use one Laughly account for everyone on your service. You will be rate-limited, and radios won't function properly.
  • Content (artists, albums, and tracks) marked with radio_only: true cannot be played on-demand. You can choose to not display these to the user at all, or you can display them and offer to launch the associated artist radio when the user tries to select them (see Radio section below).
  • All POST request data should be URL-encoded

Sign-Up / Sign-In

  • POST /auth/signup
    • Required parameters: email, password (must be at least 6 chars), gender ('m' or 'f'), birthday (e.g. '1996')
    • Example: curl -XPOST https://laughly.herokuapp.com/auth/signup -d '[email protected]&password=pass1923&gender=m&birthday=1996'
  • POST /auth/signin
    • Parameters: email, password
  • This will result in an account ID and an access token. The token only expires if unused for ~60 days straight.
  • If the client's token expires, use POST /auth/signin again to obtain a new one.
  • All subsequent API requests should include the header Authorization: account_id+access_token (a literal '+' character between them).

Content Lists

  • GET /api/trending/artists => array of artists
  • GET /api/trending/albums => array of albums
  • GET /api/trending/tracks => array of tracks
  • GET /api/latest/albums => array of albums
  • These endpoints are paginated. Use query params page and results_per_page as needed.
  • GET /api/radios => array of radios
    • Gets a listing of all our radios. Genre radios will be marked with is_genre: true.

Search for Content

Multi-Result Searches

  • GET /api/search/artists => multi-search response
  • GET /api/search/albums => multi-search response
  • GET /api/search/tracks => multi-search response
  • GET /api/search/radios => multi-search response
  • These require param query.
  • These are paginated. Use query params page and results_per_page as needed.

Top-Result Searches

  • These are useful for voice interfaces, where the user cannot visually scan multiple results.
  • GET /api/search/top/artist => top-search response
  • GET /api/search/top/album => top-search response
  • GET /api/search/top/radio => top-search response
  • GET /api/search/top/any => top-search response
    • The result could be an artist, an album, or a radio. Note: never a track.
  • These require param query.
  • Response object will have result_id, result_type, result_name, and result_data.
  • result_data has artist, album, or radio. Artists and albums will have tracks field populated.
  • If a search yielded no results, the result_id will be the empty string.

Single-Item Metadata

  • GET /api/artist/:artist_id => artist
    • Includes the artist's albums and their tracks.
  • GET /api/album/:album_id => album
    • Includes the album's tracks.
  • GET /api/track/:track_id => track
  • GET /api/radio/:radio_id => radio

Full Inventory

  • Use GET /api/client-cache to download JSON of our entire inventory of artists, albums, and tracks. (<10 megabytes).

On-Demand Streaming

  • Use GET /api/stream/:track_id at the time of playback.
    • This returns a track object that includes a signed stream_url.

Radio Streaming

  • GET /api/radio/:radio_id/next-track => track
    • Gets the next track for radio :radio_id.
    • Includes a signed stream_url.
    • The user is only allowed to skip a track when next_skip (RFC 3339 timestamp) is earlier than the current time.
  • Special radios:
    • Popular (id=F8gJpDmNol)
    • Trending (id=trending)
    • My Radio (id=me)
    • Surprise Me (id=the_universe)
    • Artist radios: For any artist, you can use his/her ID as a radio ID.
  • When listening to a radio, the user cannot go back, nor seek within a track. The user is only allowed to skip a track when next_skip property of the /next-track response (RFC 3339 timetsamp) is earlier than the current time.

Response Formats

Response bodies are always JSON, formatted like so:

{
  "header": {
    "status": 200,
    "message": "OK"
  },
  "body": <Results>
}

The following are examples of the Results objects.

Sign-in Response

{
    "token": {
        "account_id": "lFGwtuHZet",
        "access_token": "cCGbp6zWifawdgEPoWXYEWFSsxL2da",
        "created_at": "2017-05-12T18:28:10.141576925-07:00"
    }
}

Artist

{
    "id": "KQuWjoBBVk", 
    "disabled": false, 
    "name": "Louis CK", 
    "bio": "Louis Sz\u00e9kely (born September 12, 1967),known professionally as Louis C.K., is an American comedian, actor, writer, producer, director, and editor. He is the creator, star, writer, director, executive producer, and primary editor of the acclaimed FX comedy-drama series Louie. He is known for his use of observational, self-deprecating, dark and vulgar humor in his stand-up career.", 
    "spouse": "Alix Bailey", 
    "birthday": "9/12/2017", 
    "birthyear": "1967", 
    "birthplace": "Washington, District of Columbia, USA", 
    "height": "\n6' (1.83 m)    ", 
    "links": [
        "http://www.louisck.net/"
    ], 
    "tags": [
        "Louis", 
        "CK"
    ], 
    "profile_image_url": "artist-images/LouisCK3_sq.png", 
    "stats": {
        "total_tracks": 96, 
        "explicit_tracks": 96, 
        "radio_only_tracks": 85, 
        "total_duration": "05:17:50", 
        "total_albums": 5
    }, 
    "user_rating": {
        "num_ratings": 0, 
        "average": 0, 
        "local": 0, 
        "rated": false
    }, 
    "favorite": false, 
    "gallery_images": [
        "http://s3-us-west-2.amazonaws.com/laughly-backend-assets/artist-gallery-images/Artist-Gallery-KQuWjoBBVk-53LFI.png", 
        "http://s3-us-west-2.amazonaws.com/laughly-backend-assets/artist-gallery-images/Artist-Gallery-KQuWjoBBVk-XYR6w.png", 
        "http://s3-us-west-2.amazonaws.com/laughly-backend-assets/artist-gallery-images/Artist-Gallery-KQuWjoBBVk-ybeCU.png"
    ], 
    "slug": "Louis-CK", 
    "radios": [
        {
            "id": "4Mutug4JQ5", 
            "name": "Drinking", 
            "image_url": "images/jigawidwdafg.jpg", 
            "group_id": "kKgot1BubR", 
            "trending_score": 0
        }, 
        {
            "id": "5hAjkOHCUN", 
            "name": "Marriage Misery", 
            "image_url": "images/dwjifjwdgfwd.jpg", 
            "group_id": "kKgot1BubR", 
            "trending_score": 0
        }, 
        {
            "id": "dating", 
            "name": "Dating Woes", 
            "image_url": "images/dghaiwjdiakwf.jpg", 
            "group_id": "kKgot1BubR", 
            "trending_score": 0
        },
    ], 
    "last_updated": "2017-04-12T16:41:23.849-07:00", 
    "main_genre": "", 
    "quality": 3, 
    "facebook": "https://www.facebook.com/LouisCKSzekely/", 
    "twitter": "https://twitter.com/louiefx", 
    "twitter_widget_id": "859188963411607552", 
    "instagram": "https://www.instagram.com/louisckofficial/?hl=en", 
    "official_website": "", 
    "playtime": 21436604, 
    "play_count": 54930, 
    "fav_count": 1393, 
    "trending_score": 49667.996791198995, 
    "radio_trending_score": 32979.26253241082, 
    "share_count": 2, 
    "comment_count": 0, 
    "radio_only": false, 
    "city": "", 
    "state": "", 
    "country": "", 
}

Album

{
    "id": "bkIcxdtbYo",
    "disabled": false,
    "name": "If These Balls Could Talk",
    "details": "",
    "artist": {
        "id": "cHgdevVuqY",
        "name": "Louis Katz",
        "profile_image_url": "artist-images/AI-cHgdevVuqY-fXbFL.png"
    },
    "other_artists": null,
    "release_date": "20110307",
    "release_date_formatted": "March 2011",
    "record_label": "cc_records",
    "created_at": "2016-08-10T05:29:57.818-07:00",
    "updated_at": "2017-04-12T16:41:41.01-07:00",
    "image_url": "album-images/bkIcxdtbYo-3x.jpg",
    "stats": {
        "total_tracks": 25,
        "explicit_tracks": 25,
        "radio_only_tracks": 0,
        "total_duration": "49:57"
    },
    "explicit": true,
    "user_rating": {
        "num_ratings": 0,
        "average": 0,
        "local": 0,
        "rated": false
    },
    "favorite": false,
    "exclusive": false,
    "radio_only": false,
    "playtime": 240129,
    "play_count": 1540,
    "fav_count": 9,
    "trending_score": 8374.8,
    "share_count": 4,
    "comment_count": 0,
}

Track

{
    "id": "C4CPscNI9R",
    "disabled": false,
    "name": "Louisanna Liplock",
    "uploaded": "2016-04-29T05:22:20.11-07:00",
    "artist_id": "VEbi5NWc0k",
    "album_id": "BBjF4SrBQH",
    "album": {
        "id": "BBjF4SrBQH",
        "name": "Root Hog Or Die",
        "image_url": "album-images/BBjF4SrBQH-3x.jpg",
        "record_label": "IRS Records"
    },
    "track_number": 1,
    "artist": {
        "id": "VEbi5NWc0k",
        "name": "Mojo Nixon",
        "profile_image_url": "artist-images/AI-VEbi5NWc0k-0di4U.png"
    },
    "length": "04:19",
    "favorite": false,
    "user_rating": {
        "num_ratings": 0,
        "average": 0,
        "local": 0,
        "rated": false
    },
    "tags": [],
    "explicit": false,
    "radio_only": true,
    "stream_url": "https://d385ommf0irwco.cloudfront.net/tracks/track-C4CPscNI9R.mp3?Expires=1494414973&Signature=LvyOOd4n0oIu9iJ62Xpte5uBw1OWlLYrN2iXp-1QyrGV5Sw9Yan3uMM30pH38eH2WkvjohQQPBnzYyq~iBMqL5AJKLex-1PgFkY4VUWs7iu2Yc1MquLnzfH42d3LSVq43vlFgwBFgCXaCKx4VDTTXd-HIO8y80gGzW5oZY9Jf931p2h2R389~GiPNIbauHrtXSeZf1y5oDe3ByaSqwmAniCS5Ejl1EdNDg47WnYMd8PpEOWmTPNi5RMdEZquJKfAoCBcbXL3UKgZxmIxi5yWPInZrjhPovGoCSIYl-uopUcnz4CatcQQx7UaNWMEJOL97L13hp1p3kmCyt9LdxdpDw__&Key-Pair-Id=APKAIVOFBCOWP3DR45DA",
    "next_skip": "0001-01-01T00:00:00Z",
    "isrc": "",
    "thumbs_up": false,
    "thumbs_down": false,
    "playtime": 0,
    "play_count": 0,
    "fav_count": 0,
    "share_count": 0,
    "comment_count": 0
}

Radio

{
    "id": "43390vgiEs", 
    "name": "Urban", 
    "disabled": false, 
    "group_id": "3z4tWnvEw9", 
    "group_name": "By Genre", 
    "tags": [], 
    "stats": {
        "total_tracks": 1613, 
        "explicit_tracks": 1336, 
        "radio_only_tracks": 979, 
        "total_duration": "101:39:41"
    },  
    "description": "Only they can say the N word", 
    "image_url": "genre-images/urban5_sq.jpg", 
    "favorite": false, 
    "trending_score": 0, 
}

Multi-Search

{
    "num_of_pages": 10,
    "current_page": 0,
    "results": [ object1, object2, object3 ]
}

Top-Search Result

{    
    "result_id": "bkIcxdtbYo",
    "result_name": "If These Balls Could Talk",
    "result_type": "album",
    "result_data": <<The album object, including its tracks>>
}
⚠️ **GitHub.com Fallback** ⚠️