API 1.0 (Deprecated)

API Version 1.0 has been deprecated and is no longer supported Please use the new API version 2.0 which is now strictly JSON and includes OAuth 2.0 for authentication. The API methods below are RESTful implementations.

Media Statistics API 1.0

API for third-party applications to access media download statistics from Blubrry.com.

Method: Summary

Returns a summary report for a specific podcast program.

URL: http://api.blubrry.com/stats/program_keyword/summary.format
Formats: xml, json
Method(s): GET
Parameters:

month – specific month to pull summary from (optional; default: current month)
year – specific year to pull summary from (optional; default: current year)

Example output:

[xml]
<?xml version=”1.0″ encoding=”UTF-8″?>
<summary type=”array”>
<stats_url>http://stats.blubrry.com/ </stats_url>
<program_id>123</program_id>
<overall type=”array”>
<total>123</total>
<unique>123</unique>
<unique_repeat>123</unique_repeat>
</overall>
<current_month type=”array”>
<total>123</total>
<unique>123</unique>
<unique_repeat>123</unique_repeat>
</current_month>
<last_month type=”array”>
<total>123</total>
<unique>123</unique>
<unique_repeat>123</unique_repeat>
</last_month>
<media type=”array”>
<episode>
<id>123</id>
<title>Episode Title</title>
<filename>filename.ext</filename>
<date>Mon, 06 Apr 2009 05:26:15 +0000</date>
<overall>1234</overall>
<current_month>123</current_month>
</episode>
<episode>
<id>456</id>
<title>file2.ext</title>
<filename>file2.ext</filename>
<date>Mon, 01 Apr 2009 03:20:15 +0000</date>
<overall>2345</overall>
<current_month>234</current_month>
</episode>
</media>
</summary>
[/xml]

Note: The method above is still under review and may be subject to change.


Media Hosting API 1.0

API for third-party applications to manage and upload media files hosted on Blubrry.com.

Media Hosting Methods

Method: List Programs

Returns a list of hosted programs that the user has access to.

URL: https://api.blubrry.com/media/index.format
Formats: xml, json
Method(s): GET
Parameters:

  • limit – Optional. Specifies the number of results to return. Default is 20, 100 maximum. Ex: https://api.blubrry.com/media/index.json?limit=20
  • start – Optional. Specifies the start position of returned results. Ex: https://api.blubrry.com/media/index.json?start=0

Returned headers:

  • X-RawVoice-Total-Results – Indicates how many programs total are available to query. Header value can be used to determine if additional calls to List Programs is necessary.

Example output:

[xml]
<?xml version=”1.0″ encoding=”UTF-8″?>
<programs type=”array”>
<program>
<title>Program Title</title>
<keyword>program_keyword</keyword>
</program>
<program>
<title>Program Title Two</title>
<keyword>program_keyword_two</keyword>
</program>
</programs>
[/xml]

Returned headers:

X-RawVoice-Total-Results: 32

Method: List unpublished media

Returns a list of unpublished media files for the specified program.

URL: https://api.blubrry.com/media/program_keyword/index.format
Formats: xml, json
Method(s): GET
Request URL Paramters:

  • program_keyword – Required. Specifies the program to list media files of. Ex: https://api.blubrry.com/media/program_keyword/index.json

GET Query string parameters:

  • limit – Optional. Specifies the number of results to return. Default is 20, 100 maximum. Ex: https://api.blubrry.com/programs/my_program/index.json?limit=20
  • start – Optional. Specifies the start position of returned results. Ex: https://api.blubrry.com/media/my_program/index.json?start=0

Returned headers:

  • X-RawVoice-Total-Results – Indicates how many unpublished media files are available to query. Header value can be used to determine if additional calls to List Unpublished Media is necessary.

Example output:

[xml]
<?xml version=”1.0″ encoding=”UTF-8″?>
<files type=”array”>
<file>
<name>Filename.ext</name>
<length>3634344</length>
<created>Mon Jan 26 19:47:15 +0000 2009</created>
<last_modified>Mon Jan 26 19:47:15 +0000 2009</last_modified>
</file>
<file>
<name>Filename2.ext</name>
<length>4635796</length>
<created>Tue Jan 27 11:47:56 +0000 2009</created>
<last_modified>Tue Jan 27 11:47:56 +0000 2009</last_modified>
</file>
</files>
[/xml]

Returned headers:

X-RawVoice-Total-Results: 561

Method: Delete media

Deletes the specified media file.

URL: https://api.blubrry.com/media/program_keyword/mediafile.ext
Formats: xml, json
Method(s): DELETE
Request URL Paramters:

  • program_keyword – Required. Specifies the program to list media files of.
  • mediafile.ext – Required. Specifies the media file to delete.

Ex: https://api.blubrry.com/media/my_program/mediafile.ext

Query string parameters:

  • format – Optional. Specifies the format of the response returned. (json or xml)

Example URL: https://api.blubrry.com/media/my_program/mediafile.ext?format=json

Example output:

[xml]
<?xml version=”1.0″ encoding=”UTF-8″?>
<status>
<text>Media file deleted successfully.</text>
</status>
[/xml]

Method: Publish Media File

Makes the uploaded media file publicly available.

URL: https://api.blubrry.com/media/my_program/mediafile.ext
Formats: xml, json
Method(s): GET
Request URL Paramters:

  • program_keyword – Required. Specifies the program to list media files of.
  • mediafile.ext – Required. Specifies the media file to delete.

Ex: https://api.blubrry.com/media/my_program/mediafile.ext

GET Query string parameters:

  • format – Required. Specifies the format of the response returned. (json or xml)
  • publish – Required. When true, the media file will be made publicly available. (true or false)

Example URL: https://api.blubrry.com/media/my_program/episode_001.mp3?format=json&publish=true

Example output:

[xml]
<?xml version=”1.0″ encoding=”UTF-8″?>
<status type=”array”>
<text>Successfully published</text>
<media_url>https://content.blubrry.com/media/my_program/episode_001.mp3</media_url>
</status>
[/xml]

Media Migration Methods

The following api methods are for adding, removing and checking the status of media migration.

Method: Add Migrate Media URL(s)

Adds media URLs to the migration queue.

URL: https://api.blubrry.com/media/program_keyword/migrate_add.json
Formats: json
Method(s): GET, POST (POST recommended)
Request URL Parameters:

  • program_keyword – Required. Specifies the program to list media files of.

Ex: https://api.blubrry.com/media/my_program/migrate_add.json

GET / POST parameters:

  • url – individual URL to add to migration queue.
  • urls – Multiple URLs separated by new lines to add to migration queue.

Example URL: https://api.blubrry.com/media/my_program/migrate_add.json?url=http%3A%2F%2Fexample.com%2Fpath%2Fto%2Fmedia.mp3

Method: Remove Migrate Media URL(s)

Removes specified unprocessed URLs from the migration queue.

URL: https://api.blubrry.com/media/program_keyword/migrate_remove.json
Formats: json
Method(s): GET, POST (POST recommended)
Request URL Parameters:

  • program_keyword – Required. Specifies the program to list media files of.

Ex: https://api.blubrry.com/media/my_program/migrate.json

GET / POST parameters:

  • url – individual URL to add to migration queue.
  • urls – Multiple URLs separated by new lines to add to migration queue.
  • ids – one or more unique migrate ID’s separated by commas.

Example URL: https://api.blubrry.com/media/my_program/migrate_remove.json?url=http%3A%2F%2Fexample.com%2Fpath%2Fto%2Fmedia.mp3

Method: Migrate Media Status

Makes the uploaded media file publicly available.

URL: https://api.blubrry.com/media/program_keyword/migrate_status.json
Formats: json
Method(s): GET
Request URL Parameters:

  • program_keyword – Required. Specifies the program to list media files of.

Ex: https://api.blubrry.com/media/my_program/migrate_status.json

GET / POST parameters:

  • status – only return results with specific status. Status may be any one of ‘queued’, ‘downloading’, ‘completed’, ‘skipped’, ‘error’ or ” for no specific status.
  • start – start position for results, 0 indexed (0 is default)
  • limit – number of results to return, 100 maximum
  • ids – one or more unique migrate ID’s separated by commas.

Example URL: https://api.blubrry.com/media/my_program/migrate_remove.json?ids =654%2C566%2C578

Returns the status for the 3 specified migration ids (654,566,578) in a json array. The array also includes the total number of records found.

WebDAV methods

The method below is a WebDAV implementation.

Method: Upload media

Uploads a media file to the server.

URL: https://api.blubrry.com/media/program_keyword/mediafile.ext
Formats: xml, json
Method(s): PUT
Request URL Parameters:

  • program_keyword – Required. Specifies the program for uploaded media file.
  • mediafile.ext – Required. Specifies the media file to upload.

Ex: https://api.blubrry.com/media/programs/my_program/mediafile.ext

Query string parameters:

  • format – Optional. Specifies the format of the response returned. Ex: https://api.blubrry.com/media/my_program/mediafile.ext?format=json

Request headers:

X-RawVoice-MD5-Checksum – Optional. MD5 checksum of the file being uploaded. When specified, the server will return the final uploaded MD5 checksum. The MD5 checksums should match.

X-RawVoice-Range – Optional. Range of start and end bytes which supports multi-PUT requests to upload content in chunks.

Returned headers:

X-RawVoice-MD5-Checksum: – Optional. MD5 checksum of the file uploaded.
X-RawVoice-Range: 0-536870912

Example output:

[xml]
<?xml version=”1.0″ encoding=”UTF-8″?>
<status>
<text>Media file uploaded successfully.</text>
</status>
[/xml]


Social API

The Social API will allow you to create third-party applications to update your program listings and post them on various social media platforms.


Update Listing

Updates the specified program listing identified in the URL.

URL: https://api.blubrry.com/social/program_keyword/update-listing.json
Formats: JSON
Method(s): POST
Parameters: program_keyword – Required. Specifies the program to update listing for

JSON ENCODED returned results

Success {‘success’:”success message”, ‘podcast-id’:”ID”}

Success with warnings: {‘success’:”success message”, ‘podcast-id’:”ID”, “warnings”:”Warning messages”}

Error: {‘request’:”REQUEST_URI”,‘error’:”error message”}

Note: Each warning should be separated with a new line.

POST Parameters

  • feed-url – The RSS feed URL for the specified podcast. Do not try to insert with the podcast episode data, will be used for a different purpose
  • title – Required. Title of the podcast episode. This is the feed podcast episode title, which may not be the same as the blog post title. Character limit is 255. UpdateOnePostKey: podcast_title
  • date – Required. Date in RFC 2822 format. UpdateOnePostKey: podcast_post_date
  • guid – RSS item guid value. If not specified, the media-url is used as the guid value. If the guid is not unique then the API call will return with failure stating as such. UpdateOnePostKey: podcast_guid
  • media-url – Required. Podcast enclosure “url” value, must be a complete URL with protocol schema. UpdateOnePostKey: podcast_filename
  • subtitle – iTunes Subtitle of podcast episode, or the first 255 characters of blog post. Character limit 255. UpdateOnePostKey: podcast_subtitle
  • duration – iTunes duration, specified in hh:mm:ss, or mm:ss, or ss where hh, mm, ss is a numeric value zero padded, e.g. 01:13:03. UpdateOnePostKey: podcast_seconds
  • filesize – Required. File size in bytes, this is the Podcast enclosure “length”. Value should not be formatted, should not include commas. e.g. 1567456 UpdateOnePostKey: podcast_title
  • explicit – iTunes explicit value, values can be one of: yes, no, clean. Value can also be omitted or not included indicating “no”. UpdateOnePostKey: podcast_title
  • link – RSS item “link” value, should be complete URL to the blog post or page associated with the podcast episode. UpdateOnePostKey: podcast_title
  • image – RSS item “itunes:image” value or the episode’s official image in square coverart form, should be a complete URL to the episode specific image. UpdateOnePostKey: podcast_title

Get Social Options

Returns a record set of totals for a specific podcast program.

URL: http://api.blubrry.com/social/program_keyword/get-social-options.json
Formats: JSON
Method(s): GET
Parameters(s): program_keyword – Required. Specifices teh program to get social options for.

JSON ENCODED return results

Success: {“Success”:”success message”,”social-options”:”ARRAY-SOCIAL-OPTIONS“}

Error: {‘request:”REQUEST_URI”,”error”:”error message”}

Get Parameters:

  • ARRAY-SOCIAL-OPTIONS: This is an array of items of key/value pairs, some of which have an array of items within them. ARRAY-SOCIAL-OPTIONS include the following key=>value pairs
    • social-id – Identifier for the social destination, maps directly to the program_meta database table record meta_id where social network credentials are saved.
    • social-type – Type of destination, not limited to but currently supported values: twitter, facebook, youtube
    • social-image – URL to an image to represent the social network in a web page form.
    • social-title – Title of social destination, e.g. “Twitter @GeekNews” or “Todd Cochrane’s Facebook”
    • form-data – ARRAY-FORM-DATA of posting form fields with names and additional attributes.
    • Warnings – String of warning messages to display to the user at the time they are presented option to post to social.
  • ARRAY-FORM-DATA: This is an array of items of key/value pairs. The options are for generating the form and mapping the values to fields for the eventual post to social API call.
    • row-type – Specifies type of row to enter into form. Currently supported types: input-text, input-checkbox
    • row-order – Order number for the row to appear in form. Number starts with 1 and increments upward.
    • row-attributes – ROW-ATTRIBUTES-DATA specifies the attributes for the row item
  • ROW-ATTRIBUTES-DATA: Separated by type
    • HTML
      • content – Raw HTML text to be displayed in on page.
    • Input-Text
      • label – Required. Title of input, placed above input wrapped within a label tag.
      • placeholder – placeholder within input.
      • help-text – Text to go below input box.
      • rows – Number of rows for input box. Default if not specified is 1. If 2 or more, the textarea tag is used instead of input.
      • maxlength – Maximum character length for the input box.
      • name – Required. name of input field
      • value – Default value for input field
    • Input-Checkbox:
      • label – Title of input, placed to the right of checkbox within a label tag.
      • checked – value of either blank (not checked) or ‘checked’ to indicate that the input should be checked upon initial loading. If not present the default is to not initially check the input
      • name – name of input field (only used once)
      • value – value of input field
    • Input-Radio:
      • label – Title of input, placed to the right of checkbox within a label tag.
      • checked – value of either blank (not checked) or ‘checked’ to indicate that the input should be checked upon initial loading. If not present the default is to not initially check the input
      • name – name of input field (may be used multiple times to indicate a series of checkboxes)
      • value – value of input field


<?php

$social_options = array();
$social_options['success'] = 'Post to social options for Angelo Mandato';
$social_options['social-options'] = array();

// Create Twitter destination
$TwitterSocialOption = array();
$TwitterSocialOption['social-id'] = 6367;
$TwitterSocialOption['social-type'] = 'twitter';
$TwitterSocialOption['social-image'] = 'http://example.com/path/to/twitter.png';
$TwitterSocialOption['social-title'] = 'Post to @UserName Twitter';
$TwitterSocialOption['form-data'] = array();

$TwitterSocialOption['form-data'][] = array(
'field-type'=>'input-text',
'field-order'=>'1',
'label'=>'Twitter Message',
'name'=>'content-6367',
);

// Add the Twitter Social destination
$social_options['social-options'][]= $TwitterSocialOption;

// Create Facebook desination
$FacebookSocialOption = array();
$FacebookSocialOption['social-id'] = 7154;
$FacebookSocialOption['social-type'] = 'facebook';
$FacebookSocialOption['social-image'] = 'http://example.com/path/to/facebook.png';
$FacebookSocialOption['social-title'] = 'Post to Full Name Facebook';
$FacebookSocialOption['form-data'] = array();

$FacebookSocialOption['form-data'][] = array(
'field-type'=>'input-text',
'field-order'=>'1',
'label'=>'Media File Title',
'name'=>'title-7154',
'maxlength'=>90,
);

$FacebookSocialOption['form-data'][] = array(
'field-type'=>'input-text',
'field-order'=>'2',
'label'=>'Facebook Post Message',
'rows'=>4,
'name'=>'content-7154',
'maxlength'=>4000,
);

$FacebookSocialOption['form-data'][] = array(
'field-type'=>'input-checkbox',
'field-order'=>'3',
'label'=>'Your Facebook Wall',
'name'=>'destination-7154-wall',
'value'=>'::wall::',
‘checked’=>’checked’,
);

$FacebookSocialOption['form-data'][] = array(
'field-type'=>'input-checkbox',
'field-order'=>'4',
'label'=>'Name of Fan Page',
'name'=>'destination-7154-734',
'value'=>'Name of Fan Page',
);

// Add the Facebook Social destination
$social_options['social-options'][]= $FacebookSocialOption;

// Create YouTube desination
$YouTubeSocialOption = array();
$YouTubeSocialOption['social-id'] = 9561;
$YouTubeSocialOption['social-type'] = 'youtube';
$YouTubeSocialOption['social-image'] = 'http://example.com/path/to/youtube.png';
$YouTubeSocialOption['social-title'] = 'Post to YouTube Account';
$YouTubeSocialOption['form-data'] = array();

$YouTubeSocialOption['form-data'][] = array(
'field-type'=>'input-text',
'field-order'=>'1',
'label'=>'Title',
'name'=>'title-9561',
'maxlength'=>100,
);

$YouTubeSocialOption['form-data'][] = array(
'field-type'=>'input-text',
'field-order'=>'2',
'label'=>'Description',
'name'=>'description-9561',
'maxlength'=>4000,
);

// Add the YouTube Social destination
$social_options['social-options'][]= $YouTubeSocialOption;

echo json_encode( $social_options);
exit;

?>

JSON ENCODED Results:

{“success”:”Post to social options for Angelo Mandato”,”social-options”:[

{“social-id”:6367,”social-type”:”twitter”,
“social-image”:”http:\/\/example.com\/path\/to\/twitter.png”,
“social-title”:”Post to@UserName Twitter”,
“form-data”:[{“field-type”:”input-text”,”field-order”:”1″,”label”:”Twitter Message”,”name”:”content-6367″}]},

{“social-id”:7154,
“social-type”:”facebook”,
“social-image”:”http:\/\/example.com\/path\/to\/facebook.png”,
“social-title”:”Post to Full Name Facebook”,
“form-data”:[

{“field-type”:”input-text”,”field-order”:”1″,”label”:”Media File Title”,”name”:”title-7154″,”maxlength”:90},
{“field-type”:”input-text”,”field-order”:”2″,”label”:”Facebook Post Message”,”rows”:4,”name”:”content-7154″,”maxlength”:4000},
{“field-type”:”input-checkbox”,”field-order”:”3″,”label”:”Your Facebook Wall”,”name”:”destination-7154-wall”,”value”:”::wall::”, “checked”:”checked”},
{“field-type”:”input-checkbox”,”field-order”:”4″,”label”:”Name of Fan Page”, “name”:”destination-7154-734″,”value”:”Name of Fan Page”}]},

{“social-id”:9561,”social-type”:”youtube”,”social-image”:”http:\/\/example.com\/path\/to\/youtube.png”,”social-title”:”Post to YouTube Account”,
“form-data”:[
{“field-type”:”input-text”,”field-order”:”1″,”label”:”Title”,”name”:”title-9561″,”maxlength”:100},
{“field-type”:”input-text”,”field-order”:”2″,”label”:”Description”,”name”:”description-9561″,”maxlength”:4000}]

}]}

 


Post to Social

Information to specific social destinations to the specified program identified in the URL (program_keyword)

URL: http://api.blubrry.com/social/program_keyword/post.json
Formats: JSON
Method(s): POST
Parameters: program_keyword – Required. Specifies the program to post for

Post Parameters

  • podcast-id – Required. ID of podcast to post to social.
  • post-data – Required. ARRAY-OF-DESTINATIONS to post to with specified parameters
  • ARRAY-OF-DESTINATIONS: Each item has specific social network information as well as values to post to that social network. These values are specific to that social network.
  • social-id – Required. Destination social ID which is the meta_id value of the social network settings in the programs_meta database table.
  • social-type – Required. Type of destination, not limited to but currently supported values: twitter, facebook, youtube
  • social-data – Required. SOCIAL-DATA-ARRAY of data to be posted to the specified social network
  • SOCIAL-DATA-ARRAY: Each item has specific post to social information for the social network it is used for.
  • Twitter: SOCIAL-DATA-ARRAY:
    • content{SOCIAL-ID} – Required. Message to post to twitter. Character limit: 140
  • Facebook SOCIAL-DATA-ARRAY:
    • title{SOCIAL-ID} – Required. Title of media file. Character limit: 90
    • description{SOCIAL-ID}– Posting content to Facebook wall or fan page. Character limit: 4000 (true limit 63,206)
    • destination-{SOCIAL-ID}-{PAGE-ID} – One or more facebook destinations.  A special destination to the users’ personal wall is indicated with the page ID “wall” having the value “::wall::”. All other destinations specified go to Facebook fan pages the user has permission to post to.
  • YouTube SOCIAL-DATA-ARRAY:
    • title-{SOCIAL-ID} – Required. Title of posting to YouTube. Character limit: 100
    • description-{SOCIAL-ID} – Description of posting to YouTube. Character limit: 4000 (true limit 5,000)