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.
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
/search
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
orq=^shared
will return the list of printers owned by or shared with the user, respectively.
- Setting
- 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 asDORMANT
. - 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
.