SearchAPI

class minim.api.musixmatch.SearchAPI(client: APIClient, /)

Bases: MusixmatchResourceAPI

Search-related endpoints for the Musixmatch Lyrics API.

Note

This class groups search-related endpoints for convenience. Musixmatch does not provide a dedicated Search API.

Important

This class is managed by MusixmatchLyricsAPIClient and should not be instantiated directly.

Parameters:

clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

match_track	Matcher > matcher.track.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for it.
match_track_lyrics	Matcher > matcher.lyrics.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its lyrics.
match_track_subtitles	Matcher > matcher.subtitle.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its subtitles.
search_artists	Artist > artist.search: Search for artists in the Musixmatch catalog.
search_tracks	Track > track.search: Search for tracks in the Musixmatch catalog.

match_track(*, artist: str | None = None, track: str | None = None, isrc: str | None = None) → dict[str, Any]

Matcher > matcher.track.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for it.

Subscription

Required

Musixmatch Basic plan

Access music metadata and static lyrics. Learn more.

Parameters:

artiststr; keyword-only; optional

Artist name to match.

trackstr; keyword-only; optional

Track name to match.

isrcstr; keyword-only; optional

ISRC of the track.

Example: "USUM70905526".

Returns:

trackdict[str, Any]

Musixmatch metadata for the matched track.

Sample response

{
  "message": {
    "body": {
      "track": {
        "album_id": <int>,
        "album_name": <str>,
        "artist_id": <int>,
        "artist_name": <str>,
        "commontrack_id": <int>,
        "commontrack_isrcs": <list[list[str]]>,
        "explicit": <int>,
        "has_lyrics": <int>,
        "has_richsync": <int>,
        "has_subtitles": <int>,
        "instrumental": <int>,
        "num_favourite": <int>,
        "primary_genres": {
          "music_genre_list": [
            {
              "music_genre": {
                "music_genre_id": <int>,
                "music_genre_name": <str>,
                "music_genre_name_extended": <str>,
                "music_genre_parent_id": <int>,
                "music_genre_vanity": <str>
              }
            }
          ]
        },
        "restricted": <int>,
        "track_edit_url": <str>,
        "track_id": <int>,
        "track_isrc": <str>,
        "track_length": <int>,
        "track_lyrics_translation_status": [
          {
            "from": <str>,
            "perc": <int>,
            "to": <str>
          }
        ],
        "track_name": <str>,
        "track_rating": <int>,
        "track_share_url": <str>,
        "track_spotify_id": <str>,
        "updated_time": <str>
      }
    },
    "header": {
      "cached": <int>,
      "confidence": <int>,
      "execute_time": <float>,
      "mode": <str>,
      "status_code": <int>
    }
  }
}

match_track_lyrics(*, artist: str | None = None, track: str | None = None, isrc: str | None = None) → dict[str, Any]

Matcher > matcher.lyrics.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its lyrics.

Subscription

Required

Musixmatch Basic plan

Access music metadata and static lyrics. Learn more.

Parameters:

artiststr; keyword-only; optional

Artist name to match.

trackstr; keyword-only; optional

Track name to match.

isrcstr; keyword-only; optional

ISRC of the track.

Example: "USUM70905526".

Returns:

lyricsdict[str, Any]

Musixmatch metadata for the matched track’s lyrics.

Sample response

{
  "message": {
    "body": {
      "lyrics": {
        "explicit": <int>,
        "lyrics_body": <str>,
        "lyrics_copyright": <str>,
        "lyrics_id": <int>,
        "lyrics_language": <str>,
        "pixel_tracking_url": <str>,
        "region_restriction": {
          "allowed": <list[str]>,
          "blocked": <list[str]>
        },
        "script_tracking_url": <str>,
        "updated_time": <str>
      }
    },
    "header": {
      "execute_time": <float>,
      "status_code": <int>
    }
  }
}

match_track_subtitles(*, artist: str | None = None, track: str | None = None, isrc: str | None = None, duration: int | str | None = None, max_duration_deviation: int | str | None = None) → dict[str, Any]

Matcher > matcher.subtitle.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its subtitles.

Subscription

Required

Musixmatch Scale plan

Access time-synced lyrics. Learn more.

Parameters:

artiststr; keyword-only; optional

Artist name to match.

trackstr; keyword-only; optional

Track name to match.

isrcstr; keyword-only; optional

ISRC of the track.

Example: "USUM70905526".

durationint or str; keyword-only; optional

Target subtitle duration, in seconds.

max_duration_deviationint or str; keyword-only; optional

Maximum deviation allowed from the requested duration. Only applicable when duration is specified.

Returns:

subtitlesdict[str, Any]

Musixmatch metadata for the matched track’s subtitles.

Sample response

{
  "message": {
    "body": {
      "subtitle": {
        "html_tracking_url": <str>,
        "lyrics_copyright": <str>,
        "pixel_tracking_url": <str>,
        "published_status": <int>,
        "publisher_list": [],
        "restricted": <int>,
        "script_tracking_url": <str>,
        "subtitle_avg_count": <int>,
        "subtitle_body": <str>,
        "subtitle_id": <int>,
        "subtitle_language": <str>,
        "subtitle_language_description": <str>,
        "subtitle_length": <int>,
        "updated_time": <str>,
        "writer_list": []
      }
    },
    "header": {
      "execute_time": <float>,
      "status_code": <int>
    }
  }
}

search_artists(artist_query: str | None = None, *, artist_id: int | str | None = None, limit: int | None = None, page: int | None = None) → dict[str, Any]

Artist > artist.search: Search for artists in the Musixmatch catalog.

Subscription

Required

Musixmatch Basic plan

Access music metadata and static lyrics. Learn more.

Parameters:

artist_querystr; optional

Search query matching any word in the artist name.

artist_idint or str; keyword-only; optional

Musixmatch ID of the artist to filter results by.

Examples: 259675, "24403590".

limitint; keyword-only; optional

Maximum number of artists to return.

Valid range: 1 to 100.

API default: 10.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of artists.

Minimum value: 1.

API default: 1.

Returns:

artistsdict[str, Any]

Page of Musixmatch metadata for the matching artists.

Sample response

{
  "message": {
    "body": {
      "artist_list": [
        {
          "artist": {
            "artist_alias_list": [
              {
                "artist_alias": <str>,
              }
            ],
            "artist_comment": <str>,
            "artist_country": <str>,
            "artist_credits": {
              "artist_list": []
            },
            "artist_crowd_favourites": <int>,
            "artist_edit_url": <str>,
            "artist_facebook_url": <str>,
            "artist_fq_id": <str>,
            "artist_id": <int>,
            "artist_instagram_url": <str>,
            "artist_mbid": <str>,
            "artist_merchandising_url": <str>,
            "artist_name": <str>,
            "artist_name_translation_list": [],
            "artist_rating": <int>,
            "artist_share_url": <str>,
            "artist_tiktok_url": <str>,
            "artist_tour_url": <str>,
            "artist_twitter_url": <str>,
            "artist_vanity_id": <str>,
            "artist_website_url": <str>,
            "artist_youtube_url": <str>,
            "begin_date": <str>,
            "begin_date_year": <str>,
            "end_date": <str>,
            "end_date_year": <str>,
            "external_ids": {
              "7digital": <list[str]>,
              "amazon_music": <list[str]>,
              "itunes": <list[str]>,
              "pro_pre_release": <list[str]>,
              "spotify": <list[str]>
            },
            "managed": <int>,
            "primary_genres": {
              "music_genre_list": [
                {
                  "music_genre": {
                    "music_genre_id": <int>,
                    "music_genre_name": <str>,
                    "music_genre_name_extended": <str>,
                    "music_genre_parent_id": <int>,
                    "music_genre_vanity": <str>
                  }
                }
              ]
            },
            "restricted": <int>,
            "secondary_genres": {
              "music_genre_list": []
            },
            "updated_time": <str>
          }
        }
      ]
    },
    "header": {
      "available": <int>,
      "execute_time": <float>,
      "status_code": <int>
    }
  }
}

search_tracks(query: str | None = None, *, artist_query: str | None = None, lyrics_query: str | None = None, track_query: str | None = None, track_artist_query: str | None = None, writer_query: str | None = None, artist_id: int | str | None = None, genre_id: int | str | None = None, language: str | None = None, has_lyrics: bool | None = None, released_after: str | None = None, released_before: str | None = None, artist_popularity_sort_order: str | None = None, track_popularity_sort_order: str | None = None, page: int | None = None, limit: int | None = None) → dict[str, Any]

Track > track.search: Search for tracks in the Musixmatch catalog.

Subscription

Required

Musixmatch Basic plan

Access music metadata and static lyrics. Learn more.

Parameters:

querystr; optional

Search query matching any word in the artist name, track name, or lyrics.

artist_querystr; keyword-only; optional

Search query matching any word in the artist name.

lyrics_querystr; keyword-only; optional

Search query matching any word in the track’s lyrics.

track_querystr; keyword-only; optional

Search query matching any word in the track name.

track_artist_querystr; keyword-only; optional

Search query matching any word in the track artist name.

writer_querystr; keyword-only; optional

Search query matching any word in the track writer name.

artist_idint or str; keyword-only; optional

Musixmatch ID of the artist to filter results by.

Examples: 259675, "24403590".

genre_idint or str; keyword-only; optional

Musixmatch genre ID to filter results by.

languagestr; keyword-only; optional

ISO 639-1 language code to filter results by lyrics availability.

Example: "it".

has_lyricsbool; keyword-only; optional

Whether to only include tracks that have lyrics.

API default: False.

released_afterstr or datetime.datetime; keyword-only; optional

Only return tracks released after this date, in YYYYMMDD format.

released_beforestr or datetime.datetime; keyword-only; optional

Only return tracks released before this date, in YYYYMMDD format.

artist_popularity_sort_orderstr; keyword-only; optional

Sort order for artist popularity.

Valid values: "asc", "desc".

track_popularity_sort_orderstr; keyword-only; optional

Sort order for track popularity.

Valid values: "asc", "desc".

limitint; keyword-only; optional

Maximum number of tracks to return.

Valid range: 1 to 100.

API default: 10.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of tracks.

Minimum value: 1.

API default: 1.

Returns:

tracksdict[str, Any]

Page of Musixmatch metadata for the matching tracks.

Sample response

{
  "message": {
    "body": {
      "track_list": [
        {
          "track": {
            "album_id": <int>,
            "album_name": <str>,
            "artist_id": <int>,
            "artist_name": <str>,
            "commontrack_id": <int>,
            "commontrack_isrcs": <list[list[str]]>,
            "explicit": <int>,
            "has_lyrics": <int>,
            "has_richsync": <int>,
            "has_subtitles": <int>,
            "instrumental": <int>,
            "num_favourite": <int>,
            "primary_genres": {
              "music_genre_list": [
                {
                  "music_genre": {
                    "music_genre_id": <int>,
                    "music_genre_name": <str>,
                    "music_genre_name_extended": <str>,
                    "music_genre_parent_id": <int>,
                    "music_genre_vanity": <str>
                  }
                }
              ]
            },
            "restricted": <int>,
            "track_edit_url": <str>,
            "track_id": <int>,
            "track_isrc": <str>,
            "track_length": <int>,
            "track_lyrics_translation_status": [
              {
                "from": <str>,
                "perc": <int>,
                "to": <str>
              }
            ],
            "track_name": <str>,
            "track_rating": <int>,
            "track_share_url": <str>,
            "track_spotify_id": <str>,
            "updated_time": <str>
          }
        }
      ]
    },
    "header": {
      "available": <int>,
      "execute_time": <float>,
      "status_code": <int>
    }
  }
}