393 lines
14 KiB
Plaintext
393 lines
14 KiB
Plaintext
FORMAT: 1A
|
|
HOST: http://localhost:8080/api
|
|
|
|
# AzuraCast
|
|
AzuraCast is a standalone, turnkey web radio management tool. Radio stations hosted by AzuraCast expose a public API for viewing now playing data, making requests and more.
|
|
|
|
## Authenticating
|
|
Some request types require an API key, either to perform administrative steps or avoid public rate-limiting. API keys can be generated from the AzuraCast global administration panel. When making an authenticated request, any of the following methods can be used to supply the key:
|
|
|
|
* The "X-API-Key" HTTP header supplied in the request
|
|
* The "key" parameter supplied via GET or POST (?key=a1b2c3...)
|
|
|
|
## Important Notes
|
|
* Many API calls are cached for performance reasons, and some implement rate-limits to prevent flooding the system. Typically, calls authenticated with an API key have rate limits removed.
|
|
* API signatures may change between software versions. Check the GitHub repository for more information when updating.
|
|
* All timestamps in API calls are supplied as UNIX timestamps, i.e. seconds from 1/1/1970.
|
|
|
|
## Station "Short Codes"
|
|
In lieu of a station ID, some station-related API calls allow for what is called a "shortcode". This is the name of the station, in lower case, with its special characters removed. For example, "My Awesome Radio!" would become "my_awesome_radio".
|
|
|
|
## Song Identifiers
|
|
Most database entries have an auto-incrementing unique identifier, but songs use a hash-based identification system that avoids collisions based on spacing or punctuation differences.
|
|
|
|
# Group Now Playing
|
|
Retrieve "Now Playing" information about active stations.
|
|
|
|
### GET /nowplaying
|
|
Returns all now playing data for active stations.
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: [
|
|
{
|
|
station: {
|
|
id: 1,
|
|
name: "Pony Radio Station",
|
|
shortcode: "pony_radio_station",
|
|
description: "Test",
|
|
frontend: "icecast",
|
|
backend: "liquidsoap",
|
|
listen_url: "http://localhost:8080/radio/8000/radio.mp3?1479695912",
|
|
mounts: [
|
|
{
|
|
name: "/radio.mp3",
|
|
is_default: true,
|
|
url: "http://localhost:8080/radio/8000/radio.mp3?1479695912"
|
|
}
|
|
]
|
|
},
|
|
current_song: {
|
|
id: "178ebfae95842a543f30a449f2420125",
|
|
text: "YourEnigma - On Hold (Feat. Rhyme Flow)",
|
|
artist: "YourEnigma",
|
|
title: "On Hold (Feat. Rhyme Flow)",
|
|
created: 1472973486,
|
|
play_count: 2,
|
|
last_played: 1473192908,
|
|
sh_id: null
|
|
},
|
|
listeners: {
|
|
current: 0,
|
|
unique: 0,
|
|
total: 0
|
|
},
|
|
meta: {
|
|
status: "online",
|
|
bitrate: null,
|
|
format: "audio/mpeg"
|
|
},
|
|
song_history: [
|
|
{
|
|
played_at: 1473192663,
|
|
song: {
|
|
id: "86125d7861a62e19b773a5911b490675",
|
|
text: "PhonyBrony, Feather - I'll Show You My Loyalty (1st Capital Rock Version)",
|
|
artist: "PhonyBrony, Feather",
|
|
title: "I'll Show You My Loyalty (1st Capital Rock Version)",
|
|
created: 1472973505,
|
|
play_count: 2,
|
|
last_played: 1473192663
|
|
}
|
|
},
|
|
{
|
|
played_at: 1473192423,
|
|
song: {
|
|
id: "d631a2196db79ab1e6b5e8e0db69dea4",
|
|
text: "StormWolf - BBBFF (Stormwolf Remix)",
|
|
artist: "StormWolf",
|
|
title: "BBBFF (Stormwolf Remix)",
|
|
created: 1472973497,
|
|
play_count: 3,
|
|
last_played: 1473192423
|
|
}
|
|
}
|
|
],
|
|
cache: "database"
|
|
}
|
|
]
|
|
}
|
|
|
|
### GET /nowplaying/{id}
|
|
**Station Specified by Numeric ID**
|
|
|
|
Returns a single station's now-playing information based on a station identifier.
|
|
|
|
+ Parameters
|
|
+ id (number, required) - The station ID.
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: {
|
|
station: {
|
|
id: 1,
|
|
name: "Pony Radio Station",
|
|
shortcode: "pony_radio_station",
|
|
description: "Test",
|
|
frontend: "icecast",
|
|
backend: "liquidsoap",
|
|
listen_url: "http://localhost:8080/radio/8000/radio.mp3?1479695912",
|
|
mounts: [
|
|
{
|
|
name: "/radio.mp3",
|
|
is_default: true,
|
|
url: "http://localhost:8080/radio/8000/radio.mp3?1479695912"
|
|
}
|
|
]
|
|
},
|
|
current_song: {
|
|
id: "178ebfae95842a543f30a449f2420125",
|
|
text: "YourEnigma - On Hold (Feat. Rhyme Flow)",
|
|
artist: "YourEnigma",
|
|
title: "On Hold (Feat. Rhyme Flow)",
|
|
created: 1472973486,
|
|
play_count: 2,
|
|
last_played: 1473192908,
|
|
sh_id: null
|
|
},
|
|
listeners: {
|
|
current: 0,
|
|
unique: 0,
|
|
total: 0
|
|
},
|
|
meta: {
|
|
status: "online",
|
|
bitrate: null,
|
|
format: "audio/mpeg"
|
|
},
|
|
song_history: [
|
|
{
|
|
played_at: 1473192663,
|
|
song: {
|
|
id: "86125d7861a62e19b773a5911b490675",
|
|
text: "PhonyBrony, Feather - I'll Show You My Loyalty (1st Capital Rock Version)",
|
|
artist: "PhonyBrony, Feather",
|
|
title: "I'll Show You My Loyalty (1st Capital Rock Version)",
|
|
created: 1472973505,
|
|
play_count: 2,
|
|
last_played: 1473192663
|
|
}
|
|
},
|
|
{
|
|
played_at: 1473192423,
|
|
song: {
|
|
id: "d631a2196db79ab1e6b5e8e0db69dea4",
|
|
text: "StormWolf - BBBFF (Stormwolf Remix)",
|
|
artist: "StormWolf",
|
|
title: "BBBFF (Stormwolf Remix)",
|
|
created: 1472973497,
|
|
play_count: 3,
|
|
last_played: 1473192423
|
|
}
|
|
}
|
|
],
|
|
cache: "database"
|
|
}
|
|
}
|
|
|
|
+ Response 400 (application/json)
|
|
|
|
Returned if an invalid station ID is specified.
|
|
|
|
+Body
|
|
|
|
{
|
|
status: "error",
|
|
error: "Station not found."
|
|
}
|
|
|
|
# Group Stations
|
|
Information about the service's hosted radio stations.
|
|
|
|
### GET /stations
|
|
List all stations from all categories.
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: [
|
|
{
|
|
id: 1,
|
|
name: "Best Pony Radio",
|
|
shortcode: "best_pony_radio",
|
|
description: "Test",
|
|
frontend: "icecast",
|
|
backend: "liquidsoap",
|
|
listen_url: "http://localhost:8080/radio/8000/radio.mp3?1479695912",
|
|
mounts: [
|
|
{
|
|
name: "/radio.mp3",
|
|
is_default: true,
|
|
url: "http://localhost:8080/radio/8000/radio.mp3?1479695912"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
|
|
### GET /stations/{id}
|
|
Station info for the specified numeric identifier.
|
|
|
|
+ Parameters
|
|
+ id (number, required) - The station ID.
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: {
|
|
id: 1,
|
|
name: "Best Pony Radio",
|
|
shortcode: "best_pony_radio",
|
|
description: "Test",
|
|
frontend: "icecast",
|
|
backend: "liquidsoap",
|
|
listen_url: "http://localhost:8080/radio/8000/radio.mp3?1479695912",
|
|
mounts: [
|
|
{
|
|
name: "/radio.mp3",
|
|
is_default: true,
|
|
url: "http://localhost:8080/radio/8000/radio.mp3?1479695912"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
|
|
+ Response 400 (application/json)
|
|
|
|
Returned if an invalid station ID is specified.
|
|
|
|
+Body
|
|
|
|
{
|
|
status: "error",
|
|
error: "Station not found."
|
|
}
|
|
|
|
# Group Song Requests
|
|
Information about available tracks that can be requested, and functionality to submit those requests programmatically.
|
|
|
|
### GET /requests/{station_id}/list
|
|
Get all currently requestable songs from the specified station.
|
|
|
|
+ Parameters
|
|
+ station_id (number, required) - The station ID.
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: [
|
|
{
|
|
song: {
|
|
id: "b0df73b9260ea324ec873c8a6f90f0dc",
|
|
text: "BlackGryph0n/Baasik - Crusader (Are We There Yet)",
|
|
artist: "BlackGryph0n/Baasik",
|
|
title: "Crusader (Are We There Yet)",
|
|
created: 1472973479,
|
|
play_count: 2,
|
|
last_played: 1473029524
|
|
},
|
|
request_song_id: 5,
|
|
request_url: "/api/requests/submit/id/1/song_id/5"
|
|
},
|
|
{
|
|
song: {
|
|
id: "feea15c78f90b918d71b00972e051e19",
|
|
text: "Aviators/Omnipony - Monster",
|
|
artist: "Aviators/Omnipony",
|
|
title: "Monster",
|
|
created: 1472973479,
|
|
play_count: 4,
|
|
last_played: 1473179043
|
|
},
|
|
request_song_id: 10,
|
|
request_url: "/api/requests/submit/id/1/song_id/10"
|
|
}
|
|
]
|
|
}
|
|
|
|
+ Response 400 (application/json)
|
|
|
|
Returned if an invalid station ID is specified.
|
|
|
|
+Body
|
|
|
|
{
|
|
status: "error",
|
|
error: "Station not found."
|
|
}
|
|
|
|
### POST /requests/{station_id}/submit/{song_id}
|
|
Submit a request for a station to play a song with the specified ID.
|
|
|
|
+ Parameters
|
|
+ station_id (number, required) - The station ID.
|
|
+ song_id (number, required) - The song ID (supplied from the /requests/list endpoint)
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: "Request submitted successfully."
|
|
}
|
|
|
|
+ Response 400 (application/json)
|
|
|
|
Returned if any of the following circumstances occur:
|
|
* Invalid station ID specified
|
|
* Invalid song ID specified
|
|
* Song requests disabled by station
|
|
* Song played too recently on the station
|
|
* Request was rate-limited by IP
|
|
* Duplicate request (already pending)
|
|
|
|
+Body
|
|
|
|
{
|
|
status: "error",
|
|
error: "(Detailed error message)"
|
|
}
|
|
|
|
# Group Utilities
|
|
Utility functions to verify the functionality of the system.
|
|
|
|
### GET /
|
|
The homepage of the API, that provides a basic ping function and a link to this documentation.
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: "The AzuraCast API is online and functioning."
|
|
}
|
|
|
|
### GET /status
|
|
A basic ping function that returns the current UNIX timestamp (for caching tests).
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: {
|
|
online: "true",
|
|
timestamp: 0123456789
|
|
}
|
|
}
|
|
|
|
### GET /time
|
|
Return the server's timezone configuration, as well as several formats of the current UTC and localized timestamp.
|
|
|
|
+ Response 200 (application/json)
|
|
|
|
{
|
|
status: "success",
|
|
result: {
|
|
timestamp: 1473194546,
|
|
gmt_datetime: "2016-09-06 8:42:26",
|
|
gmt_date: "September 6, 2016",
|
|
gmt_time: "8:42pm",
|
|
gmt_timezone: "GMT",
|
|
gmt_timezone_abbr: "GMT",
|
|
local_datetime: "2016-09-06 3:42:26",
|
|
local_date: "September 6, 2016",
|
|
local_time: "3:42pm",
|
|
local_timezone: "US/Central",
|
|
local_timezone_abbr: "CDT"
|
|
}
|
|
} |