Developer Resources - Metadata API

« Back


Revision 1.14 - updated 2013.05.28

Description

The Metadata API allows external services to access parts of the Bambuser database via HTTP. Multiple data formats are available (XML, JSON etc).

A request to the API requires a valid API key. The API key is private and should not be publicly readable. The key will be restricted to a specific domain or ip-adress in the future. We might provide alternative API keys in the future, designed to be used in client-side applications (JavaScript etc.)

An API key and / or hostname might be subject to a maximum number of polls per hour. Contact info@bambuser.com if you think you will be hitting such a limit.

Request

The request should be made as a HTTP GET (or HTTP POST) call with the format http://api.bambuser.com/method.format?api_key=xxxx&paramX=valueX...

Methods

/broadcast/<vid>

Returns metadata for a single broadcast. This endpoint replaces getVideo.

<vid> is the id of the requested broadcast.

Required url parameters
api_key Your API key.
Must not be made publicly available - if you are building a client-side application, please discuss with us first.

Create new metadata key »

 

/broadcast

Returns metadata for a set of broadcasts matching the query parameters. This endpoint replaces getVideos.

Required url parameters
api_key Your API key.
Received from Bambuser staff.
Must not be made publicly available - if you are building a client-side application, please discuss with us first.
Optional url parameters
username Limit search to a single user or a set of users separated by comma (,).
Default: all users you have access to.

The value must be url encoded if you are using GET!
I.e.
' ' (space)»+
Å»%C3%A5
etc...
type Filter by type.

Available options:
live
archived

Default: both live and archived broadcasts
tag Filter search by a single tag or a set of tags separated by a comma (,).

The value must be url encoded if you are using GET! (see example above)
Default: all tags you have access to.
max_age Limit the search to broadcasts created within x seconds. Should be a positive numeric value.

Default: all broadcasts
limit Limit the number of search results. Should be a positive numeric value.

Default: 10
Maximum: 50 (currently, might be subject to change)
page Access older results by specifying which results page you want returned. Given a limit of 10, page 1 will return results 11-20, page 2 will return 21-30 etc.

Default: 0
geo_distance Limit the search geographically, by setting geo_distance to a radius in meters. You also need to specify the center point by setting lat and lon.
lat Latitude of the center point, when limiting search to a geographic area.
lon Longitude of the center point, when limiting search to a geographic area.

Response

A typical broadcast metadata structure contains the following fields. Note that in addition to these, new fields may be added over time and undocumented fields may be present.

Always available
vid Integer id that uniquely identifies the Bambuser broadcast.
title String The broadcast title, set in the broadcast device before starting the broadcast.
type StringAvailable values: "live", "archived"
username String Bambuser username of the broadcasting user
created Integer Unix timestamp indicating when the broadcast started.
Sometimes available
preview String URL to the preview image.
page String URL to the broadcast page on bambuser.com.
width Integer The native width of the broadcast material, in pixels.
height Integer The native height of the broadcast material, in pixels.
length Integer The length of the broadcast, in seconds.
lat String latitude of the latest position received.
WGS84 map datum.
lon String longitude of the latest position received.
WGS84 map datum.
position_accuracy Float Accuracy of the position, in meters.
position_type String Available values: "gps", "network", "country", "manual".
trail String URL to a KML file with all registered positions for the broadcast.
views_live Integer Number of viewers during the live broadcast.

Note: This value is currently subject to latency of several minutes, sometimes up to an hour.
views_total Integer Total number of views, both on the live and archived version of the broadcast.

Note: This value is currently subject to latency of several minutes, sometimes up to an hour.
comment_count Integer Number of comments on the broadcast.
device_class String Type of broadcast device
Available values: "webcam", "phone".
device_name String Broadcast device model info
F.e. "Nokia E71"
tags Array List of tags added to the broadcast.

Available keys for each tag are:
  • tag:String
    A descriptive string up to 50 characters long.
  • position:Integer
    Values greater than zero indicates that the tag marks a certain position (number of seconds from start) in the broadcast.
  • created:Integer
    The created time is a unix timestamp for when the tag was created.

Response formats

JSON JavaScript Object Notation, see http://en.wikipedia.org/wiki/JSON

Example »

XML A simple XML structure is returned.

The document contains a <feed> tag with the actual content within it.

Example »

Tip: Firefox is useful for testing the simple XML transport format. Type the request string into the addressbar as you would with any website URL and Firefox will diplay the result nicely. Safari on OS X (and Internet Explorer on Windows?) tries to save the result as a file, which typically makes testing harder.

Rate Limiting

Please be kind to our servers. The metadata API is mainly indended to be used by server-side applications that use reasonable caching strategies.

You should not fire an API request each time a user of your application loads a web page. Instead, cache the API results in your database or use tools like memcached, then refresh the data in a reasonable pace.

If API requests using your API key are fired too rapidly, you will start to see "503 Service Temporarily Unavailable" responses. Stay below a handful of requests per minute and you'll be fine.

Errors

Should an error occur, you will get an HTTP status code in the 400 (client errors) or 500 (server errors) range. In most cases the response body contains an error object with more specific information. Examples »

Error object
Variable Description
type A string that identifies the type of error that occured
message Error message in plain English
Broadcast related error types
TypeDescription
broadcast_not_foundThe specified broadcast id is not valid.
broadcast_removedThe owner of this broadcast chose to remove the specified broadcast.
broadcast_not_archivedThe owner of the specified broadcast chose to disable archiving, hence it only existed as a live stream.
broadcast_not_availableThe specified broadcast is currently unavailable for some unspecified reason.
broadcast_no_accessYou don't have permission to access to the specified broadcast. This error is returned if you try to access a private broadcast.
user_not_availableThe user account that the selected broadcast was produced with is not available anymore. This error is returned when the user has closed the account as well as when account is temporarily or permanently blocked by the administrators.
Generic error types
TypeDescription
method_invalid_nameThe specified API endpoint name contains invalid characters
method_not_foundThe API endpoint you specified does not exist
method_no_accessYou don't have permission to use the specified API endpoint.
missing_parameterThe endpoint requires a url parameter that you did not supply.

Examples

/broadcast/<vid>

Metadata for broadcast 1234 in JSON format
Query: http://api.bambuser.com/broadcast/1234.json?api_key=xxxx

Result:
{ "result": { "vid": "1234", "title": "Misc testing", "type": "archived", "username": "tomsun", "created": "1196829421", "preview": "http://archive.bambuser.com/archive/batch1/ade3b23583583d4c.jpg", "page": "http://bambuser.com/v/1234" } }

Metadata for broadcast 1234 in XML format
Query: http://api.bambuser.com/broadcast/1234.xml?api_key=xxxx

Result:
<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vid>1234</vid>
  <title>Misc testing</title>
  <type>archived</type>
  <username>tomsun</username>
  <created>1196829421</created>
  <preview>http://archive.bambuser.com/archive/batch1/ade3b23583583d4c.jpg</preview>
  <page>http://bambuser.com/v/1234</page>
</feed>
Attempt to get metadata for a removed broadcast
Query: http://api.bambuser.com/broadcast/1276969.json?api_key=xxxx

Result:
{ "result": { "vid": "1276969", "username": "tomsun", "error": { "type": "broadcast_removed", "message": "This broadcast was removed by user" } } }

Query: http://api.bambuser.com/broadcast/1276969.xml?api_key=xxxx

Result:
<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vid>1276969</vid>
  <username>tomsun</username>
  <error>
    <type>broadcast_removed</type>
    <message>This broadcast was removed by user</message>
  </error>
</feed>

 

/broadcast

Three latest broadcasts from Jonny in JSON format
Query: http://api.bambuser.com/broadcast.json?username=Jonny&limit=3&api_key=xxxx

Result:
{ "result": [ { "vid": "47615", "title": "uej", "type": "archived", "username": "Jonny", "created": "1227634981", "preview": "http://archive2.bambuser.com/archive-r5/b0cf8ce08c690ae7541ce7d4ee57b598-1.jpg", "page": "http://bambuser.com/v/47615" }, { "vid": "47536", "title": "At High-Tech Building", "type": "archived", "username": "Jonny", "created": "1227608400", "preview": "http://archive2.bambuser.com/archive-r5/310f588db2aeff1d3d63185c005cb3f0-1.jpg", "page": "http://bambuser.com/v/47536" }, { "vid": "47522", "title": "at the tunnelbana", "type": "archived", "username": "Jonny", "created": "1227604196", "preview": "http://archive2.bambuser.com/archive-r5/7a0530d9d28f7628b7c279cc84eee0ce-1.jpg", "page": "http://bambuser.com/v/47522" } ] }


Five latest archived broadcasts from Jonny and Månster in XML format
Query: http://api.bambuser.com/broadcast.xml?username=Jonny,M%C3%A5nster&type=archived&limit=5&api_key=xxxx

Result:
<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <item>
    <vid>47616</vid>
    <title>Test</title>
    <type>archived</type>
    <username>Månster</username>
    <created>1227635017</created>
    <preview>http://archive2.bambuser.com/archive-r5/6119cc85147ab9d8a6991aa4f085a055-1.jpg</preview>
    <page>http://bambuser.com/v/47616</page>
  </item>
  <item>
    <vid>47615</vid>
    <title>uej</title>
    <type>archived</type>
    <username>Jonny</username>
    <created>1227634981</created>
    <preview>http://archive2.bambuser.com/archive-r5/b0cf8ce08c690ae7541ce7d4ee57b598-1.jpg</preview>
    <page>http://bambuser.com/v/47615</page>
  </item>
  <item>
    <vid>47538</vid>
    <title>Mixing</title>
    <type>archived</type>
    <username>Månster</username>
    <created>1227608683</created>
    <preview>http://archive2.bambuser.com/archive-r5/d772bf2aaacb30fc0c358cce53801908-1.jpg</preview>
    <page>http://bambuser.com/v/47538</page>
  </item>
  <item>
    <vid>47536</vid>
    <title>At High-Tech Building</title>
    <type>archived</type>
    <username>Jonny</username>
    <created>1227608400</created>
    <preview>http://archive2.bambuser.com/archive-r5/310f588db2aeff1d3d63185c005cb3f0-1.jpg</preview>
    <page>http://bambuser.com/v/47536</page>
  </item>
  <item>
    <vid>47522</vid>
    <title>at the tunnelbana</title>
    <type>archived</type>
    <username>Jonny</username>
    <created>1227604196</created>
    <preview>http://archive2.bambuser.com/archive-r5/7a0530d9d28f7628b7c279cc84eee0ce-1.jpg</preview>
    <page>http://bambuser.com/v/47522</page>
  </item>
</feed>

You can leave feedback to Bambuser Crew via this form.