Skip to main content

Browsing and Searching in Music API

Welcome to the tutorial on how to effectively browse and search for resources using Music API. This guide will walk you through the necessary steps to utilize the API's browsing and searching capabilities to find the resources you need.

Prerequisites​

Before you begin, make sure you have:

  • The authentication credentials required to access the API.
  • Familiarity with HTTP methods and response codes.

Browsing Resources​

Endpoint Overview​

The API provides multiple /browse endpoints that allow you to retrieve a list of stations, audiobooks, podcasts or artists:

  • GET /api/v2/stations/browse
  • GET /api/v2/audiobooks/browse
  • GET /api/v2/podcasts/browse
  • GET /api/v2/artists/browse

Retrieving a List of Stations​

To browse stations, make a GET request to the /stations/browse endpoint. Here's an example using curl:

curl -X GET "https://music-service.stingray.com/api/v2/stations/browse" -H "Authorization: Bearer YOUR_JWT"

By default, the resources are sorted by popularity in ascending order which means the least popular stations are returned. To refine the response, we'll have to pass the sortType and sortDirection in the request.

To retrieve the most popular stations, we can use the sort type POPULARITY with the sort direction DESCENDING.

curl -X GET "https://music-service.stingray.com/api/v2/stations/browse?sortType=POPULARITY&sortDirection=DESCENDING" -H "Authorization: Bearer YOUR_JWT"

Pagination​

The API supports pagination to help manage large sets of resources. Use the limit and offset parameters to control the output:

curl -X GET "https://music-service.stingray.com/api/v2/stations/browse?limig=10&offset=20" -H "Authorization: Bearer YOUR_JWT"

The API response contains the total number of resources available for the browsing parameters used in the request. This should help the pagination behavior of an application to react properly when using the API.

{
    "items": [
        {
            "id": "022",
            "name": "The Spa",
            "description": "Calm your soul, soothe your body, and inspire your mind with purely instrumental electro-acoustic music. The Spa is home to new age and instrumental music, creating an aural landscape that will transport you to a peaceful and tranquil place.",
            "coverUrl": "https://img.stingray.com/v3/token",
            "tags": [
                {
                    "id": "ELECTRONIC",
                    "label": "Electronic"
                },
                {
                    "id": "CULTURE_ASIA",
                    "label": "Asia"
                },
                {
                    "id": "INSTRUMENTAL",
                    "label": "Instrumental"
                },
                {
                    "id": "MISCELLANEOUS",
                    "label": "Miscellaneous"
                },
                {
                    "id": "MISCELLANEOUS_NEW_AGE",
                    "label": "New Age"
                }
            ]
        },
        ...
    ],
    "size": 10,
    "offset": 0,
    "total": 19
}

Localisation​

Some fields also support localisation like the title and description of a station. To retrieve a localised version of the resource, simply use the accept-language header of the request.

For a list of supported language, check out the official localisation documentation

curl -X GET "https://music-service.stingray.com/api/v2/stations/browse" -H "Authorization: Bearer YOUR_JWT" -H "accept-language: es"

Tags​

A list of tags is available in the API to further refine the browsing response by categorizing the stations.

The tags are themselves grouped by category called filters, which are obtainable through the /stations/filters request.

curl -X GET "https://music-service.stingray.com/api/v2/stations/filters" -H "Authorization: Bearer YOUR_JWT"

Once you have the list of filters, you can retrieve a list of tags for each filter by using the /stations/filters/{filterId}/tags request. Replace {filterId} with the identifier of a filter obtained from the previous step.

For example, to retrieve the tags associated with the GENRE filter, we can do the following request:

curl -X GET "https://music-service.stingray.com/api/v2/stations/filters/GENRE/tags" -H "Authorization: Bearer YOUR_JWT"

This will return a list of tags in the following format:

[
    {
        "id": "CLASSICAL",
        "label": "Classical",
        "childrenTags": []
    },
    {
        "id": "COUNTRY",
        "label": "Country and Roots",
        "childrenTags": []
    },
    {
        "id": "ELECTRONIC",
        "label": "Electronic",
        "childrenTags": []
    },
    ...
]

Each object in the response represents a tag that can be used to filter the stations. To retrieve the most popular country stations, we would then perform the following request:

curl -X GET "https://music-service.stingray.com/api/v2/stations/browse?sortType=POPULARITY&sortDirection=DESCENDING&tags=COUNTRY" -H "Authorization: Bearer YOUR_JWT"

Retrieving a List of Audiobooks or Podcasts​

note

Audiobooks and Podcasts are restricted resources in the API. Contact Stingray for more details on how to gain access to those resources.

To browse audiobooks and podcasts, make a GET request to /audiobooks/browse and /podcasts/browse respectively. 

curl -X GET "https://music-service.stingray.com/api/v2/audiobooks/browse" -H "Authorization: Bearer YOUR_JWT"
curl -X GET "https://music-service.stingray.com/api/v2/podcasts/browse" -H "Authorization: Bearer YOUR_JWT"

The functionalities are similar to those of the station browsing endpoints except that there are no tags and filters available. Besides that, you can paginate the response with the limit and offset parameters, sort it with the sortType and sortDirection parameters, localise the response with the accept-language header and further refine the results with the available query parameters.

Retrieving a List of Artists​

In Music API, an artist represents the host of a podcast, the author of a book or the artist of a song contained in a station. To browse artists, make a GET request to /artists/browse:

curl -X GET "https://music-service.stingray.com/api/v2/artists/browse" -H "Authorization: Bearer YOUR_JWT"

Filtering the Results​

The browsing of artists can be further refined by using the artistType parameter of the request. The possible values are:

  • MUSIC: To retrieve artists having songs in at least one station.
  • HOST: To retrieve artists having at least one podcast.
  • AUTHOR: To retrieve artists having at least one audiobook.

For example, to browse the music artists in alphabetical order, you can make the following request:

curl -X GET "https://music-service.stingray.com/api/v2/artists/browse?artistType=MUSIC&sortType=ALPHABETICAL&sortDirection=ASCENDING" -H "Authorization: Bearer YOUR_JWT"

Searching for Resources​

Search Endpoint​

To search for specific resources, use the /search endpoint:

GET /api/v2/search

Constructing Search Queries​

You can search for assets by including the query parameters query in your request. For instance, to locate assets containing the keyword "sunset", append query=sunset to your request parameters.

curl -X GET "https://music-service.stingray.com/api/v2/search?query=sunset" -H "Authorization: Bearer YOUR_JWT"

Filtering Results​

By default, search queries return results for every type of resources you have access to, but the API allows you to filter search results using the type of resources with the query parameter searchAssetType. The allowed values are STATION, PODCAST, AUDIOBOOK and ARTIST.

Here's how to apply the type filter:

curl -X GET "https://music-service.stingray.com/api/v2/search?query=sunset&searchAssetType=STATION" -H "Authorization: Bearer YOUR_JWT"

Pagination​

Similar to the browsing, the search API supports pagination to help manage large sets of assets. You can use the limit and offset parameters to control the number of results returned and their starting point, respectively. Additionally, the total value in the response can be used to manage the pagination behavior within your application.

curl -X GET "https://music-service.stingray.com/api/v2/search?query=sunset&limit=10&offset=20" -H "Authorization: Bearer YOUR_JWT"

Conclusion​

Browsing and searching for resources with Music API is straightforward once you understand the basics. With this tutorial, you should be well-equipped to find the resources you need.