swagger: '2.0' info: title: Musixmatch API description: > Musixmatch lyrics API is a robust service that permits you to search and retrieve lyrics in the simplest possible way. It just works. Include millions of licensed lyrics on your website or in your application legally. The fastest, most powerful and legal way to display lyrics on your website or in your application. #### Read musixmatch API Terms & Conditions and the Privacy Policy: Before getting started, you must take a look at the [API Terms & Conditions](http://musixmatch.com/apiterms/) and the [Privacy Policy](https://developer.musixmatch.com/privacy). We’ve worked hard to make this service completely legal so that we are all protected from any foreseeable liability. Take the time to read this stuff. #### Register for an API key: All you need to do is [register](https://developer.musixmatch.com/signup) in order to get your API key, a mandatory parameter for most of our API calls. It’s your personal identifier and should be kept secret: ``` https://api.musixmatch.com/ws/v1.1/track.get?apikey=YOUR_API_KEY ``` #### Integrate the musixmatch service with your web site or application In the most common scenario you only need to implement two API calls: The first call is to match your catalog to ours using the [track.search](#!/Track/get_track_search) function and the second is to get the lyrics using the [track.lyrics.get](#!/Lyrics/get_track_lyrics_get) api. That’s it! ## API Methods What does the musiXmatch API do? The musiXmatch API allows you to read objects from our huge 100% licensed lyrics database. To make your life easier we are providing you with one or more examples to show you how it could work in the wild. You’ll find both the API request and API response in all the available output formats for each API call. Follow the links below for the details. The current API version is 1.1, the root URL is located at https://api.musixmatch.com/ws/1.1/ Supported input parameters can be found on the page [Input Parameters](https://developer.musixmatch.com/documentation/input-parameters). Use UTF-8 to encode arguments when calling API methods. Every response includes a status_code. A list of all status codes can be consulted at [Status Codes](https://developer.musixmatch.com/documentation/status-codes). ## Music meta data The musiXmatch api is built around lyrics, but there are many other data we provide through the api that can be used to improve every existent music service. ## Track Inside the track object you can get the following extra information: ### TRACK RATING The track rating is a score 0-100 identifying how popular is a song in musixmatch. You can use this information to sort search results, like the most popular songs of an artist, of a music genre, of a lyrics language. ### INSTRUMENTAL AND EXPLICIT FLAGS The instrumental flag identifies songs with music only, no lyrics. The explicit flag identifies songs with explicit lyrics or explicit title. We're able to identify explicit words and set the flag for the most common languages. ### FAVOURITES How many users have this song in their list of favourites. Can be used to sort tracks by num favourite to identify more popular tracks within a set. ### MUSIC GENRE The music genere of the song. Can be used to group songs by genre, as input for similarity alghorithms, artist genre identification, navigate songs by genere, etc. ### SONG TITLES TRANSLATIONS The track title, as translated in different lanauages, can be used to display the right writing for a given user, example: LIES (Bigbang) becomes 在光化門 in chinese HALLELUJAH (Bigbang) becomes ハレルヤ in japanese ## Artist Inside the artist object you can get the following nice extra information: ### COMMENTS AND COUNTRY An artist comment is a short snippet of text which can be mainly used for disambiguation. The artist country is the born country of the artist/group There are two perfect search result if you search by artist with the keyword "U2". Indeed there are two distinct music groups with this same name, one is the most known irish group of Bono Vox, the other is a less popular (world wide speaking) group from Japan. Here's how you can made use of the artist comment in your search result page: U2 (Irish rock band) U2 (あきやまうに) You can also show the artist country for even better disambiguation: U2 (Irish rock band) from Ireland U2 (あきやまうに) from Japan ARTIST TRANSLATIONS When you create a world wide music related service you have to take into consideration to display the artist name in the user's local language. These translation are also used as aliases to improve the search results. Let's use PSY for this example. Western people know him as PSY but korean want to see the original name 싸이. Using the name translations provided by our api you can show to every user the writing they expect to see. Furthermore, when you search for "psy gangnam style" or "싸이 gangnam style" with our search/match api you will still be able to find the song. ### ARTIST RATING The artist rating is a score 0-100 identifying how popular is an artist in musixmatch. You can use this information to build charts, for suggestions, to sort search results. In the example above about U2, we use the artist rating to show the irish band before the japanese one in our serp. ### ARTIST MUSIC GENRE We provide one or more main artist genre, this information can be used to calculate similar artist, suggestions, or the filter a search by artist genre. ## Album Inside the album object you can get the following nice extra information: ### ALBUM RATING The album rating is a score 0-100 identifying how popular is an album in musixmatch. You can use this information to sort search results, like the most popular albums of an artist. ### ALBUM RATING The album rating is a score 0-100 identifying how popular is an album in musixmatch. You can use this information to sort search results, like the most popular albums of an artist. ### ALBUM COPYRIGHT AND LABEL For most of our albums we can provide extra information like for example: Label: Universal-Island Records Ltd. Copyright: (P) 2013 Rubyworks, under license to Columbia Records, a Division of Sony Music Entertainment. ALBUM TYPE AND RELEASE DATE The album official release date can be used to sort an artist's albums view starting by the most recent one. Album can also be filtered or grouped by type: Single, Album, Compilation, Remix, Live. This can help to build an artist page with a more organized structure. ### ALBUM MUSIC GENRE For most of the albums we provide two groups of music genres. Primary and secondary. This information can be used to help user navigate albums by genre. An example could be: Primary genere: POP Secondary genre: K-POP or Mandopop termsOfService: 'http://musixmatch.com/apiterms/' contact: name: Musixmatch email: info@musixmatch.com url: 'https://musixmatch.com' license: name: MIT url: 'http://opensource.org/licenses/MIT' version: 1.1.0 host: api.musixmatch.com schemes: - https basePath: /ws/1.1 consumes: - application/json produces: - application/json tags: - name: Track description: '' - name: Artist description: '' - name: Album description: '' - name: Lyrics description: '' - name: Subtitle description: '' - name: Snippet description: '' externalDocs: description: Find out more about Musixmatch API url: 'https://developer.musixmatch.com/' securityDefinitions: key: type: apiKey in: query name: apikey security: - key: [] definitions: Artist: title: a Artist object description: a artist in the Musixmatch database. properties: artist_credits: type: object properties: artist_list: type: array items: type: string description: '' artist_mbid: type: string description: '' artist_name: type: string description: '' secondary_genres: type: object properties: music_genre_list: type: array items: type: string description: '' artist_alias_list: type: array items: type: object properties: artist_alias: type: string description: '' artist_vanity_id: type: string description: '' restricted: type: number description: '' artist_country: type: string description: '' artist_comment: type: string description: '' artist_name_translation_list: type: array items: type: object properties: artist_name_translation: type: object properties: language: type: string description: '' translation: type: string description: '' artist_edit_url: type: string description: '' artist_share_url: type: string description: '' artist_id: type: number description: '' updated_time: type: string description: '' managed: type: number description: '' primary_genres: type: object properties: music_genre_list: type: array items: type: object properties: music_genre: type: object properties: music_genre_parent_id: type: number description: '' music_genre_name: type: string description: '' music_genre_vanity: type: string description: '' music_genre_id: type: number description: '' music_genre_name_extended: type: string description: '' artist_twitter_url: type: string description: '' artist_rating: type: number description: '' Subtitle: title: a Subtitle object description: a synchronized lyrics subtitle in the Musixmatch database. properties: subtitle_body: type: string description: '' publisher_list: type: array items: type: string description: '' subtitle_language: type: string description: '' subtitle_language_description: type: string description: '' subtitle_id: type: number description: '' pixel_tracking_url: type: string description: '' html_tracking_url: type: string description: '' restricted: type: number description: '' lyrics_copyright: type: string description: '' script_tracking_url: type: string description: '' subtitle_length: type: number description: '' updated_time: type: string description: '' writer_list: type: array items: type: string description: '' Album: title: a Album object description: a album of songs in the Musixmatch database. properties: album_coverart_500x500: type: string description: '' restricted: type: number description: '' artist_id: type: number description: '' album_name: type: string description: '' album_coverart_800x800: type: string description: '' album_copyright: type: string description: '' album_coverart_350x350: type: string description: '' artist_name: type: string description: '' primary_genres: type: object properties: music_genre_list: type: array items: type: object properties: music_genre: type: object properties: music_genre_name_extended: type: string description: '' music_genre_vanity: type: string description: '' music_genre_parent_id: type: number description: '' music_genre_id: type: number description: '' music_genre_name: type: string description: '' album_id: type: number description: '' album_rating: type: number description: '' album_pline: type: string description: '' album_track_count: type: number description: '' album_release_type: type: string description: '' album_release_date: type: string description: '' album_edit_url: type: string description: '' updated_time: type: string description: '' secondary_genres: type: object properties: music_genre_list: type: array items: type: string description: '' album_mbid: type: string description: '' album_vanity_id: type: string description: '' album_coverart_100x100: type: string description: '' album_label: type: string description: '' Track: title: a Track object description: a song in the Musixmatch database type: object properties: instrumental: type: number description: '' album_coverart_350x350: type: string description: '' first_release_date: type: string description: '' track_isrc: type: string description: '' explicit: type: number description: '' track_edit_url: type: string description: '' num_favourite: type: number description: '' album_coverart_500x500: type: string description: '' album_name: type: string description: '' track_rating: type: number description: '' track_share_url: type: string description: '' track_soundcloud_id: type: number description: '' artist_name: type: string description: '' album_coverart_800x800: type: string description: '' album_coverart_100x100: type: string description: '' track_name_translation_list: type: array items: type: string description: '' track_name: type: string description: '' restricted: type: number description: '' has_subtitles: type: number description: '' updated_time: type: string description: '' subtitle_id: type: number description: '' lyrics_id: type: number description: '' track_spotify_id: type: string description: '' has_lyrics: type: number description: '' artist_id: type: number description: '' album_id: type: number description: '' artist_mbid: type: string description: '' secondary_genres: type: object properties: music_genre_list: type: array items: type: object properties: music_genre: type: object properties: music_genre_vanity: type: string description: '' music_genre_name_extended: type: string description: '' music_genre_parent_id: type: number description: '' music_genre_name: type: string description: '' music_genre_id: type: number description: '' commontrack_vanity_id: type: string description: '' track_id: type: number description: '' track_xboxmusic_id: type: string description: '' primary_genres: type: object properties: music_genre_list: type: array items: type: object properties: music_genre: type: object properties: music_genre_vanity: type: string description: '' music_genre_name_extended: type: string description: '' music_genre_name: type: string description: '' music_genre_parent_id: type: number description: '' music_genre_id: type: number description: '' track_length: type: number description: '' track_mbid: type: string description: '' commontrack_id: type: number description: '' Lyrics: title: a Lyrics object description: a Lyrics in the Musixmatch database. type: object properties: instrumental: type: number description: '' pixel_tracking_url: type: string description: '' publisher_list: type: array items: type: string description: '' lyrics_language_description: type: string description: '' restricted: type: number description: '' updated_time: type: string description: '' explicit: type: number description: '' lyrics_copyright: type: string description: '' html_tracking_url: type: string description: '' lyrics_language: type: string description: '' script_tracking_url: type: string description: '' verified: type: number description: '' lyrics_body: type: string description: '' lyrics_id: type: number description: '' writer_list: type: array items: type: string description: '' can_edit: type: number description: '' action_requested: type: string description: '' locked: type: number description: '' Snippet: title: a Snippet object description: Snippet of lyrics text in the Musixmatch database. type: object properties: html_tracking_url: type: string description: '' instrumental: type: number description: '' restricted: type: number description: '' updated_time: type: string description: '' snippet_body: type: string description: '' pixel_tracking_url: type: string description: '' snippet_id: type: number description: '' script_tracking_url: type: string description: '' snippet_language: type: string description: '' paths: /album.tracks.get: get: security: - key: [] tags: - Track summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: album_id type: string in: query description: The musiXmatch album id required: true - name: f_has_lyrics type: string in: query description: 'When set, filter only contents with lyrics' required: false - name: page type: number in: query description: Define the page number for paginated results required: false - name: page_size type: number in: query description: Define the page size for paginated results.Range is 1 to 100. required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' available: type: number description: '' execute_time: type: number description: '' body: type: object properties: track_list: description: 'A list of tracks' type: array items: $ref: '#/definitions/Track' /album.get: get: security: - key: [] tags: - Album summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: album_id type: string in: query description: The musiXmatch album id required: true responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: album: $ref: '#/definitions/Album' /artist.related.get: get: security: - key: [] tags: - Artist summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: artist_id type: string in: query description: The musiXmatch artist id required: true - name: page_size type: number in: query description: Define the page size for paginated results.Range is 1 to 100. required: false - name: page type: number in: query description: Define the page number for paginated results required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: available: type: number description: '' status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: artist_list: description: 'A list of artists' type: array items: type: object properties: artist: $ref: '#/definitions/Artist' /artist.albums.get: get: security: - key: [] tags: - Album summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: artist_id type: string in: query description: The musiXmatch artist id required: true - name: s_release_date type: string in: query description: Sort by release date (asc|desc) required: false - name: g_album_name type: string in: query description: Group by Album Name required: false - name: page_size type: number in: query description: Define the page size for paginated results.Range is 1 to 100. required: false - name: page type: number in: query description: Define the page number for paginated results required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: available: type: number description: '' status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: album_list: description: 'A list of albums' type: array items: type: object properties: album: $ref: '#/definitions/Album' /artist.search: get: security: - key: [] tags: - Artist summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: q_artist type: string in: query description: The song artist required: false - name: f_artist_id type: number in: query description: 'When set, filter by this artist id' required: false - name: page type: number in: query description: Define the page number for paginated results required: false - name: page_size type: number in: query description: Define the page size for paginated results.Range is 1 to 100. required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: available: type: number description: '' status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: artist_list: description: 'A list of artists' type: array items: type: object properties: artist: $ref: '#/definitions/Artist' /artist.get: get: security: - key: [] tags: - Artist summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: artist_id type: string in: query description: "\tThe musiXmatch artist id" required: true responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: artist: $ref: '#/definitions/Artist' /matcher.subtitle.get: get: security: - key: [] tags: - Subtitle summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: q_track type: string in: query description: The song title required: false - name: q_artist type: string in: query description: "\tThe song artist" required: false - name: f_subtitle_length type: number in: query description: Filter by subtitle length in seconds required: false - name: f_subtitle_length_max_deviation type: number in: query description: Max deviation for a subtitle length in seconds required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: subtitle: $ref: '#/definitions/Subtitle' /matcher.track.get: get: security: - key: [] tags: - Track summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: q_artist type: string in: query description: The song artist required: false - name: q_track type: string in: query description: The song title required: false - name: f_has_lyrics type: number in: query description: 'When set, filter only contents with lyrics' required: false - name: f_has_subtitle type: number in: query description: 'When set, filter only contents with subtitles' required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: track: $ref: '#/definitions/Track' /matcher.lyrics.get: get: security: - key: [] tags: - Lyrics summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: q_track type: string in: query description: The song title required: false - name: q_artist type: string in: query description: The song artist required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: lyrics: $ref: '#/definitions/Lyrics' /track.snippet.get: get: security: - key: [] tags: - Snippet summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: track_id type: string in: query description: The musiXmatch track id required: true responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: snippet: $ref: '#/definitions/Snippet' /track.lyrics.get: get: security: - key: [] tags: - Lyrics summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: track_id type: string in: query description: The musiXmatch track id required: true responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: lyrics: $ref: '#/definitions/Lyrics' /track.subtitle.get: get: security: - key: [] tags: - Subtitle summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: track_id type: string in: query description: The musiXmatch track id required: true responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: subtitle: $ref: '#/definitions/Subtitle' /track.get: get: security: - key: [] tags: - Track summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: track_id type: string in: query description: The musiXmatch track id required: true responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: track: $ref: '#/definitions/Track' /track.search: get: security: - key: [] tags: - Track summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: q_track type: string in: query description: The song title required: false - name: q_artist type: string in: query description: The song artist required: false - name: q_lyrics type: string in: query description: Any word in the lyrics required: false - name: f_artist_id type: number in: query description: 'When set, filter by this artist id' required: false - name: f_music_genre_id type: number in: query description: 'When set, filter by this music category id' required: false - name: f_lyrics_language type: number in: query description: 'Filter by the lyrics language (en,it,..)' required: false - name: f_has_lyrics type: number in: query description: 'When set, filter only contents with lyrics' required: false - name: s_artist_rating type: string in: query description: Sort by our popularity index for artists (asc|desc) required: false - name: s_track_rating type: string in: query description: Sort by our popularity index for tracks (asc|desc) required: false - name: quorum_factor type: number in: query description: >- Search only a part of the given query string.Allowed range is (0.1 – 0.9) default: 1 required: false - name: page_size type: number in: query description: Define the page size for paginated results.Range is 1 to 100. required: false - name: page type: number in: query description: Define the page number for paginated results required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: available: type: number status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: track_list: description: 'A list of tracks' type: array items: type: object properties: track: $ref: '#/definitions/Track' /chart.tracks.get: get: security: - key: [] tags: - Track summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: page type: number in: query description: Define the page number for paginated results required: false - name: page_size type: number in: query description: Define the page size for paginated results.Range is 1 to 100. required: false - name: country type: string in: query description: A valid ISO 3166 country code default: us required: false - name: f_has_lyrics type: string in: query description: 'When set, filter only contents with lyrics' required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: available: type: number status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: track_list: description: 'A list of tracks' type: array items: type: object properties: track: $ref: '#/definitions/Track' /chart.artists.get: get: security: - key: [] tags: - Artist summary: '' description: '' parameters: - name: format type: string in: query description: 'output format: json, jsonp, xml.' default: json required: false - name: callback type: string in: query description: jsonp callback required: false - name: page type: number in: query description: Define the page number for paginated results required: false - name: page_size type: number in: query description: Define the page size for paginated results.Range is 1 to 100. required: false - name: country type: string in: query description: A valid ISO 3166 country code default: us required: false responses: '200': description: The request was successful. schema: type: object properties: message: type: object properties: header: type: object properties: available: type: number status_code: type: number description: '' execute_time: type: number description: '' body: type: object properties: artist_list: description: 'A list of artists' type: array items: type: object properties: artist: $ref: '#/definitions/Artist'