radios

What it is and what it does

Radios is an async Python client for the Radio Browser API, a crowdsourced directory of internet radio and TV stations. It wraps the Radio Browser's REST endpoints to let you search, filter, and retrieve station metadata programmatically. The library depends on aiohttp for async HTTP, mashumaro for serialization, and several utility libraries (backoff, cachetools, yarl, orjson, pycountry, awesomeversion, aiodns) to handle retries, caching, URL parsing, and country/language code resolution.

You use it by creating a RadioBrowser context manager with a user agent, then awaiting methods like stations(), tags(), countries(), and languages() to query the database. It supports ordering and filtering by country code, language, tags, and other criteria, and can register station clicks. Originally developed for Home Assistant, it's maintained as an active open-source project with semantic versioning and a clear contribution process.

Use it for:

• Build a radio player app that searches and displays stations by country, language, or popularity.
• Aggregate station metadata (tags, click counts, bitrate) for analytics or recommendation systems.
• Create a station discovery tool that filters by genre or language and tracks user interactions.
• Integrate radio station data into a smart home or media center application.
• Fetch and cache station lists for offline or low-latency access in a web or mobile backend.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An async Python client for querying the Radio Browser API, a community-driven database of internet radio and TV stations, with support for filtering, sorting, and station metadata retrieval.

Yes. Low install friction, active maintenance, permissive MIT license, and no known vulnerabilities. Suitable for any Python 3.11+ project needing Radio Browser API access. The main decision point is whether the Radio Browser's data coverage and API stability meet your use case—verify that separately if production-critical.

Install

radios on PyPI

pip install radios

uv add radios

poetry add radios

Installing radios

Before you install

Low friction: pure Python wheel with no compiled dependencies. Actively maintained as of 2026-04-16 with recent release history; requires Python 3.11 or later.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install radios

import asyncio
from radios import RadioBrowser, Order

async def main():
    async with RadioBrowser(user_agent="MyApp/1.0") as radios:
        stations = await radios.stations(limit=10, order=Order.CLICK_COUNT, reverse=True)
        for station in stations:
            print(f"{station.name} ({station.click_count})")

asyncio.run(main())

Requires Python 3.11 or later; async/await syntax and event loop required.

Verify before relying

• Whether the Radio Browser API has rate limits or availability guarantees that affect production use.
• Whether station metadata fields (beyond name and click_count) are documented or discoverable.

Package facts

Evidence: radios-0.3.2-py3-none-any.whl

Keywords: radio browser, radio, web radio, radios, api, async, client

Tags

More Python Modules packages