google calendar api: calendars vs calendarList

Question

I was messing around trying to add a new calendar and it took me quite a while to figure out that I had to add it to 'Calendars' and not to 'CalendarList'. It works now, which is nice, but I what is the difference between the two concepts? It seems to me I only need Calendars? Also, CalendarList doesn't seem to work, trying to insert a Calendar returned a 404 error.

Answer 1

Calendars is a collection of all calendars in the world (it does not have a list method). When creating a new calendar, you should call an insert on the calendars collection. When you want calendar specific data (such as the timezone, the name) then you should retrieve a calendar from calendars collection using get.

CalendarLists is a collection of all calendar entries that a user added to their list (in the web UI it's the list of calendars in the left panel). You cannot create a new calendar through the calendar list collection but you can add an existing calendar to the list of your users calendars. Each user can for example have a different color for the same calendar and this detail will be stored in the calendar list entries.

What is sometimes confusing is that when you create a new calendar through calendars collection, it will be automatically added to your list.

Let me give you an example of how Calendars and CalendarLists work. Imagine your friend creates a calendar for a trip that you will be going on together. He does so by doing a Calendars.insert() call. Now he makes the calendar public (via ACLs collection) and sends you and all the friends an email of this calendar. You can go into the CalendarLists collection and do an insert() call there to add it into your list of calendars and make it blue.