Skip to main content

Python client for the Radio Browser API

Project description

Pyradios

Upload Python Package
Python package

A Python client for the Radio Browser API, allowing users to search and filter thousands of online radio stations.

📥 Installation

Install pyradios via pip:

pip install pyradios

🚀 Usage

Basic Example

from pyradios import RadioBrowser

rb = RadioBrowser()
results = rb.search(name="BBC Radio 1", name_exact=True)

print(results)

Sample Output

[
  {
    "changeuuid": "4f7e4097-4354-11e8-b74d-52543be04c81",
    "stationuuid": "96062a7b-0601-11e8-ae97-52543be04c81",
    "name": "BBC Radio 1",
    "url": "http://bbcmedia.ic.llnwd.net/stream/bbcmedia_radio1_mf_p",
    "homepage": "http://www.bbc.co.uk/radio1/",
    "tags": "bbc,indie,entertainment,music,rock,pop",
    "country": "United Kingdom",
    "countrycode": "GB",
    "language": "english",
    "codec": "MP3",
    "bitrate": 128
  }
]

🔍 Faceted Search with RadioFacets

What is RadioFacets?

RadioFacets extends RadioBrowser by providing faceted search functionality. It allows you to filter radio stations by various attributes such as:

  • Tags (tags)
  • Country Code (countrycode)
  • Language (language)
  • State/Region (state)
  • Audio Codec (codec)

Example: Using RadioFacets

from pyradios import RadioBrowser, RadioFacets

rb = RadioBrowser()
rf = RadioFacets(rb)

print(len(rf))  # Total stations available

rf_be = rf.narrow(countrycode="BE")  # Narrow by Belgium (BE)
print(len(rf_be))

rf_nl = rf_be.narrow(language="dutch")  # Further narrow by Dutch language
print(len(rf_nl))

rf_reset = rf_nl.broaden(countrycode="BE", language="dutch")  # Remove filters
print(len(rf_reset))  # Back to original count

Explanation

  • narrow(**params) → Adds filters and narrows results.
  • broaden(*keys, **params) → Removes filters and broadens results.
  • len(rf) → Returns the number of stations matching the filters.
  • rf.result → Stores the list of filtered stations.

Example Output

53768  # Total available stations
398    # Stations in Belgium
108    # Dutch-speaking stations in Belgium
53768  # Reset back to all stations

📖 Documentation

To explore all available methods and options, use Python’s built-in help() function:

from pyradios import RadioBrowser, RadioFacets

help(RadioBrowser)
help(RadioFacets)

🛠 Development Setup

Clone the repository and set up the environment:

git clone https://github.com/andreztz/pyradios.git
cd pyradios
virtualenv venv
source venv/bin/activate
pip install -e .[dev]

✅ Running Tests

Execute the test suite using pytest:

pytest

📌 Release History

  • Work in progress

📄 License

Distributed under the MIT License. See LICENSE for more details.

👥 Contributing

Contributions are welcome! Follow these steps to contribute:

  1. Fork the repository (https://github.com/andreztz/pyradios/fork)
  2. Create a feature branch (git checkout -b feature/fooBar)
  3. Commit your changes (git commit -am 'Add feature fooBar')
  4. Push to your branch (git push origin feature/fooBar)
  5. Submit a Pull Request

📧 Author: Andre P. Santos – @ztzandreandreztz@gmail.com

GitHub: https://github.com/andreztz

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyradios-2.1.1.tar.gz (15.0 kB view details)

Uploaded Source

Built Distribution

pyradios-2.1.1-py3-none-any.whl (10.4 kB view details)

Uploaded Python 3

File details

Details for the file pyradios-2.1.1.tar.gz.

File metadata

  • Download URL: pyradios-2.1.1.tar.gz
  • Upload date:
  • Size: 15.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pyradios-2.1.1.tar.gz
Algorithm Hash digest
SHA256 15101dd4cf09648b2880b6bf5bbf0841d74cc46d19f2d00ff88895b4753d7e9e
MD5 129030b35312d07e8f72334966af48a0
BLAKE2b-256 0cee42f40727e6eacaeb6a4ae257e6bead4761c2c217eb8ae3585ef94481e062

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyradios-2.1.1.tar.gz:

Publisher: publish.yml on andreztz/pyradios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyradios-2.1.1-py3-none-any.whl.

File metadata

  • Download URL: pyradios-2.1.1-py3-none-any.whl
  • Upload date:
  • Size: 10.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pyradios-2.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e19f24163c379f7cdb867b44d49598c2dc3600d5461f047d26ca8e71c0cd9858
MD5 de525f82bacde35812304e47aa562a55
BLAKE2b-256 3a1189dd15448a55406f1c1f01fc648268639f0312fcdca150e1d3e5f94d69ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyradios-2.1.1-py3-none-any.whl:

Publisher: publish.yml on andreztz/pyradios

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page