10.2 Resources: tracks

GET /tracks

Type: Collection of Tracks

Collection of all tracks.

Parameters

Duration is measured in milliseconds.

Types need to be one of the following: “cover”, “demo”, “djset”, “in progress”, “live”, “mashup”, “original”, “part”, “podcast”, “reedit”, “remix” or “sample”

Unauthenticated request (shows only public tracks):

$ curl 'http://api.soundcloud.com/tracks'

< HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<tracks type="array">
  <track>
    <id type="integer">11</id>
    <title>Final Countdown</title>
  ...
    <sharing>public</sharing>
  </track>
  <track>
    <id type="integer">21</id>
    <title>The Musical Offering</title>
  ...
    <sharing>public</sharing>
  </track>
</tracks>

Authenticated request (shows only public tracks):

$ curl -u joey:hairspray 'http://api.soundcloud.com/tracks'

< HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<tracks type="array">
  <track>
    <id type="integer">11</id>
    <title>Final Countdown</title>
    ...
    <sharing>public</sharing>
  </track>
  <track>
    <id type="integer">12</id>
    <title>Carrie</title>
    ...
    <sharing>private</sharing>
  </track>
  <track>
    <id type="integer">21</id>
    <title>The Musical Offering</title>
    ...
    <sharing>public</sharing>
  </track>
  <track>
    <id type="integer">22</id>
    <title>Ice, Ice, Baby</title>
    ...
    <sharing>private</sharing>
  </track>
</tracks>

The collection is searchable by passing the query to the resource. It then lists a subset matching the search query.

$ curl 'http://api.soundcloud.com/tracks?q=ice'

< HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<tracks type="array">
  <track>
    <bpm type="float" nil="true"></bpm>
    <comments-count type="integer">0</comments-count>
    <created-at type="datetime">2008-02-26T17:39:24+01:00</created-at>
    ...
    <sharing>public</sharing>
  </track>
</tracks>

Downloading tracks

Tracks that are downloadable can be downloaded from the download-url in the track representation.

<track>
  <id type="integer">11</id>
  <title>Final Countdown</title>
  ...
  <downloadable>true</downloadable>
  <download-url>http://sandbox-soundcloud.com/joey/final-countdown/download</download-url>
</track>

To download a public Track, do a request to the URL and follow the redirect to get the file.

Downloading a private Track requires authentication with OAuth. Please note that the host is “sandbox-soundcloud.com” and not “api.sandbox-soundcloud.com”. For the live server the host is “soundcloud.com”. A successful response will give you a redirect to the file.

Getting streams

If a track is streamable, you can get the stream version of the track from the stream-url.

<track>
  <id type="integer">11</id>
  <title>Final Countdown</title>
  ...
  <streamable>true</streamable>
  <stream-url>http://media.sandbox-soundcloud.com/stream/iEKZkw8cCBZf</stream-url>
</track>

If the track is private you need to sign the request with OAuth and the parameters MUST be sent in the query string.

So if “Final Countdown” is a private Track and we want to get it’s stream it we would get a signed URL looking something like:

http://media.sandbox-soundcloud.com/stream/iEKZkw8cCBZf?oauth_nonce=CSZMby3XFbfjqZB9LwYPYsyZqEbgTiclekrTyfaOeM&oauth_signature_method=HMAC-SHA1&oauth_token=SdMzbtW5ZQNFmkiVZrWxLA&oauth_timestamp=1225906320&oauth_consumer_key=xqw4ef0C4iqS5PC5yaX4WA&oauth_version=1.0&oauth_signature=4pVMW43V4GOMBGPomjr9pO56BBo%3D

A request to this URI will respond with the file directly. You don’t need to follow any redirects.

Sorting by hotness

The hotness of a Track is based on activity around the Track, such as comments on the Track, Users making Tracks their favorites and playbacks.
The optional date interval for the hotness ordering is the time period when the tracks were “considered hot”. If you are interested in the Tracks that have received the most attention during a specific period you can pass a time interval from which the hotness is based. The time interval is set by the independently optional bounding parameters created_at[from] and created_at[to].

Assume that current time is 2008-03-13 18:00:00.

Hot tracks the last 24 hours, from 2008-03-12 18:00:00

/tracks?order=hotness&created_at[from]=2008-03-12+18%3A00%3A00

Yesterday’s hot tracks, from 2008-03-11 00:00:00, to 2008-03-12 00:00:00

/tracks?order=hotness&created_at[from]=2008-03-11+00%3A00%3A00&created_at[to]=2008-03-12+00%3A00%3A00

Hot tracks the last seven days, from 2008-03-06

/tracks?order=hotness&created_at[from]=2008-03-06

Hot tracks this month, from 2008-03-01

/tracks?order=hotness&created_at[from]=2008-03-01

Hot tracks this year, from 2008-01-01

/tracks?order=hotness&created_at[from]=2008-01-01

The hottest tracks of all time,

/tracks?order=hotness

POST /tracks

Response headers:
Location – Canonical URI of the track

Parameters

Creates a track belonging to the logged in user. Since a file asset is attached the request must be a ‘multipart/form-data’ request, hence we can’t send data in XML-format.

$ curl -u joey:hairspray 'http://api.sandbox-soundcloud.com/tracks' \
  -F track[asset_data]=@superstitious.aif \
  -F track[title]=Superstitious \
  -F track[artwork_data]=@superstitious_artwork.png
  -F track[shared_to][emails][][address]=a.user@example.com

< HTTP/1.1 201 Created
< Location: http://api.soundcloud.com/tracks/13

The track will feature artwork and be shared to the email address “a.user@example.com”.

Next page: tracks contd.