{% extends "base.html" %} {% block head %} {% endblock %} {% block content %}
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 {{ request.build_absolute_uri }}{{ user.username|default:"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.username|default:"USER" }}/.
Currently, the only format available to get the resources is JSON.
Method | url |
---|---|
GET | {{ request.build_absolute_uri }}{{ user.username|default:"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"} }]
Method | url |
---|---|
POST | {{ request.build_absolute_uri }}{{ user.username|default:"USER" }}/scrobbles/ |
Sends scrobbles to the server.
parameter name | value type | description | mandatory |
---|---|---|---|
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 |
Method | url |
---|---|
GET | {{ request.build_absolute_uri }}{{ user.username|default:"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"}]
Method | url |
---|---|
GET | {{ request.build_absolute_uri }}{{ user.username|default:"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:
{% if user.is_authenticated %}
{{ request.build_absolute_uri }}{{user.username}}/artists/?name=Tool
{% else %}
{{ request.build_absolute_uri }}USER/artists/?name=Tool
{% endif %}
parameter name | value type | description | mandatory |
---|---|---|---|
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 |
Method | url |
---|---|
GET | {{ request.build_absolute_uri }}{{ user.username|default:"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"}]
parameter name | value type | description | mandatory |
---|---|---|---|
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 |
Method | url |
---|---|
GET | {{ request.build_absolute_uri }}{{ user.username|default:"USER" }}/artists/<artist_uuid> |
NOT IMPLEMENTED YET
parameter name | value type | description | mandatory |
---|---|---|---|
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 |
Method | url |
---|---|
GET | {{ request.build_absolute_uri }}{{ user.username|default:"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"},]
Method | url |
---|---|
GET | {{ request.build_absolute_uri }}{{ user.username|default:"USER" }}/titles/<title_uuid> |
NOT IMPLEMENTED YET
parameter name | value type | description | mandatory |
---|---|---|---|
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 |
Attention: In the following examples, you may prefer using a rc file (.wgetrc or .curlrc) instead of leaving a password in your shell history.
wget --http-user=USER --http-password=S3CRET --post-data="timestamp=1335617459&art=Tool&tit=Opiate" {{ request.build_absolute_uri }}USER/scrobbles/
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 {{ request.build_absolute_uri }}USER/scrobbles/?from=1335617400
curl --user USER:S3CRET {{ request.build_absolute_uri }}USER/artists/
Or limiting the count to the last week of scrobbles (604800 in a week in second).
curl --user USER:S3CRET {{ request.build_absolute_uri }}USER/artists/?from=$(($(date +%s) - 604800))
wget --http-user=USER --http-password=S3CRET {{ request.build_absolute_uri }}USER/
Retrieves your account information as a JSON string