PHPackages                             joeyboli/radioapisdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. joeyboli/radioapisdk

ActiveLibrary[API Development](/categories/api)

joeyboli/radioapisdk
====================

Modern PHP SDK for RadioAPI - retrieve radio stream metadata, search music tracks, and analyze image colors

10.12(4mo ago)171Apache-2.0PHPPHP >=8.3

Since Oct 13Pushed 3mo agoCompare

[ Source](https://github.com/joeyboli/RadioAPISDK)[ Packagist](https://packagist.org/packages/joeyboli/radioapisdk)[ Docs](https://github.com/joeyboli/radioapisdk)[ RSS](/packages/joeyboli-radioapisdk/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (13)Used By (0)

RadioAPI PHP Client
===================

[](#radioapi-php-client)

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.

[![PHP Version](https://camo.githubusercontent.com/cc9cdea9aa96b40a822425e981b0a030e3371202973c7d57b74e8e99834f81dc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c7565)](https://www.php.net/)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)

Table of Contents
-----------------

[](#table-of-contents)

- [What You Can Do](#what-you-can-do)
- [Getting Started](#getting-started)
- [Quick Example](#quick-example)
- [Setup & Configuration](#setup--configuration)
- [Core Features](#core-features)
    - [Stream Metadata](#get-stream-info)
    - [Music Search](#search-for-music)
    - [Color Extraction](#extract-colors-from-images)
- [Metadata Endpoints (UUID-based)](#work-with-metadata-endpoints)
    - [Creation & Management](#create-an-endpoint)
    - [Fetching Metadata & History](#fetch-metadata-via-uuid)
    - [Analytics](#analytics-and-stats)
    - [Fluent Usage](#fluent-response-methods)
- [Working with Responses](#working-with-responses)
- [Error Handling](#when-things-go-wrong)
- [Tips & Best Practices](#tips-and-best-practices)

---

What You Can Do
---------------

[](#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
---------------

[](#getting-started)

PHP 8.1+ and ElliePHP HttpClient are required.

```
composer require joeyboli/radioapisdk
```

Quick Example
-------------

[](#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
-------------------------

[](#setup--configuration)

### The Basics

[](#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

[](#available-services)

ConstantDescription`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
-------------

[](#core-features)

### Get Stream Info

[](#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

[](#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

[](#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
----------------------------

[](#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

[](#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

[](#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

[](#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

[](#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
----------------------

[](#working-with-responses)

All API methods return specialized response objects implementing `ResponseInterface`.

### Common Methods

[](#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

[](#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
--------------------

[](#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
-----------------------

[](#tips-and-best-practices)

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

License
-------

[](#license)

MIT licensed

Contributing
------------

[](#contributing)

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

Changelog
---------

[](#changelog)

### 1.1.0 (2026-03-19)

[](#110-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)

[](#109-2026-02-04)

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

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance79

Regular maintenance activity

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~14 days

Total

12

Last Release

107d ago

Major Versions

1.0.11 → 10.122026-03-03

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/43940776?v=4)[Joey 😎](/maintainers/joeyboli)[@joeyboli](https://github.com/joeyboli)

---

Top Contributors

[![joeyboli](https://avatars.githubusercontent.com/u/43940776?v=4)](https://github.com/joeyboli "joeyboli (29 commits)")

---

Tags

phpapistreamingmetadatamusiccolorsradio

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/joeyboli-radioapisdk/health.svg)

```
[![Health](https://phpackages.com/badges/joeyboli-radioapisdk/health.svg)](https://phpackages.com/packages/joeyboli-radioapisdk)
```

###  Alternatives

[fennb/phirehose

A PHP interface to the Twitter Streaming API.

699410.8k4](/packages/fennb-phirehose)[mozex/anthropic-laravel

Laravel integration for the Anthropic API: facade, config publishing, install command, testing fakes, messages, streaming, tool use, thinking, and batches.

74331.3k1](/packages/mozex-anthropic-laravel)[mozex/anthropic-php

PHP client for the Anthropic API: messages, streaming, tool use, thinking, web search, code execution, batches, and more.

49552.5k18](/packages/mozex-anthropic-php)[redwebcreation/twitter-stream-api

Consume the Twitter Stream API in real-time.

3220.9k1](/packages/redwebcreation-twitter-stream-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)