New JSON format for the Google Calendar API

Wednesday, September 29, 2010 | 4:55 PM

Labels: , ,

It’s been almost four years since the Calendar API has supported the JSON format. However, our existing JSON format isn’t perfect. It is very much an automatic translation from our Atom format and as a result it is very wordy and lacks the elegance that a native JSON dialect would offer. It also supports only read operations.

We have made our new JSON implementation cleaner, simpler and closer to what you would expect from JSON. For example, the long XML namespace prefixes are no more, and we've removed many pieces of metadata specific to Atom documents that come across as noise in JSON, making it easier to parse.

We’re calling this new format JSON-C. One of the major advantages of the JSON-C format, besides being read-write and more readable than the former JSON implementation, is that it is more compact than the Atom based format. Below is an example:

Creating an event using JSON-C

POST /calendar/feeds/default/private/full HTTP/1.1
Host: www.google.com
Authorization: ...
Content-Type: application/json
GData-Version: 2.0
Content-Length: 233

{
"data": {
"title": "Tennis with Beth",
"details": "Meet for a quick lesson.",
"transparency": "opaque",
"status": "confirmed",
"location": "Rolling Lawn Courts",
"when": [
{
"start": "2010-04-17T15:00:00.000Z",
"end": "2010-04-17T17:00:00.000Z"
}
]
}
}

Creating an event using Atom

POST /calendar/feeds/default/private/full HTTP/1.1
Host: www.google.com
Authorization: ...
Content-Type: application/atom+xml
GData-Version: 2.0
Content-Length: 571

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'>
<category scheme='http://schemas.google.com/g/2005#kind'
term='http://schemas.google.com/g/2005#event'/>
<title type='text'>Tennis with Beth</title>
<content type='text'>Meet for a quick lesson.</content>
<gd:transparency value='http://schemas.google.com/g/2005#event.opaque'/>
<gd:eventStatus value='http://schemas.google.com/g/2005#event.confirmed'/>
<gd:where valueString='Rolling Lawn Courts'/>
<gd:when startTime='2006-04-17T15:00:00.000Z' endTime='2006-04-17T17:00:00.000Z'/>
</entry>
In the example above the body of the request is 59% smaller in JSON-C than in Atom. If you use gzip compression, the saving is still 37% of the size of the Atom body. This could make a big difference in mobile or other bandwidth-constrained environments.

To retrieve events or other data in the JSON-C format, you have to specify the ‘alt’ URL parameter with the value ‘jsonc’ as shown below:

Requesting an event in JSON-C

GET /calendar/feeds/default/private/full/1234567890?alt=jsonc HTTP/1.1
Host: www.google.com
Authorization: ...
GData-Version: 2.0

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
...
{
"apiVersion": "2.3",
"data": {
"title": "Tennis with Beth",
"details": "Meet for a quick lesson.",
"location": "Rolling Lawn Courts",
...
}
}
For the request above, the body of the response is 53% smaller in JSON-C than in Atom - 30% smaller when using gzip compression.

To learn more about our new JSON-C format please read our updated Developer’s Guide. Have fun!

Want to weigh in on this topic? Discuss on Buzz

3 comments:

SNL Bailout said...

This update seems to have broken the exportFormat=html or maybe it's just coincidence?

Either way it seems to have broken for both the Calendar API and Google Docs

See open issue #300 for googlecl here

Simone said...

I'm sorry, this surely is the wrong place to ask for support, but on the official support forums nobody could help me so far...

Can somebody explain me why this calendar http://www.stellarivoli.it/Pages/Season_iCal.ashx, when imported in google calendar, is shown with the wrong name? The tag X-WR-CALNAME is being totally ignored and I can't figure out why.

I apologize for bothering you.

Thanks, bye!

Sapres Centauri said...

Is there a way to add input from PHP into JSON so that it updates the calendar automatically?

I have a form that gets filled out, PHP processes the form and send a notification out. How can I turn the PHP processed data (date, event) to work with JSON