Manage Courses

A Course resource represents a class, such as "M. Smith's 4th period math," and its assigned teachers, student roster, and metadata.

Each course is identified by a unique ID assigned by the server. Additionally, names may be associated with a course and used in place of the unique ID. Each name, called an Alias, exists in a namespace that restricts who can create and view it.

Two namespaces are supported:

  • Domain: The domain namespace is useful for creating aliases that all users need access to, but that are not specific to any one program. For example, alternate listings for a course, such as MATH 127 and COMSCI 127, should be created in the domain namespace. Aliases in the domain namespace may only be created by domain administrators but are visible to all users in a domain.
  • Developer project: The developer project namespace is useful for managing aliases specific to an application. For example, an application that uses alternate identifiers for courses can create aliases to map its identifier to Classroom courses. Aliases created in this namespace are tied to a specific Google API Console project. Any user of an application can create and view aliases in the namespace for that application's developer project.

Create a course

You can add a course using the courses.create() method, as shown in the following sample:

.NET

            var course = new Course
            {
                Name = "10th Grade Biology",
                Section = "Period 2",
                DescriptionHeading = "Welcome to 10th Grade Biology",
                Description = "We'll be learning about about the structure of living creatures "
                    + "from a combination of textbooks, guest lectures, and lab work. Expect "
                    + "to be excited!",
                Room = "301",
                OwnerId = "me",
                CourseState = "PROVISIONED"
            };

            course = service.Courses.Create(course).Execute();
            Console.WriteLine("Course created: {0} ({1})", course.Name, course.Id);

Java

Course course = new Course()
        .setName("10th Grade Biology")
        .setSection("Period 2")
        .setDescriptionHeading("Welcome to 10th Grade Biology")
        .setDescription("We'll be learning about about the structure of living creatures "
                + "from a combination of textbooks, guest lectures, and lab work. Expect "
                + "to be excited!")
        .setRoom("301")
        .setOwnerId("me")
        .setCourseState("PROVISIONED");
course = service.courses().create(course).execute();
System.out.printf("Course created: %s (%s)\n", course.getName(), course.getId());

PHP

$course = new Google_Service_Classroom_Course(array(
  'name' => '10th Grade Biology',
  'section' => 'Period 2',
  'descriptionHeading' => 'Welcome to 10th Grade Biology',
  'description' => 'We\'ll be learning about about the structure of living ' .
                   'creatures from a combination of textbooks, guest ' .
                   'lectures, and lab work. Expect to be excited!',
  'room' => '301',
  'ownerId' => 'me',
  'courseState' => 'PROVISIONED'
));
$course = $service->courses->create($course);
printf("Course created: %s (%s)\n", $course->name, $course->id);

Python

course = {
    'name': '10th Grade Biology',
    'section': 'Period 2',
    'descriptionHeading': 'Welcome to 10th Grade Biology',
    'description': """We'll be learning about about the structure of living
                 creatures from a combination of textbooks, guest
                 lectures, and lab work. Expect to be excited!""",
    'room': '301',
    'ownerId': 'me',
    'courseState': 'PROVISIONED'
}
course = service.courses().create(body=course).execute()
print u'Course created: {0} ({1})'.format(course.get('name'),
    course.get('id'))

When you create a course, you can optionally add metadata such as the course description, time, or location.

In order to create a course, the user making the request must have the appropriate permissions in their user profile.

Courses are created with the courseState set to PROVISIONED by default; however, this can be overridden to ACTIVE. If the course is created in the PROVISIONED state, the teacher identified in the ownerId must accept the class in the Classroom UI or the course must be updated through the API to change the courseState to ACTIVE and make it available to their students.

Retrieve course details

You can retrieve a single course's metadata with the courses.get() method, as shown in the following sample:

.NET

string courseId = "123456";
Course course = null;
try
{
    course = service.Courses.Get(courseId).Execute();
    Console.WriteLine("Course '{0}' found\n.", course.Name);
}
catch (GoogleApiException e)
{
    if (e.HttpStatusCode == HttpStatusCode.NotFound)
    {
        Console.WriteLine("Course with ID '{0}' not found.\n", courseId);
    }
    else
    {
        throw e;
    }
}

Java

String courseId = "123456";
Course course = null;
try {
    course = service.courses().get(courseId).execute();
    System.out.printf("Course '%s' found.\n", course.getName());
} catch (GoogleJsonResponseException e) {
    GoogleJsonError error = e.getDetails();
    if (error.getCode() == 404) {
        System.out.printf("Course with ID '%s' not found.\n", courseId);
    } else {
        throw e;
    }
}

PHP

$courseId = '123456';
try {
  $course = $service->courses->get($courseId);
  printf("Course '%s' found.\n", $course->name);
} catch (Google_Service_Exception $e) {
  if ($e->getCode() == 404) {
    printf("Course with ID '%s' not found.\n", $courseId);
  } else {
    throw $e;
  }
}

Python

course_id = '123456'
try:
    course = service.courses().get(id=course_id).execute()
    print u'Course "{0}" found.'.format(course.get('name'))
except errors.HttpError as e:
    error = simplejson.loads(e.content).get('error')
    if(error.get('code') == 404):
        print u'Course with ID "{0}" not found.'.format(course_id)
    else:
        raise

For a list of courses, use the the courses.list(), as shown in the following sample:

.NET

            string pageToken = null;
            var courses = new List<Course>();

            do
            {
                var request = service.Courses.List();
                request.PageSize = 100;
                request.PageToken = pageToken;
                var response = request.Execute();
                courses.AddRange(response.Courses);
                pageToken = response.NextPageToken;
            } while (pageToken != null);

            if (courses.Count == 0)
            {
                Console.WriteLine("No courses found.");
            }
            else
            {
                Console.WriteLine("Courses:");
                foreach (var course in courses)
                {
                    Console.WriteLine("{0} ({1})\n", course.Name, course.Id);
                }
            }

Java

String pageToken = null;
List<Course> courses = new ArrayList<Course>();

do {
    ListCoursesResponse response = service.courses().list()
            .setPageSize(100)
            .setPageToken(pageToken)
            .execute();
    courses.addAll(response.getCourses());
    pageToken = response.getNextPageToken();
} while (pageToken != null);

if (courses.isEmpty()) {
    System.out.println("No courses found.");
} else {
    System.out.println("Courses:");
    for (Course course : courses) {
        System.out.printf("%s (%s)\n", course.getName(), course.getId());
    }
}

PHP

$pageToken = NULL;
$courses = array();

do {
  $params = array(
    'pageSize' => 100,
    'pageToken' => $pageToken
  );
  $response = $service->courses->listCourses($params);
  $courses = array_merge($courses, $response->courses);
  $pageToken = $response->nextPageToken;
} while (!empty($pageToken));

if (count($courses) == 0) {
  print "No courses found.\n";
} else {
  print "Courses:\n";
  foreach ($courses as $course) {
    printf("%s (%s)\n", $course->name, $course->id);
  }
}

Python

courses = []
page_token = None

while True:
    response = service.courses().list(pageToken=page_token,
                                      pageSize=100).execute()
    courses.extend(response.get('courses', []))
    page_token = response.get('nextPageToken', None)
    if not page_token:
        break

if not courses:
    print 'No courses found.'
else:
    print 'Courses:'
    for course in courses:
        print u'{0} ({1})'.format(course.get('name'), course.get('id'))

You can also list only the courses for a specific user. For more information, see Retrieve courses for a user.

Update course information

You can update some course metadata after the course is created. However, some fields such as the ownerId can only be set during course creation. The following fields can be updated any time after the course is created:

  • name
  • section
  • descriptionHeading
  • description
  • room
  • courseState

To update all fields in a course, use the courses.update() method, as shown in the following sample:

.NET

string courseId = "123456";
var course = service.Courses.Get(courseId).Execute();
course.Section = "Period 3";
course.Room = "302";
course = service.Courses.Update(course, courseId).Execute();
Console.WriteLine("Course '{0}' updated.\n", course.Name);

Java

String courseId = "123456";
Course course = service.courses().get(courseId).execute();
course.setSection("Period 3");
course.setRoom("302");
course = service.courses().update(courseId, course).execute();
System.out.printf("Course '%s' updated.\n", course.getName());

PHP

$courseId = '123456';
$course = $service->courses->get($courseId);
$course->section = 'Period 3';
$course->room = '302';
$course = $service->courses->update($courseId, $course);
printf("Course '%s' updated.\n", $course->name);

Python

course_id = '123456'
course = service.courses().get(id=course_id).execute()
course['section'] = 'Period 3'
course['room'] = '302'
course = service.courses().update(id=course_id, body=course).execute()
print u'Course "{0}" updated.'.format(course.get('name'))

You can also update specific fields using the courses.patch() method, as shown in the following sample:

.NET

            string courseId = "123456";
            var course = new Course
            {
                Section = "Period 3",
                Room = "302"
            };

            var request = service.Courses.Patch(course, courseId);
            request.UpdateMask = "section,room";
            course = request.Execute();
            Console.WriteLine("Course '{0}' updated.\n", course.Name);

Java

String courseId = "123456";
Course course = new Course()
        .setSection("Period 3")
        .setRoom("302");
course = service.courses().patch(courseId, course)
        .setUpdateMask("section,room")
        .execute();
System.out.printf("Course '%s' updated.\n", course.getName());

PHP

$courseId = '123456';
$course = new Google_Service_Classroom_Course(array(
  'section' => 'Period 3',
  'room' => '302'
));
$params = array(
  'updateMask' => 'section,room'
);
$course = $service->courses->patch($courseId, $course, $params);
printf("Course '%s' updated.\n", $course->name);

Python

course_id = '123456'
course = {
    'section': 'Period 3',
    'room': '302'
}
course = service.courses().patch(id=course_id, updateMask='section,room',
                                 body=course).execute()
print u'Course "{0}" updated.'.format(course.get('name'))

Add an alias for a course

You can set an alias when creating a course by supplying an alias string for the id. This alias must not already exist for another course. You can add aliases for an existing course with the courses.aliases.create() method, as shown in the following sample:

.NET

            string courseId = "123456";
            string alias = "p:bio10p2";
            var courseAlias = new CourseAlias
            {
                Alias = alias
            };

            try
            {
                courseAlias = service.Courses.Aliases.Create(courseAlias, courseId).Execute();
                Console.WriteLine("Alias '{0}' created.\n", courseAlias.Alias);
            }
            catch (GoogleApiException e)
            {
                if (e.HttpStatusCode == HttpStatusCode.Conflict)
                {
                    Console.WriteLine("Alias '{0}' is already in use.\n", alias);
                }
                else
                {
                    throw e;
                }
            }

Java

String courseId = "123456";
String alias = "p:bio10p2";
CourseAlias courseAlias = new CourseAlias().setAlias(alias);
try {
    courseAlias = service.courses().aliases().create(courseId, courseAlias).execute();
    System.out.printf("Alias '%s' created.\n", courseAlias.getAlias());
} catch (GoogleJsonResponseException e) {
    GoogleJsonError error = e.getDetails();
    if (error.getCode() == 409) {
        System.out.printf("Alias '%s' is already in use.\n", alias);
    } else {
        throw e;
    }
}

PHP

$courseId = '123456';
$alias = 'p:bio10p2';
$courseAlias = new Google_Service_Classroom_CourseAlias(array(
  'alias' => $alias
));
try {
  $courseAlias = $service->courses_aliases->create($courseId, $courseAlias);
  printf("Alias '%s' created.\n", $courseAlias->alias);
} catch (Google_Service_Exception $e) {
  if ($e->getCode() == 409) {
    printf("Alias '%s' is already in use.\n", $alias);
  } else {
    throw $e;
  }
}

Python

course_id = '123456'
alias = 'p:bio10p2'
course_alias = {
    'alias': alias
}
try:
    course_alias = service.courses().aliases().create(
        courseId=course_id,
        body=course_alias).execute()
except errors.HttpError as e:
    error = simplejson.loads(e.content).get('error')
    if(error.get('code') == 409):
        print u'Alias "{0}" is already in use.'.format(
            course_alias.get('alias'))
    else:
        raise

Retrieve course aliases

You can retrieve the aliases for a course using the courses.aliases.list() method, as shown in the following sample:

.NET

            string courseId = "123456";
            string pageToken = null;
            var courseAliases = new List<CourseAlias>();

            do
            {
                var request = service.Courses.Aliases.List(courseId);
                request.PageSize = 100;
                request.PageToken = pageToken;
                var response = request.Execute();
                courseAliases.AddRange(response.Aliases);
                pageToken = response.NextPageToken;
            } while (pageToken != null);

            if (courseAliases.Count == 0)
            {
                Console.WriteLine("No aliases found.");
            }
            else
            {
                Console.WriteLine("Aliases:");
                foreach (var courseAlias in courseAliases)
                {
                    Console.WriteLine(courseAlias.Alias);
                }
            }

Java

String courseId = "123456";
String pageToken = null;
List<CourseAlias> courseAliases = new ArrayList<CourseAlias>();

do {
    ListCourseAliasesResponse response = service.courses().aliases().list(courseId)
            .setPageSize(100)
            .setPageToken(pageToken)
            .execute();
    courseAliases.addAll(response.getAliases());
    pageToken = response.getNextPageToken();
} while (pageToken != null);

if (courseAliases.isEmpty()) {
    System.out.println("No aliases found.");
} else {
    System.out.println("Aliases:");
    for (CourseAlias courseAlias : courseAliases) {
        System.out.println(courseAlias.getAlias());
    }
}

PHP

$courseId = '123456';
$pageToken = NULL;
$courseAliases = array();

do {
  $params = array(
    'pageSize' => 100,
    'pageToken' => $pageToken
  );
  $response = $service->courses_aliases->listCoursesAliases(
      $courseId, $params);
  $courseAliases = array_merge($courseAliases, $response->aliases);
  $pageToken = $response->nextPageToken;
} while (!empty($pageToken));

if (count($courseAliases) == 0) {
  print "No aliases found.\n";
} else {
  print "Aliases:\n";
  foreach ($courseAliases as $courseAlias) {
    printf("%s\n", $courseAlias->alias);
  }
}

Python

course_id = '123456'
page_token = None
course_aliases = []

while True:
    response = service.courses().aliases().list(
        courseId=course_id,
        pageSize=100,
        pageToken=page_token).execute()

    course_aliases.extend(response.get('aliases', []))
    page_token = response.get('nextPageToken', None)
    if not page_token:
        break

if not course_aliases:
    print 'No aliases found.'
else:
    print 'Aliases:'
    for course_alias in course_aliases:
        print course_alias.get('alias')

Send feedback about...

Classroom API
Classroom API