MediaDrop provides a simple API for grabbing media info. A GET request to any of the public methods on this page will return a JSON object with the returned information.
MediaDrop’s controllers render JSON objects by preparing what we call a JSON-ready dict. In these dicts, all keys are Python’s unicode type and all values are of a type in the table below. There there is a 1-1 mapping between Python types and JavaScript types:
Python JavaScript dict Object list Array unicode String int Number float Number bool Boolean None null
API KEYS: It is up to the administrator of a MediaDrop site to allow or disallow public access to that site’s API. To this end, an administrator can choose to require an API Key be sent with every API request. This key is configurable in MediaDrop’s Admin -> Settings -> Data API page.
MediaDrop provides a get method for returning information about an individual media item (given an id or slug) and an index method for returning information on a list of media items that match specified criteria.
Both of these methods make use of the media_info dicts provided by the private _info method.
Return a media_info dict–a JSON-ready dict for describing a media instance.
| Return type: | JSON-ready dict |
|---|---|
| Returns: | The returned dict has the following fields:
|
If you know the id or slug of a single media item you want to query, use the get method (available by default at /api/media/get).
Examples:
http://demo.getmediacore.com/api/media/get?id=24&api_key=zPDyJXdjrPgmFxHC1xw
http://demo.getmediacore.com/api/media/get?slug=the-seed&api_key=zPDyJXdjrPgmFxHC1xw
To return a filtered list of media info, use the index method (available by default at /api/media).
Examples:
http://demo.getmediacore.com/api/media?type=video&api_key=zPDyJXdjrPgmFxHC1xw
Query for a list of media.
| Parameters: |
|
|---|---|
| Raises APIException: | |
If there is an user error in the query params. |
|
| Return type: | JSON-ready dict |
| Returns: | The returned dict has the following fields:
|
MediaDrop provides a files method for returning information about the mediadrop.model.media.MediaFile instances associated with a given mediadrop.model.media.Media instance.
This method makes use of the file_info dicts provided by the private _file_info method.
Return a file_info dict–a JSON-ready dict for describing a media file.
| Return type: | JSON-ready dict |
|---|---|
| Returns: | The returned dict has the following fields:
|
When you know the id or slug of a single media instance that you want to get the file info for, files method (available by default at /api/media/files).
Examples:
http://demo.getmediacore.com/api/media/files?id=24&api_key=zPDyJXdjrPgmFxHC1xw
http://demo.getmediacore.com/api/media/files?slug=the-seed&api_key=zPDyJXdjrPgmFxHC1xw
List all files related to specific media.
| Parameters: |
|
|---|---|
| Raises webob.exc.HTTPNotFound: | |
If the media doesn’t exist. |
|
| Return type: | JSON-ready dict |
| Returns: | The returned dict has the following fields:
|
MediaDrop provides two methods of listing categories: index for listing all categories in a flat list, and tree for listing all categories in the hierarchy tree.
Both of these methods make use of the category_info dicts provided by the private _info method.
Return a JSON-ready dict representing the given category instance.
| Return type: | JSON-Ready dict |
|---|---|
| Returns: | The returned dict has the following fields:
|
To query a flat list of categories, use the index method (available by default at /api/categories).
Examples:
http://demo.getmediacore.com/api/categories?api_key=zPDyJXdjrPgmFxHC1xw
Query for a flat list of categories.
| Parameters: |
|
|---|---|
| Return type: | JSON-ready dict |
| Returns: | The returned dict has the following fields:
|
To query a hierarchy of categories, use the tree method (available by default at /api/categories/tree).
Examples:
http://demo.getmediacore.com/api/categories/tree?api_key=zPDyJXdjrPgmFxHC1xw
http://demo.getmediacore.com/api/categories/tree?slug=short-film&api_key=zPDyJXdjrPgmFxHC1xw
Query for an expanded tree of categories.
| Parameters: |
|
|---|---|
| Return type: | JSON-ready dict |
| Returns: | The returned dict has the following fields:
|
The following Python code fetches the first 6 videos published in February, 2011, and outputs a simple HTML snippet with a thumbnail, title, link, and short description of each video.
import urllib
try:
import json # py26
except:
import simplejson as json # py25 and under
api_url = 'http://demo.getmediacore.com/api/media'
api_key = 'zPDyJXdjrPgmFxHC1xw'
excerpt_length = 180
def fetch_media_list(**kwargs):
kwargs['api_key'] = api_key
querystring = urllib.urlencode(kwargs)
f = urllib.urlopen(api_url + '?' + querystring)
return json.loads(f.read())
def truncate(text):
if len(text) > excerpt_length:
right = text[:excerpt_length].rindex(' ')
text = text[:right] + '…'
return text
result = fetch_media_list(
type='video',
published_after='2011-02-01 00:00:00',
limit=6
)
videos = result['media']
output = ["<h1>Previews:</h1>"]
for v in videos:
output.append(
'<div><a href="%s"><img src="%s" alt="%s"/>%s</a>%s</div>' % (
v['url'], v['thumbs']['s']['url'], v['title'], v['title'],
truncate(v['description_plain'])
)
)
print '\n'.join(output)
The following PHP code fetches the first 6 videos published in February, 2011, and outputs a simple HTML snippet with a thumbnail, title, link, and short description of each video.
<?php
$media_api = 'http://demo.getmediacore.com/api/media';
$api_key = 'zPDyJXdjrPgmFxHC1xw';
$excerpt_length = 180;
function fetch_media_list($data) {
global $media_api, $api_key;
$data['api_key'] = $api_key;
$uri = $media_api . '?' . http_build_query($data);
return json_decode(file_get_contents($uri));
}
function truncate($text) {
global $excerpt_length;
if (strlen($text) > $excerpt_length) {
$left = 0;
$right = strrpos(substr($text, 0, $excerpt_length-1), ' ');
$text = substr($text, $left, $right) . '…';
}
return $text;
}
$result = fetch_media_list(array(
'type' => 'video',
'published_after' => '2011-02-01%2000:00:00',
'limit' => 6
));
$videos = $result->media;
?>
<h1>Previews:</h1>
<?php foreach ($videos as $video): ?>
<div>
<a href="<?php echo $video->url; ?>">
<img src="<?php echo $video->thumbs->s->url; ?>"
alt="<?php echo $video->title; ?>" />
<?php echo $video->title; ?>
</a>
<?php echo truncate($video->description_plain); ?>
</div>
<?php endforeach ?>