This API was turned down in January 2019 and is deprecated. Migrate to Cloud Firestore or another data store.

Google Realtime API Overview

The Google Realtime API provides collaboration as a service for files in Google Drive via the use of operational transforms. The API is a JavaScript library hosted by Google that provides collaborative objects, events, and methods for creating collaborative applications.

How does it work?

The Realtime API lets you, the developer, design a shared data model that looks just like a local, in-memory data model. You write code to manipulate maps, lists, and your own custom JavaScript data model objects. When your code makes a change to the data model on behalf of some user, the data model automatically changes for all the users on the document.

These collaborative data model objects work just like local in-memory data model objects, with one exception. Unlike a local JavaScript data model, a collaborative Realtime API data model may change as a result of edits that were made by someone other than the current user. As a result, applications need to attach listeners to a collaborative document so that the UI may be updated to reflect remote changes.

The Realtime API is based on the same collaboration technology used by Google Docs. Whenever a collaborative data model is modified, the change is applied immediately to the local, in-memory copy of the document. The API then silently sends a representation of the change to the server (called a "mutation") so that the change can be recorded in the document and communicated to other collaborators. The mutations have been carefully designed so that conflicts between collaborators can always be automatically resolved, so users will never have to see a message about edit conflicts.

Realtime data models are "eventually consistent." That means that if all collaborators stop editing, eventually everyone will see the same data model. However, we make no guarantees about when all the collaborators will see the changes or what order the changes will be delivered in.

What is the Realtime API good for?

Applications where multiple people need to edit the same data simultaneously. Document editors are excellent examples of this kind of application.

What is the Realtime API not good for?

Applications where multiple people need to edit the same data in a particular order. A board game is an example of this kind of application, where changes from users need to occur in a particular order. This kind of app is very, very difficult to write using the Realtime API because, by design, at any given moment it's impossible to know whether other collaborators have made changes to the document.

What does the Realtime API do for me?

The Realtime API handles all aspects of data transmission, storage, and conflict resolution when multiple users are editing a file. Specifically, it provides:

  • Functions to load and work with Realtime documents.
  • Built-in collaborative objects (strings, lists, and maps).
  • The ability to create your own custom collaborative objects.
  • Events for detecting changes to the collaborative model or collaborators joining or leaving the document.
  • A text binder for binding collaborative string objects to the DOM.

The Realtime API provides all the tools you need to create a fully collaborative application without running your own server.

What doesn't the Realtime API do?

The primary goal of the Realtime API is to handle the heavy lifting of implementing realtime collaboration so you can focus on building your app. The Realtime API is designed to work with other APIs such as the Drive and OAuth APIs to handle functionality not directly related to collaboration. Examples of tasks that are not handled by the API include:

  • Converting to/from binary formats—These are the responsibility of the app.
  • Reading/writing to files—This is already handled by Drive.
  • Model locking—Drive already supports a last-write-wins consistency model.

The Realtime API, combined with the Drive and OAuth APIs, provides everything you need to create a fully functional collaborative app, leaving you free to focus on the application-specific logic.

Lifecycle of a Realtime App

In a typical scenario a Realtime application will:

  1. Enable the Drive API
  2. Load the Realtime library
  3. Authorize requests
  4. Open/create a file
  5. Load a document and initialize the data model
  6. Make changes/listen for changes on the data model

To learn more about building applications and data models, see Create a Realtime Application and Build a Collaborative Data Model.

Watch the video overview

The video from the Google I/O session provides a brief overview of how the Realtime API works and what you can do with it. If you'd like to learn what the Realtime API is with a demonstration and some tips directly from the developers, click play, sit back, and enjoy.

Send feedback about...

Realtime API
Realtime API
Need help? Visit our support page.