BBC Backstage

Bangladesh River Journey - API

Documentation for the of the BBC World Service's .

  1. The Original Mashup

    BBC Bangladesh River Journey

    The Bangladesh River Journey is a mashup of posts from a BBC World Service trip to track climate change in Bangladesh.

    The trip has coincided with a tragic cyclone, further highlighting the importance of climate change awareness.

    During the month-long trip, photos are being posted to Flickr, messages sent to Twitter and diary entries sent to the site. The mashup puts all of these on a map, letting you navigate around and follow the trip.

    The journalists have a navigation device and post their coordinates to Twitter each time they reach a new location (e.g. this post). The mashup system then uses the coordinates to map each photo, tweet and diary entry.

    Hidden Technologies

    Some of the hidden technologies in the mashup are described in a blog post by the site developers, Dharmafly.

    The site uses HTML microformats and contains hidden data, such as descriptions for each Flickr photo (CSS is used to hide this from view, but the page can be seen here in full). The page is ripe for some Greasemonkey remixing...

  2. Create Your Own Mashup

    The API can be used to access all the data related to the Bangladesh River Journey. With this, you can create your own, entirely new mashup.

    You could extend your own mashup by harnessing the Flickr API, , Google Maps API and others.

    Do you have any ideas for innovative ways to remix and mashup the data? Go ahead and experiment... You can share it, along with any thoughts or questions, on the BBC Backstage mailing list.

  3. API Documentation

    The base url is

    If you visit the base url, you'll see a simple feed (technically, it's GeoRSS), with the latest 20 posts from the trip.

    To interact with the API, you can add parameters and values to the base url as a . For example: base_url?parameter=value

    Parameters affect the types of posts that the API returns. Your mashup application can request data from the API by calling the base url, along with any of the optional parameters.

    The parameters and their possible values are described below. You do not need all of this information to start using the API. Click the examples to get an idea of the possibilities:

    1. format

      • Description

        The format parameter affects the data format of the API response. Instead of an RSS feed, you can request the posts to be returned in a number of other formats.

      • Possible values

        rss, xml, json, js, xoxo, xhtml, kml

      • Default

        'rss'

      • Examples

      • Notes

        • is often (but not exclusively) used for exchanging data in JavaScript. The 'json' format returns a JSON object with a single property: items. This is an array of posts.

          Note that if you try to directly view the 'json' response, your browser may ask if you want to download a file. This is normal and is due to the 'application/json' mime-type (see below). This is not an issue when using the format within mashup scripts.

        • The 'js' (JavaScript) format is virtually identical to the 'json' format, except that the JSON object is passed as a function call to processJSON(), a function that must be defined within your own script. An alternative callback function name can be given by passing the 'jsoncallback' parameter.

        • The 'xoxo' format is simple, semantic XHTML that uses the microformat.

          By default, the response is a complete, valid XHTML document. You can optionally pass the simpleXml parameter to strip out the Doctype and outer elements, ready to insert straight into the DOM of a page.

        • The 'xhtml' format is similar in purpose to the 'xoxo' format. However, in this case, the structure of XHTML is identical to that used on the Bangladesh River Journey website.

          This is ideal for use in Greasemonkey scripts that modify the original mashup site, particularly when used with the simpleXml parameter.

        • KML is the data format used by mapping applications like Google Earth.

          To retrieve the KML feed for the entire journey, set numPosts to all.

        • The character encoding is always .
        • The returned depends on the format:
          • rss: application/rss+xml
          • xml: application/xml
          • json: application/json
          • js: application/x-javascript
          • xoxo: text/html
          • kml: application/vnd.google-earth.kml+xml
        • As a tool during development, the Mime-type can be omitted, by passing the omitMIMEType parameter.

    2. types

      • Description

        A comma-delimited list of the types of post to be returned.

      • Possible values

        twitter, flickr, bbcDiary, gps

      • Default

        'twitter, flickr, bbcDiary'

      • Examples

      • Notes

        • 'gps' is a post containing information about a location on the trip and is derived from the Twitter post that contained the coordinates for the location.

    3. id

      • Description

        A comma-delimited list of specific posts, addressed by their id values.

      • Default

        none

      • Example

      • Notes

        • If your mashup application caches the ids of posts, you could use this parameter to retrieve further information about each post at a later date.

        • Id values are derived from the first letter of the post 'type' and the id of the post on the 3rd Party website - e.g. the Flickr photo id or the Twitter status id.

    4. numPosts

      • Description

        The maximum number of posts to be returned. This is either a number or the string 'all'.

      • Default

        20

      • Example

      • Notes

        • When narrowing results with other parameters, remember to set numPosts=all if you need all the related posts back.

          For example, if you use from and to, or lat and lng, you will only get a maximum of 20 posts, unless you pass the 'numPosts' parameter.

    5. sort

      • Description

        Sort the returned posts by a specified property.

      • Possible values

        date, title, description, lng, lat, id, point, type, place

      • Default

        'date'

      • Example

      • Notes

        • You may want to use this in conjunction with the 'order' parameter.

    6. order

    7. from

      • Description

        This narrows the set of posts returned to those made after the specified date.

      • Default

        The date of the first post

      • Example

      • Notes

        • You can use any value that is accepted by the PHP function strtotime - e.g. 'now', 'yesterday', '2007-11-05', 'last Wednesday', '2 Nov 2007 16:00'.
        • The timezone is GMT.

    8. to

    9. lat

      • Description

        The specific latitude of a GPS point on the trip.

      • Default

        none

      • Example

      • Notes

        • This must be used in conjunction with the 'lng' parameter.
        • The lat/lng pair refers to a specific location, as posted in the original GPS point. The API does not return the nearest posts to an arbitrary lat/lng value.

    10. lng

      • Description

        The specific longitude of a GPS point on the trip.

      • Default

        none

      • Notes

    11. point

      • Description

        The sequential number for a GPS point on the trip, starting from 1.

      • Default

        none

      • Example

    12. jsoncallback

    13. simpleXml

      • Description

        This parameter can be passed when requesting 'xoxo' or 'xhtml' formats to strip out the Doctype and outer elements.

      • Possible values

        0, 1

      • Default

        0

      • Example

        View the source and compare the following:

      • Notes

        • This can be used to achieve a simple insertion of XHTML code straight into the DOM, within an Ajax mashup - a technique known as (or 'Jah'). A simple example of Ahah.

    14. omitMIMEType

      • Description

        As a tool during development, you can set 'omitMIMEType = 1' to omit the mime-type header. This is useful, for example, for viewing JSON responses directly in a browser.

      • Default

        0

      • Examples

    15. Example Responses

      • Xml

        <?xml version="1.0"?>
<root>
   <twitter timestamp="T1195046302">
      <id>t413892132</id>
      <timestamp>1195046302</timestamp>
      <date>2007-11-14T19:18:22+06:00</date>
      <type>twitter</type>
      <title>At Daulatdia ferry terminal expecting bad weather as cyclone in the Bay of Bengal heads north.</title>
      <description>At Daulatdia ferry terminal expecting bad weather as cyclone in the Bay of Bengal heads north.</description>
      <link>http://twitter.com/bangladeshboat/statuses/413892132</link>
      <dateRSS>Wed, 14 Nov 2007 19:18:22 +0000</dateRSS>
      <lat>+23.77083</lat>
      <lng>+89.78509</lng>
      <point>16</point>
      <place>Daulatdia, Bangladesh</place>
   </twitter>
</root>

      • Json

        {"items":[
      {
        "id": "t413892132",
        "timestamp": 1195046302,
        "date": "2007-11-14T19:18:22+06:00",
        "type": "twitter",
        "title": "At Daulatdia ferry terminal expecting bad weather as cyclone in the Bay of Bengal heads north.",
        "truncated": false,
        "description": "At Daulatdia ferry terminal expecting bad weather as cyclone in the Bay of Bengal heads north.",
        "link": "http://twitter.com/bangladeshboat/statuses/413892132",
        "lat": "+23.77083",
        "lng": "+89.78509",
        "point": 16,
        "place": "Daulatdia, Bangladesh"
      }
]}

      • Xoxo

        <ol class="hfeed xoxo">
  <li class="hentry xfolkentry postid-t413892132">
    <dl class="twitter">
      <dt class="entry-title entry-content description">
        <a rel="bookmark" class="taggedlink" href="http://twitter.com/bangladeshboat/statuses/413892132" title="At Daulatdia ferry terminal expecting bad weather as cyclone in the Bay of Bengal heads north. (on Twitter)">At Daulatdia ferry terminal expecting bad weather as cyclone in the Bay of Bengal heads north.</a>
      </dt>
      <dd class="date">
          <abbr class="published" title="2007-11-14T19:18:22+06:00">about 3 hours ago</abbr>
      </dd>
      <dd class="location">
        <abbr class="geo point-16" title="+23.77083;+89.78509">Daulatdia, Bangladesh</abbr>
      </dd>
    </dl>
  </li>
</ol>

      • Notes

        • Most of the returned data should be self-explanatory, having read the parameter descriptions above.
        • The timestamp is the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT). Note that JavaScript uses milliseconds for Date objects - so remember to multiply by 1000.
        • The truncated property indicates whether a post description has been truncated. In theory, you may need to use the Flickr API to retrieve a post's full description. In practice, however, none of the posts are likely to have truncated = true.
        • The order property on bbcDiary posts relates to the ordering of that post on the Bangladesh River Journey site. This order is editorially selected for the site by the BBC and may not relate to the publication date.

  4. Greasemonkey Remixes

    Do you want to tweak the original mashup, instead of creating a totally new one?

    Greasemonkey is an extension for the browser. It lets you write JavaScript for specific web pages (in this case, the Bangladesh River Journey) and allows you to interact with the DOM to perform all sorts of voodoo wizardry...

    Greasemonkey scripts can use Ajax to introduce external content into the page. Unlike standard JavaScript, you can use Ajax to contact any server, not just the one that served the web page.

    An example Greasemonkey script is , which adds content to BBC News pages.

    Greasemonkey API

    The JavaScript for the River Journey site includes an abundance of Greasemonkey filters to make it even easier to interact with. Take a look at the JavaScript source code and look for calls similar to:
    applyFilters(filterName, payload).

    For example, within the function Waypoint.createIcon, you'll see: 

    icon = applyFilters('waypointCreateIcon', icon, this);

    Any function in a Greasemonkey script that is registered to the filter waypointCreateIcon will be passed the variables icon and the Waypoint object (this). Functions registered to this filter should return the first variable (icon), which will then be integrated into the main script.

    To register a function to a filter, simply send it through the method unsafeWindow.addFilter, returning the appropriate variable at the end of the function (though not all filters require a variable to be returned).

    For example, you could change the map marker icons with this code: 

    function changeIcon(icon, waypoint){
  icon.image = 'myImage.jpg';
  return icon;
}
unsafeWindow.addFilter('waypointCreateIcon', changeIcon);

    Prioritising Functions

    You can optionally add an argument priority (a Number) when registering a function. If more than one function is registered to the same filter, perhaps from a variety of different Greasemonkey scripts, the functions will be called in priority order, with the lowest numbers first. The argument can be positive or negative. The default is zero.

    In the following example, the function doThat would be called by the filter waypointShowPost first: 

    var addFilter = unsafeWindow.addFilter;

function doThis(){
  // do stuff
}
addFilter('waypointShowPost', null, 5);

function doThat(){
  // do stuff
}
addFilter('waypointShowPost', null, -30);