Admin SDK

Google Apps Calendar Resource API

The Google Apps Calendar Resource API allows Google Apps administrators to retrieve and manage the Google Calendar resources of their domains in the form of Google Data API feeds.

You can add resources that users in your domain will be able to schedule on their calendars, such as conference rooms, projectors, or company vehicles.

The Google Apps Calendar Resource API supports the Google Data API protocol. The Google Data API conforms to the Atom Publishing Protocol (AtomPub) publishing and editing model. The AtomPub HTTP requests use the Representational Set Transfer (RESTful) design approach to web services. For more information, see the Google Data APIs Overview.



Audience

This document is intended for programmers who want to write client applications that can modify and retrieve information about their domain's Google Calendar resources. It provides examples of the basic Calendar Resource API interactions using raw XML and HTTP.

This document assumes that you understand the general ideas behind the Google Data API protocol, and that you are familiar with administering Google Calendar resources. For more information about creating a calendar resource in the control panel, see Scheduling calendar resources.

Getting Started

Creating an account

The Google Apps Calendar Resource API is enabled for the Google Apps for Business and Education. You may want to sign up for a Google Apps for Business account for testing purposes. For more information about which APIs are enabled for each Google Apps product version, see the Google Apps APIs Getting Started.

Developing a naming strategy for your calendar resources

When you are creating and updating a calendar resource, you need a flexible naming strategy for your resource names, descriptions, and categories. Descriptive resource information helps users schedule the resource, and helps calendar administrators manage resources over time. We have assembled a few suggestions to consider when building your resources:

  • Resource ID -- This resource ID is used in every API request. If the resource is created within the control panel, this ID is a series of random numbers. But, when created within the API, you can use your own naming convention to create an ID name that is easier to reference and use. These names are subject to the same rules as any Google Apps user name:

    • The maximum length is 100 characters. The minimum length is 1 character.
    • The resourceId can not begin with a dot. Nor can the name have more than one consecutive dot. An example of an incorrect resourceId is .CR..NYC
    • The legal characters include: 'a' through 'z', 'A' through 'Z', '0' through '9', '.', '-', '_'
    • A suggested naming pattern is: [resource type]-[city]-[building]-[floor or location]-[name]-[optional information]
      • CR-NYC-14-12-BR
        This conference room is in New York city, building 14, floor 12, room initials BR (Boardroom).
      • CAM-PARIS-L-CAMCORD-HD-2
        This is the camera in your Paris office building's lobby. It is the high definition camcorder, specifically camera number 2.
  • Resource common name -- In the calendar user interface, the common name is the name seen by the user when selecting from a calendar's resource list. The common name has to be easy to find, give enough information for a decision, but remain short and concise in the list. Use consistent naming and punctuation when organizing these resources so that the resources can be managed and physically located. A resource common name is limited to 100 characters. Note, the above resource IDs are in capital letters, and the resource common names are mixed-case.

    Since conference rooms are the most common resource, this example includes a special conference room recommendation which groups your conference room listings together.

    • The suggested pattern for a conference room is: [city]-[building]-[floor or location]-[optional, resource specific information]
      • NYC-14-12-Boardroom-15-VC
        This conference room is in New York city in building 14, on floor 12. The room's name is Boardroom which holds 15 people and has video conferencing equipment.
    • The suggested pattern for a general resource type is: (resource type)-[city]-[building]-[floor or location]-[optional, resource specific information]
      • (Guest Office)-Tokyo-44-2-245C
        This guest office in Tokyo is in building 44 on the second floor. It is office number 245, and, of all of the desks in this office, this guest is specifically reserving desk 'C'.
      • (Bike)-London-43-Lobby-Bike-1
        This bicycle is in London at building 43's lobby. This is 'Bike 1' (rather than 'Bike 2' or 'Bike 3').
      • (Vehicle)-LA-Chrevrolet-Main-North-4
        This vehicle is in Los Angeles. It is a Chrevrolet parked at the Main building in the North parking lot in parking space 4.
      • (Camera)-Paris-Lobby-Camcorder-HD-2+tripod+batteries
        This camera is kept in the Paris office's lobby. It is the high definition camcorder, camera number '2'. It includes a tripod and batteries.
  • Resource description -- This summary answers the question, "What additional information do I need other than this resource's name, and where it is located?" For example: contact information or special instructions. A resource description is limited to 1,000 characters.

  • Resource type -- A resource type is found by asking the question, "What are my resource categories?" For example: conference rooms, guest offices, phone rooms, bikes, vehicles, cameras, projectors, shared servers, basketball courts, bulldozers, etc. The resource type name is limited to 100 characters.

Creating a new calendar resource

To create a calendar resource, use the following POST request:

POST https://apps-apis.google.com/a/feeds/calendar/resource/2.0/{domain name}/

The following table shows the properties to be set when creating a calendar resource.

Name XML attribute Example XML value Description Possible values
resourceId name="resourceId" value="CR-NYC-14-12-BR" The unique name for the resource any string up to 100 characters
resourceCommonName name="resourceCommonName" value="Boardroom" The resource name seen by users in a calendar's resource list any string up to 100 characters
resourceDescription name="resourceDescription" value="This conference room is in New York city, building 14, floor 12, Boardroom" The brief summary of the resource to be shown in the control panel any string up to 1,000 characters
resourceType name="resourceType" value="CR" The type is a general category common to several resources any string up to 100 characters
  • We recommend standardizing on a naming strategy that makes it easy to remember this resource ID. For naming suggestions and additional naming rules, see Developing a naming strategy for your calendar resources.
  • When a resource is created in the control panel, the resourceId is a series of numbers.
  • The only required property is resourceId, all other fields are optional.
  • Resource hierarchies are automatically created when three of more resources are added with the same first three characters in their common name. In the calendar resource list, these hierarchies occur when the calendar resource list begins to scroll and the immediate screen is full with several resources.

Calendar Resource Creation Examples

Example 1

  • The domain is example.com.
  • The resourceId is CR-NYC-14-12-BR.
  • The resourceCommonName is Boardroom.
  • The resourceDescription is Conference room in New York city, building 14, floor 12, Boardroom.
  • The resourceType is CR.

Protocol

POST https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/

<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name='resourceId' value='CR-NYC-14-12-BR'/>
  <apps:property name='resourceCommonName' value='Boardroom'/>
  <apps:property name='resourceDescription' value='Conference room in New York city, building 14, floor 12, Boardroom'/>
  <apps:property name='resourceType' value='CR'/>
</atom:entry> 

Python

from gdata.calendar_resource.client import CalendarResourceClient
...

client = CalendarResourceClient(domain='example.com')
client.ClientLogin(email='admin@example.com', password='p@55w0rd', source='example-appname-v1')

new_calendar_resource = client.CreateResource(
    resource_id='CR-NYC-14-12-BR',
    resource_common_name='Boardroom',
    resource_description='Conference room in New York city, building 14, floor 12, Boardroom',
    resource_type='CR')

.NET

using Google.GData.Apps;
using Google.GData.Client;
using Google.GData.Extensions;
using Google.GData.Extensions.Apps;
...

CalendarResourceService service = new CalendarResourceService("example.com", "your-apps");
service.setUserCredentials("adminUsername", "adminPassword");

AppsExtendedEntry entry = service.CreateCalendarResource(
    "CR-NYC-14-12-BR",
    "Boardroom",
    "Conference room in New York city, building 14, floor 12, Boardroom",
    "CR");

Retrieving calendar resources

Retrieving a single calendar resource

To create a calendar resource, send the following GET request to the resource ID's feed URL. Include the Authorization header as described in Authenticating:

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/{domain name}/{resourceId}/

A successful response returns an HTTP 200 status code from the Google Data API status codes.

The response entry element returns the same properties used when creating a resource along with the calendar's encoded resourceEmail property:

resourceEmail

The resource email address is the public address used to view and reserve this resource in a calendar. The system's naming convention for resourceEmail is <domain name>_nnn...@resource.calendar.google.com. This is the ID in a calendar's Calendar Details page's Calendar Address section. Your calendar must be public for others to use this calendar address.

Retrieving all calendar resources

The API's XML feed uses pagination for results listing more than 100 calendar resources. For a large response, each page of results returns a maximum of 100 entries, and includes a URI in a <link rel='next'...> tag pointing to the next page of results. When developing your client application, your code needs to manage these additional results.

To retrieve the first page of resource entries associated with a particular calendar, send an HTTP GET request ending with a forward slash to a resource feed URL. Include the Authorization header as described in Authenticating.

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/{domain name}/

Optionally, you can send an HTTP GET request with an empty string in the start parameter to a resource feed URL.

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/{domain name}/?start=""

A successful response returns an HTTP 200 status code from the Google Data API status codes.

If the domain has over 100 resources, the response includes a next URI of the next page of results:

<link rel="next" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/calendar/resource/2.0/domainName/?start=the next page's first resourceId>

To retrieve these additional pages, use the next URI in your subsequent GET requests to retrieve all of your calendar resources:

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/{domain name}/?start=the next page's first resourceId

Calendar Resource Retrieval Examples

Example 1, Retrieving a single calendar resource

  • The domain is example.com.
  • The resourceId is CR-NYC-14-12-BR.

Protocol

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR

<entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR</id>
    <updated>2008-10-17T15:19:46.467Z</updated>
    <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR'/>
    <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR'/>
    <apps:property name='resourceId' value='CR-NYC-14-12-BR'/>
    <apps:property name='resourceCommonName' value='Boardroom'/>
    <apps:property name='resourceEmail' value='domain_123456@resource.calendar.google.com'/>
    <apps:property name='resourceDescription' value='This conference room is in New York city, building 14, floor 12, Boardroom'/>
    <apps:property name='resourceType' value='CR'/>
</entry>

Python

from gdata.calendar_resource.client import CalendarResourceClient
...

client = CalendarResourceClient(domain='example.com')
client.ClientLogin(email='admin@example.com', password='p@55w0rd', source='example-appname-v1')

calendar_resource = client.GetResource(resource_id='CR-NYC-14-12-BR')

.NET

using Google.GData.Apps;
using Google.GData.Client;
using Google.GData.Extensions;
using Google.GData.Extensions.Apps;
...

CalendarResourceService service = new CalendarResourceService("example.com", "your-apps");
service.setUserCredentials("adminUsername", "adminPassword");

AppsExtendedEntry entry = service.RetrieveCalendarResource("CR-NYC-14-12-BR");

Example 2, Retrieving all calendar resources

  • The domain is example.com.

Protocol

GET https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/

<feed xmlns:atom='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:apps='http://schemas.google.com/apps/2006'>
   <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com</id>
   <updated>2008-10-17T15:29:21.064Z</atom:updated>
   <link rel='next' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/?start=the next resourceId'/>
   <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com'/>
   <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com'/>
   <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com?start=CR-NYC-14-12-BR'/>
   <openSearch:startIndex>1</openSearch:startIndex>
   <entry>
      <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR</id>
      <updated>2008-10-17T15:29:21.064Z</updated>
      <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR'/>
      <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR'/>
      <apps:property name='resourceId' value='CR-NYC-14-12-BR'/>
      <apps:property name='resourceCommonName' value='Boardroom'/>
      <apps:property name='resourceEmail' value='domain_123456@resource.calendar.google.com'/>
      <apps:property name='resourceDescription' value='This conference room is in New York city, building 14, floor 12, Boardroom'/>
      <apps:property name='resourceType' value='CR'/>
   </entry>
   <entry>
        <id>https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/?start=(Bike)-London-43-Lobby-Bike-1</id>
        <updated>2008-10-17T15:29:21.064Z</updated>
        <link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/(Bike)-London-43-Lobby-Bike-1'/>
        <link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/(Bike)-London-43-Lobby-Bike-1'/>
        <apps:property name='resourceId' value='(Bike)-London-43-Lobby-Bike-1'/>
        <apps:property name='resourceCommonName' value='London bike-1'/>
        <apps:property name='resourceEmail' value='domain_123457@resource.calendar.google.com'/>
        <apps:property name='resourceDescription' value='Bike is in London at building 43's lobby.'/>
        <apps:property name='resourceType' value='(Bike)'/>
    </entry>
</feed>

Python

from gdata.calendar_resource.client import CalendarResourceClient
...

client = CalendarResourceClient(domain='example.com')
client.ClientLogin(email='admin@example.com', password='p@55w0rd', source='example-appname-v1')

calendar_resources = client.GetResourceFeed()

.NET

using Google.GData.Apps;
using Google.GData.Client;
using Google.GData.Extensions;
using Google.GData.Extensions.Apps;
...

CalendarResourceService service = new CalendarResourceService("example.com", "your-apps");
service.setUserCredentials("adminUsername", "adminPassword");

AppsExtendedEntry entry = service.RetrieveAllCalendarResources();

Updating a calendar resource

To update a calendar resource, send a PUT request to a resource ID's feed URL. Include the Authorization header as described in Authenticating.

PUT https://apps-apis.google.com/a/feeds/calendar/resource/2.0/{domain name}/{resourceId}/

You can update the resourceCommonName, resourceDescription, and resourceType properties.

Calendar Resource Update Examples

Example 1

  • The domain is example.com.
  • The resourceId is CR-NYC-14-12-BR.
  • The new resourceCommonName is new common name.
  • The new resourceDescription is new description.
  • The new resourceType is new type.

Protocol

PUT https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'>
    <apps:property xmlns:apps='http://schemas.google.com/apps/2006' name='resourceCommonName' value='new common name'/>
    <apps:property xmlns:apps='http://schemas.google.com/apps/2006' name='resourceDescription' value='new description'/>
    <apps:property xmlns:apps='http://schemas.google.com/apps/2006' name='resourceType' value='new type'/>
</atom:entry>

Python

from gdata.calendar_resource.client import CalendarResourceClient
...

client = CalendarResourceClient(domain='example.com')
client.ClientLogin(email='admin@example.com', password='p@55w0rd', source='example-appname-v1')

updated_calendar_resource = client.UpdateResource(
    resource_id='CR-NYC-14-12-BR',
    resource_common_name='new common name',
    resource_description='new description',
    resource_type='new type')

.NET

using Google.GData.Apps;
using Google.GData.Client;
using Google.GData.Extensions;
using Google.GData.Extensions.Apps;
...

CalendarResourceService service = new CalendarResourceService("example.com", "your-apps");
service.setUserCredentials("adminUsername", "adminPassword");

AppsExtendedEntry entry = service.UpdateCalendarResource("CR-NYC-14-12-BR",
                                                         "new common name",
                                                         "new description",
                                                         "new type");

Deleting a calendar resource

To delete a calendar resource, send a DELETE request to a resource ID's feed URL. Include the Authorization header as described in Authenticating.

DELETE https://apps-apis.google.com/a/feeds/calendar/resource/2.0/{domain name}/{resourceId}

A successful response returns an HTTP 200 status code from the Google Data API status codes. The XML body of a successful response to a DELETE request is empty.

Calendar Resource Delete Examples

Example 1

  • The domain is example.com.
  • The resourceId is CR-NYC-14-12-BR.

Protocol

DELETE https://apps-apis.google.com/a/feeds/calendar/resource/2.0/example.com/CR-NYC-14-12-BR

Python

from gdata.calendar_resource.client import CalendarResourceClient
...

client = CalendarResourceClient(domain='example.com')
client.ClientLogin(email='admin@example.com', password='p@55w0rd', source='example-appname-v1')

client.DeleteResource(resource_id='CR-NYC-14-12-BR')

.NET

using Google.GData.Apps;
using Google.GData.Client;
using Google.GData.Extensions;
using Google.GData.Extensions.Apps;
...

CalendarResourceService service = new CalendarResourceService("example.com", "your-apps");
service.setUserCredentials("adminUsername", "adminPassword");

AppsExtendedEntry entry = service.DeleteCalendarResource("CR-NYC-14-12-BR");

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.