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!

Posted by Nicolas Garnier, Google Calendar API Team

Want to weigh in on this topic? Discuss on Buzz