README

A clean, modern PHP client for RadioAPI that makes working with radio streams and music data feel effortless. Get real-time stream metadata, search across all the major streaming platforms, and even pull color palettes from album artwork—all with an API that just works.

What You Can Do
Getting Started
Quick Example
Setup & Configuration
Core Features
Metadata Endpoints (UUID-based)
Working with Responses
Error Handling
Tips & Best Practices

What You Can Do

Stream Metadata - Pull current track info from any radio stream.
Metadata Endpoints - Create UUID-based metadata endpoints for JC Player, AzuraCast, RadioKing and Live365.
Track History & Popularity - Retrieve recently played and most frequent tracks for your endpoints.
Analytics - Monitor usage statistics for your metadata endpoints.
Music Search - Find tracks across Spotify, Deezer, Apple Music, and more.
Color Extraction - Grab dominant colors from album art for dynamic theming.
Fluent API - Natural method chaining and rich response objects.

Getting Started

PHP 8.1+ and ElliePHP HttpClient are required.

composer require joeyboli/radioapisdk

Quick Example

use RadioAPI\RadioAPI;

// Set up your client
$api = RadioAPI::make('https://api.radioapi.io', 'your-api-key')
    ->service(RadioAPI::SPOTIFY)
    ->withHistory();

// Find out what's playing on a stream
$stream = $api->getStreamTitle('https://stream.example.com/radio');

if ($stream->isSuccess()) {
    $track = $stream->getCurrentTrack();
    echo "Now playing: {$track['artist']} - {$track['song']}\n";
    
    foreach ($stream->getHistory() as $historical) {
        echo "Previously: {$historical['artist']} - {$historical['song']}\n";
    }
}

Setup & Configuration

The Basics

use RadioAPI\RadioAPI;

// Simple instantiation
$api = new RadioAPI('https://api.radioapi.io', 'your-api-key');

// Or using the fluent factory
$api = RadioAPI::make('https://api.radioapi.io', 'your-api-key')
    ->language('en')           // Response language (ISO 639-1)
    ->service(RadioAPI::AUTO)  // Default service/platform
    ->withHistory()            // Include track history by default
    ->timeout(60);             // Request timeout in seconds

Available Services

Constant	Description
`RadioAPI::SPOTIFY`	Spotify
`RadioAPI::DEEZER`	Deezer
`RadioAPI::APPLE_MUSIC`	Apple Music / iTunes
`RadioAPI::YOUTUBE_MUSIC`	YouTube Music
`RadioAPI::FLO_MUSIC`	FLO Music
`RadioAPI::LINE_MUSIC`	LINE Music
`RadioAPI::KKBOX_MUSIC`	KKBOX
`RadioAPI::AUTO`	Automatic provider detection
`RadioAPI::AZURACAST`	AzuraCast platform
`RadioAPI::LIVE365`	Live365 platform
`RadioAPI::RADIOKING`	RadioKing platform

Core Features

Get Stream Info

Pull current track metadata from any radio stream.

$response = $api->getStreamTitle(
    streamUrl: 'https://stream.example.com/radio',
    service: RadioAPI::SPOTIFY, // Optional override
    withHistory: true           // Optional override
);

if ($response->isSuccess()) {
    echo $response->getArtist() . ' - ' . $response->getTitle();
}

Search for Music

Find tracks across various streaming services.

$response = $api->searchMusic(
    query: 'The Beatles - Hey Jude',
    service: RadioAPI::SPOTIFY, // Optional
    language: 'en'              // Optional
);

foreach ($response->getTracks() as $track) {
    echo "{$track['artist']} - {$track['title']}\n";
}

Extract Colors from Images

Analyze album artwork to generate dynamic themes.

$colors = $api->getImageColors('https://example.com/album-art.jpg');

if ($colors->isSuccess()) {
    echo "Dominant Hex: " . $colors->getDominantColorHex();
    echo "Text Color Hex: " . $colors->getTextColorHex();
}

Work with Metadata Endpoints

Metadata endpoints allow you to wrap complex configurations (JC Player, AzuraCast, etc.) behind a single UUID-based URL.

Create an Endpoint

$endpoint = $api->createMetadataEndpoint(
    kind: 'jcplayer',
    url: 'https://your-stream-url',
    options: [
        'service' => RadioAPI::AUTO,
        'locale'  => 'en',
        'history' => true,
    ]
);

$uuid = $endpoint->getUuid();
echo "Endpoint URL: " . $endpoint->getEndpointUrl();

Supported Kinds:

jcplayer: Standard stream URL processing.
azuracast: AzuraCast API or stream URL.
radioking: RadioKing player URL.
live365: Live365 station URL.

Fetch Metadata via UUID

Once an endpoint is created, you can fetch its metadata easily.

// Fetch current metadata
$stream = $api->getMetadata($uuid, ['locale' => 'fr']);

// Fetch track history
$history = $api->getMetadataHistory($uuid, ['limit' => 20]);

// Fetch most played tracks
$popular = $api->getMetadataPopular($uuid, ['limit' => 10]);

Analytics and Stats

Monitor the performance and usage of your endpoints.

// General stats for all your endpoints
$globalStats = $api->getMetadataStats(['days' => 30]);

// Detailed stats for a specific endpoint
$stats = $api->getMetadataEndpointStats($uuid, ['days' => 7]);

echo "Total Requests: " . $stats->getTotalRequests();
print_r($stats->getRequestsByDay());

Fluent Response Methods

The MetadataEndpointResponse object provides convenient methods to perform actions directly on the endpoint it represents.

$endpoint = $api->createMetadataEndpoint('jcplayer', '...');

// Update the endpoint
$endpoint->update(['history' => false]);

// Get live metadata
$metadata = $endpoint->getMetadata();

// Get history or popular tracks
$history = $endpoint->getHistory();
$popular = $endpoint->getPopular();

// Get its specific stats
$stats = $endpoint->getStats();

// Or delete it
$endpoint->delete();

Working with Responses

All API methods return specialized response objects implementing ResponseInterface.

Common Methods

isSuccess(): bool - Whether the request was successful.
getError(): ?string - Returns the error message if unsuccessful.
getRawData(): array - The full raw response array.

Specialized Responses

StreamTitleResponse: getArtist(), getTitle(), getAlbum(), getCurrentTrack(), getHistory(), getStreamInfo().
MusicSearchResponse: getTracks(), getFirstTrack(), getResultCount(), getTracksByService(service).
ColorResponse: getDominantColorHex(), getTextColorHex(), getDominantColorRgb(), getPalette().
MetadataHistoryResponse: getTracks(), count().
MetadataPopularResponse: getTracks(), count().
MetadataStatsResponse: getTotalRequests(), getRequestsByDay(), getTopUserAgents(), getTopIps().

When Things Go Wrong

All errors throw a RadioAPIException. Always wrap your API calls in a try-catch block.

use RadioAPI\Exceptions\RadioAPIException;

try {
    $api->getStreamTitle('invalid-url');
} catch (RadioAPIException $e) {
    if ($e->isRateLimited()) {
        // Handle 429
    } elseif ($e->isUnauthorized()) {
        // Handle 401
    }
    echo "Error: " . $e->getMessage();
}

Tips and Best Practices

Reuse Your Client: Avoid creating a new RadioAPI instance for every request.
Check Success: Always use isSuccess() before accessing specific data if you're not using try-catch for everything.
Use Constants: Use RadioAPI::SPOTIFY etc. instead of raw strings to avoid typos.
Leverage Fluent Methods: Use the methods on response objects for cleaner, more readable code.

License

MIT licensed

Contributing

Pull requests are welcome! Please ensure all code follows the existing style and includes proper type declarations.

Changelog

1.1.0 (2026-03-19)

Added full support for Metadata Endpoints API.
Added Track History and Popular Tracks retrieval for endpoints.
Added General and Endpoint-specific Analytics.
Introduced fluent methods in MetadataEndpointResponse for easy management.
Added dedicated response objects: MetadataHistoryResponse, MetadataPopularResponse, MetadataStatsResponse.

1.0.9 (2026-02-04)

Complete rewrite using ElliePHP HttpClient.
Fluent configuration API.
Better type safety with PHP 8.1+.
Improved error handling.

joeyboli / radioapisdk

Maintainers

Package info

Statistics

Security