DrivecastAPI 2.0 PHP Library

From DriveCast Wiki

Contents 1 DrivecastAPI 2.0 PHP Library 1.1 Overview 1.2 How it works 1.2.1 Make a request 1.3 Fetch the results and the request status 1.4 The result object 1.5 A practical example 1.6 Feed 1.6.1 Read the feed 1.7 Playlist 1.7.1 Get the list of playlists 1.7.2 Get a playlist 1.7.3 Create an empty playlist 1.7.4 Delete a playlist 1.8 Device 1.9 Get the Device list 1.10 How to know if a device exists 1.11 Create a new device 1.12 Delete a device 1.13 Library 1.13.1 Get the list of library elements 1.13.2 Get a particular library element 1.13.3 Delete a library element 1.13.4 Modify the metadata associated to a library element 1.14 Radio 1.14.1 Get the list of the available radios 1.15 Recording 1.15.1 Get the list of recordings 1.15.2 Get a recording 1.15.3 Create a new recording 1.15.4 Update a recording 1.15.5 Delete a recording 1.16 Podcast 1.16.1 Get the list of podcasts 1.16.2 Get a podcast 1.16.3 Delete a podcast 1.16.4 Insert a podcast 1.16.5 Update a podcast 1.17 DCST 1.17.1 Get the DCST link 1.18 Thumbnail 1.18.1 Get a Thumbnail 1.18.2 How to write a Thumbnail to a file in PHP

DrivecastAPI 2.0 PHP Library

Overview

This is the implementation of a library, using the programming language PHP, that allows to fetch data from the Drivecast API 2.0.

Here you can find the actual implementation of the DrivecastAPI 2.0 PHP Class.

How it works

The PHP implementation consists of an object called DrivecastAPI, which provides one user method: handleRequest.

The code to create a DrivecastAPI object reference is:

include("DrivecastAPI_2.0.php");
$api = new DrivecastAPI("username","password");
$api->setAPIkey("your APIkey");

You can get your personal APIkey under the Software menu, Developer Tools submenu section of your Drivecast account.

Make a request

To make a request call the method handleRequest

$api->handleRequest("resource","action");

The function handleRequest returns true or false, according to the request result.

Fetch the results and the request status

The instance of the DivecastAPI Object, contains three attributes.

$api->statuscode
// contains the HTTP Response code (200, 400 etc)

$api->statusdesc
// contains the reason phrase of the response (like OK, Unhautorized)

See the Drivecast API 2.0 reference, for the complete list of these codes.

$api->result
// if there are attachment data, it is the standard Class Object containing all the responses in a key/value array, otherwise it is empty

Here is a simple way to print the results of the request.

if($api->handleRequest('feed','read')){
  print_r($api->statuscode);
  echo "<br>";
  print_r($api->statusdesc);
  echo "<br>";
  print_r($api->result);
}
else{
 # something goes wrong, let us see which is the error
 print_r($api->statuscode);
 echo "<br>";
 print_r($api->statusdesc);
}

The result object

To understand which key/value pairs are available when you perform a request, you need to consult the Drivecast API 2.0 documentation.

A practical example

Feed

Read the feed

Request the feeds of your Drivecast user

$api->handleRequest('feed','read');

If you need to get a device feed, specifying a serial (not so usual, you must add to Drivecast two Devices with the same name to obtain a serial associated to the Device)

$api->handleRequest('feed/deviceName/serial');

Otherwise:

$api->handleRequest('feed/deviceName');

To catch the results for a Feed request:

$api->result->feedURL
$api->result->opmlURL
$api->result->recsURL

Playlist

Get the list of playlists

$api->handleRequest('playlist','read');

In order to get the elements attributes, you need to make a for cycle:

for($i=0; $i < sizeof($api->result->elements); $i++){
  print_r($api->result->elements[$i]->name);
}

For a complete list of playlist item attributes, see the API 2.0 playlist reference.

Get a playlist

$api->handleRequest('playlist/elementID','read');

To get the attributes of the returned item:

if($api->handleRequest('playlist/elementID','read')){
  print_r($api->result->elements[0]->name);
}

For a complete list of playlist item attributes, see the API 2.0 playlist reference.

Create an empty playlist

$api->handleRequest('playlist/MyPlaylist','create');

Delete a playlist

$api->handleRequest('playlist/MyPlaylist','delete');

Device

Get the Device list

$api->handleRequest('device','read');

How to know if a device exists

if($api->handleRequest('device/deviceName','read')){
 # the device exists...
}
else{
 # the device does not exist...
}

Create a new device

$api->handleRequest('device/deviceName','create');

Delete a device

$api->handleRequest('device/deviceName','delete');

Library

Get the list of library elements

$api->handleRequest('library','read');

In order to get the attributes of each element, you need to perform a for cycle, as the following one:

for($i=0; $i < sizeof($api->result->elements); $i++){
  print_r($api->result->elements[$i]->uid);
  print_r($api->result->elements[$i]->author);
  print_r($api->result->elements[$i]->title);
  print_r($api->result->elements[$i]->description);
}

For a complete list of library item attributes, see the API 2.0 library reference.

Get a particular library element

$api->handleRequest('library/elementID','read');

In order to get the attributes of the returned item:

if($api->handleRequest('library/elementID','read')){
  print_r($api->result->elements[0]->title);
}

For a complete list of library item attributes, see the API 2.0 library reference.

Delete a library element

$api->handleRequest('library/elementID','delete');

Modify the metadata associated to a library element

$obj = new LibraryItem("Modified Author","Modified Title","Modified Description");
$api->handleRequest('library/elementID','modify',$obj);

The LibraryItem object structure is:

LibraryItem("author","title","description")

You can also set the attributes after the instance of the object

$obj = new LibraryItem();
$obj->author = "author";
$obj->title = "title";
$obj->description = "description";

Radio

Get the list of the available radios

$api->handleRequest('radio','read');

In order to get the attributes of each element, you need to perform a for cycle, as the following one:

for($i=0; $i < sizeof($api->result->elements); $i++){
  print_r($api->result->elements[$i]->uid);
  print_r($api->result->elements[$i]->radio_name);
}

For a complete list of radio item attributes, see the API 2.0 radio reference.

Recording

Get the list of recordings

$api->handleRequest('recording','read');

In order to get the attributes of each element, you need to perform a for cycle, as the following one:

for($i=0; $i < sizeof($api->result->elements); $i++){
  print_r($api->result->elements[$i]->uid);
  print_r($api->result->elements[$i]->title);
  print_r($api->result->elements[$i]->radio_name);
}

For a complete list of recording item attributes, see the API 2.0 recording reference.

Get a recording

$api->handleRequest('recording/elementID','read');

In order to get the attributes of the returned item:

if($api->handleRequest('recording/elementID','read')){
  print_r($api->result->elements[0]->title);
}

For a complete list of recording item attributes, see the API 2.0 recording reference.

Create a new recording

$obj = new Recording("VirginRadioIt","2009-05-24 10:11:12","2009-05-24 11:10:12","weekly","on cloud","2","new record");
$api->handleRequest('recording','create',$obj);

The structure of the Recording object is:

Recording("radio_idname","timezone_used","from_time","to_time","repeat","rectype","keep","title")

If you need to insert a stream, you need to set the "radio_idname" as "Radio Stream" and you must specify the radio URL, as the following:

Recording("Radio Stream","timezone_used","from_time","to_time","repeat","rectype","keep","title","radio_url")

Update a recording

$obj = new Recording("KossuthRadio","radio","2009-05-24 10:11:12","2009-05-24 11:10:12","weekly",on cloud",2","modified recording title"}';
$api->handleRequest('recording/elementID','modify',$obj);

Delete a recording

$api->handleRequest('recording/elementID','delete');

Podcast

Get the list of podcasts

$api->handleRequest('podcast','read');

In order to get the attributes of each element, you need to perform a for cycle, as the following one:

for($i=0; $i < sizeof($api->result->elements); $i++){
  print_r($api->result->elements[$i]->uid);
  print_r($api->result->elements[$i]->title);
  print_r($api->result->elements[$i]->description);
}

For a complete list of podcast item attributes, see the API 2.0 podcast reference.

Get a podcast

$api->handleRequest('podcast/elementID','read');

To get the attributes of the returned item:

if($api->handleRequest('podcast/elementID','read')){
  print_r($api->result->elements[0]->uid);
}

For a complete list of podcast item attributes, see the API 2.0 podcast reference.

Delete a podcast

$api->handleRequest('podcast/elementID','delete');

Insert a podcast

$obj = new Podcast();
$obj->podcast_url = "http://rss.cnn.com/services/podcasting/newscast/rss.xml";
$obj->podcast_title = "Podcast Title";
$obj->podcast_description = "Podcast Description";
$api->handleRequest('podcast','create',$obj);

The structure of the Podcast object is:

Podcast("podcast_url","podcast_title","podcast_description")

Update a podcast

$obj = new Podcast();
$obj->podcast_url="http://rss.cnn.com/services/podcasting/newscast/rss.xml";
$obj->podcast_title="Podcast Title Modified";
$obj->podcast_description="Podcast Description MODIFIED";
$api->handleRequest('podcast/elementID','modify',$obj);

DCST

Get the DCST link

The dcst is a short link that points to a recording or podcast item. In order to obtain a dcst link make:

$api->handleRequest('dcst/recording/elementID','read');
$api->handleRequest('dcst/podcast/elementID','read');

Thumbnail

Get a Thumbnail

$api->handleRequest('thumbnail/elementID','read');

Where elementID is a library UID.
In this case, $api->statuscode and $api->statusdesc are empty, while $api->result contains the image data.

How to write a Thumbnail to a file in PHP

Here is a simple example on how to write the thumbnail returned by the PHP library, into a file

if($api->handleRequest('thumbnail/elementID','read')){
   $imageData = $api->result;
   $imageFile = "thumbnail.jpg";
   $fh = fopen($imageFile, 'wa+') or die("can't open file");
   fwrite($fh, $imageData);
   fclose($fh);
 }

You must have write permission in the directory on which you want to write the image file.