MegaRadio API Documentation

🚀 Quick Start

Base URL for all API requests:

Base URL: https://api.themegaradio.com

For Mobile Developers

All mobile apps should use https://api.themegaradio.com as the base URL. Web browsers use https://themegaradio.com with built-in API proxy.

Fetch popular stations with a single request:

// React Native / JavaScript

const response = await fetch('https://api.themegaradio.com/api/stations/popular?limit=20');

const stations = await response.json();

// Each station object:

// { name, url, urlResolved, country, favicon, votes, codec, bitrate, slug, ... }

# cURL

curl https://api.themegaradio.com/api/stations/popular?limit=10

🔐 Authentication

Three ways to authenticate API requests:

Method	Header	Use Case
API Key	`X-API-Key: your_key`	Server-to-server, mobile apps
User Token	`X-API-User-Token: token`	Per-user actions (favorites, ratings)
Session Cookie	`Cookie: connect.sid=...`	Web browser (auto-managed)

API Key Tiers

Demo

Free

50 req/day • Auto-generated per IP

Free

1,000 req/day • Register required

Pro

Contact

50,000 req/day • Priority support

// Get a demo API key (auto-generated, 24h cooldown per IP)

const res = await fetch('https://api.themegaradio.com/api/api-keys/demo', { method: 'POST' });

const { apiKey } = await res.json();

// Use the API key

fetch('https://api.themegaradio.com/api/stations/popular', {

  headers: { 'X-API-Key': apiKey }

});

📻 Stations

Browse, search, and discover 40,000+ radio stations.

GET /api/stations Search & list stations

GET /api/station/:identifier Get station by ID or slug

GET /api/stations/popular Trending / most voted stations

GET /api/stations/nearby Find stations near user location

GET /api/stations/random Random station discovery

POST /api/stations/batch Fetch multiple stations by IDs

GET /api/now-playing/:id Live stream metadata (song/artist)

Query Parameters for /api/stations

Param	Type	Description
`q`	string	Search query (name, tags, country)
`country`	string	Filter by country name
`genre`	string	Filter by genre/tag
`codec`	string	Filter by codec (MP3, AAC, OGG)
`limit`	number	Results per page (default: 20, max: 100)
`offset`	number	Pagination offset
`sort`	string	Sort: votes, clickCount, name, random

// Search for jazz stations in Germany

fetch('https://api.themegaradio.com/api/stations?q=jazz&country=Germany&limit=10')

🎶 Genres & Countries

GET /api/genres All available genres

GET /api/genres/discoverable Top genres for homepage display

GET /api/countries All countries with station counts

GET /api/regions World regions (Africa, Asia, Europe...)

GET /api/regions/:region/:country Stations by region and country

GET /api/location Auto-detect user country from IP

🎧 Streaming

Stream proxy handles CORS, HTTPS upgrades, and ICY metadata extraction.

GET /api/stream/:encodedUrl Proxy audio stream (CORS-safe)

GET /api/stream/hls/:encodedUrl HLS stream proxy

Smart Streaming Logic

HTTPS streams: Play directly in the client (no proxy needed)
HTTP streams: Must use the proxy for CORS and mixed-content safety
Stream URL must be URL-encoded in the path: /api/stream/http%3A%2F%2Fexample.com%2Fstream

// React Native audio playback

const station = await fetch('https://api.themegaradio.com/api/station/mangoradio').then(r => r.json());

const streamUrl = station.url.startsWith('https')

  ? station.url  // Direct HTTPS — no proxy needed

  : `https://api.themegaradio.com/api/stream/${encodeURIComponent(station.url)}`;

// Use streamUrl in your audio player (e.g., react-native-track-player)

⭐ User Engagement

Favorites, ratings, follows, and trending data. Requires authentication.

POST /api/stations/:id/favorite Toggle favorite AUTH

POST /api/stations/:id/rate Submit rating (1-5 stars) AUTH

GET /api/trending Global trending stations

POST /api/stations/:id/comment Add comment AUTH

GET /api/stations/:id/comments Get station comments

POST /api/follow/:userId Follow / unfollow user AUTH

GET /api/profile/:slug Public user profile

POST /api/listening/record Record listening history AUTH

👤 User Authentication

POST /api/auth/signup Register new account

POST /api/auth/login Email & password login

POST /api/auth/logout Logout (clear session)

GET /api/auth/me Current user info AUTH

PUT /api/auth/profile Update profile AUTH

POST /api/auth/google Google Sign-In (idToken)

DELETE /api/user/delete-account Permanently delete account AUTH

// Google Sign-In for mobile
const res = await fetch('https://api.themegaradio.com/api/auth/google', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    idToken: 'google_id_token_here',
    email: '[email protected]',
    name: 'User Name',
    googleId: 'google_user_id'
  })
});

💰 Subscription (Mobile IAP)

Report and verify in-app purchases from iOS/Android.

POST /api/user/subscription Report purchase (productId + transactionId) AUTH

GET /api/user/subscription Check subscription status & features AUTH

POST /api/user/subscription/cancel Cancel subscription AUTH

Product IDs

Product ID	Plan	Features
`megaradio_remove_ads_yearly1`	Remove Ads	Ad-free experience
`megaradio_premium_monthly1`	Premium Monthly	All features
`megaradio_premium_yearly`	Premium Yearly	All features
`megaradio_premium_lifetime`	Premium Lifetime	All features, forever

// Report purchase after successful IAP

await fetch('https://api.themegaradio.com/api/user/subscription', {

  method: 'POST',

  headers: {

    'Content-Type': 'application/json',

    'X-API-User-Token': userToken

  },

  body: JSON.stringify({

    productId: 'megaradio_premium_monthly1',

    transactionId: 'GPA.1234-5678',

    platform: 'android'  // or 'ios'

  })

});

⚡ WebSocket

Real-time connections for live metadata and casting.

WS wss://api.themegaradio.com/ws/metadata Live now-playing updates

WS wss://api.themegaradio.com/ws/cast Cast / remote control commands

WS wss://api.themegaradio.com/ws/chat Live station chat

// Subscribe to now-playing for a station

const ws = new WebSocket('wss://api.themegaradio.com/ws/metadata');

ws.onopen = () => {

  ws.send(JSON.stringify({ type: 'subscribe', stationId: 'station_id_here' }));

};

ws.onmessage = (event) => {

  const data = JSON.parse(event.data);

  console.log(`Now playing: ${data.title} - ${data.artist}`);

};

📺 Cast & TV

Chromecast, TV app, and device code login support.

GET /api/tv/init TV app initialization payload

POST /api/cast/session/create Create cast pairing session

POST /api/cast/command Send playback command

POST /api/user/push-token Register push notification token AUTH

🛡 Rate Limits

Scope	Limit	Window
Global API	100 requests	1 minute
Auth endpoints (login/register)	10 attempts	15 minutes
Demo API Key	50 requests	24 hours
Free API Key	1,000 requests	24 hours
Pro API Key	50,000 requests	24 hours

Rate Limit Response

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating when to retry.

⚠️ Error Handling

All errors follow a consistent JSON format:

{

  "error": "Human-readable error message",

  "message": "Detailed description (optional)"

}

Status	Meaning
`200`	Success
`400`	Bad request (invalid params)
`401`	Unauthorized (missing/invalid auth)
`403`	Forbidden (insufficient permissions)
`404`	Not found
`429`	Rate limited
`500`	Internal server error