---
id: radios
version: "0.3.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# radios — Asynchronous Python client for the Radio Browser API

License: permissive · Maintenance: active · Downloads: 93.3K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 93.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

radio browser api client, async radio station search, internet radio api python, radio metadata lookup, web radio streaming client, radio station database query, asyncio radio api, async-http-client, radio-metadata, api-wrapper

[View on SkillFed](https://skillfed.io/packages/radios) · [View on PyPI](https://pypi.org/project/radios/)