Meta Broadcast

we write about the things we build and the things we consume

taking our new atlas api explorer for a spin

Written by Liam Green-Hughes on 26 Jun 2012

If you have had a fantastic idea for a new product that can make use of Atlas, our audio and video metadata index, we understand that the last thing you would want to do is to spend hours reading documentation before you can get on with building it. So to make it easier to get started with Atlas we built an API Explorer (below) which aims to help you understand how to use Atlas and the results it returns in roughly the time it takes to have a cup of tea.

I've been working on updating the API Explorer to incorporate the latest features of Atlas. It can be found at: http://atlas.metabroadcast.com/#apiExplorer. The first thing you will notice is that there is a box for an API key. Don't worry if you haven't got an API key, Atlas is still a rich source of data without one.

The API Explorer is designed to function as interactive documentation. You can quickly see the various endpoints that the API offers and the parameters that they need. To make things as easy as possible we have included documentation not only on what the endpoints are for but also for each parameter. Where appropriate we have also included some default values. On the Schedule tab you will see that all of the parameters are populated, so why not go ahead and click Run!

After the results are returned from the API you can see the outcome of your call in the Response section. The default view is a JSON representation, but other formats are available, as well. Scrolling through the results you can quickly note the structure (see the information above the API Explorer for an explanation) and information in the data returned by Atlas. You will also notice that you didn't have to write a single line of code to get started!

The aim of the API Explorer is to enable users and potential users to learn about, and take Atlas for a ride in one easy to use place. We've noticed with some API explorers that they do not incorporate documentation on what endpoints are for, and information about the parameters needed. For example, the Explore the Twitter API console provides a handy way to test out API calls, but you have to look elsewhere to find out what each endpoint does, and the parameters needed. We've tried to avoid this by incorporating the information you need right into the API Explorer with the hope that this will enable you to understand the API in a shorter time.

If you have used the API explorer in the past you will have noticed some new endpoints have been added. One of these is Content Groups. Such groups exist for all sorts of reasons, they might be a curated collection, a playlist of related items or maybe a broadcast season. If you click on Run by the GET /content_groups.json you will see some examples of content groups returned. A good specific example is the collection “Early Films” from the UK public arts project The Space. If you take the id property (which we use to identify an item in Atlas) from from the entry for the collection (in this case "cbbp") and put it in the id parameter box for GET /content_groups/:id (shown below) and click Run you will see links to some of the early work of noted British film directors including Ridley Scott.

Atlas can help you pinpoint content related to a specific topic. Say you want to watch a programme about zebras, one way to do this might be to do a search, but then you might get results returned to do with Zebra Crossings or Ice Station Zebra—not what you were after. Atlas solved this problem with its topics endpoint. To get the content we need takes only two steps: finding the id for a topic and then using that to get related content.

Go to the GET /topics/json (shown above) section and enter “dbpedia” for the namespace and “http://dbpedia.org/resource/Zebra” for the topic (this is the DBPedia entry for a Zebra, you can take the end part of Wikipedia URLs to work out DBPedia URLs). Click Run and you should see some details returned including an ID. Copy that ID to the GET /topics/:id/content.json id parameter box and click Run. You should now see some content specifically related to Zebras the animal rather than any other type of Zebra.

Zebras aside, hopefully this post has been a useful guided tour of some of the new features of the API Explorer. We believe it will prove to be a very useful interactive documentation tool and make it easy to start using Atlas. Why not take it for a spin today and tell us what you think?

blog comments powered by Disqus

blog

• 21 May 2013 - a sense of identity in atlas
• 20 May 2013 - the pursuit of metappiness: the makeover, or dealing with a growing team
• 20 May 2013 - taking transmedia to the next level
• 15 May 2013 - atlas release notes - week to 14th may
• 15 May 2013 - mongodb: beware the scan and order

archivefeed

metabroadcast