Radio Browser Stations API

openapi: 3.2.0
info:
  title: Radio Browser Stations API
  description: 'Radio Browser is a free community-driven directory of internet radio

    stations.'
  version: 0.7.44
  contact:
    name: Radio Browser
    url: https://www.radio-browser.info/
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: https://de1.api.radio-browser.info
  description: Germany 1 mirror
- url: https://nl1.api.radio-browser.info
  description: Netherlands 1 mirror
- url: https://at1.api.radio-browser.info
  description: Austria 1 mirror
- url: https://all.api.radio-browser.info
  description: Round-robin pool entry (resolve via DNS)
tags:
- name: Stations
  description: Browse, search, and list radio stations.
paths:
  /json/stations:
    get:
      tags:
      - Stations
      operationId: listStations
      summary: List All Stations
      description: Return the full collection of radio stations as JSON.
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/HideBroken'
      responses:
        '200':
          description: Array of station objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/search:
    get:
      tags:
      - Stations
      operationId: searchStations
      summary: Search Stations
      description: Advanced search across the station database using multiple optional filters.
      parameters:
      - in: query
        name: name
        schema:
          type: string
        description: Match station name (substring, case-insensitive).
      - in: query
        name: nameExact
        schema:
          type: boolean
          default: false
      - in: query
        name: country
        schema:
          type: string
      - in: query
        name: countrycode
        schema:
          type: string
          description: ISO 3166-1 alpha-2 country code.
      - in: query
        name: state
        schema:
          type: string
      - in: query
        name: language
        schema:
          type: string
      - in: query
        name: tag
        schema:
          type: string
      - in: query
        name: tagList
        schema:
          type: string
          description: Comma-separated tag list.
      - in: query
        name: codec
        schema:
          type: string
      - in: query
        name: bitrateMin
        schema:
          type: integer
          minimum: 0
      - in: query
        name: bitrateMax
        schema:
          type: integer
          minimum: 0
      - in: query
        name: order
        schema:
          type: string
          enum:
          - name
          - url
          - homepage
          - favicon
          - tags
          - country
          - state
          - language
          - votes
          - codec
          - bitrate
          - lastcheckok
          - lastchecktime
          - clicktimestamp
          - clickcount
          - clicktrend
          - random
      - in: query
        name: reverse
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/HideBroken'
      responses:
        '200':
          description: Filtered list of stations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/byuuid:
    get:
      tags:
      - Stations
      operationId: getStationsByUuid
      summary: Get Stations By UUID
      description: Return the stations matching the supplied station UUIDs.
      parameters:
      - in: query
        name: uuids
        required: true
        schema:
          type: string
        description: One UUID or a comma-separated list of UUIDs.
      responses:
        '200':
          description: Array of matching stations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/byname/{searchterm}:
    get:
      tags:
      - Stations
      operationId: getStationsByName
      summary: Get Stations By Name
      parameters:
      - in: path
        name: searchterm
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stations whose name matches the search term.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/bycountry/{searchterm}:
    get:
      tags:
      - Stations
      operationId: getStationsByCountry
      summary: Get Stations By Country
      parameters:
      - in: path
        name: searchterm
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stations registered in the given country.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/bycountrycodeexact/{searchterm}:
    get:
      tags:
      - Stations
      operationId: getStationsByCountryCode
      summary: Get Stations By Country Code
      parameters:
      - in: path
        name: searchterm
        required: true
        schema:
          type: string
          description: ISO 3166-1 alpha-2 country code.
      responses:
        '200':
          description: Stations matching the country code exactly.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/bylanguage/{searchterm}:
    get:
      tags:
      - Stations
      operationId: getStationsByLanguage
      summary: Get Stations By Language
      parameters:
      - in: path
        name: searchterm
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stations broadcasting in the given language.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/bytag/{searchterm}:
    get:
      tags:
      - Stations
      operationId: getStationsByTag
      summary: Get Stations By Tag
      parameters:
      - in: path
        name: searchterm
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stations tagged with the given keyword.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/bycodec/{searchterm}:
    get:
      tags:
      - Stations
      operationId: getStationsByCodec
      summary: Get Stations By Codec
      parameters:
      - in: path
        name: searchterm
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stations using the given audio codec.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/byurl:
    get:
      tags:
      - Stations
      operationId: getStationsByUrl
      summary: Get Stations By Stream URL
      parameters:
      - in: query
        name: url
        required: true
        schema:
          type: string
          format: uri
      responses:
        '200':
          description: Stations registered with the given stream URL.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/topclick:
    get:
      tags:
      - Stations
      operationId: getTopClickStations
      summary: Get Top Clicked Stations
      parameters:
      - in: path
        name: rowcount
        schema:
          type: integer
          minimum: 1
        required: false
      responses:
        '200':
          description: Stations ranked by click count.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/topvote:
    get:
      tags:
      - Stations
      operationId: getTopVoteStations
      summary: Get Top Voted Stations
      responses:
        '200':
          description: Stations ranked by vote count.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/lastclick:
    get:
      tags:
      - Stations
      operationId: getLastClickStations
      summary: Get Recently Clicked Stations
      responses:
        '200':
          description: Stations sorted by most recent click.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/lastchange:
    get:
      tags:
      - Stations
      operationId: getLastChangeStations
      summary: Get Recently Changed Stations
      responses:
        '200':
          description: Stations sorted by most recent change.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
  /json/stations/broken:
    get:
      tags:
      - Stations
      operationId: getBrokenStations
      summary: Get Broken Stations
      responses:
        '200':
          description: Stations whose latest health check failed.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
components:
  schemas:
    Station:
      type: object
      description: A radio station entry in the Radio Browser directory.
      properties:
        changeuuid:
          type: string
          format: uuid
        stationuuid:
          type: string
          format: uuid
        serveruuid:
          type:
          - string
          - 'null'
          format: uuid
        name:
          type: string
        url:
          type: string
          format: uri
        url_resolved:
          type: string
          format: uri
        homepage:
          type: string
          format: uri
        favicon:
          type: string
          format: uri
        tags:
          type: string
          description: Comma-separated tag list.
        country:
          type: string
        countrycode:
          type: string
          description: ISO 3166-1 alpha-2.
        iso_3166_2:
          type: string
        state:
          type: string
        language:
          type: string
          description: Comma-separated language list.
        languagecodes:
          type: string
          description: Comma-separated ISO 639 codes.
        votes:
          type: integer
        lastchangetime:
          type: string
        lastchangetime_iso8601:
          type: string
          format: date-time
        codec:
          type: string
        bitrate:
          type: integer
          description: Kilobits per second.
        hls:
          type: integer
          enum:
          - 0
          - 1
        lastcheckok:
          type: integer
          enum:
          - 0
          - 1
        lastchecktime:
          type: string
        lastchecktime_iso8601:
          type: string
          format: date-time
        lastcheckoktime:
          type: string
        lastcheckoktime_iso8601:
          type: string
          format: date-time
        lastlocalchecktime:
          type: string
        lastlocalchecktime_iso8601:
          type: string
          format: date-time
        clicktimestamp:
          type: string
        clicktimestamp_iso8601:
          type:
          - string
          - 'null'
          format: date-time
        clickcount:
          type: integer
        clicktrend:
          type: integer
        ssl_error:
          type: integer
          enum:
          - 0
          - 1
        geo_lat:
          type:
          - number
          - 'null'
          format: float
        geo_long:
          type:
          - number
          - 'null'
          format: float
        geo_distance:
          type:
          - number
          - 'null'
          format: float
        has_extended_info:
          type: boolean
  parameters:
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 0
        default: 100000
      description: Maximum rows to return.
    Offset:
      in: query
      name: offset
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Starting offset for pagination.
    HideBroken:
      in: query
      name: hidebroken
      schema:
        type: boolean
        default: false
      description: Exclude stations whose last health check failed.