soundcloud / api watch
public
Forks0Right
Watchers52Right
Description: SoundCloud API Code
Home | Edit | New

03 Resource Types

The resources can have different roles, but when processing the response data from the API the five resource types are all you have to keep in mind.

User

Users are the active object. Users are able to create Tracks, Comments, make other Users their contacts and make Tracks favorites. Full search, filtering and usage documentation here.

XML representation:

<user>
  <id type="integer">1</id>
  <username>joey</username>
  <full-name>Joey Tempest</full-name>
  <permalink>joey</permalink>
  <description>Stormwind, just like a wind.</description>
  <city>Upplands Väsby</city>
  <country>Sweden</country>
  <discogs-name>joeytempest</discogs-name>
  <myspace-name>joeyt</myspace-name>
  <website>http://www.europe.com/~joeyt/</website>
  <website-title>Home of the Stormwind</website-title>
  <online>true</online>
  <avatar-url>http://a1.soundcloud.com/profile_images/0000/0000/i123456.jpg</avatar-url>
  <permalink-url>http://soundcloud.com/joey</permalink-url>
  <uri>http://api.soundcloud.com/users/1</uri>
  <track-count>1</track-count>
  <followings-count>2</followings-count>
  <followers-count>57900</followers-count>
</user>

Track

Tracks have two different sharing modes, public and private. Public tracks are accessible to all users and private tracks are only accessible to users to whom the Track’s creator has explicitly given permission. Full search, filtering and usage documentation here.

XML representation:

<track>
  <id type="integer">1</id>
  <user-id type="integer">881091440</user-id>
  <title>Final Countdown</title>
  <permalink>final-countdown</permalink>
  <description>This is a song I wrote with some friends a couple of years ago.</description>
  <sharing>public</sharing>
  <bpm type="float">118.2</bpm>
  <comments-count type="integer">23</comments-count>
  <created-at type="datetime">2008-02-20T18:44:35+01:00</created-at>
  <downloadable type="boolean">false</downloadable>
  <downloads-count type="integer">34</downloads-count>
  <duration type="integer">31000</duration>
  <genre>Rock</genre>
  <streamable type="boolean">true</streamable>
  <uri>http://api.soundcloud.com/tracks/1</uri>
  <user>
    <uri>http://api.soundcloud.com/users/1</uri>
    <username>joey</username>
    <permalink>joey</permalink>
    <permalink-url>http://soundcloud.com/joey</permalink-url>   
  </user>
  <permalink-url>http://soundcloud.com/joey/final-countdown</permalink-url>
  <playback-count>644</playback-count>
  <artwork-url>http://a1.soundcloud.com/artworks/0200/120/i02911_big.jpg</artwork-url>
  <waveform-url>http://a1.soundcloud.com/assets/1/072/001/00001026/waveform-medium.png</waveform-url>
  <purchase-url>http://my-music-shop.com/tracks/final-countdown/</purchase-url>
  <stream-url>http://media.soundcloud.com/joey/final-countdown.mp3</stream-url>
  <user-playback-count>2</user-playback-count>
  <user-favorite>false</user-favorite>
</track>

Playlist (Set)

Playlists are collections of tracks created by the owner of the tracks. Full search, filtering and usage documentation here.

XML representation:

<playlist>
  <created-at type="datetime">2008-07-22T13:28:59+02:00</created-at>
  <description/>
  <genre/>
  <id type="integer">1</id>
  <permalink>my-own-set</permalink>
  <title>My Set</title>
  <user-id type="integer">1</user-id>
  <permalink-url>http://soundcloud.com/joey/sets/my-own-set</permalink-url>
  <uri>http://api.soundcloud.com/playlists/1</uri>
  <artwork-url>
    http://a1.soundcloud.com/images/default_artwork_big.png?5216
  </artwork-url>
  <duration>538320</duration>
  <type/>
  <user>
    <uri>http://api.soundcloud.com/users/1</uri>
    <username>joey</username>
    <permalink>joey</permalink>
    <permalink-url>http://soundcloud.com/joey</permalink-url>
  </user>
  <tracks type="array">
    <track>
      <bpm type="float" nil="true"/>
      <created-at type="datetime">2008-06-25T16:38:02+02:00</created-at>
      ...
      <user-favorite>false</user-favorite>
    </track>
    <track>
      <bpm type="float">126.1</bpm>
      <created-at type="datetime">2007-07-28T18:58:54+02:00</created-at>
      ...
      <user-favorite>false</user-favorite>
    </track>
  </tracks>
</playlist>

Group

Groups contain tracks contributed by users. Users can join a group to get notifications about new tracks and discussion posts. Groups can be moderated by a group of users.

Groups are currently read only resources

Full search, filtering and usage documentation.

XML representation:

<group>
  <description>A description of the group.</description>
  <id type="integer">1</id>
  <name>This is the group name</name>
  <short-description>A shorter description.</short-description>
  <uri>http://api.soundcloud.com/groups/1</uri>
  <permalink-url>http://soundcloud.com/groups/group-name</permalink-url>
  <permalink>group-name</permalink>
  <creator>
    <uri>http://api.soundcloud.com/users/1</uri>
    <username>joey</username>
    <permalink>joey</permalink>
    <permalink-url>http://soundcloud.com/joey</permalink-url>
  </creator>
</group>

Comment

Comments can be made on a Track. Users can only read comments made on Tracks they have access to. If a timestamp is supplied the comment will be displayed at, or around, that time during playback of the Track on the SoundCloud website. Full search, filtering and usage documentation here.

XML representation:

<comment>
  <id type="integer">1</id>
  <track-id type="integer">1</track-id>
  <user-id type="integer">1</user-id>
  <body>Great guitar solo!</body>
  <timestamp type="integer">2010000</timestamp>
  <uri>http://api.soundcloud.com/comments/1</uri>
</comment>

Event

Events are notifications informing a User about things that have happened concerning them, and contains the related resources.

They are always ordered with the latest events first.

In the examples below the User receiving the event is called “the recipient”.

Full search, filtering and usage documentation here.

Comment

Another User creates a Comment on a Track of the recipient or in a Comment thread where the recipient has also made a comment.

<event>
  <created-at type="datetime">2008-04-04T11:05:15+02:00</created-at>
  <id type="integer">4</id>
  <resource_id type="integer">1</id>
  <type>Comment</type>
  <comment>
     <id type="integer">1</id>
     ...
  </comment>
</event>

Track

A User gives the recipient access to a private Track or a User whom the recipient is a fan of creates a public Track.

<event>
  <created-at type="datetime">2008-04-03T11:05:15+02:00</created-at>
  <id type="integer">3</id>
  <resource_id type="integer">1</id>
  <type>Track</type>
  <track>
    <id type="integer">1</id>
    ...
  </track>
</event>

Fan

A User adds the recipient as a contact, hence becomes a fan of the recipient.

<event>
  <created-at type="datetime">2008-04-02T11:05:15+02:00</created-at>
  <id type="integer">2</id>
  <resource_id type="integer">1</id>
  <type>Fan</type>
  <user>
    <id type="integer">1</id>
    ...
  </user>
</event>

Favorite

A User adds one of the recipient’s Tracks to their favorites.

<event>
  <created-at type="datetime">2008-04-01T11:05:15+02:00</created-at>
  <id type="integer">1</id>
  <resource_id type="integer">1</id>
  <type>Favorite</type>
  <track>
    <id type="integer">1</id>
    ...
  </track>
</event>

Pages feed

Last edited by soundcloud, Thu Sep 17 09:21:14 -0700 2009
Home | Edit | New
Versions: