Skip to main content

How to Sort Songs

In many of the calls, Stingray provides the to option to sort the results returned by our API.

The following steps describe the required endpoint calls for retrieving songs using the available sort types.

Audience​

This tutorial is designed for people familiar with JavaScript programming.

Requirements​

You must have a valid API key and Bearer Token. For information on how to get the token, refer to Generating Access Tokens.

To run the tutorial, you must download the full OpenAPI specification and then import it into a API testing platform. For this tutorial, we will be using Postman API. For information on how to use Postman, refer to their documentation.

To get the list of the most popular songs of our catalog, we must make the call to GET /v2/songs with the following optional query parameters:

  • sort-type: (Optional) Filter the results by sort type (a-z , popularity, date-added, or release-year).
  • sort-direction: (Optional) Set the sort direction (normal or reverse) for sort-type.
  • size: (Optional) Set the number of entries to return in the results. By default, 10 songs are returned.
  • page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).

For this example, we make the following call:

GET /v2/songs?sort-type=popularity&sort-direction=normal

Note that we set the following query parameter values:

  • sort-type=popularity: Sort results by their popularity score.
  • sort-direction=normal: In this case sort results descending, meaning from most popular to least.

Step Result​

The endpoint returns the first 10 most popular songs along with their metadata and song IDs. As shown in Figure 1, in the metadata returned for the songs, the popularity score is higher on the first item compared to the second item.

Figure 1: sample response

[
  {
    "id": "KAR:G:7366",
    "title": "Sweet Caroline (Good Times Never Seemed So Good)",
    "popularity": 0.3531332573720387 // popularity score
    // other metadata
  },
  {
    "id": "KAR:G:2511",
    "title": "Bohemian Rhapsody",
    "popularity": 0.3321034706383944 // popularity score
    // other metadata
  }
  // other responses
]

Getting the Recently Added Songs​

To get the list of the most recently added songs of our catalog, we must make the call to GET /v2/songs with the following optional query parameters:

  • sort-type: (Optional) Filter the results by sort type (a-z , popularity, date-added, or release-year).
  • sort-direction: (Optional) Set the sort direction (normal or reverse) for sort-type.
  • size: (Optional) Set the number of entries to return in the results. By default, 10 songs are returned.
  • page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).

For this example, we make the following call:

GET /v2/songs?sort-type=date-added&sort-direction=normal

Note that we set the following query parameter values:

  • sort-type=date-added: Sort results by their date added.
  • sort-direction=normal: In this case, sort results descending, meaning from most recent to least.

Step Result​

The endpoint returns the first 10 most recently added songs along with their metadata and song IDs. As shown in Figure 2, in the metadata returned for the songs, the added date of each item is very close to the actual date (the call was done on June 16th 2022).

Figure 2: sample response

[
  {
    "id": "KAR:G:2979163",
    "title": "911",
    "added_date": "2022-06-15" // June 15th 2022
    // other metadata
  },
  {
    "id": "KAR:G:2993906",
    "title": "As I Am",
    "added_date": "2022-06-15"
    // other metadata
  }
  // other responses
]

Getting the Recently Released Songs​

To get the list of the most recently released songs, we must make the call to GET /v2/songs with the following optional query parameters:

  • sort-type: (Optional) Filter the results by sort type (a-z , popularity, date-added, or release-year).
  • sort-direction: (Optional) Set the sort direction (normal or reverse) for sort-type.
  • size: (Optional) Set the number of entries to return in the results. By default, 10 songs are returned.
  • page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).

For this example, we make the following call:

GET /v2/songs?sort-type=release-year&sort-direction=reverse

Note that we set the following query parameter values:

  • sort-type=release-year: Sort results by their release year.
  • sort-direction=reverse: In this case, sort results descending, meaning from the most recent year to the least.

Step Result​

The endpoint returns the first 10 most recently released songs along with their metadata and song IDs. As shown in Figure 3, in the metadata returned for the songs, the release year of each item is the same as the actual year (the call was done in the year 2022).

Figure 3: sample response

[
  {
    "id": "KAR:G:3290476",
    "title": "When You're Gone",
    "release_year": 2022
    // other metadata
  },
  {
    "id": "KAR:G:3260227",
    "title": "Trouble with a Heartbreak",
    "release_year": 2022
    // other metadata
  }
  // other responses
]

Getting the Songs in Alphabetical Order​

To get the list songs in alphabetical order of our catalog, we must make the call to GET /v2/songs with the following optional query parameters:

  • sort-type: (Optional) Filter the results by sort type (a-z , popularity, date-added, or release-year).
  • sort-direction: (Optional) Set the sort direction (normal or reverse) for sort-type.
  • size: (Optional) Set the number of entries to return in the results. By default, 10 songs are returned.
  • page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).

For this example, we make the following call:

GET /v2/songs?sort-type=a-z&sort-direction=normal

Note that we set the following query parameter values:

  • sort-type=a-z: Sort results by alphabetical order of their title.
  • sort-direction=normal: In this case, sort results ascending, meaning from "a" to "z".

Step Result​

The endpoint returns the first songs in alphabetical order along with their metadata and song IDs. As shown in Figure 4, in the metadata returned for the songs, the title of each song is sorted alphabetically.

Figure 4: sample response

[
  {
    "id": "KAR:G:1928",
    "title": "...Baby One More Time" // ...B
    // other metadata
  },
  {
    "id": "KAR:G:2031142",
    "title": "...Ready For It?" // ...R
    // other metadata
  }
  // other responses
]

Conclusion​

It is now possible to select a song in the sorted list to play by noting down the song ID and following step 2 of the tutorial - How to Play a Karaoke Song.