Service Interfaces for Application Developers

This reference describes the Google Cloud Print service interfaces that are used by application developers to submit, retrieve, and delete print jobs, and retrieve printers associated with an authenticated account. For reference on the service interfaces relevant to cloud-ready printers and GCP connectors that enable classic printers to register themselves with Google Cloud Print, see here. The /update interface described there can also be used by application developers who wish to enable users to modify any fields of their printers from the application.

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 with your application. For more information on using OAuth2 in this context, see here. Note also that the interfaces which may cause database writes (/submit and /deletejob) require a valid XSRF token.

All responses are returned in JSON format.

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/submit.

/submit

The /submit service interface is used to send print jobs to the GCP service. Upon initialization, the state of the print job will be QUEUED. The print job is created and the appropriate printer is notified of its existence. The state of the print job can then be tracked using /jobs, as described below.

Parameters

printerid (required)
Unique printer identification (generated by Google Cloud Print). To get valid printer IDs for a given user, retrieve the list of available printers for that Google Account by querying the /search service interface.
title (required)
Title of the print job, to be used within GCP.
ticket (required)
Print ticket in CJT format.
capabilities (deprecated, please use "ticket" instead)
Printer capabilities (XPS or PPD). Each GCP printer has, associated with it, a list of key-value capabilities representing printer-specific attributes (available printing formats, copy count, etc.). Capabilities for a given printer can be retrieved using the /printer service interface. These retrieved capabilities can then be used to specify desired options on the print job (for instance, print 5 copies instead of the default 1, or print duplex instead of single-sided).
content (required)
Document to print (can be a file or a string).
contentType (optional)
Document type (used to determine the conversion to be done, if any).
  • Upon submission, GCP attempts to convert the document to a type supported by the printer. GCP officially supports conversion from the types "url", "application/pdf", "image/jpeg", and "image/png". For Microsoft Office formats (doc/docx, xls/xlsx, ppt/pptx) and various other content types such as "text/html", "text/plain", and "application/postscript", reliable conversion can be expected but is not guaranteed.
  • If the printer directly supports printing a document submitted to GCP, conversion may not be necessary. Since the printer may support obscure content types not recognized by GCP, the /submit interface accepts documents of any type. It is at the point when the printer attempts to download the document that the print job will be aborted if the document cannot be printed.
  • For the specially-handled content type "url", the URL provided as a string in the "content" parameter should point to a publicly accessible page (there should be no necessary authentication, cookies, etc.). The linked resource can have any content type, but PDF is recommended for highest fidelity.
  • If this parameter is not provided, the content type will be determined on a best-effort basis from the HTTP request data.
tag (optional, repeated parameter)
One or more tags to add to the print job. You can attach a set of unique tags to a print job, and these will be available to the printer to which the print job is submitted. This feature may be especially useful if your application both sends and receives print jobs.

Response

The JSON response object contains a Boolean success indicator, a message, the XSRF token used, a listing of the request parameters, and the created job object data.

It is also important to check the HTTP response status code, and handle errors indicated by Google's webservers. For example, HTTP status 413, "Request Entity Too Large," indicates that a job failed to print because it is too large.

/deletejob

The /deletejob interface deletes the given print job.

Parameters

jobid (required)
The ID of the print job to be deleted. The print job must be owned by the authenticated user.

Response

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

/jobs

The /jobs interface returns a list of print jobs which the authenticated user has permission to view, filtered by various search options.

Parameters

printerid (optional)
Include this parameter to restrict the search to jobs submitted to the specified printer that the authenticated user has permission to view (which includes the jobs submitted by users with whom the authenticated user has shared the printer if the authenticated user owns it).
owner (optional)
Include this parameter to restrict the search to jobs submitted by the given user email address that the authenticated user has permission to view. To include only the authenticated user's own jobs, the value 'me' can be used as an alias for the authenticated user's email address.
status (optional)
Include this parameter to restrict the search to jobs which currently have the given status.
q (optional)
Include this parameter to restrict the search to jobs whose title or tags contain the given query as a substring (case-insensitively).
offset (optional)
Include this parameter to start the search at the given offset.
limit (optional)
Include this parameter to restrict the search to this many jobs past the offset.
sortorder (optional)
Include this parameter to specify the sort order of the returned print jobs. The supported values are:
  • CREATE_TIME: Sort jobs in chronological order of submission.
  • CREATE_TIME_DESC (default): Sort jobs in reverse chronological order of submission.
  • STATUS: Sort jobs in ascending* order of status.
  • STATUS_DESC: Sort jobs in descending* order of status.
  • TITLE: Sort jobs in lexicographic order of title.
  • TITLE_DESC: Sort jobs in reverse lexicographic order of title.
*For legacy job statuses, IN_PROGRESS < QUEUED < ERROR < DONE.

Response

The JSON response object contains a Boolean success indicator, a listing of the request parameters, and a list of print jobs. The fields annotated with * are present in all returned jobs at the time of this writing, but applications should not depend on the unconditional presence of any of these fields.

  • id*: print job's GCP ID
  • printerid*: printer's GCP ID
  • printerName*: printer's display name
  • title*: document title
  • contentType*: document content type (MIME type)
  • fileUrl*: URL where the document data can be accessed while the print job is active
  • ticketUrl* (deprecated, please use the /ticket interface instead): URL where the print job's ticket can be accessed
  • createTime*: timestamp of when the print job was created
  • updateTime*: timestamp of when the print job state was last updated
  • semanticState*: state of the print job in Print Job State format
  • uiState*: print job's Print Job UI State, which is a form of of Print Job State localized for the authenticated user and convenient for display in a UI
  • status* (deprecated): legacy job status
  • errorCode* (deprecated): error code string or integer if the status is ERROR
  • message* (deprecated): error message string if the status is ERROR
  • tags*: array of free-form strings – print jobs are tagged as ^own if the user is the owner (submitter) of the job, and ^shared if the job was merely shared with the user
  • ownerId: email address of print job's owner (submitter)
  • numberOfPages: number of pages in the document
  • printerType: printer's type (see the /search interface for possible types)
  • driveUrl: URL of the saved PDF in Google Drive if printerType is DRIVE and the job completed successfully

/printer

The /printer interface retrieves all of the fields of the specified printer, including its capabilities.

Parameters

printerid (required)
The ID of the printer whose capabilities are desired. The printer must be either owned by or shared with the authenticated user.
client (optional)
Include this parameter with any value (possibly the client name) to augment the printer's capabilities with options that can managed by the server. Some options that can be added (depending on the printer) are page range, orientation, page fitting.
extra_fields (optional)
Comma-separated list of extra fields to include in the returned printer object, see Extra Fields for Printers for more information.
use_cdd (deprecated)
Include use_cdd=false to receive printer capabilities as provided by the printer instead of in CDD format. (Capabilities in legacy formats are normally translated to CDD.) It is recommended ignoring this option in new client development.
printer_connection_status (deprecated, please use "extra_fields" instead)
A Boolean that specifies whether or not to return the printer's connectionStatus field.

Response

The JSON response object contains a Boolean success indicator, a listing of the request parameters, and a list of printers consisting of a single entry which contains the fields of the requested printer. The fields annotated with * are present in all returned printers at the time of this writing, but applications should not depend on the unconditional presence of any of these fields.

  • id*: printer's GCP ID
  • name*: system name of the printer
  • defaultDisplayName*: default printer display name
  • displayName*: user-specified printer display name
  • description*: descriptive string about the printer
  • type*: printer type (for possible types see the /search interface "type" parameter below)
  • proxy*: connector through which this printer is run, if any
  • createTime*: timestamp of when the printer was registered
  • accessTime*: timestamp of last /fetch request sent by the printer (if the printer has never sent a /fetch, this field is equal to createTime)
  • updateTime*: timestamp of last /update performed on the printer
  • isTosAccepted*: whether the user needs to accept the printer's terms of service
  • tags*: array of free-form strings provided by the printer/proxy or the Cloud Print server – any of the tags ^recent, ^connector, ^own, ^shared_directly, ^can_share, ^can_update, ^can_delete may be added by the server
  • capabilities*: printer capabilities
  • capsFormat: format of the capabilities. Normally "cdd", but it may be "xps" or "ppd" if use_cdd=false option is provided
  • capsHash*: a hash or digest value of the capabilities data
  • ownerId: printer owner's email address
  • ownerName: printer owner's name
  • access: printer's access control list, see Printer ACL
  • public: whether printer is public (anyone can submit print jobs to it)
  • quotaEnabled: whether quota restriction is enabled for a public printer
  • dailyQuota: number of pages each user is allotted to print per day on a quota-enabled public printer
  • currentQuota: number of pages the authenticated user has remaining to print today on a quota-enabled public printer
  • local_settings: printer's local settings
  • any GCP 2.0 string fields (uuid, manufacturer, model, gcpVersion, setupUrl, supportUrl, updateUrl, firmware, supportedContentTypes) that were provided for the printer via /register or /update
  • any extra fields that were requested using the extra_fields parameter

The /search interface returns a list of printers accessible to the authenticated user, filtered by various search options. Note that by default, /search will not include printers that have been offline for a long time (i.e. whose connectionStatus is DORMANT). This behavior can be overridden if ALL or DORMANT is passed as the value of the optional connection_status parameter.

Parameters

q (optional)
If q is specified, then only printers whose name, display name, or tags contain the given query as a substring (case-insensitively) will be returned.
  • Setting q=^recent will return the list of recently used printers, which will have all fields including capabilities.
  • Setting q=^own or q=^shared will return the list of printers owned by or shared with the user, respectively.
If q is not specified, then all printers accessible to (owned by or shared with) the authenticated user will be returned.
type (optional)
If type is specified, then only printers of the given type will be returned. The possible types are GOOGLE, HP, DOCS, DRIVE, FEDEX, ANDROID_CHROME_SNAPSHOT, IOS_CHROME_SNAPSHOT.
connection_status (optional)
If connection_status is specified, then only printers whose connection status matches the supplied value will be returned. You may provide one of the four values listed in the Extra Fields for Printers section below or you may specify ALL, which will match all printers, including those marked as DORMANT.
use_cdd (optional)
If q contains the substring "^recent", then providing use_cdd=true will cause the capabilities of the returned printers to be in CDD format; if q does not contain "^recent" then this parameter has no effect.
extra_fields (optional)
Comma-separated list of extra fields to include in the returned printer objects, see Extra Fields for Printers for more information. For backward compatibility, connectionStatus is always returned when the extra_fields parameter is omitted.

Response

The JSON response object contains a Boolean success indicator, a listing of the request parameters, and a list of printers. All fields are listed, except for capabilities which must be retrieved using a call to /printer (unless q contains the substring "^recent", in which case the recent printers are returned with their capabilities).

Extra Fields for Printers

Some fields of printer objects returned in the /printer, /search, and /list interfaces either take some time to compute or have the potential to be large in size. Therefore, GCP provides the ability to choose whether these so-called "extra fields" are included in the JSON response. The following extra fields are available at this time:

  • connectionStatus: printer's connection status, which can be one of the following:
    • ONLINE: The printer has an active XMPP connection to Google Cloud Print.
    • UNKNOWN: The printer's connection status cannot be determined.
    • OFFLINE: The printer is offline.
    • DORMANT: The printer has been offline for quite a while.
  • semanticState: printer's Cloud Device State as it was provided by the printer or software connector via the /register or /update API, with the "cloud_connection_state" field filled in based on the current connection status. For printers which do not have CDS, requesting this extra field will have no effect.
  • uiState: printer's Cloud Device UI State, which is a form of CDS localized for the authenticated user and convenient for display in a UI. Printers which do not have CDS are returned with a basic form of UI state based on their connection status when this field is requested.
  • queuedJobsCount: the number of jobs submitted to this printer that are currently in QUEUED state.

The extra fields to be included in the response are specified as a comma-separated list in the URL parameter "extra_fields" of the request. For example, extra_fields=connectionStatus,uiState or extra_fields=queuedJobsCount.