Fred van den Driessche

atlas schedule 4.0 api

Update, March 14th 2014: You can now create and manage your own Atlas API key. Read the instructions on our blog.

As Jonathan wrote on the discussion group a few days ago we have a small present for you all in the form of an alpha release of the Atlas version 4.0 schedule end-point. We’ve been writing about the various aspects of the work we’ve been doing on this front for a while now so it’s great to finally get an initial preview out for you all to have a look at.

show me the data

Let’s cut to the chase, here’s an example request for you to try:

http://atlas.metabroadcast.com/4.0/schedules/hkqs.json?source=pressassociation.com&from=2012-12-24T00:00:00.000Z&to=2012-12-25T00:00:00.000Z

There are a few things to notice about the response compared to the equivalent 3.0 schedule query, some more obvious than others:

  • There are far fewer fields returned by default. To get data about different aspects of the resources you’ll now need to request the fields you want explicitly: try adding “&annotations=channel.summary,content.summary” to the end of query above. The annotations from 3.0, which you can find on the API Explorer, should work all though you’ll need to prefix them with “content.“.

  • The resource structure has changed. Rather than requesting and filtering the schedule resource directly as in 3.0 you now request a sub-resource for a channel, for example schedules/hkqs provides the schedule for BBC One London. This means for now you can only request one channel at a time. Additionally, you can request a maximum of 24 hours at a time, down from 15 days in 3.0.

  • Press Association schedules without an API Key. Data for the previous and next week from the Press Association is now available without an API key for personal, non-commercial use.

One further thing to note is the support for simple content negotiation via the Accept header. In place of the .json extension you can specify Accept: application/json in your request headers. Currently only JSON is supported but other formats will be added in time.

life on the inside

We’ve fundamentally changed the way that we write out the responses in this new end-point. Previously we’ve copied the required fields from the internal data model to an output version known as the simple model then used a serialization framework such as gson or JAXB to write it out in a specific format.

We now serialize directly from the internal model. This provides much greater flexibility in two main regards:

  • A field will be supplied if and only if its relevant annotation is requested. If a field is requested but we have no data for it you’ll be able to determine that explicitly: the field will be present but with a null or empty value. Conversely, if the field is not active (because the required annotation is not requested) the field will be entirely absent.

  • The server-side is fully decoupled from the simple model so it can be moved in its entirety to the client-side. This should make working with Atlas server-side somewhat more, err, simple.

wrapping up

This is very much an alpha release, almost everything is subject to change, though the changes are likely to be small. We may give and we may take way. Again, just like the XMLTV feed, the data is for personal, non-commercial use but if you’d like to use if for anything else please don’t hesitate to get in touch.

One thing we’ll be working on next is generating IDs for the content in Atlas to replace all the nulls you can see currently. We’ll also be looking at releasing a 4.0 channels resource soon to make it easier to find schedules for other channels. Incidently, some other channel IDs include: hkrh (BBC Two England), hkvp, (ITV1 London), hkvb (Channel 4) and hkvh (Channel 5); working out the others are left as an after-dinner puzzle for the reader.

Please let us know your feedback and how we can make it even better, either in the comments or on the discussion group.

blog comments powered by Disqus