Content-api build 524 released: adds date refinements, story packages and video encodings

[Stephen Wells]

We have released build 524 of the content api to http://content.guardianapis.com. This includes the following changes:

Date refinements:

It is now possible to refine searches by date as well as by tag and section. To enable date refinements add a "show-refinements=date" parameter (or show-refinements=all) to your search request. The date refinements will indicate the number of items that were published in the following date spans:

• today
• yesterday
• last 7 days
• last 30 days
• each distinct year we have matching content for (2010, 2009 ...)

The api url each date refinement sets the from-date and to-parameters to constrain your search

from-date and to-date support time:

The from-date and to-date parameters support an optional time. To specify a date with time add a "T" followed by the time formatted as HH24:mm:ss.

For example to find all items published before 2pm on the 15th of October 2010 then use the following url:

http://content.guardianapis.com/search.json?to-date=2010-10-15T14:00:00

Story packages:

Story packages are bundles of content that are about the same story. For example for today's top story, prince William's engagement, we bundle together an editorial piece, a rolling live blog, a gallery, a poll and a profile of Kate Middleton. If you visit any of these pages on the guardian site you can see the package to the right hand side of the content with the heading "More on this story".

We have added these story packages into the api. To view the package associated with a story visit the item endpoint for the story and add the "show-story-package=true" parameter to the request:

http://content.guardianapis.com/uk/2010/nov/16/prince-william-kate-middleton-engagement.json?show-story-package=true

All the usual show-fields and show-tags etc. parameters are supported and configure how the package content is returned.

The contents of the story package are only available in the item endpoint, however we have added a new field on content to indicate that the story has a story package. this field is called "has-story-package" and can be accessed using the show-fields parameter in the usual way.

Video encodings:

The video media assets have been expanded to include a list of different formats for the video. This allows our partners to choose the transcoding of the video that is most appropriate for their application. An example of the video asset JSON is as follows:

{

"type": "video",

"rel": "body",

"index": 1,

"file": "...",

"fields": {

"source": "guardian.co.uk",

"embeddable": "false",

"durationSeconds": "58",

"height": "360",

"thumbnail": "...",

"durationMinutes": "2",

"stillImageUrl": "...",

"width": "480",

"blockAds": "true"

},

"encodings": [

{

"format": "mp4",

"file": "...mp4"

},

{

"format": "m3u8",

"file": "...m3u8"

}

]

}

See the content api explorer for an exmaple of the xml.

Please note that the video encoding is currently work in progress and the vast majority of videos are only available in mp4 format.

As always, please give your feedback on this list or mail openpl...@guardian.co.uk.

    Stephen Wells

Please consider the environment before printing this email.
------------------------------------------------------------------
Visit guardian.co.uk - newspaper website of the year
www.guardian.co.uk  www.observer.co.uk

To save up to 33% when you subscribe to the Guardian and the Observer
visit http://www.guardian.co.uk/subscriber

---------------------------------------------------------------------

This e-mail and all attachments are confidential and may also
be privileged. If you are not the named recipient, please notify
the sender and delete the e-mail and all attachments immediately.
Do not disclose the contents to another person. You may not use
the information for any purpose, or store, or copy, it in any way.

Guardian News & Media Limited is not liable for any computer
viruses or other material transmitted with or as part of this
e-mail. You should employ virus checking software.

Guardian News & Media Limited

A member of Guardian Media Group plc
Registered Office
PO Box 68164
Kings Place
90 York Way
London
N1P 2AP

Registered in England Number 908396

[Graham Tackley]

On Nov 16, 2:51 pm, Stephen Wells <stephen.we...@guardian.co.uk>
wrote:
> We have released build 524 of the content api tohttp://content.guardianapis.com. This includes the following changes:
> ...
>
> *from-date and to-date support time:*

>
> The from-date and to-date parameters support an optional time. To specify a
> date with time add a "T" followed by the time formatted as HH24:mm:ss.
>
> For example to find all items published before 2pm on the 15th of October
> 2010 then use the following url:
>
> http://content.guardianapis.com/search.json?to-date=2010-10-15T14:00:00
>

> ...

Just to clarify this a little, as date and date time handling always
seems to cause confusion.

The content API always reports dates in ISO 8601 format, normalised to
our local timezone here in London, UK. So they normally end in "Z" in
winter time (when we're on GMT/UTC) and end in "+01:00" in summer time
when we're on UTC+1. This is true both for XML and json.

The from-date and to-date parameters support either just a date or a
date and time (with optional time zone).

1. If you specify just a date (e.g. 2010-07-20) this is interpreted as
"midnight london local time at the start of 2010-07-20" for the from-
date, and for the to-date as "one millisecond before midnight london
local time at the start of 2010-07-21".

2. If you specify a date and time without any timezone information (as
in Stephen's example 2010-10-15T14:00:00) this is interpreted as
london local time, in this case 2pm UTC. Note that when summer time
applies in the UK, times specified like this are interpreted as UTC+1.
So 2010-07-20T14:00:00 means 1pm UTC.

3. To avoid any confusion, specify the date and time with a time zone
in standard ISO 8601 format, i.e. Z (for UTC) or +/-HH:MM. You can
specify this in your local time zone, which we should convert
correctly. Note that dates and times in responses are always uk time
zone based, as noted above. (NB: if you're hacking the url in your
browser, remember that it will interpret "+" as a space, use "%2B"
instead.) So a from-date=2010-07-20T01:00:00-08:00&order-by=oldest
representing 1am PST on 20 July 2010 returns content with a web
publication date of 2010-07-20T10:00:44+01:00 as its first result -
the first item after 9am UTC (or 10am British Summer Time which is UTC
+1).

Hope this helps. Please post to this list if it doesn't seem to be
working correctly for you.

Oh, and I notice we haven't updated the api explorer yet to support
date-times for these fields, sorry, we'll try to do this in the next
few days.

Cheers
g

[1] http://en.wikipedia.org/wiki/ISO_8601