Cloud Print

Service Interfaces for Printers and Connectors

This reference describes the Google Cloud Print service interfaces that are used by printers and GCP software connectors to register printers with Google Cloud Print, a web service for printing. Connectors can run as part of a standalone software application (in which case they are called software connectors), or they can be included in printer firmware for developing cloud-ready printers (in which case they are simply referred to as printers). Once a printer is registered with the service, it can then receive jobs from and communicate status with Google Cloud Print. Use of Google Cloud Print enables platform- and format-independent printing. For reference on the service interfaces relevant to application developers, see here.

Every API call you make must contain the following Authorization HTTP header: Authorization: OAuth YOUR_ACCESS_TOKEN, where YOUR_ACCESS_TOKEN refers to an OAuth2 access token. To fetch an access token, you will need to make use of the refresh token already stored in the printer memory (as detailed here). For more information on using OAuth2 in this context, see here. Note also that the interfaces which may cause database writes (/control, /delete, /register, and /update) require a valid XSRF token.

All responses are returned in JSON format.

The following diagrams show the typical sequence of calls made by a cloud-ready printer or GCP software connector to register a printer and its attributes with Google Cloud Print, update this printer data, list all current printers registered for a given proxy, and delete a printer from the list of registered printers. Other interfaces allow a printer or connector to communicate the current state of a print job to GCP (the control interface) and to fetch a printer's next available job(s) from GCP.

Note: The parameters listed in these diagrams are for GCP 1.0. Click the name of any interface to see its currently supported GCP 2.0 specification.

interface_flow_diagram

job_management

Job Availability Notification

Google Cloud Print can provide print job availability notification through Google Talk, using a persistent XMPP connection. The printer or software connector should initiate this connection to Google Talk XMPP servers and subscribe to the printing notification. Details of this connection and open source code for libjingle can be found at Google Talk Developer Documentation. This XMPP connection also needs an authentication token as with the HTTP requests described above. Details of this XMPP connection and notification will be added here soon. In the absence of such a persistent connection, the printer or software connector can use frequent polling of available jobs using the /fetch interface.

Error Handling

For all interfaces, Google Cloud Print will respond with an object containing a Boolean success variable set to false if there was an error in processing the request. There will also be a message variable in the response describing the reason for the error, a numeric error code, and a listing of the request parameters. For example:

{
 "success": false,
 "message": "Missing required parameters.",
 "errorCode": 2,
 "request": { ... }
}

API Simulation Page

GCP provides a simulate page containing HTML forms which provide a convenient way to make requests to the various service interfaces for testing and debugging purposes.
Disclaimer: This page is not an officially supported feature of GCP and any aspect of it may change at any time.

Calling Syntax

To use the interfaces, you need to prepend the Google Cloud Print URL https://www.google.com/cloudprint to the interface names, for example https://www.google.com/cloudprint/control.

/control

This interface can be used by the printer or software connector to update Google Cloud Print about the state of a print job on the printer device. This information is used for user interface and troubleshooting purposes. GCP 2.0 compliant printers must use the parameter semantic_state_diff (in Print Job State Diff format) instead of the deprecated status, code and message parameters. They must make a best effort to update the state of any job they are processing whenever it changes. None of these parameters are used for any control, disabling, or filtering of the print job or the printer.

Parameters

jobid (required)
Unique job identification (generated by server).
semantic_state_diff (optional, but recommended)
Print Job State Diff, use this to update the state type (and cause if the type is ABORTED or STOPPED) and the number of printed pages.
status (deprecated, please use semantic_state_diff instead)
Legacy job status.
code (deprecated, please use semantic_state_diff instead)
Error code string or integer (as returned by the printer or OS) if the status is ERROR.
message (deprecated, please use semantic_state_diff instead)
Error message string (as returned by the printer or OS) if the status is ERROR.

The following diagram shows the transitions between the seven job state types defined in JobState:

Response

The JSON response object contains a Boolean success indicator, a message, the XSRF token used, a listing of the request parameters, and the updated job object. For example:

{
 "success": true,
 "message": "Job updated successfully.",
 "xsrf_token": "...",
 "request": { ... },
 "job": { ... }
}

/delete

This interface is used to delete a printer from Google Cloud Print.

Parameters

printerid (required)
Unique printer identification (generated by Google Cloud Print).

Response

The JSON response object contains a Boolean success indicator, a message, the XSRF token used, and a listing of the request parameters. For example:

{
 "success": true,
 "message": "Printer deleted successfully.",
 "xsrf_token": "...",
 "request": { ... }
}

/fetch

This interface is used to fetch the next available jobs for the specified printer.

Parameters

printerid (required)
Unique printer identification (generated by Google Cloud Print).

Response

The JSON response object contains a Boolean success indicator, a listing of the request parameters, and a list of jobs. The list contains only the jobs that are in QUEUED status/state.

Sample Response

{
 "success": true,
 "request": { ... },
 "jobs": [
  {
   "id": "954c36d0-cf2d-e841-d960-ae98cbf504de",
   "title": "CloudPrint_Architecture.pdf",
   "status": "QUEUED",
   "fileUrl": "https://www.google.com/cloudprint/download?id\u003d954c36d0-cf2d-e841-d960-ae98cbf504de",
   "rasterUrl": "https://www.google.com/cloudprint/download?id\u003d954c36d0-cf2d-e841-d960-ae98cbf504de\u0026forcepwg\u003d1",
   ... (more fields) ...
  }
 ]
}

/ticket

GCP 1.0 printers and connectors download their job tickets from a ticketUrl field included in the job objects in the /fetch response. This legacy ticket is returned in either XPS (XML Paper Specification) or PPD (Postscript Printer Description) format, depending on the "format" parameter specified in the ticketUrl.

GCP 2.0 printers and connectors do not need to understand either of these legacy formats; they only need to understand the CJT (Cloud Job Ticket) format. To get a CJT for a given print job, use the /ticket interface, specifying the parameters jobid=<id> and use_cjt=true.

/download

The fileUrl field in the /fetch response points to the data to be printed. GCP 1.0 printers and connectors must specify the MIME types they can accept to print in the Accept header of the download request as defined by the HTTP protocol. GCP 2.0 printers and connectors, on the other hand, must report their list of supported content types in their CDD. GCP uses this list to perform document conversions before the printer downloads the document. Consequently, GCP 2.0 printers cannot control the document format they receive by specifying MIME types in the Accept header of the download request. However, if the printer cannot print the document downloaded from the fileUrl for any reason (e.g. the document is a PDF which contains transparency and the printer cannot handle transparency), it can request the document in PWG-raster format from the rasterUrl as a fallback mechanism.

When performing a request to the fileUrl or rasterUrl to download a PWG-raster document, GCP supports an optional query parameter skippages. When skippages=N is specified, the first N pages of the PWG-raster document are skipped. Page skipping is relative to the PWG-raster document after page reordering and not relative to the original document. This parameter can be used by the printer if it needs to resume printing pages from some point, say after a paper jam. The parameter is for PWG-raster documents only and has no effect for documents downloaded in PDF format.

The fileUrl in the example /fetch response above is https://www.google.com/cloudprint/download?id=<jobid>, but printers and connectors must not assume that the fileUrl will follow this pattern in general. They must download the file data for each print job from the fileUrl returned in the corresponding /fetch response (and fall back on the corresponding rasterUrl if necessary).

/list

This interface provides a listing of all the printers for the given user. It can be used to compare the printers registered and available locally. If a software connector is connected to multiple printers, this interface is useful to keep the local printers and printers registered with Google Cloud Print in sync. With this interface, the software connector does not need to maintain a state or mapping of the local printers and needs to store only the unique proxy ID required as a parameter.

Parameters

proxy (required)
Identification of the proxy, as submitted while registering the printer.
extra_fields (optional)
Comma-separated list of extra fields to include in the returned printer objects, see Extra Fields for Printers for more information. The queuedJobsCount extra field is useful here so that a software connector does not need to make a /fetch call for printers with zero queued jobs. Note that the /printer interface must be used in order to retrieve a printer's capabilities.

Response

The JSON response object contains a Boolean success indicator, a listing of the request parameters, and a list of printer objects assigned to the software connector specified by the given proxy. For example:

{
 "success": true,
 "request": { ... },
 "printers": [
  {
   "id": "2f4b5bca-c967-7728-6af5-1dea2a9eb2d3",
   "name": "My home printer",
   "proxy": "ksdjf-7237sf9238-2837jidf",
   "ownerId": "example@gmail.com",
   ... (many more fields) ...
  },
  {
   "id": "5af36c4b-0e45-6cfd-c833-b6bca2a8e6d1",
   "name": "Another printer",
   "proxy": "ksdjf-7237sf9238-2837jidf",
   "ownerId": "example@gmail.com",
   ... (many more fields) ...
  }
 ]
}

/register

This interface is used to register printers. GCP 2.0 compliant printers must provide their capabilities, defaults and features via the capabilities parameter in CDD format, they must provide their registration-time state via the semantic_state parameter in CDS format, and they must include use_cdd=true. For older printers, the capabilities and defaults can be in XPS or PPD format.

This should be an HTTP multipart POST since it needs to upload printer capabilities and defaults data, which are generally too large to URL-encode. The capabilities (XPS, PPD or CDD) and defaults (XPS only) may be provided as file or string fields in the multipart message, and all other parameters must be provided as string fields.

Parameters

printer (required)
System name of the printer (need not be unique).
default_display_name (optional)
Name of the printer to be displayed to users. If a default display name is not provided, the system name is displayed.
proxy (required)
Identification of the printer client or proxy (many printers can share the same proxy).
uuid (required for GCP 2.0)
Manufacturer-provided serial number of the printer.
manufacturer (required for GCP 2.0)
Name of the printer manufacturer.
model (required for GCP 2.0)
Printer model.
gcp_version (required for GCP 2.0)
Version of the GCP protocol supported by the printer, e.g. "2.0".
setup_url (required for GCP 2.0)
URL with printer setup instructions.
support_url (required for GCP 2.0)
URL that user should be directed to if they are in need of printer support.
update_url (required for GCP 2.0)
URL that user should be directed to if printer needs a firmware update.
firmware (required for GCP 2.0)
Version of the printer's firmware.
local_settings (optional, but recommended for GCP 2.0)
Current local settings of the printer (see Local settings).
semantic_state (required for GCP 2.0)
Current state of the printer in CDS format.
use_cdd (required to be true for GCP 2.0)
Set this to "true" if the capabilities are provided in CDD format.
capabilities (required)
Printer capabilities (XPS, PPD or CDD).
defaults (required for XPS only)
Printer default settings (XPS only).
capsHash (optional)
A hash or digest value of the capabilities data. This value is useful, for example, to compare values and check whether the local printer's capabilities have changed.
tag (optional, repeated parameter)
Tags (free-form string values) to add to the printer. You can attach a set of unique tags to a printer, which may be useful to store additional metadata about the printer for later use by your application.
data (optional, repeated parameter)
Private data to add to the printer. Private data values are similar to tags except that they are write-only; they can be added in /register and added or removed in /update, but they are never rendered in responses from the server.
description (deprecated)
Descriptive string about the printer.
content_types (deprecated, supported content types must be provided in CDD for GCP 2.0)
Comma-separated list of content types that printer supports.

Response

The JSON response object contains a Boolean success indicator, the XSRF token used, a listing of the request parameters, and a list of printers consisting of a single entry which contains the fields of the printer added in the request. For example:

{
 "success": true,
 "xsrf_token": "...",
 "request": { ... },
 "printers": [
  {
   "id": "2f4b5bca-c967-7728-6af5-1dea2a9eb2d3",
   "name": "My home printer",
   "proxy": "ksdjf-7237sf9238-2837jidf",
   ... (many more fields) ...
  }
 ]
}

/update

This interface is used to update various attributes and parameters of a printer registered with Google Cloud Print. GCP 2.0 compliant printers must make a best effort to update their state whenever it changes (using either the semantic_state or semantic_state_diff parameter).

Parameters

printerid (required)
Unique printer identification (generated by Google Cloud Print).
printer (optional)
System name of the printer (need not be unique).
default_display_name (optional)
Name of the printer to be displayed to users. If a default display name is not provided, the system name is displayed. Providing this parameter as the empty string clears any existing default display name.
display_name (optional, for use by GCP clients only)
Display name of the printer customized by an authenticated user. This name is only displayed to the user who provided it; all other users see the default display name. Providing this parameter as the empty string clears any existing customized display name.
proxy (optional)
Identification of the printer client or proxy (many printers can share the same proxy).
uuid (optional)
Manufacturer-provided serial number of the printer.
manufacturer (optional)
Name of the printer manufacturer.
model (optional)
Printer model.
gcp_version (optional)
Version of the GCP protocol supported by the printer, e.g. "2.0".
setup_url (optional)
URL with printer setup instructions.
support_url (optional)
URL that user should be directed to if they are in need of printer support.
update_url (optional)
URL that user should be directed to if printer needs a firmware update.
firmware (optional)
Version of the printer's firmware.
local_settings (optional)
Current (provided or confirmed by the printer) or pending (provided by a client) local settings of the printer (see Local settings).
semantic_state (optional, mutually exclusive with semantic_state_diff)
Current state of the printer in CDS format; overwrites the CDS stored for the printer.
semantic_state_diff (optional, mutually exclusive with semantic_state)
Diff on the CDS stored for the printer; interpreted as described in CDS Diff Interpretation.
use_cdd (required to be true for GCP 2.0 if capabilities are provided)
Set this to "true" if the capabilities are provided in CDD format.
capabilities (optional)
Printer capabilities (XPS, PPD or CDD).
defaults (optional)
Printer default settings (XPS only).
capsHash (optional)
A hash or digest value of the capabilities data. This value is useful, for example, to compare values and check whether the local printer's capabilities have changed.
tag (optional, repeated parameter)
Tags (free-form string values) to add to the printer. You can attach a set of unique tags to a printer, which may be useful to store additional metadata about the printer for later use by your application.
remove_tag (optional, repeated parameter)
Can be used to remove existing tags from the printer. Each existing tag that matches at least one of the patterns* provided for this parameter will be removed.
data (optional, repeated parameter)
Private data to add to the printer. Private data values are similar to tags except that they are write-only; they can be added in /register and added or removed in /update, but they are never rendered in responses from the server.
remove_data (optional, repeated parameter)
Can be used to remove existing private data from the printer. Each existing private data string that matches at least one of the patterns* provided for this parameter will be removed.
description (deprecated)
Descriptive string about the printer. Providing this parameter as the empty string clears any existing description.
content_types (deprecated, supported content types must be provided in CDD for GCP 2.0)
Comma-separated list of content types that printer supports.

*Values of the repeated parameters remove_tag and remove_data are treated as regular expressions. Therefore, the characters .\+*?^$|()[{ must be escaped with a \ to be treated literally, and the other regular expression metacharacters !=:-]}<> may need to be escaped if they are used within unescaped parentheses, square brackets, or braces.

Response

The JSON response object contains a Boolean success indicator, a message, the XSRF token used, a listing of the request parameters, and the updated printer object. For example:

{
 "success": true,
 "message": "Printer updated successfully.",
 "xsrf_token": "...",
 "request": { ... },
 "printer": { ... }
}

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.