Niland Logo Niland API

Radios

Overview

Endpoints for retrieving, searching and managing radios.

List Radios

Use this endpoint to list all radios.

GET /radios

Input

Name Type Description
page Integer Page number (default 1)
page_size Integer Result number per page (default 20, max 1000)

Example

GET /radios?key=...&page_size=1

Response

For a valid query

Status: 200 OK

For an invalid query

Status: 400 Bad Request

Get a Radio

Use this endpoint to retrieve a specifi radio.

GET /radios/{radio_id}

Example

GET /radios/563b9cb15fb5b184008b4604?key=...

Response

For a valid radio id

Status: 200 OK

For an invalid radio id

Status: 404 Not Found

Create a Radio

Use this endpoint to create a new radio based on tracks and/or tags and/or user.

POST /radios

Input

Name Type Description
seeds Array Array of Niland Track IDs
tags Array Array of Tag IDs
user String User Reference
discovery_rate Integer Percentage of track discovery (between 0 and 100, default 70)

Example

Response

For a valid query

Status: 201 Created OR 200 OK if a radio already exists with those parameters

For an invalid query

Status: 400 Bad Request

Edit a Radio

Use this endpoint to edit a radio.

PATCH /radios/{radio_id}

Input

Name Type Description
seeds Array Array of Niland Track IDs
tags Array Array of Tag IDs
user String User external ID
discovery_rate Integer Percentage of track discovery (between 0 and 100, default 70)

Example

PATCH /radios/56420e1ff799b98527f3109d

Response

For a valid query

Status: 200 OK

For an invalid query

Status: 400 Bad Request

Delete a Radio

Use this endpoint to delete a radio.

DELETE /radios/{radio_id}

Response

For a valid radio id

Status: 204 No Content

For an invalid radio id

Status: 404 Not Found

Get Next Radio Tracks

Use this endpoint to retrieve the next tracks to play.

GET /radios/{radio_id}/next

Response

For a valid radio id which is not yet prepared

This means that the radio is not ready yet. You have to follow the redirect until you get a 200 status.

Status: 302 Redirect

For a valid radio id

Status: 200 OK

For an invalid radio id

Status: 404 Not Found

Notify a Skip

In order to get better results, you should tell us when a user skips a track.

POST /radios/{radio_id}/skips

Input

Notice: One parameter only is required.

Name Type Description
track Integer Niland Track ID
reference String Track Reference

Example

POST /radios/56420e1ff799b98527f3109d/skips

Response

For a valid query

Status: 201 Created

For an invalid query

Status: 400 Bad Request

For an invalid radio id

Status: 404 Not Found

Notify a Like

In order to get better results, you should tell us when a user likes a track.

POST /radios/{radio_id}/likes

Input

Notice: One parameter only is required.

Name Type Description
track Integer Niland Track ID
reference String Track Reference

Example

POST /radios/56420e1ff799b98527f3109d/likes

Response

For a valid query

Status: 201 Created

For an invalid query

Status: 400 Bad Request

For an invalid radio id

Status: 404 Not Found

Notify a Dislike

In order to get better results, you should tell us when a user dislikes a track.

POST /radios/{radio_id}/dislikes

Input

Notice: One parameter only is required.

Name Type Description
track Integer Niland Track ID
reference String Track Reference

Example

POST /radios/56420e1ff799b98527f3109d/dislikes

Response

For a valid query

Status: 201 Created

For an invalid query

Status: 400 Bad Request

For an invalid radio id

Status: 404 Not Found

Notify a Ban

In order to get better results, you should tell us when a user bans a track.

POST /radios/{radio_id}/bans

Input

Notice: One parameter only is required.

Name Type Description
track Integer Niland Track ID
reference String Track Reference

Example

POST /radios/56420e1ff799b98527f3109d/bans

Response

For a valid query

Status: 201 Created

For an invalid query

Status: 400 Bad Request

For an invalid radio id

Status: 404 Not Found

Notify a Favorite

In order to get better results, you should tell us when a user add a track to his favorites.

POST /radios/{radio_id}/favorites

Input

Notice: One parameter only is required.

Name Type Description
track Integer Niland Track ID
reference String Track Reference

Example

POST /radios/56420e1ff799b98527f3109d/favorites

Response

For a valid query

Status: 201 Created

For an invalid query

Status: 400 Bad Request

For an invalid radio id

Status: 404 Not Found

Notify a Not Played Track

In order to get better results, you should tell us when a user has not played a track before get the next tracks.

POST /radios/{radio_id}/notplayeds

Input

Notice: One parameter only is required.

Name Type Description
track Integer Niland Track ID
reference String Track Reference

Example

POST /radios/56420e1ff799b98527f3109d/notplayeds

Response

For a valid query

Status: 201 Created

For an invalid query

Status: 400 Bad Request

For an invalid radio id

Status: 404 Not Found
  • Overview
  • List Radios
  • Get a Radio
  • Create a Radio
  • Edit a Radio
  • Delete a Radio
  • Get Next Radio Tracks
  • Notify a Skip
  • Notify a Like
  • Notify a Dislike
  • Notify a Ban
  • Notify a Favorite
  • Notify a Not Played Track
  • Overview
  • API Reference
    • Suggestions
    • Tracks
    • Tags
    • Users
    • Radios
    • Playlists
  • Tutorials
    • Getting Started
    • Search For Tracks
    • Personalized Radio (soon)

© 2016 Niland