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

    stations. The API exposes the complete station database along with

    metadata (countries, languages, codecs, tags, states) and supports

    click counting, voting, and station submission.


    Servers are reached through a round-robin DNS pool. Resolve

    `all.api.radio-browser.info` to obtain the list of mirrors, then call

    one of them (for example `de1.api.radio-browser.info`). The base URL

    `api.radio-browser.info` also resolves to one of the active mirrors.


    Clients MUST send a descriptive `User-Agent` header in the form

    `appname/appversion`. Voting is throttled to one vote per station per

    IP every 10 minutes. Click counts are aggregated once per station per

    IP per 24 hours.

    '
  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:
  parameters:
    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.
    Limit:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 0
        default: 100000
      description: Maximum rows to return.
  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
          format: uuid
          nullable: true
        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
          format: date-time
          nullable: true
        clickcount:
          type: integer
        clicktrend:
          type: integer
        ssl_error:
          type: integer
          enum:
          - 0
          - 1
        geo_lat:
          type: number
          format: float
          nullable: true
        geo_long:
          type: number
          format: float
          nullable: true
        geo_distance:
          type: number
          format: float
          nullable: true
        has_extended_info:
          type: boolean