Package de.sfuhrm.radiobrowser4j

Class RadioBrowser

  • public final class RadioBrowser
extends Object
    API facade for the RadioBrowser. You usually create a new instance and then use the methods to invoke API calls.
    Author:
    Stephan Fuhrmann

    • Field Detail

      • API_URL

        @Deprecated
protected static final String API_URL
        Deprecated.
        There are multiple API URLs at the moment. In the past this was a single URL. Reference for compatibility for legacy clients.
        See Also:
        Constant Field Values

    • Constructor Detail

      • RadioBrowser

        public RadioBrowser​(String apiUrl,
                    int timeout,
                    String myUserAgent)
        Creates a new API client.
        Parameters:
        apiUrl - the base URL of the API.
        timeout - the timeout in milliseconds for connecting and reading.
        myUserAgent - the user agent string to use.

      • RadioBrowser

        public RadioBrowser​(int timeout,
                    String myUserAgent)
        Creates a new API client.
        Parameters:
        timeout - the timeout for connect and read requests in milliseconds. Must be greater than zero.
        myUserAgent - the user agent String for your user agent. Must be something to point to you.

    • Method Detail

      • listCountries

        public Map<String,​Integer> listCountries()
        List the known countries.
        Returns:
        a list of countries (keys) and country usages (values).
        See Also:
        API

      • listCodecs

        public Map<String,​Integer> listCodecs()
        List the known codecs.
        Returns:
        a list of codecs (keys) and codec usages (values).
        See Also:
        API

      • listLanguages

        public Map<String,​Integer> listLanguages()
        List the known languages.
        Returns:
        a list of languages (keys) and language usages (values).
        See Also:
        API

      • listTags

        public Map<String,​Integer> listTags()
        List the known tags.
        Returns:
        a list of tags (keys) and tag usages (values).
        See Also:
        API

      • listStations

        public List<Station> listStations​(Paging paging,
                                  ListParameter... listParam)
        Get a list of all stations. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        listParam - the optional listing parameters.
        Returns:
        the partial list of the stations. Can be empty for exceeding the possible stations.

      • listStations

        public Stream<Station> listStations​(ListParameter... listParam)
        Get a list of all stations. Will return all stations in a stream..
        Parameters:
        listParam - the optional listing parameters.
        Returns:
        the full stream of stations..

      • listBrokenStations

        public List<Station> listBrokenStations​(Paging paging)
        Get a list of all broken stations. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        Returns:
        the partial list of the broken stations. Can be empty for exceeding the possible stations.

      • listBrokenStations

        public Stream<Station> listBrokenStations()
        Get a list of all broken stations as one continuous stream.
        Returns:
        the continuous stream of all broken stations.

      • listImprovableStations

        public List<Station> listImprovableStations​(Paging paging)
        Get a list of all improvable stations. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        Returns:
        the partial list of the improvable stations. Can be empty for exceeding the possible stations.

      • listImprovableStations

        public Stream<Station> listImprovableStations()
        Get a list of all broken stations as one continuous stream.
        Returns:
        the continuous stream of all improvable stations.

      • listTopClickStations

        public List<Station> listTopClickStations​(Paging paging)
        Get a list of the top click stations. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        Returns:
        the partial list of the top click stations. Can be empty for exceeding the possible stations.

      • listTopClickStations

        public Stream<Station> listTopClickStations()
        Get a stream of all top click stations.
        Returns:
        the complete stream of all top click stations.

      • listTopVoteStations

        public List<Station> listTopVoteStations​(Paging paging)
        Get a list of the top vote stations. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        Returns:
        the partial list of the top vote stations. Can be empty for exceeding the possible stations.

      • listTopVoteStations

        public Stream<Station> listTopVoteStations()
        Get a stream of the top vote stations.
        Returns:
        the complete stream of the top vote stations.

      • listLastClickStations

        public List<Station> listLastClickStations​(Paging paging)
        Get a list of the last clicked stations. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        Returns:
        the partial list of the last clicked stations. Can be empty for exceeding the possible stations.

      • listLastClickStations

        public Stream<Station> listLastClickStations()
        Get a stream of last clicked stations.
        Returns:
        the complete stream of the last clicked stations.

      • listLastChangedStations

        public List<Station> listLastChangedStations​(Paging paging)
        Get a list of the last changed stations. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        Returns:
        the partial list of the last clicked stations. Can be empty for exceeding the possible stations.

      • listLastChangedStations

        public Stream<Station> listLastChangedStations()
        Get a stream of last changed stations.
        Returns:
        the complete stream of the last changed stations.

      • listDeletedStations

        public List<Station> listDeletedStations()
        Get a list of the deleted stations. Will return a single batch.
        Returns:
        the partial list of the deleted stations. Can be empty for exceeding the possible stations.

      • getStationById

        public Optional<Station> getStationById​(String id)
        Get a station referenced by the ID.
        Parameters:
        id - the id of the station to retrieve.
        Returns:
        an optional containing either the station or nothing. Nothing is returned if the API didn't find the station by the given ID:

      • listStationsBy

        public List<Station> listStationsBy​(Paging paging,
                                    SearchMode searchMode,
                                    String searchTerm,
                                    ListParameter... listParam)
        Get a list of stations matching a certain search criteria. Will return a single batch.
        Parameters:
        paging - the offset and limit of the page to retrieve.
        searchMode - the field to match.
        searchTerm - the term to search for.
        listParam - the optional listing parameters.
        Returns:
        the partial list of the stations. Can be empty for exceeding the number of matching stations.

      • listStationsBy

        public Stream<Station> listStationsBy​(SearchMode searchMode,
                                      String searchTerm,
                                      ListParameter... listParam)
        Get a stream of stations matching a certain search criteria.
        Parameters:
        searchMode - the field to match.
        searchTerm - the term to search for.
        listParam - the optional listing parameters.
        Returns:
        the full stream of matching stations.

      • resolveStreamUrl

        public URL resolveStreamUrl​(Station station)
        Resolves the streaming URL for the given station.
        Parameters:
        station - the station to retrieve the stream URL for.
        Returns:
        the URL of the stream.
        Throws:
        RadioBrowserException - if the URL could not be retrieved

      • deleteStation

        public void deleteStation​(Station station)
        Deletes a station. The station is only marked as being deleted.
        Parameters:
        station - the station to delete from the REST service.

      • undeleteStation

        public void undeleteStation​(Station station)
        Undeletes a station. The station is only marked as being deleted.
        Parameters:
        station - the station to delete from the REST service.

      • postNewStation

        public String postNewStation​(Station station)
        Posts a new station to the server. Note: This call only transmits certain fields. The fields are: name, url, homepage, favicon, country, state, language and tags.
        Parameters:
        station - the station to add to the REST service.
        Returns:
        the id of the new station.
        Throws:
        RadioBrowserException - if there was a problem creating the station.
        See Also:
        The API endpoint

      • editStation

        public String editStation​(Station station)
        Edits an existing station on the server. Note: This call only transmits certain fields. The fields are: name, url, homepage, favicon, country, state, language and tags.
        Parameters:
        station - the station to edit with the REST service.
        Returns:
        the id of the station.
        Throws:
        RadioBrowserException - if there was a problem editing the station.