Full API Reference

This is an attempt to fully document all the functions, objects and attributes of the Atlas API. Shout if we’ve missed anything.

Functions


In a Atlas API call:
http://atlasapi.org/2.0/brands.json?brand.uri=http://www.bbc.co.uk/programmes/b00jnwlc

The brands part of the URL determines what collection of information you are filtering over. These can either be items, playlists or brands.

Items

Searching against /items encapsulates both episodes and items, including both episodic pieces of content and one-offs. Episodes will also contain a summary of the its parent Brand.

Queries


Playlists

Searching against /playlists encapsulates both playlists and brands, including both established series of episodes, and randomly constructed lists.

Querys


Brands

Brands are a specialisations of Playlists and contain only Episodes. All of the queries available for Playlists apply to Brands, plus some more interesting ones, but will only return Brands that match.

Querys


Common Query Parameters

Additionally, there are query parameters that can be applied to all queries.

Limit and offset

limit and offset can be applied to any query to help paginate through the results. Take title searches, for example, can result in rather a lot of results. Here is how you’d paginate through them:


Integer Operators

There are common filter operators that can be applied to any integer queries:


Date Operators

There are common filter operators that can be applied to any date queries:


Output Objects and Attributes

As mentioned in the Data Model there are two output objects: Items and Playlists. This section will document their attributes in full.

Items

Items can be contained in Playlists, or stand on their own (by requesting either /playlists or /items). They also contain Locations, which describe the ways you can get to the actual media for a piece of content.

  • uri: the canonical URI of a piece of content – http://www.bbc.co.uk/programmes/b007tk0k
  • curie: the namespaced unique identifier – bbc:b007tk0k
  • aliases: any known URLs that point at the canonical URI, these can be from url-shortening services, Facebook ‘like’ pages, whatever
  • title: the title
  • description: the description
  • publisher: the code used for the publisher, which is usually the hostname – bbc.co.uk or channel4.com
  • image: an image for the item
  • thumbnail: a thumbnail which will often be the same as the image, only smaller
  • genres: a list of genre URIs, containing both external and internal representations – http://ref.atlasapi.org/genres/atlas/comedy

There are 2 types of genres, both internal Atlas ones and external ones. When Atlas finds an Item that has an external genre defined, it will add its own equivalent genre, so that you can query on either.

So, if Atlas comes across the Channel 4 genre: 

http://www.channel4.com/programmes/tags/comedy
it will additionally add: 
http://ref.atlasapi.org/genres/atlas/comedy

  • tags: a list of tag URIs – http://ref.atlasapi.org/tags/aardman
  • containedIn: a list of playlist URIs that this item is contained in – http://www.bbc.co.uk/programmes/b0080bbs
  • locations: a list of Location objects (defined below) that describe the media associated with this item
  • episodeNumber: for episodic items, the episode number
  • seriesNumber: for episodic items, the series number
  • brand: for episodic items, a summary playlist object that contains the brand’s uri, curie, title and description

Locations

Locations describe where the media for their parent Item can be found and how to access it. An Item can have many different Locations as it can be encoded for various devices and available in different ways in different countries.

  • duration: duration in seconds of a piece of media
  • publishedDuration: the published duration in seconds, as this is often different to the actual duration
  • rating: a URI that represents the the rating (whether it contains adult content)
  • ratingText: a description of the rating classification
  • transmissionTime: the date and time of when it was transmitted
  • advertisingDuration: length, in seconds, of the advertising contained
  • audioBitRate: integer value for the bit rate of the audio encoding, in kbits/sec
  • audioChannels: integer value for the audio channels
  • audioCoding: the audio mime-type, like ‘ogg’ or ‘mp3’
  • bitRate: integer value for the average bitrate, in kbits/sec
  • containsAdvertising: whether the media contains advertising or not
  • dataContainerFormat: mime-type for the data container format
  • dataSize: numeric value for the size of the data
  • distributor: code for the distributor
  • hasDOG: whether the media includes a significant Digital Onscreen Graphic throughout the majority of playtime (the logo of the broadcast channel)
  • source: how this data was orignially distributed (e.g., DVB-S)
  • videoAspectRatio: the aspect ratio (e.g., 16:9)
  • videoBitRate: the video bit rate, in kbits/sec
  • videoCoding: the video encoding scheme MIME type, e.g., video/H264
  • videoFrameRate: number of frames per second
  • videoHorizontalSize: number of horizontal pixels
  • videoProgressiveScan: whether the video has progressive scan
  • videoVerticalSize: number of vertical pixels
  • availabilityStart: the date and time when the media becomes / became available
  • drmPlayableFrom: the first time at which DRM will not attempt to stop playback of this content
  • restrictedBy: URI of a policy that describes how the media is restricted
  • transportIsLive: whether the media transport is currently live
  • transportSubType: additional details about the transport type (e.g., HTTP or FTP)
  • transportType: the behaviour that can be expected from the Location URI

  • download: the content can be downloaded from the URI, at a speed faster than needed to watch the content
  • stream: the resource is fast enough to stream, but not download
  • embed: the URI points to an object that can be embedded in a web page
  • link: the URI points to a web page that has the content embedded
  • indirect: the URI points to further information at how to get to the content

  • uri: whether you can actually get the data
  • embedCode: the embed snippet that can be used to embed the media
  • available: whether the content is currently available

Playlists

Playlists are groupings of items and other playlists. These can either be structured Brands or random assortments.

  • uri: the canonical URI of a piece of content – http://www.bbc.co.uk/programmes/b0080bbs
  • curie: the namespaced unique identifier – bbc:b0080bbs
  • aliases: any known URLs that point at the canonical URI, these can be from url-shortening services, Facebook ‘like’ pages, whatever
  • title: the playlists’s title
  • description: the playlist’s description
  • publisher: the code used for the publisher, which is usually the hostname – bbc.co.uk or channel4.com
  • playlists: a list of child playlists that this playlist contains (say, if the current playlist is ‘mentioned on Twitter’, it might contain ‘Eastenders’)
  • items: a list of the items that the playlist contains, which will be episodic if the playlist is a brand

Formats

The available formats are JSON, XML, HTML, RDF.XML, ATOM, RSS, OEMBED.JSON and OEMBED.XML. That enough for you? To learn how the objects and attributes are encoded in the various formats, it’s worth seeing for yourself:


Sources

Atlas has adapters written for 10 or so different sources of content, all providing varying qualities of data.

Broadcasters

  • Hulu – Good source of US available on-demand videos
  • BBC – One of the most complete sources, with schedule and on-demand metadata for both video and audio
  • Channel 4 – Similar quality of video data, with a longer back-catalogue. Update: Unfortunately, the adapter has stopped bringing in fresh content as of July 22nd 2010.
  • ITV – Work in progress
  • Five – Coming soon


Video Sharing Services

  • YouTube – Good quality adapter
  • Blip.tv – Reasonable quality
  • Vimeo – Currently only getting the embeddable video, needs more work
  • Flickr – Similarly, needs more work
  • DailyMotion – Reasonable quality
  • TED – Reasonable quality

Reference Services

  • Wikipedia – Used to decorate content information or to fill gaps where no content can currently be found
  • Freebase – Used to derive equivalence between TV shows
  • IMDB – Uses DBpedia to get information on content using its IMDB ID

Atlas Is

  • The open-source, open-API index that gathers and stores video & audio information from 10+ sources, so that you can build cool apps swiftly
  • The way to learn all about a content link, or to find the content link itself

Atlas Does

  • Runs sophisticated title searches
  • Helps you get to content you can actually watch, like "I want to watch Glee and I am in the US"
  • Automatically produces all content lists needed for an online video service, from episodes in a brand to a-to-z lists and the current highlights
  • Stores all you expect: title, description, image, thumbnail, genres, tags and many ways to play it
  • Keeps an eye on Twitter, indexing all content mentions and what's currently hot
  • Next to web, finds mobile and TV friendly content
  • Lets you ask for content by time, like "What's on the BBC right now"
  • Outputs information in many different formats

Atlas Will

  • Figure equivalent content from different sources
  • Search across title, description, tags and genres
  • Add more and more sources, and improve and augment the data from the current ones