Skip to main content

How to Retrieve Filter IDs

In many calls, you have the option to filter the results returned by the Karaoke API. The filters have static enum values (e.g. a boolean) to specify if the song is a duet, the song's rating, or the gender of the artist.

note

Some dynamic filters (i.e. new filter item can be added over time) may also require an identitfier to be passed to the call.

The filters to be discussed are as follows:

The following steps describe the required endpoint calls for retrieving the different filter IDs and how to use these IDs to filter songs.

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.

Genres Filter​

Step 1: Retrieving a Genre​

To explore the genres filter available in the API, we must make a call to GET /v2/genres.

For this example, we will make the following call:

GET /v2/genres;

Step Result​

The endpoint returns all the possible genres available in the API, along with their label and thumbnails.

From the sample response shown in Figure 1, take note of the id value 12. We will be using the genres ID in Step 2: Filtering Songs by a Specific Genre.

Figure 1: Step 1-A sample response

{
  "genres": [
    {
      "id": "12", // genre ID
      "label": "Disney",
      "thumbnails": {
        "transparent_artist": "{thumbnail filePath}",
        "background": "{thumbnail filePath}",
        "transparent": "{thumbnail filePath}",
        "background_artist": "{thumbnail filePath}"
      }
    }
    // other responses
  ]
}

Step 2: Filtering Songs by a Specific Genre​

We will use the genres ID from step 1 to filter and get a list of songs based on the corresponding genre.

Using the following parameters, we must make a call to GET /v2/songs:

  • genre: (Optional) Filter by genre.

For this example, we make the following call :

GET /v2/songs?genre=12

Note that we set the following parameter values:

  • genre: Replaced with genres ID from the previous step.

Step Result​

The endpoint returns song IDs and metadata for songs defined as Disney. As shown in Figure 2, in the metadata returned for the songs, the genre corresponds to the genre we requested.

Figure 2: Step 2 sample response

[
  {
    "id": "KAR:G:1698509",
    "title": "Let It Go",
    "genre": {
      "id": "12",
      "label": "Disney"
    }
    // other metadata
  }
  // other responses
]

Eras Filter​

Step 1: Retrieving an Era​

To explore the eras filter available in the API, we must make a call to GET /v2/eras.

For this example we will make the following call:

GET /v2/eras;

Step Result​

The endpoint returns all the possible eras available in the API, along with their label and thumbnails.

From the sample response shown in Figure 3, take note of the id value 80s. We will be using the genre ID in Step 2: Filtering Songs by a Specific Era.

Figure 3: Step 1 sample response

{
  "eras": [
    {
      "id": "80s",
      "label": "80s",
      "thumbnails": {
        "background": "{thumbnail filePath}",
        "transparent": "{thumbnail filePath}"
      }
    }
    // other responses
  ]
}

Step 2: Filtering Songs by a Specific Era​

We will use the eras ID from step 1 to filter and get a list of songs based on the corresponding genre.

Using the following parameters, we must make a call to GET /v2/songs:

  • era: (Optional) Filter by era.

For this example, we make the following call :

GET /v2/songs?era=80s

Note that we set the following parameter values:

  • era: Replaced with era ID from the previous step.

Step Result​

The endpoint returns song IDs and metadata for songs defined as 80s. As shown in Figure 4, in the metadata returned for the songs, the era corresponds to the era we requested.

Figure 4: Step 2 sample response

[
  {
    "id": "KAR:G:5302",
    "title": "Livin' On A Prayer",
    "release_year": 1987,
    "era": {
      "id": "80s",
      "label": "80s"
    }
    // other metadata
  }
  // other responses
]

Languages Filter​

Step 1: Retrieving a Language​

To explore the languages filter available in the API, we must make a call to GET /v2/languages.

For this example we will make the following call:

GET /v2/languages;

Step Result​

The endpoint returns all the possible eras available in the API, along with their label and thumbnails.

From the sample response shown in Figure 5, take note of the id value jpn. We will be using the genre ID in Step 2: Filtering Songs by a Specific Language.

Figure 5: Step 1 sample response

{
  "languages": [
    {
      "id": "jpn",
      "label": "Japanese",
      "thumbnails": {
        "background": "{thumbnail filePath}",
        "transparent": "{thumbnail filePath}"
      }
    }
    // other responses
  ]
}

Step 2: Filtering Songs by a Specific Language​

We will use the languages ID from step 1 to filter and get a list of songs based on the corresponding language.

Using the following parameters, we must make a call to GET /v2/songs:

  • language: (Optional) Filter by language.

For this example, we will the following call :

GET /v2/songs?language=jpn

Note that we set the following parameter values:

  • languages: Replaced with language ID from the previous step

Step Result​

The endpoint returns song IDs and metadata for songs defined as Japanese. As shown in Figure 6, in the metadata returned for the songs, the language corresponds to the language we requested.

Figure 6: Step 2 sample response

[
  {
    "id": "KAR:G:2899789",
    "title": "0 choir",
    "artist_display_name": "UVERworld",
    "languages": [
      {
        "id": "jpn",
        "label": "Japanese"
      },
      {
        "id": "eng",
        "label": "English"
      }
    ]
    // other metadata
  }
  // other responses
]

Conclusion​

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