Developer Resources

Developer Resources - Metadata API

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 proivde 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. Recieved 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	String	Available 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.

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

Type	Description
broadcast_not_found	The specified broadcast id is not valid.
broadcast_removed	The owner of this broadcast chose to remove the specified broadcast.
broadcast_not_archived	The owner of the specified broadcast chose to disable archiving, hence it only existed as a live stream.
broadcast_not_available	The specified broadcast is currently unavailable for some unspecified reason.
broadcast_no_access	You don't have permission to access to the specified broadcast. This error is returned if you try to access a private broadcast.
user_not_available	The 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

Type	Description
method_invalid_name	The specified API endpoint name contains invalid characters
method_not_found	The API endpoint you specified does not exist
method_no_access	You don't have permission to use the specified API endpoint.
missing_parameter	The 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>