User Tools

Site Tools


rest_api

REST API Documentation

License

The use of this 'application programming interface - API' is subject to the creative commons license Attribution-NonCommercial-NoDerivatives 4.0 International License.

Formats

This developer API offers a pretty typical RESTful interface and all calls are available in 3 formats: JSON, XML, and JSONP.

You can pick your format by appending what you need at the end of the URL.

curl http://diy.fm/rest/v1/user/info.xml?id=316
curl http://diy.fm/rest/v1/user/info.json?id=316
curl http://diy.fm/rest/v1/user/info.jsonp?id=316&callback=test

Optionally, the response can be gzipped:

curl http://diy.fm/rest/v1/user/info.xml?id=316&gzip=true
curl http://diy.fm/rest/v1/user/info.json?id=316&gzip=true
curl http://diy.fm/rest/v1/user/info.jsonp?id=316&callback=test&gzip=true

Response

A typical response will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  ...
</response>

Status codes

200 OK  //This response code indicates that the request was successful.
 
201 Created  //This indicates the request was successful and a resource was created. It is used to confirm success of a POST request.
 
400 Bad Request  //The request was malformed. This happens when data is missing, or does not pass validation, or is in the wrong format.
 
401 Unauthorized  //This error indicates that you need to perform authentication before accessing the resource.
 
403 Forbidden  //The HTTP method used is not supported for this resource.
 
404 Not Found  //This response indicates that the required resource could not be found. This is generally returned to all requests which point to a URL with no corresponding resource.
 
422 Validation Error  //This indicates that the posted parameters didn't pass the validation rules.
 
423 User Token Expired  //You must request a new user token.
 
500 Internal Server Error  //A 500 response is used when processing fails due to unanticipated circumstances on the server side, which causes the server to error out.

Validation Error Messages

All POST requests accept the optional parameter lang. Like this, validation error messages will be returned in the requested language.

Example:

curl --header 'X-Api-Key: xxxxxx' --request POST -d "lang=de" https://diy.fm/rest/v1/user.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>422</statusCode>
    <statusMessage>Validation Error</statusMessage>
  </status>
  <created>false</created>
  <errors>
    <name>Gewünschter Benutzername darf nicht leer sein.</name>
    <password>Dein Passwort darf nicht leer sein.</password>
    <email>Deine Email-Adresse darf nicht leer sein.</email>
    <agreeToTerms>Ich akzeptiere die Nutzungsbedingungen darf nicht leer sein.</agreeToTerms>
  </errors>
</response>

Developer Authentication

You must have an API key. If you don't have one yet:

  1. Request a developer API key by email, please let us know your DIY.fm user name.

Don't lose your API key because you'll need to pass this key on every request. You can pass your API key in 2 ways: as a parameter or as a custom HTTP header:

curl 'http://diy.fm/rest/v1/user/info.xml?id=316&apiKey=xxxxxx'
 
- or -
 
curl --header "X-Api-Key:xxxxxx" http://diy.fm/rest/v1/user/info.xml?id=316

User Authentication

Step 1: Verify credentials

Before you can call our API with user credentials, you must first verify that you have the correct user/password. You can use HTTPS/SSL in order to avoid passing user credentials in clear

curl --request POST -d "user=tester&password=password" https://diy.fm/rest/v1/user/token.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <userToken>xxxxxx</userToken>
  <user>
    <id>316</id>
    <name>tester</name>
    <email>tester@url.com</email>
    <active>1</active>
  </user>
</response>

Step 2: Use token for API calls

Once you verified the user credentials, you need to save the “userToken” value passed in the response. You can then use this token as a parameter or as a header to login the user on all subsequent requests:

curl http://diy.fm/rest/v1/user/info.xml?id=316&userToken=xxxxxx
 
- or -
 
curl --header "X-User-Token:xxxxxx" http://diy.fm/rest/v1/user/info.xml?id=316

User tokens expire after 7 days (168 hours). You must request a new token.

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>423</statusCode>
    <statusMessage>User Token Expired</statusMessage>
  </status>
</response>

Alternate 1: Basic Authentication

You can also use Basic Authentication for any call requiring authentication.

curl -u tester:password https://diy.fm/rest/v1/user/info.xml?id=316

Alternate 2: Login Code (for third party applications)

The user can grant access to his account to third party applications through a login code. This is usefull for third party devices that do not have a handy interface for inserting the long login credentials (email and password). The user must activate this feature in his account settings on http://diy.fm. Otherwise, login with a login code won't be possible.

Note: It is recommendet to use HTTPS for all API calls that include the login code in order to keep it secret.

curl -u https://diy.fm/rest/v1/user/info.xml?id=316&loginCode=xxxxxx

- or -
 
curl --header "X-Login-Code:xxxxxx" https://diy.fm/rest/v1/user/info.xml?id=316

Users

Signing up Users

Creating a user account requires these steps:

1. Create user

curl --header 'X-Api-Key: xxxxxx' --request POST -d "user[name]=tester&user[password]=password&user[email]=tester@url.com&user[agreeToTerms]=1" https://diy.fm/rest/v1/user.xml

Status returned can be 201 if successful or 422 is there's a validation error:

Validation Error
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>422</statusCode>
    <statusMessage>Validation Error</statusMessage>
  </status>
  <created>false</created>
  <errors>
    <name>Name "tester" has already been taken.</name>
    <email>Email "tester@url.com" has already been taken.</email>
  </errors>
</response>
Success
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>201</statusCode>
    <statusMessage>Created</statusMessage>
  </status>
  <created>true</created>
  <activationCode>xxxxxx</activationCode>
  <user>
    <id>364</id>
    <name>tester</name>
    <email>tester@url.com</email>
    <active>0</active>
  </user>
</response>

2. Activate user

POST user/activate

Use this to build an email activation process (user must confirm the new account by clicking on a link recieved by email).

curl --header 'X-Api-Key: xxxxxx' --request POST -d "email=tester@url.com&activationCode=xxxxxx" http://diy.fm/rest/v1/user/activate.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>201</statusCode>
    <statusMessage>Created</statusMessage>
  </status>
  <activated>true</activated>
  <user>
    <id>365</id>
    <name>tester</name>
    <email>tester@url.com</email>
    <active>1</active>
  </user>
</response>

POST user/sendActivationEmail

Alternatively, you can let the DIY.fm server send an email with an activation link to the user.

curl --header 'X-Api-Key: xxxxxx' --request POST -d "email=tester@url.com&activationCode=xxxxxx" http://diy.fm/rest/v1/user/sendActivationEmail.xml

Optionally, you can pass a lang parameter to set the email language. Default is en, also available are de, fr, it and rm.

curl --header 'X-Api-Key: xxxxxx' --request POST -d "email=tester@url.com&activationCode=xxxxxx&lang=fr" http://diy.fm/rest/v1/user/sendActivationEmail.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <emailSent>true</emailSent>
</response>

3. Login

4. Create default setting

Without a default setting the player won't work.

See POST setting/default


Reset Password

To reset a user password follow these steps:

1. GET user/passwordResetCode

curl http://diy.fm/rest/v1/user/passwordResetCode.xml?email=tester@url.com
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <resetCode>xxxxxx</resetCode>
</response>

2. POST user/resetPassword

Use the resetCode (see above) to create an email verification process. Like this you can make sure that only the owner of the email address can change the password:

  1. Send the resetCode to the user by email as part of a link: http://yourWebsite.com/resetPassword?resetCode=xxxxxx&email=tester@url.com
  2. The user receives the email and clicks on the on the link.
  3. On your website, the user can choose a new password (it's good practice to let the user input the new password twice, to make sure there are no typing errors).
  4. POST the new password like below to the DIY.fm server. The new password is valid now.
curl --request POST -d "reset[email]=tester@url.com&reset[resetCode]=xxxxxx&reset[newPassword]=myNewPassword" http://diy.fm/rest/v1/user/resetPassword.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>201</statusCode>
    <statusMessage>Created</statusMessage>
  </status>
  <reset>true</reset>
</response>

GET user/info

curl 'http://diy.fm/rest/v1/user/info.xml?id=316'

Alternate 1: with userName as GET parameter:

curl 'http://diy.fm/rest/v1/user/info.xml?userName=tester'

Alternate 2: with loginCode as GET parameter:

curl 'http://diy.fm/rest/v1/user/info.xml?loginCode=xxxxxx'

Note:

  1. If the user isn't logged in to his/her account the email address and the login code info won't be returned in the response (the fields <email></email>, <loginCodeActive></loginCodeActive> and <loginCode></loginCode> will be empty).
  2. loginCode: The user can grant access to his account to third party applications through a login code. The user must activate this feature in his account settings on http://diy.fm. More information: Login Code (for third party applications).
  3. If the user is logged in to his/her account with the loginCode the user's email address won't be returned in the response (the field <email></email> will be empty). This is because of security reasons.
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <user>
    <id>316</id>
    <name>tester</name>
    <email></email>
    <loginCode></loginCode>
    <active>1</active>
  </user>
</response>

Settings

GET setting/overview

User authentication reqired.

Return all program settings of the logged in user ordered by media name:

curl http://diy.fm/rest/v1/setting/overview.xml

Pagination:

curl http://diy.fm/rest/v1/setting/overview.xml?limit=3&page=2

Return only stream settings (= scheduled radio stations):

curl http://diy.fm/rest/v1/setting/overview.xml?type=stream

Return only podcasts:

curl http://diy.fm/rest/v1/setting/overview.xml?type=podcast

Return only personalStreams or personalPodcasts (= not SRG SSR broadcasts, explicitly set by the user):

curl http://diy.fm/rest/v1/setting/overview.xml?type=personalStream

- or -

curl http://diy.fm/rest/v1/setting/overview.xml?type=personalPodcast
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <settings totalResults="4" resultsPerPage="25" currentPage="1">
    <setting>
      <id>1776</id>
      <isDefaultMedia>true</isDefaultMedia>
      <medium>
        <id>5</id>
        <type>stream</type>
        <name>Couleur 3</name>
        <language>fr</language>
        <imgUrl>http://diy.fm/images/media/thumb/5.jpg</imgUrl>
      </medium>
      <hasNewsOnFullHour>true</hasNewsOnFullHour>
      <newsMedium>
        <id>8</id>
        <type>stream</type>
        <name>Radio Svizra Rumantscha</name>
        <language>rm</language>
        <imgUrl>http://diy.fm/images/media/thumb/8.jpg</imgUrl>
      </newsMedium>
      <schedule/>
      <description></description>
    </setting>
    <setting>
      <id>1794</id>
      <isDefaultMedia>false</isDefaultMedia>
      <medium>
        <id>47</id>
        <type>stream</type>
        <name>Radio Swiss Pop</name>
        <language>en</language>
        <imgUrl>http://diy.fm/images/media/thumb/47.jpg</imgUrl>
      </medium>
      <hasNewsOnFullHour>false</hasNewsOnFullHour>
      <newsMedium/>
      <schedule>
        <asap>false</asap>
        <showOnlyAsDirectKey>false</showOnlyAsDirectKey>
        <timing>
          <startTime>16:00:00</startTime>
          <endTime>17:00:00</endTime>
          <days>
            <mon>true</mon>
            <tue>true</tue>
            <wed>true</wed>
            <thu>true</thu>
            <fri>true</fri>
            <sat>true</sat>
            <sun>true</sun>
          </days>
        </timing>
      </schedule>
      <description>Test</description>
    </setting>
    ...
  </settings>
</response>

GET setting/default

User authentication reqired.

curl http://diy.fm/rest/v1/setting/default.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <setting>
    <id>1635</id>
    <isDefaultMedia>true</isDefaultMedia>
    <medium>
      <id>7</id>
      <type>stream</type>
      <name>Radio SRF 3</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/7.jpg</imgUrl>
    </medium>
    <hasNewsOnFullHour>false</hasNewsOnFullHour>
    <newsMedium/>
    <schedule/>
    <description></description>
  </setting>
</response>

GET setting/info

User authentication reqired.

http://diy.fm/rest/v1/setting/info.xml?id=1802
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <setting>
    <id>1802</id>
    <isDefaultMedia>false</isDefaultMedia>
    <medium>
      <id>68</id>
      <type>podcast</type>
      <name>BuchZeichen</name>
      <language>de</language>
      <imgUrl>http://www.srfcdn.ch/asset/image/audio/a98212c1-92f9-4989-9745-5d0c77d14037/PODCAST</imgUrl>
    </medium>
    <hasNewsOnFullHour>false</hasNewsOnFullHour>
    <newsMedium/>
    <schedule>
      <asap>true</asap>
      <showOnlyAsDirectKey>false</showOnlyAsDirectKey>
      <timing/>
    </schedule>
    <description></description>
  </setting>
</response>

POST setting/default

User authentication reqired.

Use this to create or update the default setting. Update will overwrite the existing default setting.

Default stream without news media:

curl --request POST -d "setting[mediaId]=34" http://diy.fm/rest/v1/setting/default.xml

Default stream with news media:

curl --request POST -d "setting[mediaId]=34&setting[newsMediaId]=8" http://diy.fm/rest/v1/setting/default.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>201</statusCode>
    <statusMessage>Created</statusMessage>
  </status>
  <created>true</created>
  <setting>
    <id>2005</id>
    <isDefaultMedia>true</isDefaultMedia>
    <medium>
      <id>35</id>
      <type>stream</type>
      <name>Radio SRF 2 Kultur</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/35.jpg</imgUrl>
    </medium>
    <hasNewsOnFullHour>true</hasNewsOnFullHour>
    <newsMedium>
      <id>8</id>
      <type>stream</type>
      <name>Radio Svizra Rumantscha</name>
      <language>rm</language>
      <imgUrl>http://diy.fm/images/media/thumb/8.jpg</imgUrl>
    </newsMedium>
    <schedule/>
    <description></description>
  </setting>
</response>

POST setting/personalDefault

User authentication reqired.

Use this to create or update the default setting with a personal stream (not SRG SSR media). Update will overwrite the existing default setting.

Default personal stream without news media:

curl --request POST -d "setting[streamUrl]=http://stream.com" http://diy.fm/rest/v1/setting/personalDefault.xml

Default personal stream with news media:

curl --request POST -d "setting[streamUrl]=http://stream.com&setting[newsMediaId]=7" http://diy.fm/rest/v1/setting/personalDefault.xml

POST setting/stream

User authentication reqired.

Use this to create or update a stream setting. An update will overwrite the existing setting.

Create stream setting:

curl --request POST -d "setting[mediaId]=34&setting[startTime]=22:00:00&setting[endTime]=23:00:00&setting[mon]=1&setting[tue]=1&setting[wed]=0&setting[thu]=0&setting[fri]=0&setting[sat]=0&setting[sun]=1" http://diy.fm/rest/v1/setting/stream.xml

Create stream setting with optional parameters:

curl --request POST -d "setting[mediaId]=34&setting[startTime]=22:00:00&setting[endTime]=23:00:00&setting[mon]=1&setting[tue]=1&setting[wed]=0&setting[thu]=0&setting[fri]=0&setting[sat]=0&setting[sun]=1&setting[description]=test&setting[showOnlyAsDirectKey]=0&setting[newsMediaId]=7" http://diy.fm/rest/v1/setting/stream.xml

Update stream setting:

To update/overwrite an existing stream setting, pass the ID of the existing setting in the POST request like this: setting[id]=2015

curl --request POST -d "setting[id]=2015&setting[mediaId]=34&setting[startTime]=22:00:00&setting[endTime]=23:00:00&setting[mon]=0&setting[tue]=1&setting[wed]=0&setting[thu]=0&setting[fri]=0&setting[sat]=0&setting[sun]=1" http://diy.fm/rest/v1/setting/stream.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>201</statusCode>
    <statusMessage>Created</statusMessage>
  </status>
  <created>true</created>
  <setting>
    <id>2019</id>
    <isDefaultMedia>false</isDefaultMedia>
    <medium>
      <id>34</id>
      <type>stream</type>
      <name>Radio SRF 1</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/34.jpg</imgUrl>
    </medium>
    <hasNewsOnFullHour>true</hasNewsOnFullHour>
    <newsMedium>
      <id>7</id>
      <type>stream</type>
      <name>Radio SRF 3</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/7.jpg</imgUrl>
    </newsMedium>
    <schedule>
      <asap>false</asap>
      <showOnlyAsDirectKey>false</showOnlyAsDirectKey>
      <timing>
        <startTime>22:00:00</startTime>
        <endTime>23:00:00</endTime>
        <days>
          <mon>true</mon>
          <tue>true</tue>
          <wed>false</wed>
          <thu>false</thu>
          <fri>false</fri>
          <sat>false</sat>
          <sun>true</sun>
        </days>
      </timing>
    </schedule>
    <description>test</description>
  </setting>
</response>

POST setting/personalStream

User authentication reqired.

Use this to create or update a setting with a personal stream (not SRG SSR media). Update will overwrite the existing default setting.

Create a personal stream setting:

curl --request POST -d "setting[streamUrl]=http://stream.com&setting[startTime]=22:00:00&setting[endTime]=23:00:00&setting[mon]=1&setting[tue]=1&setting[wed]=0&setting[thu]=0&setting[fri]=0&setting[sat]=0&setting[sun]=1" http://diy.fm/rest/v1/setting/personalStream.xml

Update personal stream setting:

To update/overwrite an existing personal stream setting, pass the ID of the existing setting in the POST request like this: setting[id]=2018

curl --request POST -d "setting[id]=2018&setting[streamUrl]=http://stream1.com&setting[startTime]=20:00:00&setting[endTime]=23:00:00&setting[mon]=1&setting[tue]=1&setting[wed]=0&setting[thu]=0&setting[fri]=0&setting[sat]=0&setting[sun]=1" http://diy.fm/rest/v1/setting/personalStream.xml

POST setting/podcast

User authentication reqired.

Use this to create or update a podcast setting. An update will overwrite the existing setting.

Create podcast asap setting (= play podcast always as soon as a new episode becomes available):

curl --request POST -d "setting[mediaId]=75&setting[asap]=1" http://diy.fm/rest/v1/setting/podcast.xml

Mark podcast with alreadyListened=1

Use this in the player, when the user listens to a podcast and adds it to his settings. Like this the current episode - that she/he's already listened - won't be played again.

curl --request POST -d "setting[mediaId]=75&setting[asap]=1&setting[alreadyListened]=1" http://diy.fm/rest/v1/setting/podcast.xml

Create a timed podcast setting (= play podcast at a specific time):

curl --request POST -d "setting[mediaId]=75&setting[mon]=1&setting[tue]=1&setting[wed]=0&setting[thu]=0&setting[fri]=0&setting[sat]=0&setting[sun]=1&setting[startTime]=08:00:00" http://diy.fm/rest/v1/setting/podcast.xml

Update podcast setting:

To update/overwrite an existing podcast setting, pass the ID of the existing setting in the POST request like this: setting[id]=2023

curl --request POST -d "setting[id]=2023&setting[mediaId]=76&setting[asap]=1" http://diy.fm/rest/v1/setting/podcast.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>201</statusCode>
    <statusMessage>Created</statusMessage>
  </status>
  <created>true</created>
  <setting>
    <id>2034</id>
    <isDefaultMedia>false</isDefaultMedia>
    <medium>
      <id>75</id>
      <type>podcast</type>
      <name>Diskothek</name>
      <language>de</language>
      <imgUrl>http://www.srfcdn.ch/asset/image/audio/750f25fc-6df1-4b31-bb10-abd6ad4def6f/PODCAST</imgUrl>
    </medium>
    <hasNewsOnFullHour>false</hasNewsOnFullHour>
    <newsMedium/>
    <schedule>
      <asap>true</asap>
      <showOnlyAsDirectKey>false</showOnlyAsDirectKey>
      <timing/>
    </schedule>
    <description></description>
  </setting>
</response>

POST setting/personalPodcast

User authentication reqired.

Use this to create or update a setting with a personal podcast (not SRG SSR media). An update will overwrite the existing default setting.

Create a personal podcast setting:

curl --request POST -d "setting[feedUrl]=http://www.sciencemag.org/rss/podcast.xml&setting[asap]=1" http://diy.fm/rest/v1/setting/personalPodcast.xml

Update personal podcast setting:

To update/overwrite an existing personal podcast setting, pass the ID of the existing setting in the POST request like this: setting[id]=2024

curl --request POST -d "setting[id]=2024&setting[feedUrl]=http://www.sciencemag.org/rss/podcast1.xml&setting[asap]=1" http://diy.fm/rest/v1/setting/personalPodcast.xml

POST setting/allPodcastsByGenre

User authentication reqired.

Adds all podcasts of a given genre and language to the user's settings (as asap media).

Available languages for podcast[lang] parameter: de, fr, it, rm or others

curl --request POST -d "podcast[genreId]=1&podcast[lang]=it" http://diy.fm/rest/v1/setting/allPodcastsByGenre.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>201</statusCode>
    <statusMessage>Created</statusMessage>
  </status>
  <created>true</created>
  <totalCreated>22</totalCreated>
</response>

POST setting/removeAllPodcastsByGenre

User authentication reqired.

Removes all podcasts of a given genre and language from the user's settings.

Available languages for podcast[lang] parameter: de, fr, it, rm or others

curl --request POST -d "podcast[genreId]=1&podcast[lang]=it" http://diy.fm/rest/v1/setting/removeAllPodcastsByGenre.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <deleted>true</deleted>
  <totalDeleted>22</totalDeleted>
</response>

POST setting/delete

User authentication reqired.

Use this to delete a setting permanently (no recovery possible).

curl --request POST -d "setting[id]=2024" http://diy.fm/rest/v1/setting/delete.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <deleted>true</deleted>
</response>

Media

GET media/radioStations

Default: all radio stations will be returned:

curl 'http://diy.fm/rest/v1/media/radioStations.xml'

Optionally, the parameter lang can be set:

curl 'http://diy.fm/rest/v1/media/radioStations.xml?lang=de'

Optionally, the parameter id can be set to get a specific radio station:

curl 'http://diy.fm/rest/v1/media/radioStations.xml?id=5'

Optionally, the parameter q can be set to search for a specific radio station:

curl 'http://diy.fm/rest/v1/media/radioStations.xml?q=musi'

Pagination:

curl 'http://diy.fm/rest/v1/media/radioStations.xml?limit=2&page=3'
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <radioStations language="all" totalResults="19" resultsPerPage="2" currentPage="3">
    <station>
      <id>34</id>
      <name>Radio SRF 1</name>
      <language>de</language>
      <streamUrl>http://stream.srg-ssr.ch/m/drs1/mp3_128</streamUrl>
      <streamAacUrl>http://stream.srg-ssr.ch/m/drs1/aacp_96</streamAacUrl>
      <website>http://www.drs1.ch/</website>
      <imgUrl>http://diy.fm/images/media/thumb/34.jpg</imgUrl>
      <isNewsMedia>1</isNewsMedia>
    </station>
    <station>
      <id>35</id>
      <name>Radio SRF 2 Kultur</name>
      <language>de</language>
      <streamUrl>http://stream.srg-ssr.ch/m/drs2/mp3_128</streamUrl>
      <streamAacUrl>http://stream.srg-ssr.ch/m/drs2/aacp_96</streamAacUrl>
      <website>http://www.drs2.ch/</website>
      <imgUrl>http://diy.fm/images/media/thumb/35.jpg</imgUrl>
      <isNewsMedia>0</isNewsMedia>
    </station>
  </radioStations>
</response>

GET media/genres

Default: all genres will be returned:

curl 'http://diy.fm/rest/v1/media/genres.xml'

Optionally, the parameter id can be set to get a specific genre:

curl 'http://diy.fm/rest/v1/media/genres.xml?id=17'

Optionally, the parameter lang can be set:

curl 'http://diy.fm/rest/v1/media/genres.xml?lang=de'

Note: The lang parameter will affect the response in two ways:

  1. Only the genre name of the requested language will be returned.
  2. mediaCount = how many media (podcasts) have been found for the requested language.
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <genres language="de" totalResults="17">
    <genre>
      <id>17</id>
      <mediaCount>1</mediaCount>
      <nameDe>Bildung</nameDe>
    </genre>
    <genre>
      <id>14</id>
      <mediaCount>5</mediaCount>
      <nameDe>Comedy</nameDe>
    </genre>
    <genre>
      <id>19</id>
      <mediaCount>1</mediaCount>
      <nameDe>Familie und Kinder</nameDe>
    </genre>
    <genre>
      <id>9</id>
      <mediaCount>18</mediaCount>
      <nameDe>Gesellschaft und Kultur</nameDe>
    </genre>
    <genre>
      <id>22</id>
      <mediaCount>1</mediaCount>
      <nameDe>Gesundheit</nameDe>
    </genre>
    <genre>
      <id>15</id>
      <mediaCount>1</mediaCount>
      <nameDe>Kein Genre</nameDe>
    </genre>
    <genre>
      <id>10</id>
      <mediaCount>6</mediaCount>
      <nameDe>Kunst</nameDe>
    </genre>
    <genre>
      <id>7</id>
      <mediaCount>31</mediaCount>
      <nameDe>Musik</nameDe>
    </genre>
    <genre>
      <id>1</id>
      <mediaCount>23</mediaCount>
      <nameDe>Nachrichten und Politik</nameDe>
    </genre>
    <genre>
      <id>16</id>
      <mediaCount>1</mediaCount>
      <nameDe>Naturwissenschaften</nameDe>
    </genre>
    <genre>
      <id>11</id>
      <mediaCount>3</mediaCount>
      <nameDe>Religion und Spiritualität</nameDe>
    </genre>
    <genre>
      <id>21</id>
      <mediaCount>1</mediaCount>
      <nameDe>Spiele und Hobbys</nameDe>
    </genre>
    <genre>
      <id>23</id>
      <mediaCount>0</mediaCount>
      <nameDe>Sport und Freizeit</nameDe>
    </genre>
    <genre>
      <id>8</id>
      <mediaCount>1</mediaCount>
      <nameDe>Technologie</nameDe>
    </genre>
    <genre>
      <id>13</id>
      <mediaCount>1</mediaCount>
      <nameDe>TV und Film</nameDe>
    </genre>
    <genre>
      <id>12</id>
      <mediaCount>1</mediaCount>
      <nameDe>Wirtschaft</nameDe>
    </genre>
    <genre>
      <id>18</id>
      <mediaCount>2</mediaCount>
      <nameDe>Wissenschaft und Medizin</nameDe>
    </genre>
  </genres>
</response>

GET media/podcasts

Default: all podcasts will be returned:

curl 'http://diy.fm/rest/v1/media/podcasts.xml'

Optionally, the parameter lang can be set:

curl 'http://diy.fm/rest/v1/media/podcasts.xml?lang=rm'

Optionally, the parameter genreId can be set:

curl 'http://diy.fm/rest/v1/media/podcasts.xml?genreId=8'

Optionally, the parameter id can be set to get a specific podcast:

curl 'http://diy.fm/rest/v1/media/podcasts.xml?id=3'

Optionally, the parameter q can be set to search for a specific podcast:

curl 'http://diy.fm/rest/v1/media/podcasts.xml?q=echo'

Optionally, the parameter userId can be set to find out if a podcast is already in the user's program settings (<alreadyInSettings>true</alreadyInSettings>)

curl 'http://diy.fm/rest/v1/media/podcasts.xml?userId=368'

Pagination:

curl 'http://diy.fm/rest/v1/media/podcasts.xml?limit=2&page=11'
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <podcasts language="all" totalResults="239" resultsPerPage="2" currentPage="11">
    <podcast>
      <id>67</id>
      <name>Blues Special</name>
      <description>Der SRF 3 Blues Special hat sich voll und ganz dem Blues verschrieben. Im Mittelpunkt steht der Blues in all seinen Schattierungen, von modern über traditionell bis avangardistisch.
 
Der SRF 3 Blues Special fischt in den unendlichen Weiten des Blues und bringt neue Perlen ans Tageslicht. Der Blues Special entdeckt Blues Klassiker wieder und interviewt aufstrebende und altbekannte Heldinnen und Helden aus der Welt des Blues. Wem der Blues eine Herzens-Angelegenheit ist, für den ist der SRF 3 Blues Special respektive der Podcast der Sendung ein Pflichttermin. Jeden Montag von 21-22 Uhr. Auf SRF 3.
 </description>
      <language>de</language>
      <feedUrl>http://pod.drs.ch/blues_special_mpx.xml</feedUrl>
      <imgUrl>http://a2.mzstatic.com/us/r30/Podcasts/v4/89/f3/b8/89f3b8cf-ccf1-ef70-3017-070ba9b9052a/mza_7161183077779173021.100x100-75.jpg</imgUrl>
      <mediaFileType>mp3</mediaFileType>
      <alreadyInSettings>true</alreadyInSettings>
      <genre>
        <id>7</id>
        <nameEn>Music</nameEn>
        <nameDe>Musik</nameDe>
        <nameFr>Musique</nameFr>
        <nameIt>Musica</nameIt>
        <nameRm>Musica</nameRm>
      </genre>
    </podcast>
    <podcast>
      <id>482</id>
      <name>Bounce Hip Hop</name>
      <description>Die legendärste Radio-Rap-Show der Schweiz mit Mauro, Pablo und DJ Cutzilla.</description>
      <language>de</language>
      <feedUrl>http://pod.drs.ch/bounce_hip_hop_mpx.xml</feedUrl>
      <imgUrl>http://a2.mzstatic.com/us/r30/Podcasts4/v4/3e/77/c6/3e77c613-c00f-00fb-7d29-67b621cdca07/mza_1250739742124587813.100x100-75.jpg</imgUrl>
      <mediaFileType>mp3</mediaFileType>
      <alreadyInSettings>false</alreadyInSettings>
      <genre>
        <id>7</id>
        <nameEn>Music</nameEn>
        <nameDe>Musik</nameDe>
        <nameFr>Musique</nameFr>
        <nameIt>Musica</nameIt>
        <nameRm>Musica</nameRm>
      </genre>
    </podcast>
  </podcasts>
</response>

curl http://diy.fm/rest/v1/media/search.xml?q=sr
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <media language="all" totalResults="8" resultsPerPage="25" currentPage="1">
    <medium>
      <id>34</id>
      <type>stream</type>
      <name>Radio SRF 1</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/34.jpg</imgUrl>
    </medium>
    <medium>
      <id>35</id>
      <type>stream</type>
      <name>Radio SRF 2 Kultur</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/35.jpg</imgUrl>
    </medium>
    <medium>
      <id>7</id>
      <type>stream</type>
      <name>Radio SRF 3</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/7.jpg</imgUrl>
    </medium>
    <medium>
      <id>36</id>
      <type>stream</type>
      <name>Radio SRF 4 News</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/36.jpg</imgUrl>
    </medium>
    <medium>
      <id>37</id>
      <type>stream</type>
      <name>Radio SRF Musikwelle</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/37.jpg</imgUrl>
    </medium>
    <medium>
      <id>2</id>
      <type>stream</type>
      <name>Radio SRF Virus</name>
      <language>de</language>
      <imgUrl>http://diy.fm/images/media/thumb/2.jpg</imgUrl>
    </medium>
    <medium>
      <id>124</id>
      <type>podcast</type>
      <name>Samstagsrundschau</name>
      <language>de</language>
      <imgUrl>http://www.srfcdn.ch/asset/image/audio/60c69680-d340-4a80-9c47-34211ccaa3a4/PODCAST</imgUrl>
    </medium>
    <medium>
      <id>79</id>
      <type>podcast</type>
      <name>SRF 4 News Zeitblende</name>
      <language>de</language>
      <imgUrl>http://www.srfcdn.ch/asset/image/audio/b3ec0559-816c-4d01-bfc7-423e28b63e1c/PODCAST</imgUrl>
    </medium>
  </media>
</response>

Player

This part of the API will replace the existing player API (for example: http://diy.fm/api/getUserProgram?userId=1). If you are building a new DIY.fm player (e.g. web-based, iOS, Android etc.), please use this API.

Note: Maybe you won't need to build a new player yourself: Check out the JavaScript Player API.

GET player/random

Returns a random radio station. Use this to build a random radio player as on the DIY.fm homepage: http://diy.fm

curl http://diy.fm/rest/v1/player/random.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <mediaId>6</mediaId>
  <type>stream</type>
  <url>http://stream.srg-ssr.ch/m/retetre/mp3_128</url>
  <aacUrl>http://stream.srg-ssr.ch/m/retetre/aacp_96</aacUrl>
  <info>Rete Tre</info>
  <img>http://diy.fm/images/media/thumb/6.jpg</img>
  <infolink>http://retetre.rtsi.ch/</infolink>
</response>

GET player/newsOn

Will replace http://diy.fm/api/newsOff.

Returns whether “news” are currently on or off for SRF 1, SRF 3, La Première, Rete Uno and Radio Svizra Rumantscha.

Important: Please use this service only for an inital check if the news are on or off when the player begins to play. Once the news are on, please use the Push API to receive the news off signal.

curl http://diy.fm/rest/v1/player/newsOn.xml?mediaId=7
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <newsOn>false</newsOn>
</response>

GET player/dlsMessage

Returns the current DLS message of a radio station.

Important: Please use this service only for an inital pull. Once the station is playing, please use the Push API to receive DLS messages.

curl http://diy.fm/rest/v1/player/dlsMessage.xml?mediaId=7
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <dlsMessage>CHRIS MALINCHAK - SO GOOD TO ME</dlsMessage>
</response>

GET player/schedule

Will replace http://diy.fm/api/getUserProgram.

curl http://diy.fm/rest/v1/player/schedule.xml?userName=tester
curl http://diy.fm/rest/v1/player/schedule.xml?userId=368
curl http://diy.fm/rest/v1/player/schedule.xml?loginCode=xxxxxx
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <userId>368</userId>
  <utcReference>1384418215</utcReference>
  <cookieTracking>0</cookieTracking>
  <defaultMedia>
    <settingId>1776</settingId>
    <mediaId>5</mediaId>
    <type>stream</type>
    <url>http://stream.srg-ssr.ch/m/couleur3/mp3_128</url>
    <aacUrl>http://stream.srg-ssr.ch/m/couleur3/aacp_96</aacUrl>
    <skippedSettingCount>0</skippedSettingCount>
    <info1>Couleur 3 - Live</info1>
    <info2>My Favorite Radio Station</info2>
    <description></description>
    <img>http://diy.fm.diyfm-stage.nine.ch/images/media/thumb/5.jpg</img>
    <infolink>http://www.rsr.ch/#/couleur3/</infolink>
    <news/>
  </defaultMedia>
  <schedule>
    <utcStart>1384418215</utcStart>
    <utcEnd>1384419415</utcEnd>
    <settingId>2247</settingId>
    <mediaId>3</mediaId>
    <type>podcast</type>
    <url>http://pod.drs.ch/echo_der_zeit_mpx.xml</url>
    <skippedSettingCount>3</skippedSettingCount>
    <info1>Echo der Zeit</info1>
    <info2>Podcast</info2>
    <img>http://a4.mzstatic.com/us/r30/Podcasts4/v4/b2/08/fd/b208fd73-9e6c-58c7-400e-0506948b26e5/mza_3899807402488040020.100x100-75.jpg</img>
    <infolink>http://www.srf.ch/sendungen/echo-der-zeit</infolink>
    <mediaFileType>mp3</mediaFileType>
    <latestFile>http://podcasts.srf.ch/world/audio/Echo-der-Zeit_13-11-2013-1800.22.mp3</latestFile>
    <playbackPosition>0</playbackPosition>
    <news/>
  </schedule>
</response>

GET player/recommendations

Will replace http://diy.fm/api/getRecommendations.

curl http://diy.fm/rest/v1/player/recommendations.xml?userName=tester
curl http://diy.fm/rest/v1/player/recommendations.xml?userId=368
curl http://diy.fm/rest/v1/player/recommendations.xml?loginCode=xxxxxx
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <user>368</user>
  <recommended>
    <settingId>2247</settingId>
    <mediaId>3</mediaId>
    <alreadyInSettings>true</alreadyInSettings>
    <type>podcast</type>
    <skippedSettingCount>3</skippedSettingCount>
    <url>http://pod.drs.ch/echo_der_zeit_mpx.xml</url>
    <info1>Echo der Zeit</info1>
    <info2>Podcast</info2>
    <description>«Echo der Zeit» ist die älteste politische Hintergrundsendung von Radio SRF: Seit 1945 vermittelt die Sendung täglich die wichtigsten Nachrichten, Berichte, Reportagen, Interviews und Analysen über das aktuelle Zeitgeschehen.
 </description>
    <img>http://a4.mzstatic.com/us/r30/Podcasts4/v4/b2/08/fd/b208fd73-9e6c-58c7-400e-0506948b26e5/mza_3899807402488040020.100x100-75.jpg</img>
    <infolink>http://pod.drs.ch/echo_der_zeit_mpx.xml</infolink>
    <mediaFileType>mp3</mediaFileType>
    <latestFile>http://podcasts.srf.ch/world/audio/Echo-der-Zeit_13-11-2013-1800.22.mp3</latestFile>
    <playbackPosition>0</playbackPosition>
    <news/>
  </recommended>
  <recommended>
    <alreadyInSettings>true</alreadyInSettings>
    <settingId>1776</settingId>
    <mediaId>5</mediaId>
    <type>stream</type>
    <url>http://stream.srg-ssr.ch/m/couleur3/mp3_128</url>
    <aacUrl>http://stream.srg-ssr.ch/m/couleur3/aacp_96</aacUrl>
    <skippedSettingCount>1</skippedSettingCount>
    <info1>Couleur 3 - Live</info1>
    <info2></info2>
    <description></description>
    <img>http://diy.fm.diyfm-stage.nine.ch/images/media/thumb/5.jpg</img>
    <infolink>http://www.rsr.ch/#/couleur3/</infolink>
    <news/>
  </recommended>
  ...
</response>

GET player/publicRecommendations

curl http://diy.fm/rest/v1/player/publicRecommendations.xml
curl http://diy.fm/rest/v1/player/publicRecommendations.xml?lang=de
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <recommended>
    <settingId></settingId>
    <mediaId>3</mediaId>
    <alreadyInSettings>false</alreadyInSettings>
    <type>podcast</type>
    <url>http://pod.drs.ch/echo_der_zeit_mpx.xml</url>
    <info1>Echo der Zeit</info1>
    <info2>Podcast</info2>
    <description>«Echo der Zeit» ist die älteste politische Hintergrundsendung von Radio SRF: Seit 1945 vermittelt die Sendung täglich die wichtigsten Nachrichten, Berichte, Reportagen, Interviews und Analysen über das aktuelle Zeitgeschehen.
 </description>
    <img>http://a4.mzstatic.com/us/r30/Podcasts4/v4/b2/08/fd/b208fd73-9e6c-58c7-400e-0506948b26e5/mza_3899807402488040020.100x100-75.jpg</img>
    <infolink>http://pod.drs.ch/echo_der_zeit_mpx.xml</infolink>
    <mediaFileType>mp3</mediaFileType>
    <latestFile>http://podcasts.srf.ch/world/audio/Echo-der-Zeit_13-11-2013-1800.22.mp3</latestFile>
    <playbackPosition>0</playbackPosition>
    <news/>
  </recommended>
  ...
</response>

GET player/playbackPosition

Use this service to get the current playback position of a podcast. For example, if the podcast has been loaded/buffered previously but starts playing now/later (the user might have listened to this podcast on the DIY.fm web platform in the meantime, therefore you cannot start at playbackPosition 0).

curl http://diy.fm/rest/v1/player/playbackPosition.xml?settingId=2357
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <playbackPosition>187</playbackPosition>
  <mediaFileType>mp3</mediaFileType>
  <latestFile>http://podcasts.srf.ch/world/audio/Zambo_18-03-2014-1903.mp3</latestFile>
</response>

POST player/skipNews

User authentication reqired.

curl --request POST -d "settingId=1776" http://diy.fm/rest/v1/player/skipNews.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <skipped>true</skipped>
</response>

POST player/skipSetting

User authentication reqired.

Important for podcasts: Please call POST player/lastListened first, otherwise the podcast episode cannot be marked as “skipped” and cannot be removed from the schedule. Best practice: Call POST player/lastListened immediately after the playback of the podcast has begun.

curl --request POST -d "settingId=1776" http://diy.fm/rest/v1/player/skipSetting.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <skipped>true</skipped>
</response>

POST player/hearLater

User authentication reqired.

Important for podcasts: Please call POST player/lastListened first, otherwise the podcast episode cannot be marked as “hearLater” and cannot be removed from the schedule. Best practice: Call POST player/lastListened immediately after the playback of the podcast has begun.

curl --request POST -d "settingId=1776" http://diy.fm/rest/v1/player/hearLater.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <hearLater>true</hearLater>
</response>

POST player/lastListened

User authentication reqired.

Report back to the server which setting has been listened/played.

curl --request POST -d "settingId=1776" http://diy.fm/rest/v1/player/lastListened.xml

Important for podcasts: Pass the optional POST parameter file, otherwise the podcast episode cannot be marked as “already listened” and cannot be removed from the schedule. The parameter file is expected to be the file URL of the listened podcast audio file.

curl --request POST -d "settingId=1776&file=http://podcast.rsi.ch/rtr/profil-20130629.mp3" http://diy.fm/rest/v1/player/lastListened.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <lastListened>true</lastListened>
</response>

POST player/playbackPosition

User authentication reqired.

Important for podcasts:

  • If a podcast is playing, report the playback position back to the server in a 20 seconds interval. Also report it back if the user changes the playback position manually.
  • Please call POST player/lastListened first, otherwise the playback position cannot be set correctly. Best practice: Call POST player/lastListened immediately after the playback of the podcast has begun.
curl --request POST -d "settingId=1776&seconds=120" http://diy.fm/rest/v1/player/playbackPosition.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <playbackPosition>120</playbackPosition>
</response>

POST player/playbackComplete

User authentication reqired.

Important for podcasts:

  • If a podcast has ended report it back to the server. Like this it will be removed from the schedule.
  • Please call POST player/lastListened first, otherwise the podcast episode cannot be marked as “completed” and cannot be removed from the schedule. Best practice: Call POST player/lastListened immediately after the playback of the podcast has begun.
curl --request POST -d "settingId=1776" http://diy.fm/rest/v1/player/playbackComplete.xml
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <statusCode>200</statusCode>
    <statusMessage>OK</statusMessage>
  </status>
  <playbackComplete>1</playbackComplete>
</response>
rest_api.txt · Last modified: 2017/02/24 16:11 (external edit)