API Reference Search

The Docs are work-in-progress except API References!

Search for Music

Get information about music that match provided artist and song name.

Request

<ARTIST> string
Required

The artist name to search for.

Example: /api/search/Madeon:Song, /api/search/Rick Astley:Song

<Song> string
Required

The song or album name to search for.

Example: /api/search/Madeon:Shelter, /api/search/Rick Astley:Never Gonna Give You Up

The artist name and song name must be separated by a colon (:)
platform string
Optional

The music platform to retrieve music information/metadata from.

If provided, music information/metadata will be retrieved (only) from this music platform. If it is not provided or does not contain allowed values, it will be simply ignored and music information/metadata will be retrieved from all the available music platforms.

Default: "all"
Allowed values: "all", "deezer", "itunes" (or "apple-music"), "kkbox", "spotify", "ytmusic"
Note: The query parameter for platform is NOT ?platform=<name> (i.e. key-value pair)! Instead, you just provide the platform name directly as a key.
Example: /api/search/Madeon:Shelter?spotify

lyrics string
Optional

If provided, the API will only return the lyrics of the requested song.

Note: The query parameter for lyrics is NOT key-value pair! You only need to provide the query parameter itself. Also, if this query parameter is provided, all the other query parameters will be ignored.
Example: /api/search/Madeon:Shelter?lyrics

embed string
Optional

If provided, the API will return a ready-to-embed HTML music info card (instead of JSON) for the requested song and artist. You should use it inside an <iframe>.

Note: When using this query parameter, the API will ignore the platform query parameter and always return the music information/metadata from all the available music platforms.
Examples: 

<iframe src="https://yutify.cheapnightbot.me/api/search/Madeon:Shelter?embed" frameborder="0" width="100%" height="380" loading="lazy"></iframe>

Search embed example

Response

Successful response with the requested information about the music.

Response Examples
/api/search/Artist:Song 
{
  "album_art": "https://deezer.com/6663629/album_art.jpg",
  "album_art_source": "deezer",
  "album_title": "Song",
  "album_type": "single",
  "artists": "Artist",
  "genre": "Electronic",
  "id": {
    "deezer": 6663629,
    "itunes": 6663629,
    "kkbox": "Dx6duYxp9UagGhiqwq",
    "spotify": "6rqhFgbbKwnb9MLmUQDhG6",
    "ytmusic": "xD69iRAEiu0"
  },
  "isrc": "US1234567890",
  "lyrics": "These are the lyrics of the song...",
  "release_date": "2025-10-25",
  "tempo": null,
  "title": "Song",
  "type": "track",
  "upc": null,
  "url": {
    "deezer": "https://www.deezer.com/track/6663629",
    "itunes": "https://music.apple.com/track/6663629",
    "kkbox": "https://www.kkbox.com/tw/tc/song/Dx6duYxp9UagGhiqwq",
    "spotify": "https://open.spotify.com/track/6rqhFgbbKwnb9MLmUQDhG6",
    "ytmusic": "https://music.youtube.com/watch?v=xD69iRAEiu0"
  }
}
/api/search/Artist:Song?deezer
{
  "album_art": "https://deezer.com/6663629/album_art.jpg",
  "album_title": "Song",
  "album_type": "single",
  "artists": "Artist",
  "genre": null,
  "id": 6663629,
  "isrc": "US1234567890",
  "lyrics": null,
  "release_date": "2025-10-25",
  "tempo": 0,
  "title": "Song",
  "type": "track",
  "upc": null,
  "url": "https://www.deezer.com/track/6663629"
}
/api/search/Artist:Song?lyrics
{
  "instrumental": false,
  "trackName": "Song",
  "artistName": "Artist",
  "plainLyrics": "These are the lyrics of the song... New lines are indicated by \n (backslash n).",
  "syncedLyrics": "[00:15.96] These are the synced lyrics of the song with timestamps for each line (idk how to exaplain..)."
}
Note if lyrics query parameter was provided, none of the fields below (even marked with Always Present) will be included in the response. Only the ones with With Lyrics will be included. See the response example above.
album_art string
Always Present

The URL to the album art (image) of the requested music.

album_art_source string

The music platform name where the album art retrieved from.
Only present if music information was requested for all the streaming platforms either by providing ?platform="all" query or omitting it altogether (which is default).

Example: "deezer"

album_title string
Always Present

The title of the album for the requested music.

Note: It will be the same as the title if album_type is "single.

album_type string
Always Present

The type of the album for the requested music.

Available values: "album", "ep", "single"
Example: "single"

artists string
Always Present

A comma-separated string of artist name(s) for the requested music.

Example: "Ahrix", "花譜, Hoshimachi Suisei"

artistName string
With Lyrics

A semi-colon (;) separated string of artist name(s) for the requested music.

Example: "Ahrix", "花譜; Hoshimachi Suisei"

genre string null
Always Present

The genre of the requested music.

Example: "Electronic"

id integer string object
Always Present

The unique ID of the music on the requested music platform(s).
The "id" itself can be either integer or string based on the music platform. For example, "id" for YouTube Music will be 11 characters long alpha-numeric string.

Note: It will be a string or integer, if query parameter for platform contains a value from "Allowed values" except "all". Otherwise, if platform="all" or no query parameter provided, it will be an object with each key representing the music platform name and value being actual ID of the music on that platform.
Example: Request and Response showing what "id" field looks like:

/api/search/Madeon:Shelter?spotify
"id": "7e8XZUuB78uEOil4i3ONox"
/api/search/Madeon:Shelter
The music platform keys in this object can vary based on if that music found on respective platform or not. For example, if the music was not found on Spotify, the "id" object will not have "spotify" key. 
"id": {
  "itunes": 123456789,
  "deezer": 123456789,
  "kkbox": "XyxzETEWlclsnflt",
  "spotify": "7e8XZUuB78uEOil4i3ONox",
  "ytmusic": "AdLFtTiA8d5"
}
isrc string null
Always Present

The ISRC code of the requested music. If the album_type is not "single", then it will be null.

instrumental boolean
With Lyrics

Indicates whether the requested music is an instrumental and might not have lyrics or not.

lyrics string null
Always Present

The lyrics of the requested music.

plainLyrics string
With Lyrics

The plain lyrics of the requested music without any formatting. New lines are indicated by \n (backslash n).

Example: 

{
  "plainLyrics": "Never gonna give you up\nNever gonna let you down...",
}
release_date string
Always Present

The date when requested music was released in ISO format: YYYY-MM-DD

Example: "2025-05-14"

syncedLyrics string
With Lyrics

Time-synchronized lyrics with timestamps for each line. New lines are indicated by \n (backslash n) and each line starts with a timestamp indicating when it should

Example: 

{
  "syncedLyrics": "[00:43.08] Never gonna give you up\n[00:45.03] Never gonna let you down...",
}
tempo integer null
Always Present

The tempo of the requested music in beats per minute (BPM).
Currently, it is always going to be null. Please see this issue on GitHub for more information.

title string
Always Present

The title / name of the requested music.

trackName string
With Lyrics

The title / name of the requested music.

type string
Always Present

The type of the requested music.

Available values: "album", "track"
Note: Don't get confused with album_type! This one tells you whether you requested a track (which can be part of an album) or an album itself.
Example: If you requested a track "Third Track" which is part of an album "Best Album", then "type" will be track. However, if you requested "Best Album", the "type" will be "album".

upc string null
Always Present

The UPC code of the requested music. If the album_type is not "album" or "ep", then it will be null.

url string object
Always Present

The streaming URL of the music on the requested music platform(s).

Note: It will be a string, if query parameter for platform contains a value from "Allowed values" except "all". Otherwise, if platform="all" or no query parameter provided, it will be an object with each key representing the music platform name and value being actual streaming URL of the music on that platform.
Example: Request and Response showing what "url" field looks like:

/api/search/Madeon:Shelter?spotify
"url": "https://open.spotify.com/track/7e8XZUuB78uEOil4i3ONox"
/api/search/Madeon:Shelter
The music platform keys in this object can vary based on if that music found on respective platform or not. For example, if the music was not found on Spotify, the "url" object will not have "spotify" key. 
"url": {
  "itunes": "https://music.apple.com/album/123456789",
  "deezer": "https://www.deezer.com/track/123456789",
  "kkbox": "https://www.kkbox.com/song/XyxzETEWlclsnflt",
  "spotify": "https://open.spotify.com/track/7e8XZUuB78uEOil4i3ONox",
  "ytmusic": "https://music.youtube.com/watch?v=AdLFtTiA8d5"
}

Successful response, but requested music (information) was not found.

Response Examples
/api/search/Artist:Song 
{
  "error": "Couldn't find 'Song' by 'Artist'"
}
/api/search/Artist:Song?deezer
{
  "error": "Couldn't find 'Song' by 'Artist' on platform 'Deezer'"
}
error string
Always Present

The error message explaining that the music was not found.
If music information was requested for a specific platform, it will contain the platform name.

Unsuccessful response explaining that you have exceeded the default ratelimit.

Response Examples
/api/search/Artist:Song 
{
  "error": "ratelimit exceeded! you are allowed to make 20 request(s) per 1 minute."
}
error string
Always Present

The error message explaining you have exceeded the default ratelimit.

The default ratelimit is 20 requests per 1 minute, but might change.
It will always contain what default ratelimits are in this format: "x requests per y timeframe".