Radio Channels API

The Radio Channels API provides access to radio stations, trends, charts, and recommendations.

Radio Resource Object

Standard radio channel object structure used in responses:

{
  "id": 1,
  "name": "Radio One",
  "slug": "radio-one",
  "description": "The best hits 24/7",
  "stream_url": "https://stream.example.com/stream.mp3",
  "logo": "https://example.com/storage/logos/radio1.png",
  "country": {
    "id": 10,
    "name": "United States",
    "code": "US"
  },
  "language": "en",
  "bitrate": 128,
  "format": "mp3",
  "is_featured": true,
  "play_count": 15420,
  "likes": 342,
  "genres": [
    { "id": 1, "name": "Pop" },
    { "id": 2, "name": "Top 40" }
  ],
  "social_links": {
    "website": "https://radioone.com",
    "facebook": "https://facebook.com/radioone",
    "twitter": null,
    "instagram": null
  },
  "is_liked": false,
  "is_favorited": false,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-05T14:30:00Z"
}

List All Radios

Get a paginated list of active radio channels.

Endpoint: GET /api/v1/radios Authentication: Required

Query Parameters

Parameter	Type	Description
`search`	string	Search by name or description
`country_id`	integer	Filter by country ID
`language`	string	Filter by language code (e.g., 'en')

Response

{
  "success": true,
  "message": "Radio channels retrieved successfully",
  "data": [
    { ...RadioResource },
    { ...RadioResource }
  ]
}

Get Radio Details

Get details for a specific radio channel.

Endpoint: GET /api/v1/radios/{channel_id} Authentication: Required

Response

{
  "success": true,
  "message": "Radio channel retrieved successfully",
  "data": { ...RadioResource }
}

Featured Channels

Get a list of featured radio stations.

Endpoint: GET /api/v1/radios/featured Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`limit`	int	10	Number of stations (max 50)

Trending Channels

Get currently trending stations based on recent activity.

Endpoint: GET /api/v1/radios/trending Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`hours`	int	24	Lookback period in hours (max 168)
`limit`	int	20	Number of stations (max 100)

Charts

Get top performing stations by metric.

Endpoint: GET /api/v1/radios/charts Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`metric`	string	plays	Sort metric ('plays' or 'likes')
`period`	string	7d	Time period ('24h', '7d', '30d')
`limit`	int	50	Number of stations

User's Liked Stations

Get stations liked by the authenticated user.

Endpoint: GET /api/v1/radios/liked Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`limit`	int	20	Number of stations

User's Recent Stations

Get stations recently played by the user.

Endpoint: GET /api/v1/me/radios/recent Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`limit`	int	10	Number of stations

User's Top Stations

Get stations most played by the user.

Endpoint: GET /api/v1/me/radios/top Authentication: Required

Query Parameters

Parameter	Type	Default	Description
`limit`	int	10	Number of stations

Recommendations

Get personalized station recommendations.

Endpoint: GET /api/v1/me/radios/recommended Authentication: Required

Discover

Get a curated list of stations for discovery.

Endpoint: GET /api/v1/me/radios/discover Authentication: Required

Actions

Track Play

Record a play event for analytics.

Endpoint: POST /api/v1/radios/{channel_id}/play Authentication: Required

Response:

{
  "success": true,
  "message": "Play tracked successfully",
  "data": null
}

Toggle Like

Like or unlike a radio station.

Endpoint: POST /api/v1/radios/{channel_id}/like Authentication: Required

Response:

{
  "success": true,
  "message": "Channel liked",
  "data": {
    "is_liked": true,
    "likes_count": 343
  }
}

Check Playlists

Check which of the user's playlists contain this station.

Endpoint: GET /api/v1/radios/{channel_id}/playlists Authentication: Required

Response:

{
  "success": true,
  "message": "Playlist status retrieved successfully",
  "data": {
    "is_in_playlist": true,
    "playlist_count": 2,
    "playlists": [
      { "id": 5, "name": "My Favorites", "is_public": true },
      { "id": 8, "name": "Morning Vibes", "is_public": false }
    ]
  }
}

Authentication Genres