API (alpha state) 0.93

Authentication

The server uses currently Basic HTTP authentication.

Pay Attention: this is insecure over HTTP, please use SSL/TLS (ie HTTPS) connection to ensure confidentiality of credentials.

Accessing or posting resources under and including https://server.tld/api/USER/ triggers a 401 reply.
The client should then answer with the correct user's credentials in order to access or post resources beneath api/USER/.


Main resources

Format

Currently, the only format available to get the resources is JSON.


User

GET

Method url
GET https://server.tld/api/USER/

Get a json formated object of user's account.
No parameters available for this ressource.

    [{"pk": 4, "model": "auth.user",
      "fields": {"first_name": "Alan Mathison",
                 "last_name": "Turing",
                 "last_login": "2012-11-17T09:52:05.722Z",
                 "email": "am@turing.org",
                 "date_joined": "2012-05-08T14:47:47Z"}
    }]

Scrobbling

POST

Method url
POST https://server.tld/api/USER/scrobbles/

Sends scrobbles to the server.

Parameters

parameter namevalue typedescriptionmandatory
timestamp integer scrobble timestamp, in second since epoch yes
art string artist name yes
tit string track title name yes
alb string album name optional, not yet implemented
art_mbid string MusicBrainz Artist ID1 optional, but kinda helpful
tit_mbid string MusicBrainz Title ID1 optional
alb_mbid string MusicBrainz Album ID1 optional, not implemented yet

GET

Scrobbles

Method url
GET https://server.tld/api/USER/scrobbles/

Get a json formated list of the scobbbles. The default is to serve a year long of scrobbles, use an explicit time range to override it.
Here is a snippet with 2 scrobbles:

    [{"date": "1245167724", "track": "Opiate",    "artist": "Tool"},
     {"date": "1245166754", "track": "Vicarious", "artist": "Tool"}]

Artists scrobbles

Method url
GET https://server.tld/api/USER/scrobbles/artists/<artist_uuid>

Get a json formated list of scrobbles for a specific artist. The default is to serve a year long of scrobbles, use an explicit time range to override it.
Here is an example for the artist UUID 66fc5bf8-daa4-4241-b378-9bc9077939d2 (ie. Tool):

    [{"date": "1336649438", "track": "10.000 Days (Wings Pt 2)",
     {"date": "1336952483", "track": "Schism",
     {"date": "1337137443", "track": "The Pot",]

Artist UUID can be retrieved via artists resource. For intance you can request the following to get Tool UUID:
https://server.tld/api/USER/artists/?name=Tool

Parameters

parameter namevalue typedescriptionmandatory
from integer scrobbles lower timestamp limit, in second since epoch optional
to integer scrobbles higher timestamp limit, in second since epoch optional
limit integer Limit the number of artists returned optional
callback string JSONP2 callback function name for cross-domain requests optional

Artists related ressources

GET

Artists stats

Method url
GET https://server.tld/api/USER/artists/

Get a json formated list of artists ordered by counts.
Here is an example for two artists:

    [{"count": 4,  "name": "Tool", "is_mbid": false, "id": "66fc5bf8-daa4-4241-b378-9bc9077939d2"},
     {"count": 16, "name": "AFX",  "is_mbid": false, "id": "f2355b2f-09e4-4cf7-8ba4-51854b58f214"}]

Parameters

parameter namevalue typedescriptionmandatory
from integer scrobbles lower timestamp limit, in second since epoch optional
to integer scrobbles higher timestamp limit, in second since epoch optional
limit integer Limit the number of artists returned optional
name string Filters results searching for artists name that contains the string (ignoring case) optional
callback string JSONP2 callback function name for cross-domain requests optional

Artist stats

Method url
GET https://server.tld/api/USER/artists/<artist_uuid>

NOT IMPLEMENTED YET

Parameters

parameter namevalue typedescriptionmandatory
from integer scrobbles lower timestamp limit, in second since epoch optional
to integer scrobbles higher timestamp limit, in second since epoch optional
limit integer Limit the number of artists returned optional
callback string JSONP2 callback function name for cross-domain requests optional

Titles

GET

Titles stats

Method url
GET https://server.tld/api/USER/titles/

Get a json formated list of titles count.
Here is an example with a list of two titles:

    [{"count": 3, "artist": "Amon Tobin", "name": "Bitter & Twisted", "id": "6582137e-89e4-4409-8485-4e2a2196b500"},
     {"count": 1, "artist": "Tool",       "name": "Pushit",           "id": "cfdc01c8-a84e-4034-a3ec-38faaaa213dd"},]

Title stats

Method url
GET https://server.tld/api/USER/titles/<title_uuid>

NOT IMPLEMENTED YET

Parameters

parameter namevalue typedescriptionmandatory
from integer scrobbles lower timestamp limit, in second since epoch optional
to integer scrobbles higher timestamp limit, in second since epoch optional
limit integer Limit the number of artists returned optional
callback string JSONP2 callback function name for cross-domain requests optional

Examples

Attention: In the following examples, you may prefer using a rc file (.wgetrc or .curlrc) instead of leaving a password in your shell history.

Simple scrobbling with wget:

wget --http-user=USER --http-password=S3CRET --post-data="timestamp=1335617459&art=Tool&tit=Opiate"  https://server.tld/api/USER/scrobbles/

Retrieve scrobbles over a specific time range.

Get scrobbles from 2012-04-28 14:50:00 UTC to present (timestamp in second since epoch, UTC time zone).

wget --http-user=USER --http-password=S3CRET  https://server.tld/api/USER/scrobbles/?from=1335617400

Artists listening statistic over the year with curl

curl --user USER:S3CRET https://server.tld/api/USER/artists/

Or limiting the count to the last week of scrobbles (604800 in a week in second).

curl --user USER:S3CRET https://server.tld/api/USER/artists/?from=$(($(date +%s) - 604800))

User account

wget --http-user=USER --http-password=S3CRET https://server.tld/api/USER/

Retrieves your account information as a JSON string


1Please consult MusicBrainz's documentation for further information about MusicBrainz Identifier
2Consult JQuery for an example about JSONP ajax request