├── .github └── workflows │ └── main.yml ├── .gitignore ├── README.md ├── docs ├── album │ ├── getInfo.md │ ├── getTags.md │ ├── getTopTags.md │ └── search.md ├── artist │ ├── getCorrection.md │ ├── getInfo.md │ ├── getSimilar.md │ ├── getTags.md │ ├── getTopAlbums.md │ ├── getTopTags.md │ ├── getTopTracks.md │ └── search.md ├── auth │ ├── Desktop.md │ ├── getSession.md │ ├── getToken.md │ └── signature.md ├── bugs.md ├── chart │ ├── getTopArtists.md │ ├── getTopTags.md │ └── getTopTracks.md ├── codes.md ├── geo │ ├── getTopArtists.md │ └── getTopTracks.md ├── index.md ├── library │ └── getArtists.md ├── tag │ ├── getInfo.md │ ├── getSimilar.md │ ├── getTopAlbums.md │ ├── getTopArtists.md │ ├── getTopTags.md │ ├── getTopTracks.md │ └── getWeeklyChartList.md ├── track │ ├── getCorrection.md │ ├── getInfo.md │ ├── getSimilar.md │ ├── getTags.md │ ├── getTopTags.md │ └── search.md └── user │ ├── getFriends.md │ ├── getInfo.md │ ├── getLovedTracks.md │ ├── getPersonalTags.md │ ├── getRecentTracks.md │ ├── getTopAlbums.md │ ├── getTopArtists.md │ ├── getTopTags.md │ ├── getTopTracks.md │ ├── getWeeklyAlbumChart.md │ ├── getWeeklyArtistChart.md │ ├── getWeeklyChartList.md │ └── getWeeklyTrackChart.md └── mkdocs.yml /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: Build Documentation using MkDocs 2 | 3 | # Controls when the action will run. Triggers the workflow on push or pull request 4 | # events but only for the master branch 5 | on: 6 | push: 7 | branches: [master] 8 | 9 | jobs: 10 | build: 11 | name: Build and Deploy Documentation 12 | runs-on: ubuntu-latest 13 | steps: 14 | - name: Checkout Master 15 | uses: actions/checkout@v2 16 | 17 | - name: Set up Python 3.7 18 | uses: actions/setup-python@v2 19 | with: 20 | python-version: '3.x' 21 | 22 | - name: Install dependencies 23 | run: | 24 | python -m pip install --upgrade pip 25 | pip install mkdocs-material 26 | 27 | - name: Deploy 28 | run: | 29 | git pull 30 | mkdocs gh-deploy 31 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | site/ -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Unofficial last.fm API documentation 2 | 3 | This is a community initiative by members of the last.fm Discord to create better documentation for the last.fm API. Anyone is welcome to join and help create better documentation. 4 | 5 | ## Running the project locally 6 | 7 | To edit the documentation: 8 | 9 | 1. Install mkdocs: https://www.mkdocs.org/ 10 | 11 | 2. Install mkdocs-material: https://squidfunk.github.io/mkdocs-material/getting-started/ 12 | 13 | 3. Clone the repo 14 | 15 | 4. See a live preview using `mkdocs serve` 16 | 17 | 5. Deploy using `mkdocs gh-deploy` 18 | 19 | 20 | ## Updating your local installation (Windows) 21 | 22 | 1. Pip (as admin!): `python -m pip install -U pip` 23 | 24 | 2. Upgrade mkdocs: `pip install -U mkdocs` 25 | 26 | 3. Update mkdocs-material: `pip install --upgrade mkdocs-material` 27 | -------------------------------------------------------------------------------- /docs/album/getTags.md: -------------------------------------------------------------------------------- 1 | Get the tags applied by an individual user to an album on Last.fm. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: \* | The artist which's album should be fetched. 9 | | `album` | [string][string] | `none` | :white_check_mark: \* | The album that should be fetched. 10 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The album's MusicBrainz ID. 11 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Automatically corrects any mistakes in the artist's name. 12 | | `user` | [string][string] | `none` | :negative_squared_cross_mark: | If not in authenticated mode, this field should be provided with the user that should be looked up. 13 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 14 | 15 | \* Required unless you are using a MusicBrainz ID for the album. 16 | 17 | ## Responses 18 | Errors: 19 | 20 | - 6 : Invalid parameters - Your request is missing a required parameter 21 | - 8 : Operation failed - Something else went wrong 22 | - 9 : Invalid session key - Please re-authenticate 23 | - 10 : Invalid API key - You must be granted a valid key by last.fm 24 | - 11 : Service Offline - This service is temporarily offline. Try again later. 25 | - 13 : Invalid method signature supplied 26 | - 16 : There was a temporary error processing your request. Please try again 27 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 28 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 29 | 30 | !!! Warning 31 | This API call returns 200 OK HTTP status codes even when the response contains an error. 32 | 33 | ## Examples 34 | 35 | ??? note "Example response" 36 | 37 | | Parameter | Value | 38 | | --------- | ------------- | 39 | | artist | Metallica | 40 | | album | Metallica | 41 | | user | Burdayy | 42 | | api_key | YOUR_API_KEY | 43 | | format | json | 44 | 45 | HTTP status: `200 OK` 46 | 47 | ``` 48 | https://ws.audioscrobbler.com/2.0/?method=album.getTags&artist=Metallica&album=Metallica&user=Burdayy&api_key=YOUR_API_KEY&format=json 49 | ``` 50 | 51 | ```json 52 | { 53 | "tags": { 54 | "tag": [ 55 | { 56 | "name": "classic metal", 57 | "url": "https://www.last.fm/tag/classic+metal" 58 | } 59 | ], 60 | "@attr": { 61 | "artist": "Metallica", 62 | "album": "Metallica" 63 | } 64 | } 65 | } 66 | 67 | ``` 68 | 69 | ??? warning "Example response of an artist/album that doesnt exist" 70 | HTTP status: `200 OK` 71 | 72 | ``` 73 | https://ws.audioscrobbler.com/2.0/?method=album.gettags&artist=ArtistThatDoesntExist&album=metallica&user=burdayy&api_key=YOUR_API_KEY&format=json 74 | ``` 75 | ```json 76 | { 77 | "error": 6, 78 | "message": "Album not found", 79 | "links": [] 80 | } 81 | ``` 82 | 83 | ??? warning "Example response of an user that doesnt exist" 84 | HTTP status: `200 OK` 85 | 86 | ``` 87 | https://ws.audioscrobbler.com/2.0/?method=album.gettags&artist=metallica&album=metallica&user=UserThatDoesntExist&api_key=YOUR_API_KEY&format=json 88 | ``` 89 | ```json 90 | { 91 | "error": 6, 92 | "message": "User not found", 93 | "links": [] 94 | } 95 | ``` 96 | 97 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 98 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 99 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/album/getTopTags.md: -------------------------------------------------------------------------------- 1 | Get the top tags for an album on Last.fm, ordered by popularity. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: \* | The artist which's album should be fetched. 9 | | `album` | [string][string] | `none` | :white_check_mark: \* | The album that should be fetched. 10 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The album's MusicBrainz ID. 11 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Automatically corrects any mistakes in the artist's name. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | \* Required unless you are using a MusicBrainz ID for the album. 15 | 16 | ## Responses 17 | Errors: 18 | 19 | - 6 : Invalid parameters - Your request is missing a required parameter 20 | - 8 : Operation failed - Something else went wrong 21 | - 9 : Invalid session key - Please re-authenticate 22 | - 10 : Invalid API key - You must be granted a valid key by last.fm 23 | - 11 : Service Offline - This service is temporarily offline. Try again later. 24 | - 13 : Invalid method signature supplied 25 | - 16 : There was a temporary error processing your request. Please try again 26 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 27 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 28 | 29 | !!! Warning 30 | This API call returns 200 OK HTTP status codes even when the response contains an error. 31 | 32 | ## Attributes 33 | 34 | count : A weighted count of how often the tag was applied, with a maximum of 100 35 | 36 | ## Examples 37 | 38 | ??? note "Example response" 39 | 40 | | Parameter | Value | 41 | | --------- | ------------- | 42 | | artist | Metallica | 43 | | album | Metallica | 44 | | user | Burdayy | 45 | | api_key | YOUR_API_KEY | 46 | | format | json | 47 | 48 | HTTP status: `200 OK` 49 | 50 | ``` 51 | https://ws.audioscrobbler.com/2.0/?method=album.getTopTags&artist=Metallica&album=Metallica&user=Burdayy&api_key=YOUR_API_KEY&format=json 52 | ``` 53 | 54 | ```json 55 | { 56 | "tags": { 57 | "tag": [ 58 | { 59 | "name": "classic metal", 60 | "url": "https://www.last.fm/tag/classic+metal" 61 | } 62 | ], 63 | "@attr": { 64 | "artist": "Metallica", 65 | "album": "Metallica" 66 | } 67 | } 68 | } 69 | 70 | ``` 71 | 72 | ??? warning "Example response of an artist/album that doesnt exist" 73 | HTTP status: `200 OK` 74 | 75 | ``` 76 | https://ws.audioscrobbler.com/2.0/?method=album.gettags&artist=ArtistThatDoesntExist&album=metallica&user=burdayy&api_key=YOUR_API_KEY&format=json 77 | ``` 78 | ```json 79 | { 80 | "error": 6, 81 | "message": "Album not found", 82 | "links": [] 83 | } 84 | ``` 85 | 86 | ??? warning "Example response of an user that doesnt exist" 87 | HTTP status: `200 OK` 88 | 89 | ``` 90 | https://ws.audioscrobbler.com/2.0/?method=album.gettags&artist=metallica&album=metallica&user=UserThatDoesntExist&api_key=YOUR_API_KEY&format=json 91 | ``` 92 | ```json 93 | { 94 | "error": 6, 95 | "message": "User not found", 96 | "links": [] 97 | } 98 | ``` 99 | 100 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 101 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 102 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/album/search.md: -------------------------------------------------------------------------------- 1 | Get the top tags for an album on Last.fm, ordered by popularity. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `album` | [string][string] | `none` | :white_check_mark: | The album that should be fetched. 9 | | `limit` | [number][number] | 30 | :negative_squared_cross_mark: | The number of results to fetch per page. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | ## Responses 14 | Errors: 15 | 16 | - 6 : Invalid parameters - Your request is missing a required parameter 17 | - 8 : Operation failed - Something else went wrong 18 | - 9 : Invalid session key - Please re-authenticate 19 | - 10 : Invalid API key - You must be granted a valid key by last.fm 20 | - 11 : Service Offline - This service is temporarily offline. Try again later. 21 | - 13 : Invalid method signature supplied 22 | - 16 : There was a temporary error processing your request. Please try again 23 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 24 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 25 | 26 | !!! Warning 27 | This API call returns 200 OK HTTP status codes even when the response contains an error. 28 | 29 | ## Examples 30 | 31 | ??? note "Example response" 32 | 33 | | Parameter | Value | 34 | | --------- | ------------- | 35 | | album | Greatest Hits | 36 | | page | 2 | 37 | | api_key | YOUR_API_KEY | 38 | | format | json | 39 | 40 | HTTP status: `200 OK` 41 | 42 | ``` 43 | https://ws.audioscrobbler.com/2.0/?method=album.search&album=Greatest%20Hits&page=2&api_key=YOUR_API_KEY&format=json 44 | ``` 45 | 46 | ```json 47 | { 48 | "results": { 49 | "opensearch:Query": { 50 | "#text": "", 51 | "role": "request", 52 | "searchTerms": "greatest hits", 53 | "startPage": "2" 54 | }, 55 | "opensearch:totalResults": "1068391", 56 | "opensearch:startIndex": "50", 57 | "opensearch:itemsPerPage": "50", 58 | "album": [ 59 | { 60 | "name": "Greatest Hits", 61 | "artist": "Simply Red", 62 | "url": "https://www.last.fm/music/Simply+Red/Greatest+Hits", 63 | "image": [ 64 | { 65 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/d6a2c56c7b6295e99c8213987363d8ff.png", 66 | "size": "small" 67 | }, 68 | { 69 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/d6a2c56c7b6295e99c8213987363d8ff.png", 70 | "size": "medium" 71 | }, 72 | { 73 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/d6a2c56c7b6295e99c8213987363d8ff.png", 74 | "size": "large" 75 | }, 76 | { 77 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/d6a2c56c7b6295e99c8213987363d8ff.png", 78 | "size": "extralarge" 79 | } 80 | ], 81 | "streamable": "0", 82 | "mbid": "fb871fa5-23f2-387a-be2a-c3f1ad074393" 83 | }, 84 | ] 85 | 86 | "@attr": { 87 | "for": "greatest hits" 88 | } 89 | } 90 | } 91 | ``` 92 | 93 | ??? warning "Example response of an album that doesnt exist" 94 | HTTP status: `200 OK` 95 | 96 | ``` 97 | https://ws.audioscrobbler.com/2.0/?method=album.search&album=albumthatdoesntexist&page=2&api_key=YOUR_API_KEY&format=json 98 | ``` 99 | ```json 100 | { 101 | "results": { 102 | "opensearch:Query": { 103 | "#text": "", 104 | "role": "request", 105 | "searchTerms": "albumthatdoesntexist", 106 | "startPage": "2" 107 | }, 108 | "opensearch:totalResults": "0", 109 | "opensearch:startIndex": "50", 110 | "opensearch:itemsPerPage": "50", 111 | "albummatches": { 112 | "album": [] 113 | }, 114 | "@attr": { 115 | "for": "albumthatdoesntexist" 116 | } 117 | } 118 | } 119 | ``` 120 | 121 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 122 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 123 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/artist/getCorrection.md: -------------------------------------------------------------------------------- 1 | Use the Last.fm corrections data to check whether the supplied artist has a correction to a canonical artist. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: | The artist name to correct. 9 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 10 | 11 | ## Responses 12 | Errors: 13 | 14 | - 2 : Invalid service - This service does not exist 15 | - 3 : Invalid Method - No method with that name in this package 16 | - 4 : Authentication Failed - You do not have permissions to access the service 17 | - 5 : Invalid format - This service doesn't exist in that format 18 | - 6 : Invalid parameters - Your request is missing a required parameter 19 | - 7 : Invalid resource specified 20 | - 8 : Operation failed - Something else went wrong 21 | - 9 : Invalid session key - Please re-authenticate 22 | - 10 : Invalid API key - You must be granted a valid key by last.fm 23 | - 11 : Service Offline - This service is temporarily offline. Try again later. 24 | - 13 : Invalid method signature supplied 25 | - 16 : There was a temporary error processing your request. Please try again 26 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 27 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 28 | 29 | !!! Warning 30 | This API call returns 200 OK HTTP status codes even when the response contains an error. 31 | 32 | ## Examples 33 | 34 | ??? note "Example response" 35 | 36 | | Parameter | Value | 37 | | --------- | ------------- | 38 | | artist | Avici | 39 | | api_key | YOUR_API_KEY | 40 | | format | json | 41 | 42 | HTTP status: `200 OK` 43 | 44 | ``` 45 | https://ws.audioscrobbler.com/2.0/?method=artist.getCorrection&artist=Avici&api_key=YOUR_API_KEY&format=json 46 | ``` 47 | 48 | ```json 49 | { 50 | "corrections": { 51 | "correction": { 52 | "artist": { 53 | "name": "Avicii", 54 | "mbid": "c85cfd6b-b1e9-4a50-bd55-eb725f04f7d5", 55 | "url": "https://www.last.fm/music/Avicii" 56 | }, 57 | "@attr": { 58 | "index": "0" 59 | } 60 | } 61 | } 62 | } 63 | ``` 64 | 65 | ??? warning "Example response of an artist/track that doesnt exist" 66 | HTTP status: `200 OK` 67 | 68 | ``` 69 | https://ws.audioscrobbler.com/2.0/?method=artist.getCorrection&artist=artistdoesntexist&api_key=YOUR_API_KEY&format=json 70 | ``` 71 | ```json 72 | { 73 | "corrections": "\n " 74 | } 75 | ``` 76 | 77 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 78 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/artist/getSimilar.md: -------------------------------------------------------------------------------- 1 | Get all the artists similar to this artist. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: \* | The artist name to fetch information for. 9 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The artist's MusicBrainz ID. 10 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Transform misspelled artist names into correct artist names, returning the correct version instead. The corrected artist name will be returned in the response. 11 | | `limit` | [number][number] | 30 | :negative_squared_cross_mark: | The number of results to fetch per page. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | \* Required unless you are using a MusicBrainz ID for the artist. 15 | 16 | ## Responses 17 | Errors: 18 | 19 | - 2 : Invalid service - This service does not exist 20 | - 3 : Invalid Method - No method with that name in this package 21 | - 4 : Authentication Failed - You do not have permissions to access the service 22 | - 5 : Invalid format - This service doesn't exist in that format 23 | - 6 : Invalid parameters - Your request is missing a required parameter 24 | - 7 : Invalid resource specified 25 | - 8 : Operation failed - Something else went wrong 26 | - 9 : Invalid session key - Please re-authenticate 27 | - 10 : Invalid API key - You must be granted a valid key by last.fm 28 | - 11 : Service Offline - This service is temporarily offline. Try again later. 29 | - 13 : Invalid method signature supplied 30 | - 16 : There was a temporary error processing your request. Please try again 31 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 32 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 33 | 34 | !!! Warning 35 | This API call returns 200 OK HTTP status codes even when the response contains an error. 36 | 37 | ## Examples 38 | 39 | ??? note "Example response" 40 | 41 | | Parameter | Value | 42 | | --------- | ------------- | 43 | | artist | Metallica | 44 | | api_key | YOUR_API_KEY | 45 | | format | json | 46 | 47 | HTTP status: `200 OK` 48 | 49 | ``` 50 | https://ws.audioscrobbler.com/2.0/?method=artist.getSimilar&artist=Metallica&api_key=YOUR_API_KEY&format=json 51 | ``` 52 | 53 | ```json 54 | { 55 | "similarartists": { 56 | "artist": [ 57 | { 58 | "name": "Megadeth", 59 | "mbid": "a9044915-8be3-4c7e-b11f-9e2d2ea0a91e", 60 | "match": "1", 61 | "url": "https://www.last.fm/music/Megadeth", 62 | "image": [ 63 | { 64 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 65 | "size": "small" 66 | }, 67 | { 68 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 69 | "size": "medium" 70 | }, 71 | { 72 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 73 | "size": "large" 74 | }, 75 | { 76 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 77 | "size": "extralarge" 78 | }, 79 | { 80 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 81 | "size": "mega" 82 | }, 83 | { 84 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 85 | "size": "" 86 | } 87 | ], 88 | "streamable": "0" 89 | }, 90 | { 91 | "name": "Pantera", 92 | "mbid": "541f16f5-ad7a-428e-af89-9fa1b16d3c9c", 93 | "match": "0.600213", 94 | "url": "https://www.last.fm/music/Pantera", 95 | "image": [ 96 | { 97 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 98 | "size": "small" 99 | }, 100 | { 101 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 102 | "size": "medium" 103 | }, 104 | { 105 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 106 | "size": "large" 107 | }, 108 | { 109 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 110 | "size": "extralarge" 111 | }, 112 | { 113 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 114 | "size": "mega" 115 | }, 116 | { 117 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 118 | "size": "" 119 | } 120 | ], 121 | "streamable": "0" 122 | }, 123 | { 124 | "name": "Slayer", 125 | "mbid": "bdacc37b-8633-4bf8-9dd5-4662ee651aec", 126 | "match": "0.564283", 127 | "url": "https://www.last.fm/music/Slayer", 128 | "image": [ 129 | { 130 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 131 | "size": "small" 132 | }, 133 | { 134 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 135 | "size": "medium" 136 | }, 137 | { 138 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 139 | "size": "large" 140 | }, 141 | { 142 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 143 | "size": "extralarge" 144 | }, 145 | { 146 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 147 | "size": "mega" 148 | }, 149 | { 150 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 151 | "size": "" 152 | } 153 | ], 154 | "streamable": "0" 155 | }, 156 | ... and 97 more 157 | ], 158 | "@attr": { 159 | "artist": "Metallica" 160 | } 161 | } 162 | } 163 | ``` 164 | 165 | ??? warning "Example response of an artist/track that doesnt exist" 166 | HTTP status: `200 OK` 167 | 168 | ``` 169 | https://ws.audioscrobbler.com/2.0/?method=artist.getSimilar&artist=artistthatdoesntexist&api_key=YOUR_API_KEY&format=json 170 | ``` 171 | ```json 172 | { 173 | "error": 6, 174 | "message": "The artist you supplied could not be found", 175 | "links": [] 176 | } 177 | ``` 178 | 179 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 180 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 181 | [key]: https://www.last.fm/api/account/create 182 | -------------------------------------------------------------------------------- /docs/artist/getTags.md: -------------------------------------------------------------------------------- 1 | Get the tags applied by an individual user to an artist on Last.fm. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: \* | The artist name to fetch information for. 9 | | `user` | [string][string] | `none` | :white_check_mark: \** | The user to look up the tags for. 10 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The artist's MusicBrainz ID. 11 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Transform misspelled artist names into correct artist names, returning the correct version instead. The corrected artist name will be returned in the response. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | \* Required unless you are using a MusicBrainz ID for the artist. 15 | \** Required unless the method is called in authenticated mode. 16 | 17 | ## Responses 18 | Errors: 19 | 20 | - 2 : Invalid service - This service does not exist 21 | - 3 : Invalid Method - No method with that name in this package 22 | - 4 : Authentication Failed - You do not have permissions to access the service 23 | - 5 : Invalid format - This service doesn't exist in that format 24 | - 6 : Invalid parameters - Your request is missing a required parameter 25 | - 7 : Invalid resource specified 26 | - 8 : Operation failed - Something else went wrong 27 | - 9 : Invalid session key - Please re-authenticate 28 | - 10 : Invalid API key - You must be granted a valid key by last.fm 29 | - 11 : Service Offline - This service is temporarily offline. Try again later. 30 | - 13 : Invalid method signature supplied 31 | - 16 : There was a temporary error processing your request. Please try again 32 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 33 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 34 | 35 | !!! Warning 36 | This API call returns 200 OK HTTP status codes even when the response contains an error. 37 | 38 | ## Examples 39 | 40 | ??? note "Example response" 41 | 42 | | Parameter | Value | 43 | | --------- | ------------- | 44 | | artist | Metallica | 45 | | user | rj | 46 | | api_key | YOUR_API_KEY | 47 | | format | json | 48 | 49 | HTTP status: `200 OK` 50 | 51 | ``` 52 | https://ws.audioscrobbler.com/2.0/?method=artist.getTags&artist=Metallica&user=rj&api_key=YOUR_API_KEY&format=json 53 | ``` 54 | 55 | ```json 56 | { 57 | "tags": { 58 | "tag": [ 59 | { 60 | "name": "80s", 61 | "url": "https://www.last.fm/tag/80s" 62 | }, 63 | { 64 | "name": "metal", 65 | "url": "https://www.last.fm/tag/metal" 66 | } 67 | ], 68 | "@attr": { 69 | "artist": "Metallica" 70 | } 71 | } 72 | } 73 | ``` 74 | 75 | ??? warning "Example response of an artist/track that doesnt exist" 76 | HTTP status: `200 OK` 77 | 78 | ``` 79 | https://ws.audioscrobbler.com/2.0/?method=artist.getTags&artist=artistthatdoesntexist&user=rj&api_key=YOUR_API_KEY&format=json 80 | ``` 81 | ```json 82 | { 83 | "error": 6, 84 | "message": "The artist you supplied could not be found", 85 | "links": [] 86 | } 87 | ``` 88 | 89 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 90 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 91 | [key]: https://www.last.fm/api/account/create 92 | -------------------------------------------------------------------------------- /docs/artist/getTopTags.md: -------------------------------------------------------------------------------- 1 | Get the top tags for an artist on Last.fm, ordered by popularity. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: \* | The artist name to fetch information for. 9 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The artist's MusicBrainz ID. 10 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Transform misspelled artist names into correct artist names, returning the correct version instead. The corrected artist name will be returned in the response. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | \* Required unless you are using a MusicBrainz ID for the artist. 14 | 15 | ## Responses 16 | Errors: 17 | 18 | - 2 : Invalid service - This service does not exist 19 | - 3 : Invalid Method - No method with that name in this package 20 | - 4 : Authentication Failed - You do not have permissions to access the service 21 | - 5 : Invalid format - This service doesn't exist in that format 22 | - 6 : Invalid parameters - Your request is missing a required parameter 23 | - 7 : Invalid resource specified 24 | - 8 : Operation failed - Something else went wrong 25 | - 9 : Invalid session key - Please re-authenticate 26 | - 10 : Invalid API key - You must be granted a valid key by last.fm 27 | - 11 : Service Offline - This service is temporarily offline. Try again later. 28 | - 13 : Invalid method signature supplied 29 | - 16 : There was a temporary error processing your request. Please try again 30 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 31 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 32 | 33 | !!! Warning 34 | This API call returns 200 OK HTTP status codes even when the response contains an error. 35 | 36 | ## Examples 37 | 38 | ??? note "Example response" 39 | 40 | | Parameter | Value | 41 | | --------- | ------------- | 42 | | artist | Audioslave | 43 | | api_key | YOUR_API_KEY | 44 | | format | json | 45 | 46 | HTTP status: `200 OK` 47 | 48 | ``` 49 | https://ws.audioscrobbler.com/2.0/?method=artist.getTopTags&artist=Audioslave&api_key=YOUR_API_KEY&format=json 50 | ``` 51 | ```json 52 | { 53 | "toptags": { 54 | "tag": [ 55 | { 56 | "count": 100, 57 | "name": "rock", 58 | "url": "https://www.last.fm/tag/rock" 59 | }, 60 | { 61 | "count": 78, 62 | "name": "alternative rock", 63 | "url": "https://www.last.fm/tag/alternative+rock" 64 | }, 65 | { 66 | "count": 52, 67 | "name": "hard rock", 68 | "url": "https://www.last.fm/tag/hard+rock" 69 | }, 70 | { 71 | "count": 46, 72 | "name": "alternative", 73 | "url": "https://www.last.fm/tag/alternative" 74 | }, 75 | { 76 | "count": 41, 77 | "name": "Grunge", 78 | "url": "https://www.last.fm/tag/Grunge" 79 | }, 80 | { 81 | "count": 19, 82 | "name": "seen live", 83 | "url": "https://www.last.fm/tag/seen+live" 84 | }, 85 | { 86 | "count": 10, 87 | "name": "post-grunge", 88 | "url": "https://www.last.fm/tag/post-grunge" 89 | }, 90 | { 91 | "count": 8, 92 | "name": "metal", 93 | "url": "https://www.last.fm/tag/metal" 94 | }, 95 | { 96 | "count": 8, 97 | "name": "Audioslave", 98 | "url": "https://www.last.fm/tag/Audioslave" 99 | }, 100 | { 101 | "count": 5, 102 | "name": "american", 103 | "url": "https://www.last.fm/tag/american" 104 | }, 105 | { 106 | "count": 4, 107 | "name": "Chris Cornell", 108 | "url": "https://www.last.fm/tag/Chris+Cornell" 109 | }, 110 | { 111 | "count": 4, 112 | "name": "indie", 113 | "url": "https://www.last.fm/tag/indie" 114 | }, 115 | { 116 | "count": 3, 117 | "name": "00s", 118 | "url": "https://www.last.fm/tag/00s" 119 | }, 120 | { 121 | "count": 3, 122 | "name": "alternative metal", 123 | "url": "https://www.last.fm/tag/alternative+metal" 124 | }, 125 | { 126 | "count": 3, 127 | "name": "Supergroup", 128 | "url": "https://www.last.fm/tag/Supergroup" 129 | }, 130 | { 131 | "count": 2, 132 | "name": "indie rock", 133 | "url": "https://www.last.fm/tag/indie+rock" 134 | }, 135 | { 136 | "count": 2, 137 | "name": "Progressive rock", 138 | "url": "https://www.last.fm/tag/Progressive+rock" 139 | }, 140 | { 141 | "count": 2, 142 | "name": "heavy metal", 143 | "url": "https://www.last.fm/tag/heavy+metal" 144 | }, 145 | { 146 | "count": 2, 147 | "name": "classic rock", 148 | "url": "https://www.last.fm/tag/classic+rock" 149 | }, 150 | { 151 | "count": 2, 152 | "name": "Post Grunge", 153 | "url": "https://www.last.fm/tag/Post+Grunge" 154 | }, 155 | { 156 | "count": 2, 157 | "name": "punk", 158 | "url": "https://www.last.fm/tag/punk" 159 | }, 160 | { 161 | "count": 2, 162 | "name": "favorites", 163 | "url": "https://www.last.fm/tag/favorites" 164 | }, 165 | { 166 | "count": 2, 167 | "name": "tom morello", 168 | "url": "https://www.last.fm/tag/tom+morello" 169 | }, 170 | { 171 | "count": 1, 172 | "name": "USA", 173 | "url": "https://www.last.fm/tag/USA" 174 | }, 175 | { 176 | "count": 1, 177 | "name": "funk", 178 | "url": "https://www.last.fm/tag/funk" 179 | }, 180 | { 181 | "count": 1, 182 | "name": "male vocalists", 183 | "url": "https://www.last.fm/tag/male+vocalists" 184 | } 185 | ], 186 | "@attr": { 187 | "artist": "Audioslave" 188 | } 189 | } 190 | } 191 | ``` 192 | 193 | ??? warning "Example response of an artist/track that doesnt exist" 194 | HTTP status: `200 OK` 195 | 196 | ``` 197 | https://ws.audioscrobbler.com/2.0/?method=artist.getTopTags&artist=artistthatdoesntexist&api_key=YOUR_API_KEY&format=json 198 | ``` 199 | ```json 200 | { 201 | "error": 6, 202 | "message": "The artist you supplied could not be found", 203 | "links": [] 204 | } 205 | ``` 206 | 207 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 208 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 209 | [key]: https://www.last.fm/api/account/create 210 | -------------------------------------------------------------------------------- /docs/artist/search.md: -------------------------------------------------------------------------------- 1 | Search for an artist by name, ordered by relevance. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: | The artist's name for the context of the request. 9 | | `limit` | [number][number] | 30 | :negative_squared_cross_mark: | The number of results to fetch per page. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | ## Responses 14 | Errors: 15 | 16 | - 2 : Invalid service - This service does not exist 17 | - 3 : Invalid Method - No method with that name in this package 18 | - 4 : Authentication Failed - You do not have permissions to access the service 19 | - 5 : Invalid format - This service doesn't exist in that format 20 | - 6 : Invalid parameters - Your request is missing a required parameter 21 | - 7 : Invalid resource specified 22 | - 8 : Operation failed - Something else went wrong 23 | - 9 : Invalid session key - Please re-authenticate 24 | - 10 : Invalid API key - You must be granted a valid key by last.fm 25 | - 11 : Service Offline - This service is temporarily offline. Try again later. 26 | - 13 : Invalid method signature supplied 27 | - 16 : There was a temporary error processing your request. Please try again 28 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 29 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 30 | 31 | !!! Warning 32 | This API call returns 200 OK HTTP status codes even when the response contains an error. 33 | 34 | ## Examples 35 | 36 | ??? note "Example response" 37 | 38 | | Parameter | Value | 39 | | --------- | ------------- | 40 | | artist | Rammstein | 41 | | api_key | YOUR_API_KEY | 42 | | format | json | 43 | 44 | HTTP status: `200 OK` 45 | 46 | ``` 47 | https://ws.audioscrobbler.com/2.0/?method=artist.search&artist=Rammstein&api_key=YOUR_API_KEY&format=json 48 | ``` 49 | 50 | ```json 51 | { 52 | "results": { 53 | "opensearch:Query": { 54 | "#text": "", 55 | "role": "request", 56 | "searchTerms": "rammstein", 57 | "startPage": "1" 58 | }, 59 | "opensearch:totalResults": "13809", 60 | "opensearch:startIndex": "0", 61 | "opensearch:itemsPerPage": "30", 62 | "artistmatches": { 63 | "artist": [ 64 | { 65 | "name": "Rammstein", 66 | "listeners": "1913191", 67 | "mbid": "b2d122f9-eadb-4930-a196-8f221eeb0c66", 68 | "url": "https://www.last.fm/music/Rammstein", 69 | "streamable": "0", 70 | "image": [ 71 | { 72 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 73 | "size": "small" 74 | }, 75 | { 76 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 77 | "size": "medium" 78 | }, 79 | { 80 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 81 | "size": "large" 82 | }, 83 | { 84 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 85 | "size": "extralarge" 86 | }, 87 | { 88 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 89 | "size": "mega" 90 | } 91 | ] 92 | } 93 | ] 94 | }, 95 | "@attr": { 96 | "for": "rammstein" 97 | } 98 | } 99 | } 100 | ``` 101 | 102 | ??? warning "Example response of an artist that doesnt exist" 103 | HTTP status: `200 OK` 104 | 105 | ``` 106 | https://ws.audioscrobbler.com/2.0/?method=artist.search&artist=artistthatdoesntexist&api_key=YOUR_API_KEY&format=json 107 | ``` 108 | ```json 109 | { 110 | "results": { 111 | "opensearch:Query": { 112 | "#text": "", 113 | "role": "request", 114 | "searchTerms": "artistthatdoesntexisthsjdkghkjdfgh", 115 | "startPage": "1" 116 | }, 117 | "opensearch:totalResults": "0", 118 | "opensearch:startIndex": "0", 119 | "opensearch:itemsPerPage": "30", 120 | "artistmatches": { 121 | "artist": [ 122 | 123 | ] 124 | }, 125 | "@attr": { 126 | "for": "artistthatdoesntexisthsjdkghkjdfgh" 127 | } 128 | } 129 | } 130 | ``` 131 | 132 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 133 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 134 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/auth/Desktop.md: -------------------------------------------------------------------------------- 1 | This document describes how to allow your users to authenticate within your app without the requirement for a web application. -------------------------------------------------------------------------------- /docs/auth/getSession.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/lastfm-docs/api-docs/b24d4d1be5033da928403c8ee541ddd1ea89c923/docs/auth/getSession.md -------------------------------------------------------------------------------- /docs/auth/getToken.md: -------------------------------------------------------------------------------- 1 | Get a temporary unauthorized token for an API account, this applies to non-web application authorization only. 2 | 3 | ## Parameters 4 | | Method | Type | Default | Required | Description 5 | | ------ | ---- | ------- | -------- | ----------- 6 | | `api_key` | [string][string] | `none` | :white_check_mark: | A Last.fm API key. 7 | | `api_sig` | [string][string] | `none` | :white_check_mark: | A Last.fm method signature, see [signature](signature.md) 8 | 9 | ## Respones 10 | Errors: 11 | 12 | - 8 : There was an error granting the request token. Please try again later 13 | - 2 : Invalid service - This service does not exist 14 | - 3 : Invalid Method - No method with that name in this package 15 | - 4 : Authentication Failed - You do not have permissions to access the service 16 | - 5 : Invalid format - This service doesn't exist in that format 17 | - 6 : Invalid parameters - Your request is missing a required parameter 18 | - 7 : Invalid resource specified 19 | - 8 : Operation failed - Something else went wrong 20 | - 9 : Invalid session key - Please re-authenticate 21 | - 10 : Invalid API key - You must be granted a valid key by last.fm 22 | - 11 : Service Offline - This service is temporarily offline. Try again later. 23 | - 13 : Invalid method signature supplied 24 | - 16 : There was a temporary error processing your request. Please try again 25 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 26 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 27 | 28 | ## Examples 29 | 30 | ??? note "Example XML response" 31 | | Parameter | Value | 32 | | --------- | ------------- | 33 | | api_key | YOUR_API_KEY | 34 | 35 | HTTP status: `200 OK` 36 | ``` 37 | http://ws.audioscrobbler.com/2.0/?method=auth.gettoken&api_key=YOUR_API_KEY 38 | ``` 39 | ```xml 40 | 41 | cf45fe5a3e3cebe168480a086d7fe481 42 | 43 | ``` 44 | 45 | ??? note "Example JSON response" 46 | | Parameter | Value | 47 | | --------- | ------------- | 48 | | api_key | YOUR_API_KEY | 49 | | format | json | 50 | 51 | HTTP status: `200 OK` 52 | ``` 53 | http://ws.audioscrobbler.com/2.0/?method=auth.gettoken&api_key=YOUR_API_KEY&format=json 54 | ``` 55 | ```json 56 | { 57 | "token":"cf45fe5a3e3cebe168480a086d7fe481" 58 | } 59 | ``` 60 | 61 | ??? note "What to do with the token?" 62 | This token can then be used to authenticate a user by requesting the user to authorize via the auth link, with this token and your api key as parameter. 63 | 64 | | Parameter | Value | 65 | | --------- | --------------- | 66 | | api_key | YOUR_API_KEY | 67 | | token | REQUESTED_TOKEN | 68 | 69 | ``` 70 | http://www.last.fm/api/auth/?api_key=YOUR_API_KEY&token=REQUESTED_TOKEN 71 | ``` 72 | 73 | After the user has authorized via this url you can use [getSession](getSession.md) 74 | 75 | 76 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String -------------------------------------------------------------------------------- /docs/auth/signature.md: -------------------------------------------------------------------------------- 1 | Signatures are an extra parameter you have to add to any API calls that use authentication. 2 | 3 | They consist of almost all of your parameters together, in an alphabetical order and hashed as an MD5. They can be very difficult to get right the first time. 4 | 5 | ## Step by step: How to create a signature when getting a sessionkey 6 | 7 | Here are the parameters we will be using for this example: 8 | 9 | | Parameter | Value | 10 | |-----------|--------------------- | 11 | | method | auth.getSession | 12 | | api_key | YOUR_API_KEY | 13 | | token | YOUR_REQUESTED_TOKEN | 14 | | format | json | 15 | 16 | --- 17 | 18 | Gather all the parameters that you want to use in your API call. 19 | 20 | Now order them alphabetically and make sure to exclude the `format` parameter. 21 | 22 | | Parameter | Value | 23 | |-----------|--------------------- | 24 | | api_key | YOUR_API_KEY | 25 | | method | auth.getSession | 26 | | token | YOUR_REQUESTED_TOKEN | 27 | 28 | --- 29 | 30 | Now that you have this you need to make one long string of all the keys and values. 31 | 32 | ``` 33 | api_keyYOUR_API_KEYmethodauth.getSessiontokenYOUR_REQUESTED_TOKEN 34 | ``` 35 | 36 | --- 37 | 38 | When you have this string, all you need to do is add the secret you got when creating your last.fm application. 39 | 40 | Make sure to add this secret without a key, just the value is enough. In this case our secret is `YOUR_SECRET`. 41 | 42 | ``` 43 | api_keyYOUR_API_KEYmethodauth.getSessiontokenYOUR_REQUESTED_TOKENYOUR_SECRET 44 | ``` 45 | 46 | --- 47 | 48 | Now, you need to convert has this to md5. Make sure you use UTF-8 encoding. 49 | 50 | If you would encode the string above you should get the following value: 51 | 52 | ``` 53 | 94539006DE89B3C6B3C030BB1E52B9C4 54 | ``` 55 | 56 | --- 57 | 58 | Add this signature to your parameters, with the `api_sig` key. Your final parameters should now look like this: 59 | 60 | | Parameter | Value | 61 | |-----------|----------------------------------| 62 | | method | auth.getSession | 63 | | api_key | YOUR_API_KEY | 64 | | token | YOUR_REQUESTED_TOKEN | 65 | | format | json | 66 | | api_sig | 94539006DE89B3C6B3C030BB1E52B9C4 | 67 | 68 | 69 | ??? note "Example call to track.love" 70 | 71 | Note that for other endpoints, you will have to include every parameter (except format) in your signature. So, let's use track.love as an example. 72 | A typical call to track.love will have the following parameters: 73 | 74 | | Parameter | Value | 75 | |-----------|----------------------------------| 76 | | artist | KITANO REM | 77 | | track | RAINSICK | 78 | | api_key | YOUR_API_KEY | 79 | | api_sig | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | 80 | | sk | YOUR_SESSION_KEY | 81 | | format | json | 82 | 83 | This means that we get the following parameters for generating the api_sig: 84 | 85 | | Parameter | Value | 86 | |-----------|----------------------------------| 87 | | method | track.love | 88 | | artist | KITANO REM | 89 | | track | RAINSICK | 90 | | api_key | YOUR_API_KEY | 91 | | sk | YOUR_SESSION_KEY | 92 | 93 | This has to be sorted alphabetically, and secret key added: 94 | 95 | ``` 96 | api_keyYOUR_API_KEYartistKITANO REMmethodtrack.loveskYOUR_SESSION_KEYtrackRAINSICKYOUR_SECRET 97 | ``` 98 | 99 | Note that the values are not url encoded. Use standard UTF-8 encoding. 100 | 101 | The md5 of this should be: 102 | 103 | ``` 104 | 800B8884B00C9343D1D425ED271E0F42 105 | ``` 106 | 107 | Then the full post request body must be encoded like a GET url querystring: 108 | 109 | ``` 110 | method=track.love&api_key=YOUR_API_KEY&artist=KITANO%20REM&track=RAINSICK&api_sig=800B8884B00C9343D1D425ED271E0F42&sk=YOUR_SESSION_KEY&format=json 111 | ``` 112 | 113 | ## Code example: C\# 114 | 115 | It might be helpful to see an actual implementation, so here is an example that is used in [.fmbot](https://github.com/fmbot-discord/fmbot) for calls that need a signature. 116 | 117 | ```csharp 118 | 119 | if (generateSignature) 120 | { 121 | var signature = new StringBuilder(); 122 | 123 | foreach (var (key, value) in parameters 124 | .OrderBy(o => o.Key) 125 | .Where(w => !w.Key.Contains("format"))) 126 | { 127 | signature.Append(key); 128 | signature.Append(value); 129 | } 130 | 131 | signature.Append(this._secret); 132 | 133 | parameters.Add("api_sig", CreateMd5(signature.ToString())); 134 | } 135 | ``` 136 | 137 | Function that creates MD5 hash: 138 | 139 | ```csharp 140 | private static string CreateMd5(string input) 141 | { 142 | using var md5 = System.Security.Cryptography.MD5.Create(); 143 | var inputBytes = Encoding.UTF8.GetBytes(input); 144 | var hashBytes = md5.ComputeHash(inputBytes); 145 | 146 | var sb = new StringBuilder(); 147 | foreach (var t in hashBytes) 148 | { 149 | sb.Append(t.ToString("X2")); 150 | } 151 | return sb.ToString(); 152 | } 153 | ``` 154 | -------------------------------------------------------------------------------- /docs/bugs.md: -------------------------------------------------------------------------------- 1 | # Bugs 2 | The last.fm API is by no means updated or maintained regularly, due to this, responses are often riddled with inconsistency and is not up to standards. This page aims to document these bugs, and similar instances of malformed responses and be a reference for developers trying to make last.fm apps and tools. 3 | 4 | Every part of this page documents a different case and can be linked to individually to help make helping newcomers feasible. 5 | 6 | ## Status Codes 7 | Last.fm has a few bugs to iron out with its return headers, one of these causes the API to return inaccurate HTTP response codes in the return header. Some requests do not return the requested resource but still emit a HTTP 200 OK code. 8 | The `getTopTags` method for example, returns an empty array as a response if the resource has no tags, but still emits an OK in the response header. 9 | To prevent your apps breaking, all responses must be checked as just relying on return headers is not enough to validate your response. 10 | 11 | Methods that currently exhibit this behaviour 12 | - track.getTopTags 13 | - album.getTopTags 14 | - artist.getTopTags 15 | 16 | ## Attribute Fields 17 | As per [this page](https://www.last.fm/api/rest) in the official documentation, last.fm serves its JSON responses as converted XML responses, this is done automatically and leads to mistructed JSON, the most common occurrence with this is the presence of fields in the form of attributes to JSON objects, these are attached to JSON objects and can be accessed by looking through the JSON using the title as the property name. 18 | 19 | For example the [user.getInfo](https://lastfm-docs.github.io/api-docs/user/getInfo/) method has a nested JSON objected (`registered`) that includes information about when a user account was created. This includes a text 20 | field named "#text", this property can be accessed by using the title of the value (`#text`) as a key. 21 | ``` 22 | + registered["#text"] 23 | - registered.text 24 | ``` 25 | 26 | Similarly @attr fields can be accessed by using `"@attr"` as a key. 27 | 28 | ## Mistitled Fields 29 | The official documentation has schemas that reflect some fields to have data they do not. For example, the `getTopArtists` methods when called upon the `geo` endpoint should return a field for the number of listeners that the artist has in the requested country. This field is missing in the response and is replaced by a `listeners` field that reflects an artist's global listener count, not their listeners in that country as it should. 30 | 31 | Similarly certain fields containing time information are often titled differently in the documented schemas, in actuality, they are placed in a "uts" field. UTS is an abbrevation for UNIX Timestamp, this is not a common title for it. 32 | 33 | ## Random results 34 | The API has a rare bug where it will sometimes return data like recent tracks from a completely different user. This behavior is also seen on the website. This usually only happens once, and the next result will actually for the user you requested. 35 | 36 | This might mess with any playcount caching mechanisms you have, so keep that in mind. 37 | -------------------------------------------------------------------------------- /docs/chart/getTopArtists.md: -------------------------------------------------------------------------------- 1 | Returns the top artists chart. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 9 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 10 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 11 | 12 | ## Responses 13 | Errors: 14 | 15 | - 2 : Invalid service - This service does not exist 16 | - 3 : Invalid Method - No method with that name in this package 17 | - 4 : Authentication Failed - You do not have permissions to access the service 18 | - 5 : Invalid format - This service doesn't exist in that format 19 | - 6 : Invalid parameters - Your request is missing a required parameter 20 | - 7 : Invalid resource specified 21 | - 8 : Operation failed - Something else went wrong 22 | - 9 : Invalid session key - Please re-authenticate 23 | - 10 : Invalid API key - You must be granted a valid key by last.fm 24 | - 11 : Service Offline - This service is temporarily offline. Try again later. 25 | - 13 : Invalid method signature supplied 26 | - 16 : There was a temporary error processing your request. Please try again 27 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 28 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 29 | 30 | !!! Warning 31 | This API call returns 200 OK HTTP status codes even when the response contains an error. 32 | 33 | ## Examples 34 | 35 | ??? note "Example response" 36 | 37 | | Parameter | Value | 38 | | --------- | ------------- | 39 | | limit | 10 | 40 | | api_key | YOUR_API_KEY | 41 | | format | json | 42 | 43 | HTTP status: `200 OK` 44 | 45 | ``` 46 | https://ws.audioscrobbler.com/2.0/?method=chart.getTopArtists&limit=10&api_key=YOUR_API_KEY&format=json 47 | ``` 48 | ```json 49 | { 50 | "artists": { 51 | "artist": [ 52 | { 53 | "name": "The Weeknd", 54 | "playcount": "497235451", 55 | "listeners": "3389182", 56 | "mbid": "c8b03190-306c-4120-bb0b-6f2ebfc06ea9", 57 | "url": "https://www.last.fm/music/The+Weeknd", 58 | "streamable": "0", 59 | "image": [ 60 | { 61 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 62 | "size": "small" 63 | }, 64 | { 65 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 66 | "size": "medium" 67 | }, 68 | { 69 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 70 | "size": "large" 71 | }, 72 | { 73 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 74 | "size": "extralarge" 75 | }, 76 | { 77 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 78 | "size": "mega" 79 | } 80 | ] 81 | }, 82 | { 83 | "name": "Taylor Swift", 84 | "playcount": "1502167696", 85 | "listeners": "4093921", 86 | "mbid": "20244d07-534f-4eff-b4d4-930878889970", 87 | "url": "https://www.last.fm/music/Taylor+Swift", 88 | "streamable": "0", 89 | "image": [ 90 | { 91 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 92 | "size": "small" 93 | }, 94 | { 95 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 96 | "size": "medium" 97 | }, 98 | { 99 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 100 | "size": "large" 101 | }, 102 | { 103 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 104 | "size": "extralarge" 105 | }, 106 | { 107 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 108 | "size": "mega" 109 | } 110 | ] 111 | }, 112 | { 113 | "name": "Kanye West", 114 | "playcount": "795864645", 115 | "listeners": "6097008", 116 | "mbid": "164f0d73-1234-4e2c-8743-d77bf2191051", 117 | "url": "https://www.last.fm/music/Kanye+West", 118 | "streamable": "0", 119 | "image": [ 120 | { 121 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 122 | "size": "small" 123 | }, 124 | { 125 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 126 | "size": "medium" 127 | }, 128 | { 129 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 130 | "size": "large" 131 | }, 132 | { 133 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 134 | "size": "extralarge" 135 | }, 136 | { 137 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 138 | "size": "mega" 139 | } 140 | ] 141 | }, 142 | { 143 | "name": "Lana Del Rey", 144 | "playcount": "689900871", 145 | "listeners": "3514666", 146 | "mbid": "b7539c32-53e7-4908-bda3-81449c367da6", 147 | "url": "https://www.last.fm/music/Lana+Del+Rey", 148 | "streamable": "0", 149 | "image": [ 150 | { 151 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 152 | "size": "small" 153 | }, 154 | { 155 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 156 | "size": "medium" 157 | }, 158 | { 159 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 160 | "size": "large" 161 | }, 162 | { 163 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 164 | "size": "extralarge" 165 | }, 166 | { 167 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 168 | "size": "mega" 169 | } 170 | ] 171 | }, 172 | { 173 | "name": "Kendrick Lamar", 174 | "playcount": "402351668", 175 | "listeners": "3111925", 176 | "mbid": "381086ea-f511-4aba-bdf9-71c753dc5077", 177 | "url": "https://www.last.fm/music/Kendrick+Lamar", 178 | "streamable": "0", 179 | "image": [ 180 | { 181 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 182 | "size": "small" 183 | }, 184 | { 185 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 186 | "size": "medium" 187 | }, 188 | { 189 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 190 | "size": "large" 191 | }, 192 | { 193 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 194 | "size": "extralarge" 195 | }, 196 | { 197 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 198 | "size": "mega" 199 | } 200 | ] 201 | }, 202 | { 203 | "name": "Drake", 204 | "playcount": "492321658", 205 | "listeners": "5037233", 206 | "mbid": "b49b81cc-d5b7-4bdd-aadb-385df8de69a6", 207 | "url": "https://www.last.fm/music/Drake", 208 | "streamable": "0", 209 | "image": [ 210 | { 211 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 212 | "size": "small" 213 | }, 214 | { 215 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 216 | "size": "medium" 217 | }, 218 | { 219 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 220 | "size": "large" 221 | }, 222 | { 223 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 224 | "size": "extralarge" 225 | }, 226 | { 227 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 228 | "size": "mega" 229 | } 230 | ] 231 | }, 232 | { 233 | "name": "Tyler, the Creator", 234 | "playcount": "402339265", 235 | "listeners": "2416485", 236 | "mbid": "f6beac20-5dfe-4d1f-ae02-0b0a740aafd6", 237 | "url": "https://www.last.fm/music/Tyler,+the+Creator", 238 | "streamable": "0", 239 | "image": [ 240 | { 241 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 242 | "size": "small" 243 | }, 244 | { 245 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 246 | "size": "medium" 247 | }, 248 | { 249 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 250 | "size": "large" 251 | }, 252 | { 253 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 254 | "size": "extralarge" 255 | }, 256 | { 257 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 258 | "size": "mega" 259 | } 260 | ] 261 | }, 262 | { 263 | "name": "Arctic Monkeys", 264 | "playcount": "552898267", 265 | "listeners": "5131866", 266 | "mbid": "ada7a83c-e3e1-40f1-93f9-3e73dbc9298a", 267 | "url": "https://www.last.fm/music/Arctic+Monkeys", 268 | "streamable": "0", 269 | "image": [ 270 | { 271 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 272 | "size": "small" 273 | }, 274 | { 275 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 276 | "size": "medium" 277 | }, 278 | { 279 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 280 | "size": "large" 281 | }, 282 | { 283 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 284 | "size": "extralarge" 285 | }, 286 | { 287 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 288 | "size": "mega" 289 | } 290 | ] 291 | }, 292 | { 293 | "name": "SZA", 294 | "playcount": "221296230", 295 | "listeners": "1977498", 296 | "mbid": "272989c8-5535-492d-a25c-9f58803e027f", 297 | "url": "https://www.last.fm/music/SZA", 298 | "streamable": "0", 299 | "image": [ 300 | { 301 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 302 | "size": "small" 303 | }, 304 | { 305 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 306 | "size": "medium" 307 | }, 308 | { 309 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 310 | "size": "large" 311 | }, 312 | { 313 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 314 | "size": "extralarge" 315 | }, 316 | { 317 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 318 | "size": "mega" 319 | } 320 | ] 321 | }, 322 | { 323 | "name": "Billie Eilish", 324 | "playcount": "277477486", 325 | "listeners": "2315196", 326 | "mbid": "", 327 | "url": "https://www.last.fm/music/Billie+Eilish", 328 | "streamable": "0", 329 | "image": [ 330 | { 331 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 332 | "size": "small" 333 | }, 334 | { 335 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 336 | "size": "medium" 337 | }, 338 | { 339 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 340 | "size": "large" 341 | }, 342 | { 343 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 344 | "size": "extralarge" 345 | }, 346 | { 347 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 348 | "size": "mega" 349 | } 350 | ] 351 | } 352 | ], 353 | "@attr": { 354 | "page": "1", 355 | "perPage": "10", 356 | "totalPages": "538926", 357 | "total": "5389260" 358 | } 359 | } 360 | } 361 | ``` 362 | 363 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 364 | [key]: https://www.last.fm/api/account/create 365 | -------------------------------------------------------------------------------- /docs/chart/getTopTags.md: -------------------------------------------------------------------------------- 1 | Returns the top tags chart. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 9 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 10 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 11 | 12 | ## Responses 13 | Errors: 14 | 15 | - 2 : Invalid service - This service does not exist 16 | - 3 : Invalid Method - No method with that name in this package 17 | - 4 : Authentication Failed - You do not have permissions to access the service 18 | - 5 : Invalid format - This service doesn't exist in that format 19 | - 6 : Invalid parameters - Your request is missing a required parameter 20 | - 7 : Invalid resource specified 21 | - 8 : Operation failed - Something else went wrong 22 | - 9 : Invalid session key - Please re-authenticate 23 | - 10 : Invalid API key - You must be granted a valid key by last.fm 24 | - 11 : Service Offline - This service is temporarily offline. Try again later. 25 | - 13 : Invalid method signature supplied 26 | - 16 : There was a temporary error processing your request. Please try again 27 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 28 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 29 | 30 | !!! Warning 31 | This API call returns 200 OK HTTP status codes even when the response contains an error. 32 | 33 | ## Examples 34 | 35 | ??? note "Example response" 36 | 37 | | Parameter | Value | 38 | | --------- | ------------- | 39 | | limit | 10 | 40 | | api_key | YOUR_API_KEY | 41 | | format | json | 42 | 43 | HTTP status: `200 OK` 44 | 45 | ``` 46 | https://ws.audioscrobbler.com/2.0/?method=chart.getTopTags&limit=10&api_key=YOUR_API_KEY&format=json 47 | ``` 48 | ```json 49 | { 50 | "tags": { 51 | "tag": [ 52 | { 53 | "name": "rock", 54 | "url": "https://www.last.fm/tag/rock", 55 | "reach": "399561", 56 | "taggings": "4026340", 57 | "streamable": "1", 58 | "wiki": {} 59 | }, 60 | { 61 | "name": "electronic", 62 | "url": "https://www.last.fm/tag/electronic", 63 | "reach": "258618", 64 | "taggings": "2443112", 65 | "streamable": "1", 66 | "wiki": {} 67 | }, 68 | { 69 | "name": "seen live", 70 | "url": "https://www.last.fm/tag/seen+live", 71 | "reach": "82188", 72 | "taggings": "2160996", 73 | "streamable": "1", 74 | "wiki": {} 75 | }, 76 | { 77 | "name": "alternative", 78 | "url": "https://www.last.fm/tag/alternative", 79 | "reach": "264913", 80 | "taggings": "2114188", 81 | "streamable": "1", 82 | "wiki": {} 83 | }, 84 | { 85 | "name": "indie", 86 | "url": "https://www.last.fm/tag/indie", 87 | "reach": "257507", 88 | "taggings": "2044341", 89 | "streamable": "1", 90 | "wiki": {} 91 | }, 92 | { 93 | "name": "pop", 94 | "url": "https://www.last.fm/tag/pop", 95 | "reach": "230530", 96 | "taggings": "2031581", 97 | "streamable": "1", 98 | "wiki": {} 99 | }, 100 | { 101 | "name": "female vocalists", 102 | "url": "https://www.last.fm/tag/female+vocalists", 103 | "reach": "168721", 104 | "taggings": "1621018", 105 | "streamable": "1", 106 | "wiki": {} 107 | }, 108 | { 109 | "name": "metal", 110 | "url": "https://www.last.fm/tag/metal", 111 | "reach": "157331", 112 | "taggings": "1280182", 113 | "streamable": "1", 114 | "wiki": {} 115 | }, 116 | { 117 | "name": "alternative rock", 118 | "url": "https://www.last.fm/tag/alternative+rock", 119 | "reach": "168563", 120 | "taggings": "1202962", 121 | "streamable": "1", 122 | "wiki": {} 123 | }, 124 | { 125 | "name": "jazz", 126 | "url": "https://www.last.fm/tag/jazz", 127 | "reach": "148570", 128 | "taggings": "1173582", 129 | "streamable": "1", 130 | "wiki": {} 131 | } 132 | ], 133 | "@attr": { 134 | "page": "1", 135 | "perPage": "10", 136 | "totalPages": "280685", 137 | "total": "2806844" 138 | } 139 | } 140 | } 141 | ``` 142 | 143 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 144 | [key]: https://www.last.fm/api/account/create 145 | -------------------------------------------------------------------------------- /docs/codes.md: -------------------------------------------------------------------------------- 1 | # Error Codes 2 | 3 | ## Last.fm Error Codes 4 | 5 | In addition to return [HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) along with every response from the Last.fm API, failed responses include errors. [Last.fm often does not return HTTP Status Codes that accurately reflect the state of your request](https://lastfm-docs.github.io/api-docs/bugs/#status-codes). 6 | This page provides a comprehensive list of error codes returned by Last.fm, along with a short description of them. 7 | 8 | ??? warning "Example response of an error" 9 | 10 | HTTP status: `404 NOT FOUND` 11 | ```json 12 | { 13 | "error": 6, 14 | "message": "User not found" 15 | } 16 | ``` 17 | 18 | ## HTTP Status Codes Forewarning 19 | 20 | !!! warning 21 | Some API calls return HTTP 200 OK status codes even when the response contains an error. For this reason make sure to check your response payload to validate it. 22 | 23 | --- 24 | 25 | ### Last.fm Error Code 2: Service offline/service Unavailable 26 | 27 | This error usually emits when Last.fm is having server issues. However this may also happen because of a malformed request with invalid endpoints. 28 | 29 | ### Last.fm Error Code 3: Invalid Method 30 | 31 | This error emits when a request is made to an endpoint with a method that does not exist. For example, `artist.getSomeData`. While the endpoint you're making a request to might be perfectly valid, a malformed method name will prevent Last.fm from returning the data you want. For a comprehensive list of every method, refer to the API docs on this site. 32 | 33 | ### Last.fm Error Code 4: Authentication Failed 34 | 35 | This error emits when a request is made signed with a session token that has been generated for an account that has revoked access to your application. 36 | 37 | ### Last.fm Error Code 5: Invalid Response Format 38 | 39 | A `format` parameter is necessary in addition to the documented parameters, this may either have a value of `XML` or `JSON` (case insensitive). Requesting data in another format will emit this error. Some methods do support more than these 2 formats, the methods that do have their formats listed in this documentation. 40 | 41 | ### Last.fm Error Code 6: Parameter Error 42 | 43 | The Last.fm API returns this error code in response to multiple types of failed request. This error can occur because: 44 | 45 | - Your search returned no results 46 | - Your request used an invalid parameter 47 | - Your request has a parameter with an invalid value (for example, an invalid type) 48 | - The requested resource is not available 49 | 50 | ### Last.fm Error Code 7: Invalid Resource Specified 51 | 52 | This error emits when a method requests data from a resource that does not exist, for example, an artist or album that cannot have the data you requested. This might be due to using a method that is not valid on an endpoint despite being documented. 53 | 54 | ### Last.fm Error Code 8: Generic Error 55 | 56 | This error is emitted when something unexpected causes your request to fail but unfortunately Last.fm can't quite tell you what. This is a generic error. This is similar to [HTTP Error 500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500). 57 | 58 | ### Last.fm Error Code 9: Invalid Session Token 59 | 60 | This error emits when a request tries to authenticate with an invalid session key, or similar missing/malformed parameters. For a guide to auth and signing your calls, refer to [this part](https://lastfm-docs.github.io/api-docs/auth/signature/) of the site. Make sure that your session key is hashed using UTF-8 encoding in addition to MD54 61 | 62 | ### Last.fm Error Code 10: Invalid API Token 63 | 64 | This error reflects that your request was signed with an api key that is not valid. A valid API key can be generated [here](https://www.last.fm/api/account/create). 65 | 66 | ### Last.fm Error Code 11: Service Offline 67 | 68 | Last.fm is often down and you might encounter this error when a certain part of their backend is offline. Updated for the status of Last.fm's service can be found [on this Twitter account](https://twitter.com/lastfmstatus). 69 | 70 | ### Last.fm Error Code 13: Invalid Method Signature In Request Header 71 | 72 | This error signifies a malformed header, more specifically, one that hasn't been signed right. 73 | 74 | ### Last.fm Error Code 16: A Temporary Error Occurred 75 | 76 | This is another generic error similar to Last.fm error code 8, however this code implies that this request can be made again and will most likely be successful, this error usually occurs due to backend errors. 77 | 78 | ### Last.fm Error Code 17: Login Required 79 | 80 | This error occurs when a request is made to a method on the `user` endpoint, but the user doesn't have their profile privacy set to public. 81 | 82 | ### Last.fm Error Code 26: Your API key has been banned 83 | 84 | If you hit this error, your API key has been revoked. This can occur due to a plethora of reasons, most likely a violation of Last.fm's ratelimits multiple times, or a violation of their terms of service in general. To further clarify on why you were banned, contact Last.fm support. 85 | 86 | ### Last.fm Error Code 29: Rate Limit Exceeded 87 | 88 | Your IP has made too many requests in a short period. To prevent API abuse, Last.fm returns a [HTTP 429 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) and blocks your requests. Implementing throttling might be a fair consideration. 89 | 90 | ## HTTP Status Codes 91 | 92 | HTTP status codes returned in response headers are often useful for troubleshooting, however the Last.fm API is not held up to any standards. ****Make sure to check your response in addition to validating your requests using HTTP headers****. 93 | 94 | This part of this page **does not** document every HTTP error code. You can find a comprehensive guide [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). 95 | 96 | This is meant to be a refernce for the most common HTTP codes returned by the Last.fm API 97 | 98 | A general reference:- 99 | 100 | - 1\*\* Codes : Informational responses 101 | - 2\*\* Codes : Successful responses 102 | - 3\*\* Codes : Redirects 103 | - 4\*\* Codes : Client side errors 104 | - 5\*\* Codes : Server side errors 105 | 106 | ### HTTP Status Code 200: Success 107 | 108 | The HTTP 200 OK success status response code indicates that the request has succeeded. A 200 response is cacheable by default. 109 | The meaning of a success depends on the HTTP request method: 110 | 111 | - GET: The resource has been fetched and is transmitted in the message body. 112 | - HEAD: The entity headers are in the message body. 113 | - POST: The resource describing the result of the action is transmitted in the message body. 114 | - TRACE: The message body contains the request message as received by the server. 115 | 116 | The successful result of a PUT or a DELETE is often not a 200 OK but a 204 No Content (or a 201 Created when the resource is uploaded for the first time). 117 | 118 | ### HTTP Status Code 400: Bad Request 119 | 120 | The HyperText Transfer Protocol (HTTP) 400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). 121 | 122 | ### HTTP Status Code 403: Forbidden 123 | 124 | The HTTP 403 Forbidden client error status response code indicates that the server understood the request but refuses to authorize it. 125 | 126 | ### HTTP Status Code 404: Not Found 127 | 128 | The HTTP 404 Not Found client error response code indicates that the server can't find the requested resource. Links that lead to a 404 page are often called broken or dead links and can be subject to link rot. 129 | 130 | A 404 status code does not indicate whether the resource is temporarily or permanently missing. But if a resource is permanently removed, a 410 (Gone) should be used instead of a 404 status. 131 | 132 | ### HTTP Status Code 429: Too Many Requests 133 | 134 | The HTTP 429 Too Many Requests response status code indicates the user has sent too many requests in a given amount of time ("rate limiting"). 135 | 136 | A Retry-After header might be included to this response indicating how long to wait before making a new request. 137 | 138 | ### HTTP Status Code 500: Internal Server Error 139 | 140 | The HyperText Transfer Protocol (HTTP) 500 Internal Server Error server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request. 141 | 142 | This error response is a generic "catch-all" response. Usually, this indicates the server cannot find a better 5xx error code to response. Sometimes, server administrators log error responses like the 500 status code with more details about the request to prevent the error from happening again in the future. 143 | 144 | ##### The Mozilla Docs have been referenced in the last section of this page 145 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | This is a community initiative by members of the last.fm Discord to create better documentation for the last.fm API. Anyone is welcome to join and help create better documentation. 4 | 5 | ## What makes this better then the official documentation? 6 | 7 | There are multiple reasons we're doing this: 8 | 9 | - The official docs often have outdated examples, and they're all in XML 10 | - Examples with parameters and showing what objects to expect are easier to work with 11 | - The API often has weird behaviour that we feel should be documented so developers don't have to figure that out themselves 12 | - Error responses are often inconsistent and don't match the docs. It would save developers time if they are well documented 13 | - Documentation should be open source so anyone can fix errors if they find them 14 | 15 | ## Sounds great! How can I contribute? 16 | 17 | You can check out the docs [here](https://github.com/lastfm-docs/api-docs/tree/master/docs). 18 | 19 | It's all in markdown, so easy to work with. Please follow the other pages in styling and objects. 20 | 21 | We use MkDocs with some extensions for extra markdown types. Some of the extensions are: [Tabbed](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/) and [Details (collapsible objects)](https://facelessuser.github.io/pymdown-extensions/extensions/details/) 22 | 23 | ## Last.fm's API Terms of Service 24 | 25 | Please carefully read [this](https://www.last.fm/api/tos) agreement before using Last.fm's webservices, as it affects your legal rights and obligations. This agreement governs the way that you are permitted to access Last.fm data via the API. By accessing the API, You agree to accept and abide by the terms set out in the agreement in respect of your access to and use of the Last.fm data. 26 | 27 | !!! warning "Note" 28 | - Please use an identifiable User-Agent header on all requests. This helps Last.fm's logging and reduces the risk of you getting banned. 29 | - Be reasonable in your usage of the API and ensure you don't make an excessive number of calls as that can impact the reliability of the service to you and other users. Last.fm encourage best practice implementation, for example, if you're making a web application, try not to hit the API on page load. Your account may be suspended if your application is continuously making several calls per second or if you’re making excessive calls. See their [API Terms of Service](https://www.last.fm/api/tos) for more information on limits. 30 | - If you are planning to use Last.fm's API for commercial purposes, please contact them via email at [partners@last.fm](mailto:partners@last.fm). 31 | - Last.fm assume that you are using an RFC 3986-compliant HTTP client to access the web services. In particular, pay attention to your url encoding. This will not be an issue for 99% of developers. 32 | -------------------------------------------------------------------------------- /docs/library/getArtists.md: -------------------------------------------------------------------------------- 1 | A paginated list of all the artists in a user's library, with play counts and tag counts. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The user whose library you want to fetch. 9 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. Maximum 2000. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | ## Responses 14 | Errors: 15 | 16 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 17 | - 8 : Operation failed - Something else went wrong 18 | - 9 : Invalid session key - Please re-authenticate 19 | - 10 : Invalid API key - You must be granted a valid key by last.fm 20 | - 11 : Service Offline - This service is temporarily offline. Try again later. 21 | - 13 : Invalid method signature supplied 22 | - 16 : There was a temporary error processing your request. Please try again 23 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 24 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 25 | 26 | ## Examples 27 | ??? note "Example response" 28 | 29 | | Parameter | Value | 30 | | --------- | ------------ | 31 | | user | aidan- | 32 | | limit | 2 | 33 | | api_key | YOUR_API_KEY | 34 | | format | json | 35 | 36 | HTTP status: `200 OK` 37 | 38 | ``` 39 | https://ws.audioscrobbler.com/2.0/?method=library.getArtists&user=aidan-&limit=2&api_key=YOUR_API_KEY&format=json 40 | ``` 41 | 42 | ```json 43 | { 44 | "artists": { 45 | "artist": [ 46 | { 47 | "url": "https://www.last.fm/music/Queen", 48 | "mbid": "5eecaf18-02ec-47af-a4f2-7831db373419", 49 | "tagcount": "0", 50 | "playcount": "1511", 51 | "streamable": "0", 52 | "name": "Queen", 53 | "image": [ 54 | { 55 | "size": "small", 56 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 57 | }, 58 | { 59 | "size": "medium", 60 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 61 | }, 62 | { 63 | "size": "large", 64 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 65 | }, 66 | { 67 | "size": "extralarge", 68 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 69 | }, 70 | { 71 | "size": "mega", 72 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 73 | } 74 | ] 75 | }, 76 | { 77 | "url": "https://www.last.fm/music/Videoclub", 78 | "mbid": "f4903035-e9cd-4b7f-b462-0447b0cd490a", 79 | "tagcount": "0", 80 | "playcount": "1123", 81 | "streamable": "0", 82 | "name": "Videoclub", 83 | "image": [ 84 | { 85 | "size": "small", 86 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 87 | }, 88 | { 89 | "size": "medium", 90 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 91 | }, 92 | { 93 | "size": "large", 94 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 95 | }, 96 | { 97 | "size": "extralarge", 98 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 99 | }, 100 | { 101 | "size": "mega", 102 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 103 | } 104 | ] 105 | } 106 | ], 107 | "@attr": { 108 | "page": "1", 109 | "total": "1931", 110 | "user": "aidan-", 111 | "perPage": "2", 112 | "totalPages": "966" 113 | } 114 | } 115 | } 116 | 117 | ``` 118 | 119 | !!! warning 120 | To use parameters: `from` and `to`, you must declare **both** of them otherwise it will be treated with no start or end date 121 | 122 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 123 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 124 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/tag/getInfo.md: -------------------------------------------------------------------------------- 1 | Returns metadata information for a tag. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `tag` | [string][string] | `none` | :white_check_mark: | The tag name to search information for. 9 | | `lang` | [string][string] | `en` | :negative_squared_cross_mark: | The language which will be used in the response for the tag. Requires an ISO 639 alpha-1 code. 10 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 11 | 12 | ## Responses 13 | Errors: 14 | 15 | - 2 : Invalid service - This service does not exist 16 | - 3 : Invalid Method - No method with that name in this package 17 | - 4 : Authentication Failed - You do not have permissions to access the service 18 | - 5 : Invalid format - This service doesn't exist in that format 19 | - 6 : Invalid parameters - Your request is missing a required parameter 20 | - 7 : Invalid resource specified 21 | - 8 : Operation failed - Something else went wrong 22 | - 9 : Invalid session key - Please re-authenticate 23 | - 10 : Invalid API key - You must be granted a valid key by last.fm 24 | - 11 : Service Offline - This service is temporarily offline. Try again later. 25 | - 13 : Invalid method signature supplied 26 | - 16 : There was a temporary error processing your request. Please try again 27 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 28 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 29 | 30 | !!! Warning 31 | This API call returns 200 OK HTTP status codes even when the response contains an error. 32 | 33 | ## Examples 34 | ??? note "Example response" 35 | 36 | | Parameter | Value | 37 | | --------- | ------------ | 38 | | tag | metal | 39 | | api_key | YOUR_API_KEY | 40 | | format | json | 41 | 42 | HTTP status: `200 OK` 43 | 44 | ``` 45 | https://ws.audioscrobbler.com/2.0/?method=tag.getInfo&tag=metal&api_key=YOUR_API_KEY&format=json 46 | ``` 47 | 48 | ```json 49 | { 50 | "tag": { 51 | "name": "metal", 52 | "total": 1279720, 53 | "reach": 157277, 54 | "wiki": { 55 | "summary": "Metal is a subgenre of rock music that developed in the late 1960s and early 1970s. With roots in blues-rock and psychedelic rock, the bands that created heavy metal developed a thick, massive sound characterized by highly amplified distortion and extended guitar solos. Allmusic states that, “of all rock & roll’s myriad forms, heavy metal is the most extreme in terms of volume, machismo and theatricality.”\n\nHeavy metal has long had a worldwide following of fans known as metalheads or headbangers.", 56 | "content": "Metal is a subgenre of rock music that developed in the late 1960s and early 1970s. With roots in blues-rock and psychedelic rock, the bands that created heavy metal developed a thick, massive sound characterized by highly amplified distortion and extended guitar solos. Allmusic states that, “of all rock & roll’s myriad forms, heavy metal is the most extreme in terms of volume, machismo and theatricality.”\n\nHeavy metal has long had a worldwide following of fans known as metalheads or headbangers. Although early heavy metal bands such as Black Sabbath, Led Zeppelin and Deep Purple attracted large audiences, they were often critically reviled at the time. A status common throughout the history of the genre. In the mid-1970s, Judas Priest helped spur the genre’s evolution by discarding much of its blues influence. Bands in the New Wave of British Heavy Metal such as Iron Maiden and Motörhead followed in a similar vein, introducing a punk rock sensibility and an increasing emphasis on speed. ..." 57 | } 58 | } 59 | } 60 | ``` 61 | 62 | ??? warning "Example response of a tag that doesn't exist" 63 | HTTP status: `200 OK` 64 | 65 | ``` 66 | https://ws.audioscrobbler.com/2.0/?method=tag.getInfo&tag=thistagdoesntexist&api_key=YOUR_API_KEY&format=json 67 | ``` 68 | ```json 69 | { 70 | "tag": { 71 | "name": "thistagdoesntexist", 72 | "total": 0, 73 | "reach": 0, 74 | "wiki": { 75 | "summary": " Read more on Last.fm.", 76 | "content": "" 77 | } 78 | } 79 | } 80 | ``` 81 | 82 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 83 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/tag/getSimilar.md: -------------------------------------------------------------------------------- 1 | Get tags that are similar to this one. Returns tags ranked by similarity, based on listening data. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `tag` | [string][string] | `none` | :white_check_mark: | The tag name to search information for. 9 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 10 | 11 | ## Responses 12 | Errors: 13 | 14 | - 2 : Invalid service - This service does not exist 15 | - 3 : Invalid Method - No method with that name in this package 16 | - 4 : Authentication Failed - You do not have permissions to access the service 17 | - 5 : Invalid format - This service doesn't exist in that format 18 | - 6 : Invalid parameters - Your request is missing a required parameter 19 | - 7 : Invalid resource specified 20 | - 8 : Operation failed - Something else went wrong 21 | - 9 : Invalid session key - Please re-authenticate 22 | - 10 : Invalid API key - You must be granted a valid key by last.fm 23 | - 11 : Service Offline - This service is temporarily offline. Try again later. 24 | - 13 : Invalid method signature supplied 25 | - 16 : There was a temporary error processing your request. Please try again 26 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 27 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 28 | 29 | !!! Warning 30 | This API call is currently broken and returns an empty array as a response. 31 | !!! Warning 32 | This API call returns 200 OK HTTP status codes even when the response contains an error. 33 | 34 | 35 | ## Examples 36 | ??? warning "Example response" 37 | 38 | | Parameter | Value | 39 | | --------- | ------------ | 40 | | tag | metal | 41 | | api_key | YOUR_API_KEY | 42 | | format | json | 43 | 44 | HTTP status: `200 OK` 45 | 46 | ``` 47 | https://ws.audioscrobbler.com/2.0/?method=tag.getSimilar&tag=metal&api_key=YOUR_API_KEY&format=json 48 | ``` 49 | 50 | ```json 51 | { 52 | "similartags": { 53 | "tag": [], 54 | "@attr": { 55 | "tag": "n/a" 56 | } 57 | } 58 | } 59 | ``` 60 | 61 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 62 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/tag/getTopAlbums.md: -------------------------------------------------------------------------------- 1 | Get the top albums tagged by this tag, ordered by tag count. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `tag` | [string][string] | `none` | :white_check_mark: | The tag name to search information for. 9 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | ## Responses 14 | Errors: 15 | 16 | - 2 : Invalid service - This service does not exist 17 | - 3 : Invalid Method - No method with that name in this package 18 | - 4 : Authentication Failed - You do not have permissions to access the service 19 | - 5 : Invalid format - This service doesn't exist in that format 20 | - 6 : Invalid parameters - Your request is missing a required parameter 21 | - 7 : Invalid resource specified 22 | - 8 : Operation failed - Something else went wrong 23 | - 9 : Invalid session key - Please re-authenticate 24 | - 10 : Invalid API key - You must be granted a valid key by last.fm 25 | - 11 : Service Offline - This service is temporarily offline. Try again later. 26 | - 13 : Invalid method signature supplied 27 | - 16 : There was a temporary error processing your request. Please try again 28 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 29 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 30 | 31 | !!! Warning 32 | This API call returns 200 OK HTTP status codes even when the response contains an error. 33 | 34 | ## Examples 35 | ??? note "Example response" 36 | 37 | | Parameter | Value | 38 | | --------- | ------------ | 39 | | tag | metal | 40 | | api_key | YOUR_API_KEY | 41 | | format | json | 42 | 43 | HTTP status: `200 OK` 44 | 45 | ``` 46 | https://ws.audioscrobbler.com/2.0/?method=tag.getTopAlbums&tag=metal&api_key=YOUR_API_KEY&format=json 47 | ``` 48 | 49 | ```json 50 | { 51 | "albums": { 52 | "album": [ 53 | { 54 | "name": "Ten Thousand Fists", 55 | "mbid": "d618f88f-a4a7-4028-a9e7-a2f3bcc3d9c3", 56 | "url": "https://www.last.fm/music/Disturbed", 57 | "artist": { 58 | "name": "Disturbed", 59 | "mbid": "dc75517c-d268-486d-bd5b-0eaff34eeef9", 60 | "url": "https://www.last.fm/music/Disturbed" 61 | }, 62 | "image": [ 63 | { 64 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/4c090f3226a7de3c21daaa92e2d4a416.png", 65 | "size": "small" 66 | }, 67 | { 68 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/4c090f3226a7de3c21daaa92e2d4a416.png", 69 | "size": "medium" 70 | }, 71 | { 72 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/4c090f3226a7de3c21daaa92e2d4a416.png", 73 | "size": "large" 74 | }, 75 | { 76 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/4c090f3226a7de3c21daaa92e2d4a416.png", 77 | "size": "extralarge" 78 | } 79 | ], 80 | "@attr": { 81 | "rank": "1" 82 | } 83 | }, 84 | { 85 | "name": "City of Evil", 86 | "mbid": "4f7c1a59-92b1-4ba7-919f-b61a3b4b8d2a", 87 | "url": "https://www.last.fm/music/Avenged+Sevenfold", 88 | "artist": { 89 | "name": "Avenged Sevenfold", 90 | "mbid": "24e1b53c-3085-4581-8472-0b0088d2508c", 91 | "url": "https://www.last.fm/music/Avenged+Sevenfold" 92 | }, 93 | "image": [ 94 | { 95 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/50f59fc2dcff4345c3d492e1a71f634f.png", 96 | "size": "small" 97 | }, 98 | { 99 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/50f59fc2dcff4345c3d492e1a71f634f.png", 100 | "size": "medium" 101 | }, 102 | { 103 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/50f59fc2dcff4345c3d492e1a71f634f.png", 104 | "size": "large" 105 | }, 106 | { 107 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/50f59fc2dcff4345c3d492e1a71f634f.png", 108 | "size": "extralarge" 109 | } 110 | ], 111 | "@attr": { 112 | "rank": "2" 113 | } 114 | }, 115 | { 116 | "name": "Indestructible", 117 | "mbid": "8bf771ef-dad7-4ff0-911a-d9661fee3df1", 118 | "url": "https://www.last.fm/music/Disturbed", 119 | "artist": { 120 | "name": "Disturbed", 121 | "mbid": "dc75517c-d268-486d-bd5b-0eaff34eeef9", 122 | "url": "https://www.last.fm/music/Disturbed" 123 | }, 124 | "image": [ 125 | { 126 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/4fe09361eb8a41e18eb06279bb8bceb6.png", 127 | "size": "small" 128 | }, 129 | { 130 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/4fe09361eb8a41e18eb06279bb8bceb6.png", 131 | "size": "medium" 132 | }, 133 | { 134 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/4fe09361eb8a41e18eb06279bb8bceb6.png", 135 | "size": "large" 136 | }, 137 | { 138 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/4fe09361eb8a41e18eb06279bb8bceb6.png", 139 | "size": "extralarge" 140 | } 141 | ], 142 | "@attr": { 143 | "rank": "3" 144 | } 145 | }, 146 | ... and 47 more 147 | ], 148 | "@attr": { 149 | "tag": "metal", 150 | "page": "1", 151 | "perPage": "50", 152 | "totalPages": "585", 153 | "total": "29201" 154 | } 155 | } 156 | } 157 | ``` 158 | 159 | ??? warning "Example response of a tag that doesn't exist" 160 | HTTP status: `200 OK` 161 | 162 | ``` 163 | https://ws.audioscrobbler.com/2.0/?method=tag.getTopAlbums&tag=thistagdoesntexist&api_key=YOUR_API_KEY&format=json 164 | ``` 165 | ```json 166 | { 167 | "albums": { 168 | "album": [], 169 | "@attr": { 170 | "tag": "thistagdoesntexist", 171 | "page": "1", 172 | "perPage": "50", 173 | "totalPages": "0", 174 | "total": "0" 175 | } 176 | } 177 | } 178 | ``` 179 | 180 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 181 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 182 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/tag/getTopArtists.md: -------------------------------------------------------------------------------- 1 | Get the top artists tagged by this tag, ordered by tag count. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `tag` | [string][string] | `none` | :white_check_mark: | The tag name to search information for. 9 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | ## Responses 14 | Errors: 15 | 16 | - 2 : Invalid service - This service does not exist 17 | - 3 : Invalid Method - No method with that name in this package 18 | - 4 : Authentication Failed - You do not have permissions to access the service 19 | - 5 : Invalid format - This service doesn't exist in that format 20 | - 6 : Invalid parameters - Your request is missing a required parameter 21 | - 7 : Invalid resource specified 22 | - 8 : Operation failed - Something else went wrong 23 | - 9 : Invalid session key - Please re-authenticate 24 | - 10 : Invalid API key - You must be granted a valid key by last.fm 25 | - 11 : Service Offline - This service is temporarily offline. Try again later. 26 | - 13 : Invalid method signature supplied 27 | - 16 : There was a temporary error processing your request. Please try again 28 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 29 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 30 | 31 | ## Examples 32 | ??? note "Example response" 33 | 34 | | Parameter | Value | 35 | | --------- | ------------ | 36 | | tag | metal | 37 | | api_key | YOUR_API_KEY | 38 | | format | json | 39 | 40 | HTTP status: `200 OK` 41 | 42 | ``` 43 | https://ws.audioscrobbler.com/2.0/?method=tag.getTopArtists&tag=metal&api_key=YOUR_API_KEY&format=json 44 | ``` 45 | 46 | ```json 47 | { 48 | "topartists": { 49 | "artist": [ 50 | { 51 | "name": "System of a Down", 52 | "mbid": "cc0b7089-c08d-4c10-b6b0-873582c17fd6", 53 | "url": "https://www.last.fm/music/System+of+a+Down", 54 | "streamable": "0", 55 | "image": [ 56 | { 57 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 58 | "size": "small" 59 | }, 60 | { 61 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 62 | "size": "medium" 63 | }, 64 | { 65 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 66 | "size": "large" 67 | }, 68 | { 69 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 70 | "size": "extralarge" 71 | }, 72 | { 73 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 74 | "size": "mega" 75 | } 76 | ], 77 | "@attr": { 78 | "rank": "1" 79 | } 80 | }, 81 | { 82 | "name": "Disturbed", 83 | "mbid": "dc75517c-d268-486d-bd5b-0eaff34eeef9", 84 | "url": "https://www.last.fm/music/Disturbed", 85 | "streamable": "0", 86 | "image": [ 87 | { 88 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 89 | "size": "small" 90 | }, 91 | { 92 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 93 | "size": "medium" 94 | }, 95 | { 96 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 97 | "size": "large" 98 | }, 99 | { 100 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 101 | "size": "extralarge" 102 | }, 103 | { 104 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 105 | "size": "mega" 106 | } 107 | ], 108 | "@attr": { 109 | "rank": "2" 110 | } 111 | }, 112 | { 113 | "name": "Soil", 114 | "mbid": "b82cca8e-c183-413f-a60b-12bf0c229433", 115 | "url": "https://www.last.fm/music/Soil", 116 | "streamable": "0", 117 | "image": [ 118 | { 119 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 120 | "size": "small" 121 | }, 122 | { 123 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 124 | "size": "medium" 125 | }, 126 | { 127 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 128 | "size": "large" 129 | }, 130 | { 131 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 132 | "size": "extralarge" 133 | }, 134 | { 135 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 136 | "size": "mega" 137 | } 138 | ], 139 | "@attr": { 140 | "rank": "3" 141 | } 142 | }, 143 | ... and 47 more 144 | ], 145 | "@attr": { 146 | "tag": "metal", 147 | "page": "1", 148 | "perPage": "50", 149 | "totalPages": "1192", 150 | "total": "59570" 151 | } 152 | } 153 | } 154 | ``` 155 | 156 | ??? warning "Example response of a tag that doesn't exist" 157 | HTTP status: `200 OK` 158 | 159 | ``` 160 | https://ws.audioscrobbler.com/2.0/?method=tag.getTopArtists&tag=thistagdoesntexist&api_key=YOUR_API_KEY&format=json 161 | ``` 162 | ```json 163 | { 164 | "topartists": { 165 | "artist": [], 166 | "@attr": { 167 | "tag": "thistagdoesntexist", 168 | "page": "1", 169 | "perPage": "50", 170 | "totalPages": "0", 171 | "total": "0" 172 | } 173 | } 174 | } 175 | ``` 176 | 177 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 178 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 179 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/tag/getTopTags.md: -------------------------------------------------------------------------------- 1 | Fetches the top global tags on Last.fm. Sorted by popularity. (number of times used) 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 9 | 10 | ## Responses 11 | Errors: 12 | 13 | - 2 : Invalid service - This service does not exist 14 | - 3 : Invalid Method - No method with that name in this package 15 | - 4 : Authentication Failed - You do not have permissions to access the service 16 | - 5 : Invalid format - This service doesn't exist in that format 17 | - 6 : Invalid parameters - Your request is missing a required parameter 18 | - 7 : Invalid resource specified 19 | - 8 : Operation failed - Something else went wrong 20 | - 9 : Invalid session key - Please re-authenticate 21 | - 10 : Invalid API key - You must be granted a valid key by last.fm 22 | - 11 : Service Offline - This service is temporarily offline. Try again later. 23 | - 13 : Invalid method signature supplied 24 | - 16 : There was a temporary error processing your request. Please try again 25 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 26 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 27 | 28 | ## Examples 29 | ??? note "Example response" 30 | 31 | | Parameter | Value | 32 | | --------- | ------------ | 33 | | tag | metal | 34 | | api_key | YOUR_API_KEY | 35 | | format | json | 36 | 37 | HTTP status: `200 OK` 38 | 39 | ``` 40 | https://ws.audioscrobbler.com/2.0/?method=tag.getTopTags&tag=metal&api_key=YOUR_API_KEY&format=json 41 | ``` 42 | 43 | ```json 44 | { 45 | "toptags": { 46 | "@attr": { 47 | "offset": 0, 48 | "num_res": 50, 49 | "total": 2804440 50 | }, 51 | "tag": [ 52 | { 53 | "name": "rock", 54 | "count": 4024829, 55 | "reach": 399440 56 | }, 57 | { 58 | "name": "electronic", 59 | "count": 2441085, 60 | "reach": 258464 61 | }, 62 | { 63 | "name": "seen live", 64 | "count": 2159269, 65 | "reach": 82163 66 | }, 67 | ... and 47 more 68 | ] 69 | } 70 | } 71 | ``` 72 | 73 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/tag/getTopTracks.md: -------------------------------------------------------------------------------- 1 | Get the top tracks tagged by this tag, ordered by tag count. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `tag` | [string][string] | `none` | :white_check_mark: | The tag name to search information for. 9 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | ## Responses 14 | Errors: 15 | 16 | - 2 : Invalid service - This service does not exist 17 | - 3 : Invalid Method - No method with that name in this package 18 | - 4 : Authentication Failed - You do not have permissions to access the service 19 | - 5 : Invalid format - This service doesn't exist in that format 20 | - 6 : Invalid parameters - Your request is missing a required parameter 21 | - 7 : Invalid resource specified 22 | - 8 : Operation failed - Something else went wrong 23 | - 9 : Invalid session key - Please re-authenticate 24 | - 10 : Invalid API key - You must be granted a valid key by last.fm 25 | - 11 : Service Offline - This service is temporarily offline. Try again later. 26 | - 13 : Invalid method signature supplied 27 | - 16 : There was a temporary error processing your request. Please try again 28 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 29 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 30 | 31 | ## Examples 32 | ??? note "Example response" 33 | 34 | | Parameter | Value | 35 | | --------- | ------------ | 36 | | tag | metal | 37 | | api_key | YOUR_API_KEY | 38 | | format | json | 39 | 40 | HTTP status: `200 OK` 41 | 42 | ``` 43 | https://ws.audioscrobbler.com/2.0/?method=tag.getTopTracks&tag=metal&api_key=YOUR_API_KEY&format=json 44 | ``` 45 | 46 | ```json 47 | { 48 | "tracks": { 49 | "track": [ 50 | { 51 | "name": "Chop Suey!", 52 | "duration": "208", 53 | "mbid": "d758947d-d667-430b-900d-2abb110f63aa", 54 | "url": "https://www.last.fm/music/System+of+a+Down/_/Chop+Suey%21", 55 | "streamable": { 56 | "#text": "0", 57 | "fulltrack": "0" 58 | }, 59 | "artist": { 60 | "name": "System of a Down", 61 | "mbid": "cc0b7089-c08d-4c10-b6b0-873582c17fd6", 62 | "url": "https://www.last.fm/music/System+of+a+Down" 63 | }, 64 | "image": [ 65 | { 66 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 67 | "size": "small" 68 | }, 69 | { 70 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 71 | "size": "medium" 72 | }, 73 | { 74 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 75 | "size": "large" 76 | }, 77 | { 78 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 79 | "size": "extralarge" 80 | } 81 | ], 82 | "@attr": { 83 | "rank": "1" 84 | } 85 | }, 86 | { 87 | "name": "In the End", 88 | "duration": "216", 89 | "mbid": "9d70086c-5d7a-4e7f-b1ed-c53c4b11310f", 90 | "url": "https://www.last.fm/music/Linkin+Park/_/In+the+End", 91 | "streamable": { 92 | "#text": "0", 93 | "fulltrack": "0" 94 | }, 95 | "artist": { 96 | "name": "Linkin Park", 97 | "mbid": "f59c5520-5f46-4d2c-b2c4-822eabf53419", 98 | "url": "https://www.last.fm/music/Linkin+Park" 99 | }, 100 | "image": [ 101 | { 102 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 103 | "size": "small" 104 | }, 105 | { 106 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 107 | "size": "medium" 108 | }, 109 | { 110 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 111 | "size": "large" 112 | }, 113 | { 114 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 115 | "size": "extralarge" 116 | } 117 | ], 118 | "@attr": { 119 | "rank": "2" 120 | } 121 | }, 122 | { 123 | "name": "Numb", 124 | "duration": "191", 125 | "mbid": "f3217a42-bb14-4191-8c2e-c5e5413467be", 126 | "url": "https://www.last.fm/music/Linkin+Park/_/Numb", 127 | "streamable": { 128 | "#text": "0", 129 | "fulltrack": "0" 130 | }, 131 | "artist": { 132 | "name": "Linkin Park", 133 | "mbid": "f59c5520-5f46-4d2c-b2c4-822eabf53419", 134 | "url": "https://www.last.fm/music/Linkin+Park" 135 | }, 136 | "image": [ 137 | { 138 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 139 | "size": "small" 140 | }, 141 | { 142 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 143 | "size": "medium" 144 | }, 145 | { 146 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 147 | "size": "large" 148 | }, 149 | { 150 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 151 | "size": "extralarge" 152 | } 153 | ], 154 | "@attr": { 155 | "rank": "3" 156 | } 157 | }, 158 | ... and 47 more 159 | ], 160 | "@attr": { 161 | "tag": "metal", 162 | "page": "1", 163 | "perPage": "50", 164 | "totalPages": "3316", 165 | "total": "165756" 166 | } 167 | } 168 | } 169 | ``` 170 | 171 | ??? warning "Example response of a tag that doesn't exist" 172 | HTTP status: `200 OK` 173 | 174 | ``` 175 | https://ws.audioscrobbler.com/2.0/?method=tag.getTopTracks&tag=thistagdoesntexist&api_key=YOUR_API_KEY&format=json 176 | ``` 177 | ```json 178 | { 179 | "tracks": { 180 | "track": [], 181 | "@attr": { 182 | "tag": "thistagdoesntexist", 183 | "page": "1", 184 | "perPage": "50", 185 | "totalPages": "0", 186 | "total": "0" 187 | } 188 | } 189 | } 190 | ``` 191 | 192 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 193 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 194 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/tag/getWeeklyChartList.md: -------------------------------------------------------------------------------- 1 | Get a list of available charts for this tag, expressed as date ranges which can be sent to the chart services. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `tag` | [string][string] | `none` | :white_check_mark: | The tag name to search information for. 9 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 10 | 11 | ## Responses 12 | Errors: 13 | 14 | - 2 : Invalid service - This service does not exist 15 | - 3 : Invalid Method - No method with that name in this package 16 | - 4 : Authentication Failed - You do not have permissions to access the service 17 | - 5 : Invalid format - This service doesn't exist in that format 18 | - 6 : Invalid parameters - Your request is missing a required parameter 19 | - 7 : Invalid resource specified 20 | - 8 : Operation failed - Something else went wrong 21 | - 9 : Invalid session key - Please re-authenticate 22 | - 10 : Invalid API key - You must be granted a valid key by last.fm 23 | - 11 : Service Offline - This service is temporarily offline. Try again later. 24 | - 13 : Invalid method signature supplied 25 | - 16 : There was a temporary error processing your request. Please try again 26 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 27 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 28 | 29 | ## Examples 30 | ??? note "Example response" 31 | 32 | | Parameter | Value | 33 | | --------- | ------------ | 34 | | tag | metal | 35 | | api_key | YOUR_API_KEY | 36 | | format | json | 37 | 38 | HTTP status: `200 OK` 39 | 40 | ``` 41 | https://ws.audioscrobbler.com/2.0/?method=tag.getWeeklyChartList&tag=metal&api_key=YOUR_API_KEY&format=json 42 | ``` 43 | 44 | 45 | ```json 46 | { 47 | "weeklychartlist": { 48 | "chart": [ 49 | { 50 | "#text": "", 51 | "from": "1108296000", 52 | "to": "1108900800" 53 | }, 54 | { 55 | "#text": "", 56 | "from": "1108900800", 57 | "to": "1109505600" 58 | }, 59 | { 60 | "#text": "", 61 | "from": "1109505600", 62 | "to": "1110110400" 63 | }, 64 | ... and 952 more 65 | ], 66 | "@attr": { 67 | "tag": "metal" 68 | } 69 | } 70 | } 71 | ``` 72 | 73 | ??? warning "Example response of a tag that doesn't exist" 74 | HTTP status: `200 OK` 75 | 76 | ``` 77 | https://ws.audioscrobbler.com/2.0/?method=tag.getWeeklyChartList&tag=thistagdoesntexist&api_key=YOUR_API_KEY&format=json 78 | ``` 79 | ```json 80 | { 81 | "weeklychartlist": { 82 | "chart": [ 83 | { 84 | "#text": "", 85 | "from": "1108296000", 86 | "to": "1108900800" 87 | }, 88 | { 89 | "#text": "", 90 | "from": "1108900800", 91 | "to": "1109505600" 92 | }, 93 | { 94 | "#text": "", 95 | "from": "1109505600", 96 | "to": "1110110400" 97 | }, 98 | ... and 958 more 99 | ], 100 | "@attr": { 101 | "tag": "thistagdoesntexist" 102 | } 103 | } 104 | } 105 | ``` 106 | 107 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 108 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/track/getCorrection.md: -------------------------------------------------------------------------------- 1 | Use the Last.fm corrections data to check whether the supplied track has a correction to a canonical track. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: | The artist name to correct. 9 | | `track` | [string][string] | `none` | :white_check_mark: | The track name to correct. 10 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 11 | 12 | ## Responses 13 | Errors: 14 | 15 | - 2 : Invalid service - This service does not exist 16 | - 3 : Invalid Method - No method with that name in this package 17 | - 4 : Authentication Failed - You do not have permissions to access the service 18 | - 5 : Invalid format - This service doesn't exist in that format 19 | - 6 : Invalid parameters - Your request is missing a required parameter 20 | - 7 : Invalid resource specified 21 | - 8 : Operation failed - Something else went wrong 22 | - 9 : Invalid session key - Please re-authenticate 23 | - 10 : Invalid API key - You must be granted a valid key by last.fm 24 | - 11 : Service Offline - This service is temporarily offline. Try again later. 25 | - 13 : Invalid method signature supplied 26 | - 16 : There was a temporary error processing your request. Please try again 27 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 28 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 29 | 30 | !!! Warning 31 | This API call returns 200 OK HTTP status codes even when the response contains an error. 32 | 33 | ## Examples 34 | 35 | ??? note "Example response" 36 | 37 | | Parameter | Value | 38 | | --------- | ------------- | 39 | | artist | Skee-Lo | 40 | | track | I wish | 41 | | api_key | YOUR_API_KEY | 42 | | format | json | 43 | 44 | HTTP status: `200 OK` 45 | 46 | ``` 47 | https://ws.audioscrobbler.com/2.0/?method=track.getCorrection&artist=Skee-Lo&track=I%20Wish&api_key=YOUR_API_KEY&format=json 48 | ``` 49 | 50 | ```json 51 | { 52 | "corrections": { 53 | "correction": { 54 | "track": { 55 | "name": "I Wish", 56 | "mbid": "ccb9326a-6f9f-48b1-a097-1210dd14e119", 57 | "url": "https://www.last.fm/music/Skee-Lo/_/I+Wish", 58 | "artist": { 59 | "name": "Skee-Lo", 60 | "mbid": "9341a67c-4f0c-43c2-9ec4-c222d2cb97f3", 61 | "url": "https://www.last.fm/music/Skee-Lo" 62 | } 63 | }, 64 | "@attr": { 65 | "index": "0", 66 | "artistcorrected": "0", 67 | "trackcorrected": "0" 68 | } 69 | } 70 | } 71 | } 72 | 73 | ``` 74 | 75 | ??? warning "Example response of an artist/track that doesnt exist" 76 | HTTP status: `200 OK` 77 | 78 | ``` 79 | https://ws.audioscrobbler.com/2.0/?method=track.getCorrection&artist=artistthatdoesntexist&track=i%20wish&api_key=YOUR_API_KEY&format=json 80 | ``` 81 | ```json 82 | { 83 | "corrections": { 84 | "correction": { 85 | "track": { 86 | "url": "", 87 | "artist": { 88 | "url": "" 89 | } 90 | }, 91 | "@attr": { 92 | "index": "0", 93 | "artistcorrected": "0", 94 | "trackcorrected": "0" 95 | } 96 | } 97 | } 98 | } 99 | ``` 100 | 101 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 102 | [key]: https://www.last.fm/api/account/create 103 | -------------------------------------------------------------------------------- /docs/track/getSimilar.md: -------------------------------------------------------------------------------- 1 | Get the similar tracks for this track on Last.fm, based on listening data. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: \* | The artist name to fetch information for. 9 | | `track` | [string][string] | `none` | :white_check_mark: \* | The track name to fetch information for. 10 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The artist's MusicBrainz ID. 11 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Transform misspelled artist names into correct artist names, returning the correct version instead. The corrected artist name will be returned in the response. 12 | | `limit` | [number][number] | 100 | :negative_squared_cross_mark: | The number of results to fetch per page. 13 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 14 | 15 | \* Required unless you are using a MusicBrainz ID for the artist/track. 16 | 17 | ## Responses 18 | Errors: 19 | 20 | - 2 : Invalid service - This service does not exist 21 | - 3 : Invalid Method - No method with that name in this package 22 | - 4 : Authentication Failed - You do not have permissions to access the service 23 | - 5 : Invalid format - This service doesn't exist in that format 24 | - 6 : Invalid parameters - Your request is missing a required parameter 25 | - 7 : Invalid resource specified 26 | - 8 : Operation failed - Something else went wrong 27 | - 9 : Invalid session key - Please re-authenticate 28 | - 10 : Invalid API key - You must be granted a valid key by last.fm 29 | - 11 : Service Offline - This service is temporarily offline. Try again later. 30 | - 13 : Invalid method signature supplied 31 | - 16 : There was a temporary error processing your request. Please try again 32 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 33 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 34 | 35 | !!! Warning 36 | This API call returns 200 OK HTTP status codes even when the response contains an error. 37 | 38 | ## Examples 39 | 40 | ??? note "Example response" 41 | 42 | | Parameter | Value | 43 | | --------- | ------------ | 44 | | artist | Disturbed | 45 | | track | Stricken | 46 | | api_key | YOUR_API_KEY | 47 | | format | json | 48 | 49 | HTTP status: `200 OK` 50 | 51 | ``` 52 | https://ws.audioscrobbler.com/2.0/?method=track.getSimilar&artist=Disturbed&track=Stricken&api_key=YOUR_API_KEY&format=json 53 | ``` 54 | ```json 55 | { 56 | "similartracks": { 57 | "track": [ 58 | { 59 | "name": "Down With the Sickness", 60 | "playcount": 8066450, 61 | "mbid": "a8009036-b13e-4cb8-b2c7-2c3f9735b735", 62 | "match": 1, 63 | "url": "https://www.last.fm/music/Disturbed/_/Down+With+the+Sickness", 64 | "streamable": { 65 | "#text": "0", 66 | "fulltrack": "0" 67 | }, 68 | "duration": 278, 69 | "artist": { 70 | "name": "Disturbed", 71 | "mbid": "dc75517c-d268-486d-bd5b-0eaff34eeef9", 72 | "url": "https://www.last.fm/music/Disturbed" 73 | }, 74 | "image": [ 75 | { 76 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 77 | "size": "small" 78 | }, 79 | { 80 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 81 | "size": "medium" 82 | }, 83 | { 84 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 85 | "size": "large" 86 | }, 87 | { 88 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 89 | "size": "extralarge" 90 | }, 91 | { 92 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 93 | "size": "mega" 94 | }, 95 | { 96 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 97 | "size": "" 98 | } 99 | ] 100 | }, 101 | { 102 | "name": "Inside the Fire", 103 | "playcount": 3983007, 104 | "mbid": "38c28d49-c0e4-4700-93d4-1c834400fe35", 105 | "match": 0.976467, 106 | "url": "https://www.last.fm/music/Disturbed/_/Inside+the+Fire", 107 | "streamable": { 108 | "#text": "0", 109 | "fulltrack": "0" 110 | }, 111 | "duration": 233, 112 | "artist": { 113 | "name": "Disturbed", 114 | "mbid": "dc75517c-d268-486d-bd5b-0eaff34eeef9", 115 | "url": "https://www.last.fm/music/Disturbed" 116 | }, 117 | "image": [ 118 | { 119 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 120 | "size": "small" 121 | }, 122 | { 123 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 124 | "size": "medium" 125 | }, 126 | { 127 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 128 | "size": "large" 129 | }, 130 | { 131 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 132 | "size": "extralarge" 133 | }, 134 | { 135 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 136 | "size": "mega" 137 | }, 138 | { 139 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 140 | "size": "" 141 | } 142 | ] 143 | }, 144 | { 145 | "name": "Before I Forget", 146 | "playcount": 9225371, 147 | "mbid": "0692129f-cfb5-4ca2-a2a5-e2c03251388f", 148 | "match": 0.602882, 149 | "url": "https://www.last.fm/music/Slipknot/_/Before+I+Forget", 150 | "streamable": { 151 | "#text": "0", 152 | "fulltrack": "0" 153 | }, 154 | "duration": 263, 155 | "artist": { 156 | "name": "Slipknot", 157 | "mbid": "ceb7b6be-1dbb-4d80-b157-5588bc884764", 158 | "url": "https://www.last.fm/music/Slipknot" 159 | }, 160 | "image": [ 161 | { 162 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 163 | "size": "small" 164 | }, 165 | { 166 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 167 | "size": "medium" 168 | }, 169 | { 170 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 171 | "size": "large" 172 | }, 173 | { 174 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 175 | "size": "extralarge" 176 | }, 177 | { 178 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 179 | "size": "mega" 180 | }, 181 | { 182 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 183 | "size": "" 184 | } 185 | ] 186 | }, 187 | ... and 97 more 188 | ], 189 | "@attr": { 190 | "artist": "Disturbed" 191 | } 192 | } 193 | } 194 | ``` 195 | 196 | ??? warning "Example response of a track/artist that doesnt exist" 197 | HTTP status: `200 OK` 198 | 199 | ``` 200 | https://ws.audioscrobbler.com/2.0/?method=track.getSimilar&artist=Fake+Artist&track=Fake+Track&api_key=YOUR_API_KEY&format=json 201 | ``` 202 | ```json 203 | { 204 | "similartracks": { 205 | "track": [], 206 | "@attr": { 207 | "artist": "Fake Artist" 208 | } 209 | } 210 | } 211 | ``` 212 | 213 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 214 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 215 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/track/getTags.md: -------------------------------------------------------------------------------- 1 | Get the tags applied by an individual user to a track on Last.fm. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: * | The artist name to fetch information for. 9 | | `track` | [string][string] | `none` | :white_check_mark: * | The track name to fetch information for. 10 | | `user` | [string][string] | `none` | :white_check_mark: ** | The user to look up the tags for. 11 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The artist's MusicBrainz ID. 12 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Transform misspelled artist names into correct artist names, returning the correct version instead. The corrected artist name will be returned in the response. 13 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 14 | 15 | \* Required unless you are using a MusicBrainz ID for the artist/track. 16 | \** Required unless the method is called in authenticated mode. 17 | 18 | ## Responses 19 | Errors: 20 | 21 | - 2 : Invalid service - This service does not exist 22 | - 3 : Invalid Method - No method with that name in this package 23 | - 4 : Authentication Failed - You do not have permissions to access the service 24 | - 5 : Invalid format - This service doesn't exist in that format 25 | - 6 : Invalid parameters - Your request is missing a required parameter 26 | - 7 : Invalid resource specified 27 | - 8 : Operation failed - Something else went wrong 28 | - 9 : Invalid session key - Please re-authenticate 29 | - 10 : Invalid API key - You must be granted a valid key by last.fm 30 | - 11 : Service Offline - This service is temporarily offline. Try again later. 31 | - 13 : Invalid method signature supplied 32 | - 16 : There was a temporary error processing your request. Please try again 33 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 34 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 35 | 36 | !!! Warning 37 | This API call returns 200 OK HTTP status codes even when the response contains an error. 38 | 39 | ## Examples 40 | ??? note "Example response" 41 | 42 | | Parameter | Value | 43 | | --------- | ------------ | 44 | | artist | AC/DC | 45 | | track | Hells Bells | 46 | | api_key | YOUR_API_KEY | 47 | | format | json | 48 | 49 | HTTP status: `200 OK` 50 | 51 | ``` 52 | https://ws.audioscrobbler.com/2.0/?method=track.getTags&artist=AC/DC&track=Hells+Bells&user=RJ&api_key=YOUR_API_KEY&format=json 53 | ``` 54 | ```json 55 | { 56 | "tags": { 57 | "tag": [ 58 | { 59 | "name": "guitar", 60 | "url": "https://www.last.fm/tag/guitar" 61 | }, 62 | { 63 | "name": "metal", 64 | "url": "https://www.last.fm/tag/metal" 65 | }, 66 | { 67 | "name": "rock", 68 | "url": "https://www.last.fm/tag/rock" 69 | } 70 | ], 71 | "@attr": { 72 | "artist": "AC/DC", 73 | "track": "Hells Bells" 74 | } 75 | } 76 | } 77 | ``` 78 | 79 | ??? warning "Example response of an artist/track that doesnt exist" 80 | HTTP status: `200 OK` 81 | 82 | ``` 83 | https://ws.audioscrobbler.com/2.0/?method=track.getTags&artist=artistthatdoesntexist&track=trackthatdoesntexist&user=solelychloe&api_key=YOUR_API_KEY&format=json 84 | ``` 85 | ```json 86 | { 87 | "error": 6, 88 | "message": "Track not found", 89 | "links": [] 90 | } 91 | ``` 92 | 93 | 94 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 95 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 96 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/track/getTopTags.md: -------------------------------------------------------------------------------- 1 | Get the top tags for this track on Last.fm, ordered by tag count. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `artist` | [string][string] | `none` | :white_check_mark: * | The artist name to fetch information for. 9 | | `track` | [string][string] | `none` | :white_check_mark: * | The track name to fetch information for. 10 | | `mbid` | [string][string] | `none` | :negative_squared_cross_mark: | The artist's MusicBrainz ID. 11 | | `autocorrect` | [number][number] | 0 | :negative_squared_cross_mark: | Transform misspelled artist names into correct artist names, returning the correct version instead. The corrected artist name will be returned in the response. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | \* Required unless you are using a MusicBrainz ID for the artist/track. 15 | 16 | ## Responses 17 | Errors: 18 | 19 | - 2 : Invalid service - This service does not exist 20 | - 3 : Invalid Method - No method with that name in this package 21 | - 4 : Authentication Failed - You do not have permissions to access the service 22 | - 5 : Invalid format - This service doesn't exist in that format 23 | - 6 : Invalid parameters - Your request is missing a required parameter 24 | - 7 : Invalid resource specified 25 | - 8 : Operation failed - Something else went wrong 26 | - 9 : Invalid session key - Please re-authenticate 27 | - 10 : Invalid API key - You must be granted a valid key by last.fm 28 | - 11 : Service Offline - This service is temporarily offline. Try again later. 29 | - 13 : Invalid method signature supplied 30 | - 16 : There was a temporary error processing your request. Please try again 31 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 32 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 33 | 34 | !!! Warning 35 | This API call returns 200 OK HTTP status codes even when the response contains an error. 36 | 37 | ## Examples 38 | ??? note "Example response" 39 | 40 | | Parameter | Value | 41 | | --------- | ------------ | 42 | | artist | AC/DC | 43 | | track | Hells Bells | 44 | | api_key | YOUR_API_KEY | 45 | | format | json | 46 | 47 | HTTP status: `200 OK` 48 | 49 | ``` 50 | https://ws.audioscrobbler.com/2.0/?method=track.getTopTags&artist=AC/DC&track=Hells+Bells&api_key=YOUR_API_KEY&format=json 51 | ``` 52 | ```json 53 | { 54 | "toptags": { 55 | "tag": [ 56 | { 57 | "count": 100, 58 | "name": "hard rock", 59 | "url": "https://www.last.fm/tag/hard+rock" 60 | }, 61 | { 62 | "count": 58, 63 | "name": "rock", 64 | "url": "https://www.last.fm/tag/rock" 65 | }, 66 | { 67 | "count": 53, 68 | "name": "classic rock", 69 | "url": "https://www.last.fm/tag/classic+rock" 70 | }, 71 | { 72 | "count": 27, 73 | "name": "ACDC", 74 | "url": "https://www.last.fm/tag/ACDC" 75 | }, 76 | { 77 | "count": 25, 78 | "name": "heavy metal", 79 | "url": "https://www.last.fm/tag/heavy+metal" 80 | }, 81 | { 82 | "count": 14, 83 | "name": "80s", 84 | "url": "https://www.last.fm/tag/80s" 85 | }, 86 | { 87 | "count": 12, 88 | "name": "AC/DC", 89 | "url": "https://www.last.fm/tag/AC%2FDC" 90 | }, 91 | { 92 | "count": 11, 93 | "name": "metal", 94 | "url": "https://www.last.fm/tag/metal" 95 | }, 96 | { 97 | "count": 6, 98 | "name": "australian", 99 | "url": "https://www.last.fm/tag/australian" 100 | }, 101 | { 102 | "count": 6, 103 | "name": "guitar", 104 | "url": "https://www.last.fm/tag/guitar" 105 | }, 106 | { 107 | "count": 5, 108 | "name": "Rock and Roll", 109 | "url": "https://www.last.fm/tag/Rock+and+Roll" 110 | }, 111 | { 112 | "count": 5, 113 | "name": "hells bells", 114 | "url": "https://www.last.fm/tag/hells+bells" 115 | }, 116 | { 117 | "count": 4, 118 | "name": "1980", 119 | "url": "https://www.last.fm/tag/1980" 120 | }, 121 | { 122 | "count": 3, 123 | "name": "70s", 124 | "url": "https://www.last.fm/tag/70s" 125 | }, 126 | { 127 | "count": 3, 128 | "name": "Supernatural", 129 | "url": "https://www.last.fm/tag/Supernatural" 130 | }, 131 | { 132 | "count": 3, 133 | "name": "blues rock", 134 | "url": "https://www.last.fm/tag/blues+rock" 135 | }, 136 | { 137 | "count": 3, 138 | "name": "heavy rock", 139 | "url": "https://www.last.fm/tag/heavy+rock" 140 | }, 141 | { 142 | "count": 3, 143 | "name": "favorites", 144 | "url": "https://www.last.fm/tag/favorites" 145 | }, 146 | { 147 | "count": 3, 148 | "name": "classic metal", 149 | "url": "https://www.last.fm/tag/classic+metal" 150 | }, 151 | { 152 | "count": 2, 153 | "name": "rock n roll", 154 | "url": "https://www.last.fm/tag/rock+n+roll" 155 | }, 156 | { 157 | "count": 2, 158 | "name": "Awesome", 159 | "url": "https://www.last.fm/tag/Awesome" 160 | }, 161 | { 162 | "count": 2, 163 | "name": "seen live", 164 | "url": "https://www.last.fm/tag/seen+live" 165 | }, 166 | { 167 | "count": 2, 168 | "name": "australia", 169 | "url": "https://www.last.fm/tag/australia" 170 | }, 171 | { 172 | "count": 2, 173 | "name": "live", 174 | "url": "https://www.last.fm/tag/live" 175 | }, 176 | { 177 | "count": 2, 178 | "name": "ac dc", 179 | "url": "https://www.last.fm/tag/ac+dc" 180 | }, 181 | { 182 | "count": 2, 183 | "name": "classic", 184 | "url": "https://www.last.fm/tag/classic" 185 | }, 186 | { 187 | "count": 2, 188 | "name": "Hard", 189 | "url": "https://www.last.fm/tag/Hard" 190 | }, 191 | { 192 | "count": 2, 193 | "name": "10 of 10 stars", 194 | "url": "https://www.last.fm/tag/10+of+10+stars" 195 | }, 196 | { 197 | "count": 2, 198 | "name": "hardrock", 199 | "url": "https://www.last.fm/tag/hardrock" 200 | }, 201 | { 202 | "count": 2, 203 | "name": "Ac-Dc", 204 | "url": "https://www.last.fm/tag/Ac-Dc" 205 | }, 206 | { 207 | "count": 2, 208 | "name": "alternative", 209 | "url": "https://www.last.fm/tag/alternative" 210 | }, 211 | { 212 | "count": 1, 213 | "name": "heavy", 214 | "url": "https://www.last.fm/tag/heavy" 215 | }, 216 | { 217 | "count": 1, 218 | "name": "bells", 219 | "url": "https://www.last.fm/tag/bells" 220 | }, 221 | { 222 | "count": 1, 223 | "name": "male vocalist", 224 | "url": "https://www.last.fm/tag/male+vocalist" 225 | }, 226 | { 227 | "count": 1, 228 | "name": "angus young", 229 | "url": "https://www.last.fm/tag/angus+young" 230 | }, 231 | { 232 | "count": 1, 233 | "name": "back in black", 234 | "url": "https://www.last.fm/tag/back+in+black" 235 | } 236 | ], 237 | "@attr": { 238 | "artist": "AC/DC", 239 | "track": "Hells Bells" 240 | } 241 | } 242 | } 243 | ``` 244 | 245 | ??? warning "Example response of an artist/track that doesnt exist" 246 | HTTP status: `200 OK` 247 | 248 | ``` 249 | https://ws.audioscrobbler.com/2.0/?method=track.getTopTags&artist=Metallica&track=Hells+Bells&api_key=YOUR_API_KEY&format=json 250 | ``` 251 | ```json 252 | { 253 | "toptags": { 254 | "tag": [], 255 | "@attr": { 256 | "artist": "Metallica", 257 | "track": "Hells Bells" 258 | } 259 | } 260 | } 261 | ``` 262 | 263 | 264 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 265 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 266 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/track/search.md: -------------------------------------------------------------------------------- 1 | Get the top tags for this track on Last.fm, ordered by tag count. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `track` | [string][string] | `none` | :white_check_mark: | The track name to fetch information for. 9 | | `artist` | [string][string] | `none` | :negative_squared_cross_mark: | Narrow your search by specifying an artist. 10 | | `limit` | [number][number] | 30 | :negative_squared_cross_mark: | The number of results to fetch per page. 11 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | ## Responses 15 | Errors: 16 | 17 | - 2 : Invalid service - This service does not exist 18 | - 3 : Invalid Method - No method with that name in this package 19 | - 4 : Authentication Failed - You do not have permissions to access the service 20 | - 5 : Invalid format - This service doesn't exist in that format 21 | - 6 : Invalid parameters - Your request is missing a required parameter 22 | - 7 : Invalid resource specified 23 | - 8 : Operation failed - Something else went wrong 24 | - 9 : Invalid session key - Please re-authenticate 25 | - 10 : Invalid API key - You must be granted a valid key by last.fm 26 | - 11 : Service Offline - This service is temporarily offline. Try again later. 27 | - 13 : Invalid method signature supplied 28 | - 16 : There was a temporary error processing your request. Please try again 29 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 30 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 31 | 32 | !!! Warning 33 | This API call returns 200 OK HTTP status codes even when the response contains an error. 34 | 35 | ## Examples 36 | ??? note "Example response" 37 | 38 | | Parameter | Value | 39 | | --------- | ------------- | 40 | | track | Hells Bells | 41 | | api_key | YOUR_API_KEY | 42 | | format | json | 43 | 44 | HTTP status: `200 OK` 45 | 46 | ``` 47 | https://ws.audioscrobbler.com/2.0/?method=track.search&track=Hells+Bells&api_key=YOUR_API_KEY&format=json 48 | ``` 49 | ```json 50 | { 51 | "results": { 52 | "opensearch:Query": { 53 | "#text": "", 54 | "role": "request", 55 | "startPage": "1" 56 | }, 57 | "opensearch:totalResults": "11634", 58 | "opensearch:startIndex": "0", 59 | "opensearch:itemsPerPage": "30", 60 | "trackmatches": { 61 | "track": [ 62 | { 63 | "name": "Hells Bells", 64 | "artist": "AC/DC", 65 | "url": "https://www.last.fm/music/AC%2FDC/_/Hells+Bells", 66 | "streamable": "FIXME", 67 | "listeners": "796758", 68 | "image": [ 69 | { 70 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 71 | "size": "small" 72 | }, 73 | { 74 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 75 | "size": "medium" 76 | }, 77 | { 78 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 79 | "size": "large" 80 | }, 81 | { 82 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 83 | "size": "extralarge" 84 | } 85 | ], 86 | "mbid": "b6411d6b-2dca-4004-8919-e8c27ff6b286" 87 | }, 88 | { 89 | "name": "Hell's Bells", 90 | "artist": "Cary Ann Hearst", 91 | "url": "https://www.last.fm/music/Cary+Ann+Hearst/_/Hell%27s+Bells", 92 | "streamable": "FIXME", 93 | "listeners": "20485", 94 | "image": [ 95 | { 96 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 97 | "size": "small" 98 | }, 99 | { 100 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 101 | "size": "medium" 102 | }, 103 | { 104 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 105 | "size": "large" 106 | }, 107 | { 108 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 109 | "size": "extralarge" 110 | } 111 | ], 112 | "mbid": "d0fd3d3b-ae2f-40d5-a5ac-d56c0d549dc7" 113 | }, 114 | { 115 | "name": "Hell's Bells", 116 | "artist": "AC/DC", 117 | "url": "https://www.last.fm/music/AC%2FDC/_/Hell%27s+Bells", 118 | "streamable": "FIXME", 119 | "listeners": "19980", 120 | "image": [ 121 | { 122 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 123 | "size": "small" 124 | }, 125 | { 126 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 127 | "size": "medium" 128 | }, 129 | { 130 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 131 | "size": "large" 132 | }, 133 | { 134 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 135 | "size": "extralarge" 136 | } 137 | ], 138 | "mbid": "c7c25302-69ab-4a9d-b967-23cbc6793854" 139 | }, 140 | ... and 27 more 141 | ] 142 | }, 143 | "@attr": {} 144 | } 145 | } 146 | ``` 147 | 148 | ??? warning "Example response of an artist/track that doesnt exist" 149 | HTTP status: `200 OK` 150 | 151 | ``` 152 | https://ws.audioscrobbler.com/2.0/?method=track.search&track=trackthatdoesntexist&api_key=YOUR_API_KEY&format=json 153 | ``` 154 | ```json 155 | { 156 | "results": { 157 | "opensearch:Query": { 158 | "#text": "", 159 | "role": "request", 160 | "startPage": "1" 161 | }, 162 | "opensearch:totalResults": "0", 163 | "opensearch:startIndex": "0", 164 | "opensearch:itemsPerPage": "30", 165 | "trackmatches": { 166 | "track": [] 167 | }, 168 | "@attr": {} 169 | } 170 | } 171 | ``` 172 | 173 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 174 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 175 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getFriends.md: -------------------------------------------------------------------------------- 1 | # getFriends 2 | 3 | Get a list of the user's friends (follow each other) on Last.fm. 4 | 5 | No authentication required. 6 | 7 | ## Parameters 8 | | Method | Type | Default | Required | Description 9 | | ------ | ---- | ------- | -------- | ----------- 10 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch the friends of. 11 | | `recenttracks` | [boolean][boolean] | 0 | :negative_squared_cross_mark: | Whether or not to include information about friends' recent listening in the response. 12 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 13 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 14 | | `api_key`| [key][key] | `none` | :white_check_mark: | A Last.fm API key. 15 | 16 | ## Responses 17 | Errors: 18 | 19 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 20 | - 8 : Operation failed - Something else went wrong 21 | - 9 : Invalid session key - Please re-authenticate 22 | - 10 : Invalid API key - You must be granted a valid key by last.fm 23 | - 11 : Service Offline - This service is temporarily offline. Try again later. 24 | - 13 : Invalid method signature supplied 25 | - 16 : There was a temporary error processing your request. Please try again 26 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 27 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 28 | 29 | 30 | ## Examples 31 | ??? note "Example response" 32 | 33 | | Parameter | Value | 34 | | --------- | ------------ | 35 | | user | aidan- | 36 | | limit | 1 | 37 | | api_key | YOUR_API_KEY | 38 | | format | json | 39 | 40 | HTTP status: `200 OK` 41 | 42 | ``` 43 | https://ws.audioscrobbler.com/2.0/?method=user.getFriends&user=aidan-&limit=1&api_key=YOUR_API_KEY&&format=json 44 | ``` 45 | 46 | ```json 47 | { 48 | "friends":{ 49 | "user": [ 50 | { 51 | "playlists": "0", 52 | "playcount": "4", 53 | "subscriber": "0", 54 | "name": "oldmaneatintwix", 55 | "country": "United Kingdom", 56 | "image": [ 57 | { 58 | "size": "small", 59 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/1c3fd3c2548906f6ea0f2863718c2668.png" 60 | }, 61 | { 62 | "size": "medium", 63 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/1c3fd3c2548906f6ea0f2863718c2668.png" 64 | }, 65 | { 66 | "size": "large", 67 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/1c3fd3c2548906f6ea0f2863718c2668.png" 68 | }, 69 | { 70 | "size": "extralarge", 71 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/1c3fd3c2548906f6ea0f2863718c2668.png" 72 | } 73 | ], 74 | "registered": { 75 | "unixtime": "1603189685", 76 | "#text": "2020-10-20 10:28" 77 | }, 78 | "url": "https://www.last.fm/user/oldmaneatintwix", 79 | "realname": "Charlie Brown", 80 | "bootstrap": "0", 81 | "type": "user" 82 | } 83 | ], 84 | "@attr": { 85 | "page": "1", 86 | "total": "10", 87 | "user": "aidan-", 88 | "perPage": "1", 89 | "totalPages": "10" 90 | } 91 | } 92 | } 93 | 94 | ``` 95 | 96 | 97 | 98 | ??? warning "Example response of non existing user" 99 | HTTP status: `404 NOT FOUND` 100 | 101 | ``` 102 | https://ws.audioscrobbler.com/2.0/?api_key=YOUR_API_KEY&method=User.getfriends&user=userthatdoesntexist&format=json 103 | ``` 104 | 105 | ```json 106 | { 107 | "error": 6, 108 | "message": "User not found" 109 | } 110 | ``` 111 | 112 | ??? warning "Example response of a user with no friends" 113 | HTTP status: `400 BAD REQUEST` 114 | 115 | ``` 116 | https://ws.audioscrobbler.com/2.0/?api_key=YOUR_API_KEY&method=User.getfriends&user=letmeridee&format=json 117 | ``` 118 | 119 | ```json 120 | { 121 | "error": 6, 122 | "message": "no such page" 123 | } 124 | ``` 125 | 126 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 127 | [boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean 128 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 129 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getInfo.md: -------------------------------------------------------------------------------- 1 | Returns profile information about a last.fm user. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch the info of. 9 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 10 | 11 | ## Responses 12 | Errors: 13 | 14 | - 6 : Invalid parameters - Your request is missing a required parameter 15 | - 8 : Operation failed - Something else went wrong 16 | - 10 : Invalid API key - You must be granted a valid key by last.fm 17 | - 11 : Service Offline - This service is temporarily offline. Try again later. 18 | - 13 : Invalid method signature supplied 19 | - 16 : There was a temporary error processing your request. Please try again 20 | - 17 : Login required - Requested profile might not have privacy set to public. 21 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 22 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 23 | 24 | ## Examples 25 | 26 | ??? note "Example response" 27 | 28 | | Parameter | Value | 29 | | ----------- | --------------- | 30 | | user | TyphoonsNotABot | 31 | | api_key | YOUR_API_KEY | 32 | | format | json | 33 | 34 | HTTP status: `200 OK` 35 | 36 | ``` 37 | https://ws.audioscrobbler.com/2.0/?method=user.getInfo&user=TyphoonsNotABot&api_key=YOUR_API_KEY&format=json 38 | ``` 39 | 40 | ```json 41 | { 42 | "user": { 43 | "playlists": "0", 44 | "playcount": "138223", 45 | "gender": "n", 46 | "name": "TyphoonsNotABot", 47 | "subscriber": "0", 48 | "url": "https://www.last.fm/user/TyphoonsNotABot", 49 | "country": "United Kingdom", 50 | "image": [ 51 | { 52 | "size": "small", 53 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/9e9565eee02f3e08d803b7726f65f406.png" 54 | }, 55 | { 56 | "size": "medium", 57 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/9e9565eee02f3e08d803b7726f65f406.png" 58 | }, 59 | { 60 | "size": "large", 61 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/9e9565eee02f3e08d803b7726f65f406.png" 62 | }, 63 | { 64 | "size": "extralarge", 65 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/9e9565eee02f3e08d803b7726f65f406.png" 66 | } 67 | ], 68 | "registered": { 69 | "unixtime": "1561177193", 70 | "#text": 1561177193 71 | }, 72 | "type": "user", 73 | "age": "0", 74 | "bootstrap": "0", 75 | "realname": "Liam" 76 | } 77 | } 78 | ``` 79 | 80 | ??? warning "Example response of non existing user" 81 | 82 | HTTP status: `404 NOT FOUND` 83 | 84 | ``` 85 | https://ws.audioscrobbler.com/2.0/?method=user.getinfo&user=userthatdoesnotexist&api_key=YOUR_API_KEY&format=json 86 | ``` 87 | 88 | ```json 89 | { 90 | "error": 6, 91 | "message": "User not found" 92 | } 93 | ``` 94 | 95 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 96 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getLovedTracks.md: -------------------------------------------------------------------------------- 1 | Returns a list of the tracks loved scrobbled by this user. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The last.fm username to fetch the loved tracks of. 9 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. Maximum is 1000. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 12 | 13 | ## Responses 14 | Errors: 15 | 16 | - 6 : Invalid parameters - Your request is missing a required parameter 17 | - 8 : Operation failed - Something else went wrong 18 | - 9 : Invalid session key - Please re-authenticate 19 | - 10 : Invalid API key - You must be granted a valid key by last.fm 20 | - 11 : Service Offline - This service is temporarily offline. Try again later. 21 | - 13 : Invalid method signature supplied 22 | - 16 : There was a temporary error processing your request. Please try again 23 | - 17 : Login required - Requested profile might not have privacy set to public. 24 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 25 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 26 | 27 | ## Examples 28 | 29 | ??? note "Example Response" 30 | 31 | | Parameter | Value | 32 | | ----------- | ------------------ | 33 | | user | TyphoonasNorABot | 34 | | limit | 1 | 35 | | api_key | YOUR_API_KEY | 36 | | format | json | 37 | 38 | HTTP status: `200 OK` 39 | 40 | ``` 41 | https://ws.audioscrobbler.com/2.0/?method=user.getLovedTracks&user=TyphoonsNotABot&limit=1&api_key=YOUR_API_KEY&format=json 42 | ``` 43 | 44 | ```json 45 | { 46 | "lovedtracks": { 47 | "@attr": { 48 | "page": "1", 49 | "total": "7790", 50 | "user": "TyphoonsNotABot", 51 | "perPage": "1", 52 | "totalPages": "7790" 53 | }, 54 | "track": [ 55 | { 56 | "artist": { 57 | "url": "https://www.last.fm/music/The+Backseat+Lovers", 58 | "name": "The Backseat Lovers", 59 | "mbid": "" 60 | }, 61 | "mbid": "59da79dd-aed6-447c-951c-070f6b8446a1", 62 | "date": { 63 | "uts": "1603112664", 64 | "#text": "19 Oct 2020, 13:04" 65 | }, 66 | "url": "https://www.last.fm/music/The+Backseat+Lovers/_/Davy+Crochet", 67 | "image": [ 68 | { 69 | "size": "small", 70 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 71 | }, 72 | { 73 | "size": "medium", 74 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 75 | }, 76 | { 77 | "size": "large", 78 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 79 | }, 80 | { 81 | "size": "extralarge", 82 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 83 | } 84 | ], 85 | "name": "Davy Crochet", 86 | "streamable": { 87 | "fulltrack": "0", 88 | "#text": "0" 89 | } 90 | } 91 | ] 92 | } 93 | } 94 | ``` 95 | 96 | 97 | ??? warning "Example Response of a user that doesn't exist" 98 | 99 | HTTP status: `404 NOT FOUND` 100 | 101 | ``` 102 | https://ws.audioscrobbler.com/2.0/?api_key=YOUR_API_KEY&method=User.getlovedtracks&user=userthatdoesntexist&format=json 103 | ``` 104 | 105 | ```json 106 | { 107 | "error": 6, 108 | "message": "User not found" 109 | } 110 | ``` 111 | 112 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 113 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 114 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getPersonalTags.md: -------------------------------------------------------------------------------- 1 | Get a list of the user's personal tags. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch the personal tags of. 9 | | `tag` | [string][string] | `none` | :white_check_mark: | The tag that is being fetched. 10 | | `taggingtype` | [string][string] | `none` | :white_check_mark: | The type of items that have been tagged. Options are `artist`, `album` and `track`. 11 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 12 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 13 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 14 | 15 | ## Responses 16 | Errors: 17 | 18 | - 2 : Invalid service - This service does not exist 19 | - 3 : Invalid Method - No method with that name in this package 20 | - 4 : Authentication Failed - You do not have permissions to access the service 21 | - 5 : Invalid format - This service doesn't exist in that format 22 | - 6 : Invalid parameters - Your request is missing a required parameter 23 | - 7 : Invalid resource specified 24 | - 8 : Operation failed - Something else went wrong 25 | - 9 : Invalid session key - Please re-authenticate 26 | - 10 : Invalid API key - You must be granted a valid key by last.fm 27 | - 11 : Service Offline - This service is temporarily offline. Try again later. 28 | - 13 : Invalid method signature supplied 29 | - 16 : There was a temporary error processing your request. Please try again 30 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 31 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 32 | 33 | !!! Warning 34 | This API call returns 200 OK HTTP status codes even when the response contains an error. 35 | 36 | ## Examples 37 | 38 | ??? note "Example response" 39 | 40 | | Parameter | Value | 41 | | ------------ | ------------ | 42 | | user | rj | 43 | | tag | rock | 44 | | taggingtype | artist | 45 | | limit | 1 | 46 | | api_key | YOUR_API_KEY | 47 | | format | json | 48 | 49 | HTTP status: `200 OK` 50 | 51 | ``` 52 | https://ws.audioscrobbler.com/2.0/?method=user.getPersonalTags&user=rj&tag=rock&taggingtype=artist&limit=1&api_key=YOUR_API_KEY&format=json 53 | ``` 54 | 55 | ```json 56 | { 57 | "taggings": { 58 | "artists": { 59 | "artist": [ 60 | { 61 | "name": "Jack Bruce", 62 | "mbid": "94a24504-3548-4bde-a89b-273d277d194e", 63 | "url": "https://www.last.fm/music/Jack+Bruce", 64 | "streamable": "0", 65 | "image": [ 66 | { 67 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png", 68 | "size": "small" 69 | }, 70 | { 71 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png", 72 | "size": "medium" 73 | }, 74 | { 75 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png", 76 | "size": "large" 77 | }, 78 | { 79 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 80 | "size": "extralarge" 81 | }, 82 | { 83 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png", 84 | "size": "mega" 85 | } 86 | ] 87 | } 88 | ] 89 | }, 90 | "@attr": { 91 | "user": "RJ", 92 | "tag": "rock", 93 | "page": "1", 94 | "perPage": "1", 95 | "totalPages": "20", 96 | "total": "20" 97 | } 98 | } 99 | } 100 | ``` 101 | 102 | ??? warning "Example response of non existing user" 103 | HTTP status: `200 OK` 104 | 105 | ``` 106 | https://ws.audioscrobbler.com/2.0/?method=user.getpersonaltags&user=userthatdoesntexist&tag=rock&taggingtype=artist&api_key=YOUR_API_KEY&format=json&limit=1 107 | ``` 108 | 109 | ```json 110 | { 111 | "error": 6, 112 | "message": "User not found" 113 | } 114 | ``` 115 | 116 | ??? warning "Example response of a user with no tags as the ones fetched" 117 | HTTP status: `200 OK` 118 | 119 | ``` 120 | https://ws.audioscrobbler.com/2.0/?method=user.getpersonaltags&user=burdayy&tag=rock&taggingtype=artist&api_key=YOUR_API_KEY&format=json&limit=1 121 | ``` 122 | 123 | ```json 124 | { 125 | "taggings": { 126 | "artists": { 127 | "artist": [ 128 | 129 | ] 130 | }, 131 | "@attr": { 132 | "user": "Burdayy", 133 | "tag": "rock", 134 | "page": "1", 135 | "perPage": "1", 136 | "totalPages": "0", 137 | "total": "0" 138 | } 139 | } 140 | } 141 | ``` 142 | 143 | ??? warning "Example response of a tag that does not exist" 144 | HTTP status: `200 OK` 145 | 146 | ``` 147 | https://ws.audioscrobbler.com/2.0/?method=user.getpersonaltags&user=rj&tag=rock&taggingtype=taggingtypethatdoesntexist&api_key=YOUR_API_KEY&format=json&limit=1 148 | ``` 149 | ```json 150 | 151 | { 152 | "error": 6, 153 | "message": "taggingtype param missing", 154 | "links": [] 155 | } 156 | ``` 157 | 158 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 159 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 160 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getRecentTracks.md: -------------------------------------------------------------------------------- 1 | Returns a list of the tracks recently scrobbled by this user. Adds a `nowplaying` flag with a boolean value if the user is currently scrobbling. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch the recent tracks of. 9 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. Maximum is 1000. One track is added when the user is currently listening. 10 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 11 | | `from` | [number][number] | 0000000000 | :negative_squared_cross_mark: | Beginning timestamp of a range - only display scrobbles after this time, in UNIX timestamp format. Timezone is UTC. 12 | | `to` | [number][number] | `current UNIX timestamp` | :negative_squared_cross_mark: | End timestamp of a range - only display scrobbles before this time, in UNIX timestamp format (num of seconds). Timezone is UTC. 13 | | `extended` | [boolean][boolean] | 0 | :negative_squared_cross_mark: | Whether to include extra data. This data is artist info and if the user has loved a track. Changes the output format. 14 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 15 | 16 | // Add auth docs 17 | 18 | ## Responses 19 | Errors: 20 | 21 | - 6 : Invalid parameters - Your request is missing a required parameter 22 | - 8 : Operation failed - Something else went wrong 23 | - 9 : Invalid session key - Please re-authenticate 24 | - 10 : Invalid API key - You must be granted a valid key by last.fm 25 | - 11 : Service Offline - This service is temporarily offline. Try again later. 26 | - 13 : Invalid method signature supplied 27 | - 16 : There was a temporary error processing your request. Please try again 28 | - 17 : Login required - Requested profile might not have privacy set to public. 29 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 30 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 31 | 32 | ## Examples 33 | 34 | ??? note "Example response of a user currently not scrobbling" 35 | 36 | | Parameter | Value | 37 | | ----------- | ------------ | 38 | | username | frikandel_ | 39 | | limit | 1 | 40 | | extended | 1 | 41 | | format | json | 42 | 43 | HTTP status: `200 OK` 44 | 45 | ``` 46 | https://ws.audioscrobbler.com/2.0/?api_key=YOUR_API_KEY&method=User.getrecenttracks&user=frikandel_&format=json&limit=1 47 | ``` 48 | 49 | ```json 50 | { 51 | "recenttracks": { 52 | "@attr": { 53 | "page": "1", 54 | "total": "94618", 55 | "user": "frikandel_", 56 | "perPage": "1", 57 | "totalPages": "94618" 58 | }, 59 | "track": [ 60 | { 61 | "artist": { 62 | "mbid": "63aa26c3-d59b-4da4-84ac-716b54f1ef4d", 63 | "#text": "Tame Impala" 64 | }, 65 | "album": { 66 | "mbid": "0d2cb66c-3a32-4f81-b977-9231c461c34a", 67 | "#text": "Lonerism" 68 | }, 69 | "image": [ 70 | { 71 | "size": "small", 72 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 73 | }, 74 | { 75 | "size": "medium", 76 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 77 | }, 78 | { 79 | "size": "large", 80 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 81 | }, 82 | { 83 | "size": "extralarge", 84 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/7c9c4d1009514b178c82f2201e3a1fce.jpg" 85 | } 86 | ], 87 | "streamable": "0", 88 | "date": { 89 | "uts": "1603188238", 90 | "#text": "20 Oct 2020, 10:03" 91 | }, 92 | "url": "https://www.last.fm/music/Tame+Impala/_/Feels+Like+We+Only+Go+Backwards", 93 | "name": "Feels Like We Only Go Backwards", 94 | "mbid": "1587517a-9b2b-385a-b044-673fddf88004" 95 | } 96 | ] 97 | } 98 | } 99 | ``` 100 | 101 | ??? note "Example response of a user currently scrobbling" 102 | 103 | | Parameter | Value | 104 | | ----------- | ------------ | 105 | | user | frikandel_ | 106 | | limit | 1 | 107 | | extended | 1 | 108 | | api_key | YOUR_API_KEY | 109 | | format | json | 110 | 111 | HTTP status: `200 OK` 112 | 113 | ``` 114 | https://ws.audioscrobbler.com/2.0/?method=user.getRecentTracks&user=frikandel_&limit=1&extended=1&api_key=YOUR_API_KEY&format=json 115 | ``` 116 | 117 | ```json 118 | { 119 | "recenttracks": { 120 | "@attr": { 121 | "page": "1", 122 | "total": "94613", 123 | "user": "frikandel_", 124 | "perPage": "1", 125 | "totalPages": "94613" 126 | }, 127 | "track": [ 128 | { 129 | "@attr": { 130 | "nowplaying": "true" 131 | }, 132 | "artist": { 133 | "url": "https://www.last.fm/music/Tame+Impala", 134 | "mbid": "", 135 | "image": [ 136 | { 137 | "size": "small", 138 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 139 | }, 140 | { 141 | "size": "medium", 142 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 143 | }, 144 | { 145 | "size": "large", 146 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 147 | }, 148 | { 149 | "size": "extralarge", 150 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 151 | } 152 | ], 153 | "name": "Tame Impala" 154 | }, 155 | "mbid": "08b8e930-fa2d-454d-a659-069df6111a02", 156 | "image": [ 157 | { 158 | "size": "small", 159 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 160 | }, 161 | { 162 | "size": "medium", 163 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 164 | }, 165 | { 166 | "size": "large", 167 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 168 | }, 169 | { 170 | "size": "extralarge", 171 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/7c9c4d1009514b178c82f2201e3a1fce.jpg" 172 | } 173 | ], 174 | "url": "https://www.last.fm/music/Tame+Impala/_/Apocalypse+Dreams", 175 | "streamable": "0", 176 | "album": { 177 | "mbid": "0d2cb66c-3a32-4f81-b977-9231c461c34a", 178 | "#text": "Lonerism" 179 | }, 180 | "name": "Apocalypse Dreams", 181 | "loved": "0" 182 | }, 183 | { 184 | "mbid": "0632aa27-3c1f-4ca9-ae87-e656ce677bfe", 185 | "loved": "0", 186 | "artist": { 187 | "url": "https://www.last.fm/music/Tame+Impala", 188 | "mbid": "", 189 | "image": [ 190 | { 191 | "size": "small", 192 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 193 | }, 194 | { 195 | "size": "medium", 196 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 197 | }, 198 | { 199 | "size": "large", 200 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 201 | }, 202 | { 203 | "size": "extralarge", 204 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 205 | } 206 | ], 207 | "name": "Tame Impala" 208 | }, 209 | "image": [ 210 | { 211 | "size": "small", 212 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 213 | }, 214 | { 215 | "size": "medium", 216 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 217 | }, 218 | { 219 | "size": "large", 220 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/7c9c4d1009514b178c82f2201e3a1fce.jpg" 221 | }, 222 | { 223 | "size": "extralarge", 224 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/7c9c4d1009514b178c82f2201e3a1fce.jpg" 225 | } 226 | ], 227 | "date": { 228 | "uts": "1603186824", 229 | "#text": "20 Oct 2020, 09:40" 230 | }, 231 | "streamable": "0", 232 | "url": "https://www.last.fm/music/Tame+Impala/_/Endors+Toi", 233 | "name": "Endors Toi", 234 | "album": { 235 | "mbid": "0d2cb66c-3a32-4f81-b977-9231c461c34a", 236 | "#text": "Lonerism" 237 | } 238 | } 239 | ] 240 | } 241 | } 242 | ``` 243 | 244 | ??? warning "Example response of non existing user" 245 | 246 | HTTP status: `404 NOT FOUND` 247 | 248 | ``` 249 | https://ws.audioscrobbler.com/2.0/?api_key=YOUR_API_KEY&method=User.getrecenttracks&user=userthatdoesntexist&format=json 250 | ``` 251 | 252 | ```json 253 | { 254 | "error": 6, 255 | "message": "User not found" 256 | } 257 | ``` 258 | 259 | ??? warning "Example response of user with 'Hide recent listening information' enabled" 260 | 261 | HTTP status: `403 FORBIDDEN` 262 | 263 | ``` 264 | https://ws.audioscrobbler.com/2.0/?YOUR_API_KEY=censored&method=User.getrecenttracks&user=frikandel_&format=json 265 | ``` 266 | 267 | ```json 268 | { 269 | "error": 17, 270 | "message": "Login: User required to be logged in" 271 | } 272 | ``` 273 | 274 | // Add auth docs 275 | 276 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 277 | [boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean 278 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 279 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getTopAlbums.md: -------------------------------------------------------------------------------- 1 | Get the top albums listened to by a user. You can stipulate a time period. Sends the overall chart by default. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch top albums for. 9 | | `period` | [string][string] | overall | :negative_squared_cross_mark: | The time period over which to retrieve top albums for. Can be `overall`, `7day`, `1month`, `3month`, `6month` or `12month`. 10 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 11 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | ## Responses 15 | Errors: 16 | 17 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 18 | - 8 : Operation failed - Something else went wrong 19 | - 9 : Invalid session key - Please re-authenticate 20 | - 10 : Invalid API key - You must be granted a valid key by last.fm 21 | - 11 : Service Offline - This service is temporarily offline. Try again later. 22 | - 13 : Invalid method signature supplied 23 | - 16 : There was a temporary error processing your request. Please try again 24 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 25 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 26 | 27 | 28 | ## Examples 29 | ??? note "Example response" 30 | 31 | | Parameter | Value | 32 | | --------- | ------------ | 33 | | user | aidan- | 34 | | limit | 3 | 35 | | api_key | YOUR_API_KEY | 36 | | format | json | 37 | 38 | HTTP status: `200 OK` 39 | 40 | ``` 41 | https://ws.audioscrobbler.com/2.0/?method=user.getTopAlbums&user=aidan-&limit=3&api_key=YOUR_API_KEY&format=json 42 | ``` 43 | 44 | ```json 45 | { 46 | "topalbums": { 47 | "album": [ 48 | { 49 | "artist": { 50 | "url": "https://www.last.fm/music/Joy+Division", 51 | "name": "Joy Division", 52 | "mbid": "9a58fda3-f4ed-4080-a3a5-f457aac9fcdd" 53 | }, 54 | "@attr": { 55 | "rank": "1" 56 | }, 57 | "image": [ 58 | { 59 | "size": "small", 60 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/043311d565be4296bb13f299ba1f08de.jpg" 61 | }, 62 | { 63 | "size": "medium", 64 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/043311d565be4296bb13f299ba1f08de.jpg" 65 | }, 66 | { 67 | "size": "large", 68 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/043311d565be4296bb13f299ba1f08de.jpg" 69 | }, 70 | { 71 | "size": "extralarge", 72 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/043311d565be4296bb13f299ba1f08de.jpg" 73 | } 74 | ], 75 | "playcount": "596", 76 | "url": "https://www.last.fm/music/Joy+Division/The+Best+Of", 77 | "name": "The Best Of", 78 | "mbid": "" 79 | }, 80 | { 81 | "artist": { 82 | "url": "https://www.last.fm/music/Lily+Allen", 83 | "name": "Lily Allen", 84 | "mbid": "6e0c7c0e-cba5-4c2c-a652-38f71ef5785d" 85 | }, 86 | "@attr": { 87 | "rank": "2" 88 | }, 89 | "image": [ 90 | { 91 | "size": "small", 92 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/13ac538c05b22f5d4f5290d4740b59f4.png" 93 | }, 94 | { 95 | "size": "medium", 96 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/13ac538c05b22f5d4f5290d4740b59f4.png" 97 | }, 98 | { 99 | "size": "large", 100 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/13ac538c05b22f5d4f5290d4740b59f4.png" 101 | }, 102 | { 103 | "size": "extralarge", 104 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/13ac538c05b22f5d4f5290d4740b59f4.png" 105 | } 106 | ], 107 | "playcount": "484", 108 | "url": "https://www.last.fm/music/Lily+Allen/It%27s+Not+Me,+It%27s+You+(Special+Edition)", 109 | "name": "It's Not Me, It's You (Special Edition)", 110 | "mbid": "" 111 | }, 112 | { 113 | "artist": { 114 | "url": "https://www.last.fm/music/System+of+a+Down", 115 | "name": "System of a Down", 116 | "mbid": "cc0b7089-c08d-4c10-b6b0-873582c17fd6" 117 | }, 118 | "@attr": { 119 | "rank": "3" 120 | }, 121 | "image": [ 122 | { 123 | "size": "small", 124 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/e0ea42e8dd3e4f1aaa61a7bd0c833117.png" 125 | }, 126 | { 127 | "size": "medium", 128 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/e0ea42e8dd3e4f1aaa61a7bd0c833117.png" 129 | }, 130 | { 131 | "size": "large", 132 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/e0ea42e8dd3e4f1aaa61a7bd0c833117.png" 133 | }, 134 | { 135 | "size": "extralarge", 136 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/e0ea42e8dd3e4f1aaa61a7bd0c833117.png" 137 | } 138 | ], 139 | "playcount": "482", 140 | "url": "https://www.last.fm/music/System+of+a+Down/Hypnotize", 141 | "name": "Hypnotize", 142 | "mbid": "0c63d2e4-2a99-4cc4-8991-a88dba182bbd" 143 | } 144 | ], 145 | "@attr": { 146 | "page": "1", 147 | "total": "3344", 148 | "user": "aidan-", 149 | "perPage": "3", 150 | "totalPages": "1115" 151 | } 152 | } 153 | } 154 | 155 | ``` 156 | 157 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 158 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 159 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getTopArtists.md: -------------------------------------------------------------------------------- 1 | Get the top artists listened to by a user. You can stipulate a time period. Sends the overall chart by default. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch top artists for. 9 | | `period` | [string][string] | overall | :negative_squared_cross_mark: | The time period over which to retrieve top albums for. Can be `overall`, `7day`, `1month`, `3month`, `6month` or `12month`. 10 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 11 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 12 | | `api_key` |[key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | 15 | ## Responses 16 | Errors: 17 | 18 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 19 | - 8 : Operation failed - Something else went wrong 20 | - 9 : Invalid session key - Please re-authenticate 21 | - 10 : Invalid API key - You must be granted a valid key by last.fm 22 | - 11 : Service Offline - This service is temporarily offline. Try again later. 23 | - 13 : Invalid method signature supplied 24 | - 16 : There was a temporary error processing your request. Please try again 25 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 26 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 27 | 28 | 29 | ## Examples 30 | ??? note "Example response" 31 | 32 | | Parameter | Value | 33 | | --------- | ------------ | 34 | | user | aidan- | 35 | | limit | 3 | 36 | | api_key | YOUR_API_KEY | 37 | | format | json | 38 | 39 | HTTP status: `200 OK` 40 | 41 | ``` 42 | https://ws.audioscrobbler.com/2.0/?method=user.getTopArtists&user=aidan-&limit=3&api_key=YOUR_API_KEY&format=json 43 | ``` 44 | 45 | ```json 46 | { 47 | "topartists": { 48 | "artist": [ 49 | { 50 | "@attr": { 51 | "rank": "1" 52 | }, 53 | "mbid": "5eecaf18-02ec-47af-a4f2-7831db373419", 54 | "url": "https://www.last.fm/music/Queen", 55 | "playcount": "1511", 56 | "image": [ 57 | { 58 | "size": "small", 59 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 60 | }, 61 | { 62 | "size": "medium", 63 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 64 | }, 65 | { 66 | "size": "large", 67 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 68 | }, 69 | { 70 | "size": "extralarge", 71 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 72 | }, 73 | { 74 | "size": "mega", 75 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 76 | } 77 | ], 78 | "name": "Queen", 79 | "streamable": "0" 80 | }, 81 | { 82 | "@attr": { 83 | "rank": "2" 84 | }, 85 | "mbid": "f4903035-e9cd-4b7f-b462-0447b0cd490a", 86 | "url": "https://www.last.fm/music/Videoclub", 87 | "playcount": "1124", 88 | "image": [ 89 | { 90 | "size": "small", 91 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 92 | }, 93 | { 94 | "size": "medium", 95 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 96 | }, 97 | { 98 | "size": "large", 99 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 100 | }, 101 | { 102 | "size": "extralarge", 103 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 104 | }, 105 | { 106 | "size": "mega", 107 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 108 | } 109 | ], 110 | "name": "Videoclub", 111 | "streamable": "0" 112 | }, 113 | { 114 | "@attr": { 115 | "rank": "3" 116 | }, 117 | "mbid": "c0252a1b-0133-46bb-8c4f-cade46349ec3", 118 | "url": "https://www.last.fm/music/Alestorm", 119 | "playcount": "1079", 120 | "image": [ 121 | { 122 | "size": "small", 123 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 124 | }, 125 | { 126 | "size": "medium", 127 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 128 | }, 129 | { 130 | "size": "large", 131 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 132 | }, 133 | { 134 | "size": "extralarge", 135 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 136 | }, 137 | { 138 | "size": "mega", 139 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 140 | } 141 | ], 142 | "name": "Alestorm", 143 | "streamable": "0" 144 | } 145 | ], 146 | "@attr": { 147 | "page": "1", 148 | "total": "1931", 149 | "user": "aidan-", 150 | "perPage": "3", 151 | "totalPages": "644" 152 | } 153 | } 154 | } 155 | 156 | ``` 157 | 158 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 159 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 160 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getTopTags.md: -------------------------------------------------------------------------------- 1 | Get the top tags used by this user. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch top tags for. 9 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 10 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 11 | 12 | ## Responses 13 | Errors: 14 | 15 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 16 | - 8 : Operation failed - Something else went wrong 17 | - 9 : Invalid session key - Please re-authenticate 18 | - 10 : Invalid API key - You must be granted a valid key by last.fm 19 | - 11 : Service Offline - This service is temporarily offline. Try again later. 20 | - 13 : Invalid method signature supplied 21 | - 16 : There was a temporary error processing your request. Please try again 22 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 23 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 24 | 25 | !!! Warning 26 | This API call returns 200 OK HTTP status codes even when the response contains an error. 27 | 28 | ## Examples 29 | ??? note "Example response" 30 | 31 | | Parameter | Value | 32 | | --------- | ------------ | 33 | | user | rj | 34 | | limit | 5 | 35 | | api_key | YOUR_API_KEY | 36 | | format | json | 37 | 38 | HTTP status: `200 OK` 39 | 40 | ``` 41 | https://ws.audioscrobbler.com/2.0/?method=user.getTopTags&user=rj&limit=5&api_key=YOUR_API_KEY&format=json 42 | ``` 43 | 44 | ```json 45 | { 46 | "toptags": { 47 | "tag": [ 48 | { 49 | "name": "rock", 50 | "count": "20", 51 | "url": "https://www.last.fm/tag/rock" 52 | }, 53 | { 54 | "name": "jazz", 55 | "count": "17", 56 | "url": "https://www.last.fm/tag/jazz" 57 | }, 58 | { 59 | "name": "metal", 60 | "count": "10", 61 | "url": "https://www.last.fm/tag/metal" 62 | }, 63 | { 64 | "name": "soul", 65 | "count": "8", 66 | "url": "https://www.last.fm/tag/soul" 67 | }, 68 | { 69 | "name": "female vocalists", 70 | "count": "8", 71 | "url": "https://www.last.fm/tag/female+vocalists" 72 | } 73 | ], 74 | "@attr": { 75 | "user": "RJ" 76 | } 77 | } 78 | } 79 | 80 | ``` 81 | 82 | ??? warning "Example response of a user with no tags" 83 | HTTP status: `200 OK` 84 | 85 | ``` 86 | https://ws.audioscrobbler.com/2.0/?method=user.gettoptags&user=aidan-&api_key=YOUR_API_KEY&format=json 87 | ``` 88 | 89 | ```json 90 | { 91 | "toptags": { 92 | "tag": [], 93 | "@attr": { 94 | "user": "aidan-" 95 | } 96 | } 97 | } 98 | ``` 99 | 100 | ??? warning "Example response of a user that does not exist" 101 | HTTP status: `200 OK` 102 | 103 | ``` 104 | https://ws.audioscrobbler.com/2.0/?method=user.gettoptags&user=userthatdoesntexist&api_key=YOUR_API_KEY&format=json 105 | ``` 106 | 107 | ```json 108 | { 109 | "error": 6, 110 | "message": "User not found", 111 | "links": [] 112 | } 113 | ``` 114 | 115 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 116 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 117 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getTopTracks.md: -------------------------------------------------------------------------------- 1 | Get the top tracks listened to by a user. You can stipulate a time period. Sends the overall chart by default. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch top tracks for. 9 | | `period` | [string][string] | overall | :negative_squared_cross_mark: | The time period over which to retrieve top albums for. Can be `overall`, `7day`, `1month`, `3month`, `6month` or `12month`. 10 | | `limit` | [number][number] | 50 | :negative_squared_cross_mark: | The number of results to fetch per page. 11 | | `page` | [number][number] | 1 | :negative_squared_cross_mark: | The page number to fetch. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | 15 | ## Responses 16 | Errors: 17 | 18 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 19 | - 8 : Operation failed - Something else went wrong 20 | - 9 : Invalid session key - Please re-authenticate 21 | - 10 : Invalid API key - You must be granted a valid key by last.fm 22 | - 11 : Service Offline - This service is temporarily offline. Try again later. 23 | - 13 : Invalid method signature supplied 24 | - 16 : There was a temporary error processing your request. Please try again 25 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 26 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 27 | 28 | 29 | ## Examples 30 | ??? note "Example response" 31 | 32 | | Parameter | Value | 33 | | --------- | ------------ | 34 | | user | aidan- | 35 | | limit | 3 | 36 | | api_key | YOUR_API_KEY | 37 | | format | json | 38 | 39 | HTTP status: `200 OK` 40 | 41 | ``` 42 | https://ws.audioscrobbler.com/2.0/?method=user.getTopTracks&user=aidan-&limit=3&api_key=YOUR_API_KEY&format=json 43 | ``` 44 | 45 | ```json 46 | { 47 | "toptracks": { 48 | "@attr": { 49 | "page": "1", 50 | "total": "5171", 51 | "user": "aidan-", 52 | "perPage": "3", 53 | "totalPages": "1724" 54 | }, 55 | "track": [ 56 | { 57 | "@attr": { 58 | "rank": "1" 59 | }, 60 | "duration": "205", 61 | "playcount": "440", 62 | "artist": { 63 | "url": "https://www.last.fm/music/Joy+Division", 64 | "name": "Joy Division", 65 | "mbid": "9a58fda3-f4ed-4080-a3a5-f457aac9fcdd" 66 | }, 67 | "image": [ 68 | { 69 | "size": "small", 70 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 71 | }, 72 | { 73 | "size": "medium", 74 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 75 | }, 76 | { 77 | "size": "large", 78 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 79 | }, 80 | { 81 | "size": "extralarge", 82 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 83 | } 84 | ], 85 | "streamable": { 86 | "fulltrack": "0", 87 | "#text": "0" 88 | }, 89 | "mbid": "00046764-a84c-3568-b8b1-6a8174f7ca0b", 90 | "name": "Love Will Tear Us Apart", 91 | "url": "https://www.last.fm/music/Joy+Division/_/Love+Will+Tear+Us+Apart" 92 | }, 93 | { 94 | "@attr": { 95 | "rank": "2" 96 | }, 97 | "duration": "222", 98 | "playcount": "399", 99 | "artist": { 100 | "url": "https://www.last.fm/music/Videoclub", 101 | "name": "Videoclub", 102 | "mbid": "f4903035-e9cd-4b7f-b462-0447b0cd490a" 103 | }, 104 | "image": [ 105 | { 106 | "size": "small", 107 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 108 | }, 109 | { 110 | "size": "medium", 111 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 112 | }, 113 | { 114 | "size": "large", 115 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 116 | }, 117 | { 118 | "size": "extralarge", 119 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 120 | } 121 | ], 122 | "streamable": { 123 | "fulltrack": "0", 124 | "#text": "0" 125 | }, 126 | "mbid": "f2d3087b-913d-41e4-aa94-0c207fd30d1d", 127 | "name": "Roi", 128 | "url": "https://www.last.fm/music/Videoclub/_/Roi" 129 | }, 130 | { 131 | "@attr": { 132 | "rank": "3" 133 | }, 134 | "duration": "193", 135 | "playcount": "352", 136 | "artist": { 137 | "url": "https://www.last.fm/music/Clara+Luciani", 138 | "name": "Clara Luciani", 139 | "mbid": "a6386935-e6ee-4aaa-aaa8-70f56b79bc29" 140 | }, 141 | "image": [ 142 | { 143 | "size": "small", 144 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 145 | }, 146 | { 147 | "size": "medium", 148 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 149 | }, 150 | { 151 | "size": "large", 152 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 153 | }, 154 | { 155 | "size": "extralarge", 156 | "#text": "https://lastfm.freetls.fastly.net/i/u/300x300/2a96cbd8b46e442fc41c2b86b821562f.png" 157 | } 158 | ], 159 | "streamable": { 160 | "fulltrack": "0", 161 | "#text": "0" 162 | }, 163 | "mbid": "03b34579-3c04-4c34-a203-728500e95f52", 164 | "name": "La grenade", 165 | "url": "https://www.last.fm/music/Clara+Luciani/_/La+grenade" 166 | } 167 | ] 168 | } 169 | } 170 | 171 | ``` 172 | 173 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 174 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 175 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getWeeklyAlbumChart.md: -------------------------------------------------------------------------------- 1 | Get an album chart for a user profile, for a given date range. If no date range is supplied, it will return the most recent album chart for this user. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch the charts of. 9 | | `limit` | [number][number] | `none` | :negative_squared_cross_mark: | The number of results to fetch. Maximum 1000. 10 | | `from` | [number][number] | `UNIX timestamp of the seventh most recent time it was 12pm (UTC)` | :negative_squared_cross_mark: | The date at which the chart should start from (can preceed a week). 11 | | `to` | [number][number] | `UNIX timestamp of the last time it was 12pm (UTC)` | :negative_squared_cross_mark: | The date at which the chart should end on. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | ## Responses 15 | Errors: 16 | 17 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 18 | - 8 : Operation failed - Something else went wrong 19 | - 9 : Invalid session key - Please re-authenticate 20 | - 10 : Invalid API key - You must be granted a valid key by last.fm 21 | - 11 : Service Offline - This service is temporarily offline. Try again later. 22 | - 13 : Invalid method signature supplied 23 | - 16 : There was a temporary error processing your request. Please try again 24 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 25 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 26 | 27 | ## Examples 28 | ??? note "Example response" 29 | 30 | | Parameter | Value | 31 | | --------- | ------------ | 32 | | user | aidan- | 33 | | limit | 2 | 34 | | api_key | YOUR_API_KEY | 35 | | format | json | 36 | 37 | HTTP status: `200 OK` 38 | 39 | ``` 40 | https://ws.audioscrobbler.com/2.0/?method=user.getWeeklyAlbumChart&user=aidan-&limit=2&api_key=YOUR_API_KEY&format=json 41 | ``` 42 | 43 | ```json 44 | { 45 | "weeklyalbumchart": { 46 | "album": [ 47 | { 48 | "artist": { 49 | "mbid": "cc0b7089-c08d-4c10-b6b0-873582c17fd6", 50 | "#text": "System of a Down" 51 | }, 52 | "@attr": { 53 | "rank": "1" 54 | }, 55 | "mbid": "0c63d2e4-2a99-4cc4-8991-a88dba182bbd", 56 | "playcount": "417", 57 | "name": "Hypnotize", 58 | "url": "https://www.last.fm/music/System+of+a+Down/Hypnotize" 59 | }, 60 | { 61 | "artist": { 62 | "mbid": "", 63 | "#text": "The Pogues" 64 | }, 65 | "@attr": { 66 | "rank": "2" 67 | }, 68 | "mbid": "", 69 | "playcount": "114", 70 | "name": "Hell's Ditch (Expanded Edition)", 71 | "url": "https://www.last.fm/music/The+Pogues/Hell%27s+Ditch+(Expanded+Edition)" 72 | } 73 | ], 74 | "@attr": { 75 | "user": "aidan-", 76 | "from": "1602504000", 77 | "to": "1603108800" 78 | } 79 | } 80 | } 81 | 82 | ``` 83 | 84 | !!! warning 85 | To use parameters: `from` and `to`, you must declare **both** of them otherwise it will be treated with no start or end date 86 | 87 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 88 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 89 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getWeeklyArtistChart.md: -------------------------------------------------------------------------------- 1 | Get an artist chart for a user profile, for a given date range. If no date range is supplied, it will return the most recent artist chart for this user. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :negative_squared_cross_mark: | The Last.fm username to fetch the charts of. 9 | | `limit` | [number][number] | `none` | :negative_squared_cross_mark: | The number of results to fetch. Maximum 1000. 10 | | `from` | [number][number] | `UNIX timestamp of the seventh most recent time it was 12pm (UTC)` | :negative_squared_cross_mark: | The date at which the chart should start from (can preceed a week). 11 | | `to` | [number][number] | `UNIX timestamp of the last time it was 12pm (UTC)` | :negative_squared_cross_mark: | The date at which the chart should end on. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | 15 | ## Responses 16 | Errors: 17 | 18 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 19 | - 8 : Operation failed - Something else went wrong 20 | - 9 : Invalid session key - Please re-authenticate 21 | - 10 : Invalid API key - You must be granted a valid key by last.fm 22 | - 11 : Service Offline - This service is temporarily offline. Try again later. 23 | - 13 : Invalid method signature supplied 24 | - 16 : There was a temporary error processing your request. Please try again 25 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 26 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 27 | 28 | ## Examples 29 | ??? note "Example response" 30 | 31 | | Parameter | Value | 32 | | --------- | ------------ | 33 | | user | aidan- | 34 | | limit | 2 | 35 | | api_key | YOUR_API_KEY | 36 | | format | json | 37 | 38 | HTTP status: `200 OK` 39 | 40 | ``` 41 | https://ws.audioscrobbler.com/2.0/?method=user.getWeeklyArtistChart&user=aidan-&limit=2&api_key=YOUR_API_KEY&format=json 42 | ``` 43 | 44 | ```json 45 | { 46 | "weeklyartistchart": { 47 | "artist": [ 48 | { 49 | "@attr": { 50 | "rank": "1" 51 | }, 52 | "mbid": "cc0b7089-c08d-4c10-b6b0-873582c17fd6", 53 | "playcount": "572", 54 | "name": "System of a Down", 55 | "url": "https://www.last.fm/music/System+of+a+Down" 56 | }, 57 | { 58 | "@attr": { 59 | "rank": "2" 60 | }, 61 | "mbid": "d41a6875-b626-4c0f-89a1-aecb643d29ff", 62 | "playcount": "165", 63 | "name": "The Pogues", 64 | "url": "https://www.last.fm/music/The+Pogues" 65 | } 66 | ], 67 | "@attr": { 68 | "user": "aidan-", 69 | "from": "1602504000", 70 | "to": "1603108800" 71 | } 72 | } 73 | } 74 | 75 | ``` 76 | 77 | !!! warning 78 | To use parameters: `from` and `to`, you must declare **both** of them otherwise it will be treated with no start or end date 79 | 80 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 81 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 82 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /docs/user/getWeeklyTrackChart.md: -------------------------------------------------------------------------------- 1 | Get a track chart for a user profile, for a given date range. If no date range is supplied, it will return the most recent track chart for this user. 2 | 3 | No authentication required. 4 | 5 | ## Parameters 6 | | Method | Type | Default | Required | Description 7 | | ------ | ---- | ------- | -------- | ----------- 8 | | `user` | [string][string] | `none` | :white_check_mark: | The Last.fm username to fetch the friends of. 9 | | `limit` | [number][number] | `none` | :negative_squared_cross_mark: | The number of results to fetch. Maximum 1000. 10 | | `from` | [number][number] | `UNIX timestamp of the seventh most recent time it was 12pm (UTC)` | :negative_squared_cross_mark: | The date at which the chart should start from (can preceed a week). 11 | | `to` | [number][number] | `UNIX timestamp of the last time it was 12pm (UTC)` | :negative_squared_cross_mark: | The date at which the chart should end on. 12 | | `api_key` | [key][key] | `none` | :white_check_mark: | A Last.fm API key. 13 | 14 | ## Responses 15 | Errors: 16 | 17 | - 6 : Invalid parameters - Your request was either missing a required parameter, the parameter was not found, or had 0 results 18 | - 8 : Operation failed - Something else went wrong 19 | - 9 : Invalid session key - Please re-authenticate 20 | - 10 : Invalid API key - You must be granted a valid key by last.fm 21 | - 11 : Service Offline - This service is temporarily offline. Try again later. 22 | - 13 : Invalid method signature supplied 23 | - 16 : There was a temporary error processing your request. Please try again 24 | - 26 : Suspended API key - Access for your account has been suspended, please contact Last.fm 25 | - 29 : Rate limit exceeded - Your IP has made too many requests in a short period 26 | 27 | ## Examples 28 | ??? note "Example response" 29 | 30 | | Parameter | Value | 31 | | --------- | ------------ | 32 | | user | aidan- | 33 | | limit | 2 | 34 | | api_key | YOUR_API_KEY | 35 | | format | json | 36 | 37 | HTTP status: `200 OK` 38 | 39 | ``` 40 | https://ws.audioscrobbler.com/2.0/?method=user.getWeeklyTrackChart&user=aidan-&limit=2&api_key=YOUR_API_KEY&format=json 41 | ``` 42 | 43 | ```json 44 | { 45 | "weeklytrackchart": { 46 | "@attr": { 47 | "user": "aidan-", 48 | "from": "1602504000", 49 | "to": "1603108800" 50 | }, 51 | "track": [ 52 | { 53 | "artist": { 54 | "mbid": "cc0b7089-c08d-4c10-b6b0-873582c17fd6", 55 | "#text": "System of a Down" 56 | }, 57 | "@attr": { 58 | "rank": "1" 59 | }, 60 | "mbid": "0f1f8fdb-d14b-4629-8c29-43f041d52f88", 61 | "url": "https://www.last.fm/music/System+of+a+Down/_/Kill+Rock+%27n+Roll", 62 | "image": [ 63 | { 64 | "size": "small", 65 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 66 | }, 67 | { 68 | "size": "medium", 69 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 70 | }, 71 | { 72 | "size": "large", 73 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 74 | } 75 | ], 76 | "name": "Kill Rock 'n Roll", 77 | "playcount": "176" 78 | }, 79 | { 80 | "artist": { 81 | "mbid": "cc0b7089-c08d-4c10-b6b0-873582c17fd6", 82 | "#text": "System of a Down" 83 | }, 84 | "@attr": { 85 | "rank": "2" 86 | }, 87 | "mbid": "145977d0-21c8-449a-b11c-1e2f96e26af3", 88 | "url": "https://www.last.fm/music/System+of+a+Down/_/Stealing+Society", 89 | "image": [ 90 | { 91 | "size": "small", 92 | "#text": "https://lastfm.freetls.fastly.net/i/u/34s/2a96cbd8b46e442fc41c2b86b821562f.png" 93 | }, 94 | { 95 | "size": "medium", 96 | "#text": "https://lastfm.freetls.fastly.net/i/u/64s/2a96cbd8b46e442fc41c2b86b821562f.png" 97 | }, 98 | { 99 | "size": "large", 100 | "#text": "https://lastfm.freetls.fastly.net/i/u/174s/2a96cbd8b46e442fc41c2b86b821562f.png" 101 | } 102 | ], 103 | "name": "Stealing Society", 104 | "playcount": "51" 105 | } 106 | ] 107 | } 108 | } 109 | 110 | ``` 111 | 112 | !!! warning 113 | To use parameters: `from` and `to`, you must declare **both** of them otherwise it will be treated with no start or end date 114 | 115 | [string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String 116 | [number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number 117 | [key]: https://www.last.fm/api/account/create -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Unofficial Last.fm API docs 2 | site_description: Unofficial documentation for the Last.fm API 3 | 4 | repo_url: https://github.com/lastfm-docs/api-docs 5 | repo_name: lastfm-docs/api-docs 6 | 7 | edit_uri: edit/master/docs 8 | 9 | theme: 10 | name: 'material' 11 | features: 12 | - content.action.edit 13 | icon: 14 | edit: material/pencil 15 | palette: 16 | # Light mode 17 | - media: "(prefers-color-scheme: light)" 18 | scheme: default 19 | primary: indigo 20 | accent: indigo 21 | toggle: 22 | icon: material/toggle-switch-off-outline 23 | name: Switch to dark mode 24 | 25 | # Dark mode 26 | - media: "(prefers-color-scheme: dark)" 27 | scheme: slate 28 | primary: blue 29 | accent: blue 30 | toggle: 31 | icon: material/toggle-switch 32 | name: Switch to light mode 33 | markdown_extensions: 34 | - admonition 35 | - pymdownx.details 36 | - pymdownx.superfences 37 | - pymdownx.tabbed 38 | - pymdownx.emoji 39 | - toc: 40 | permalink: true 41 | --------------------------------------------------------------------------------