Linking API

Introduction

The Linking API provides a reliable interface to configure and forward users directly to a Data Studio report via a URL. When users follow a Linking API URL they will have a streamlined experience to quickly view and interact with their data.

This document describes the required format of Linking API URLs and the available parameters.

Use case and benefits

The Linking API can be used to provide pre-configured reports for your customers to view and interact with their data. Key benefits of the Linking API are as follows:

  • A one-click report creation experience for your customers.
    • The data configuration is provided in the URL so users don't need to configure the report for their data.
    • Users can save the report with a single click and revisit the report at any time.
  • Create reports at scale. The Linking API reduces the time required to duplicate or create new reports.
  • Enable product integrations. The stable interface allows you to integrate Data Studio into a product workflow.

How it works

The following describes how developers and users interact with the Linking API.

Linking API developer workflow

The developer prepares the template reports, data sources, and formats a Linking API URL. The typical workflow for developers is as follows:

  1. Decide whether to use a blank report, the default report template provided by Data Studio or create a Data Studio report that will serve as a template. This includes configuring the template data sources.
  2. Format a Linking API URL for your specific use case. If applicable, specify the report template and other parameters, including the report name, data source name and data source configurations.
  3. Use the Linking API URL to direct users to the report.

Linking API user experience

The user follows a Linking API URL, that if configured correctly by the developer, will direct them to a Data Studio report that allows them to view and interact with data they have access to. A typical user experience may be as follows:

  1. In a browser, the user visits a service that has integrated with the Linking API.
  2. A call to action invites the user to click a link to view their data in Data Studio.
  3. The user follows the link and is directed to a Data Studio report. The report loads and the user is able to view and interact with their data.
  4. The user clicks “Edit and share”. The report is saved to their Data Studio account.
  5. The user now has full access and control over their own copy of the report. They can view, edit and share at any time.

Requirements

To ensure a Linking API URL works as expected, the following is required:

  1. A report, to serve as a template. If not provided then a blank report or default report, provided by Data Studio, can be used.
  2. Users of a Linking API URL must have, at a minimum, view access to the template report. Depending on the type of data sources used in the report and the configuration provided via the Linking API, users may also require view access to data sources. See Template permissions for details.
  3. The Connector type of each data source must support configuration via the Linking API. Refer to the Connector reference for a list of supported connectors.
  4. Users of the Linking API URL must have access to the data configured in the Linking API URL. If the user does not have access to the underlying data, any dependent report components will show an error.

URL parameters

A Linking API URL must be of the following form:

https://datastudio.google.com/reporting/create?parameters

The URL is expected to be used in the context of a web browser, typically by a user clicking on a link or being redirected to the URL. It can also be used to Embed a report.

Example URL

The following is an example Linking API URL. The report name is set and a single BigQuery data source is configured:

https://datastudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.connector=bigQuery
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

Certain URL parameters are required, while some are optional. The following is a list of parameters used to define a Linking API URL:

Control parameters

Control parameters determine the state of the report when viewed via the Linking API URL.

Parameter name Description
c.reportId
Optional. The template Report ID. Data Studio will open and configure the report specified. For details on how to find the ID, see Report ID. If unspecified, a blank report or default report template is used, see Use a blank or default report for details.
c.pageId
Optional. The ID of the initial page to load in the report. Defaults to the first page of the report if unspecified, .
c.mode
Optional. The initial report mode. One of view or edit. Defaults to view if unspecified.
c.explain
Optional. The visibility of the info/debug dialog. Set to true to show the dialog button. Defaults to false if unspecified. See Troubleshooting configuration issues to learn more.

Example

https://datastudio.google.com/reporting/create?
  c.reportId=12345
  &c.pageId=g7u8s9
  &c.mode=edit
  &r.reportName=MyNewReport
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

Report parameters

Report parameters override report properties.

Parameter name Description
r.reportName
Optional. Sets the report name. If unspecified, defaults to the template report name.
r.measurementId

Optional. Sets the Google Analytics Measurement IDs to Measure report usage. Use a comma to separate multiple IDs.

If r.measurementId and r.keepMeasurementId are unspecified, the Google Analytics Measurement IDs report setting defaults to unset. If r.measurementId and r.keepMeasurementId are set, r.keepMeasurementId takes precedence to set the ID.
r.keepMeasurementId

Optional. Set to true to use the template report Google Analytics Measurement IDs. Defaults to false if unspecified.

If r.measurementId and r.keepMeasurementId are unspecified, the Google Analytics Measurement IDs report setting defaults to unset. If r.measurementId and r.keepMeasurementId are set, r.keepMeasurementId takes precedence to set the ID.

Example

https://datastudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &r.measurementId=G-XXXXXXXXXX
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

Data source parameters

Data source parameters allow you to define a data source configuration and the data to access for data sources in the template report.

An alias is used to reference a data source in an existing report. Using an alias allows for backwards compatibility if a data source is added/removed from the template report.

For details on how to find a data source alias, see Data source alias.

Data source parameters

The following parameters are common across all connector types:

Name Description
ds.alias.datasourceName

Optional. Sets the name of the data source.

If ds.datasourceName and ds.keepDatasourceName are unspecified, the data source name defaults to a naming convention that includes the connector type and the time of creation (e.g. samples - 12/12/21, 10:53 PM). If ds.datasourceName and ds.keepDatasourceName are set, ds.datasourceName takes precedence to set the data source name.
ds.alias.keepDatasourceName

Optional. Set to true to use the template data source name. Defaults to false if unspecified.

If ds.datasourceName and ds.keepDatasourceName are unspecified, the data source name defaults to a naming convention that includes the connector type and the time of creation (e.g. samples - 12/12/21, 10:53 PM). If ds.datasourceName and ds.keepDatasourceName are set, ds.datasourceName takes precedence to set the data source name.
ds.alias.connector
Optional.

The connector type of the data source. For more information on supported connector types, see the Connector reference.

If set then all required connector parameters for the connector type must be specified in the Linking API URL and the template data source configuration will be replaced in its entirety.

If unspecified, then zero or more connector parameters for the connector type can be specified in the Linking API URL. The template data source configuration will be used to specify any parameters not provided in the Linking API URL. For details on how to identify the connector type of the template data source, see Connector type.

To learn more about how the ds.connector parameter affects whether a template data source configuration is replaced in its entirety or used to update unspecified parameters, see Replace vs update.
ds.alias.refreshFields
Optional.

Set to true to use the data source configuration specified via the Linking API to refresh data source fields and update report components with new field selections. true is typically specified when switching the connector type or for connector types where a configuration change yields different fields (e.g. fields for BigQuery data sources often change with different table configurations).

Set to false to leave the data source fields unchanged from the template report. false is typically specified when the new data configuration yields the exact same fields and you would prefer to maintain any field changes you've made to the template data source.

If unspecified, defaults vary by connector type. Review the Connector reference for connector specific defaults in case you want to override the default behavior.

Considerations when using refreshFields:
  • If refreshFields is set to false and the data source configuration specified via the Linking API yields different fields from what's used in the template report, the user will likely see a configuration error for the affected components.
  • Changes to fields in the template data source (e.g. name, type, aggregation, etc.) do not carry-over to new data sources when refreshFields is set to true. Set refreshFields to false to maintain field configurations from the template data source.
  • Calculated fields and Parameters defined in template data sources will always be copied to newly created data sources and are not affected by the value of refreshFields.
ds.alias.connectorParameters
Required. The data source configuration for the connector type. For details on how to identify the connector used to create a data source, see Connector type. For details on the data source parameters available for each connector type, see the Connector reference.

Replace vs update - Data source configurations

When setting data source parameters, the presence or omission of the ds.connector parameter in the Linking API URL indicates the intention to replace or update the template data source configuration, respectively.

The following table details how the ds.connector parameter affects whether a template data source configuration is replaced in its entirety or used to update unspecified parameters:

Is ds.connector set? Expected configuration and behavior Typical use
Yes Replace. The template data source configuration is replaced in its entirety, using the data source parameters specified in the Linking API URL. You must specify all required parameters for the connector type. See Required parameters when ds.connector is set.
  • When changing the connector type of a data source. E.g. If you configured a BigQuery data source in the template report but want to configure a Sheets data source via the Linking API. This will require a new connector configuration to be defined in its entirety.
  • When you want to guarantee the configuration of a data source. Replacing the configuration avoids any unknown values potentially being used from the template data source.
No Update. The template data source configuration will be used to specify any parameters not provided in the Linking API URL. All connector parameters for the connector type are optional, unless otherwise stated.

This simplifies the Linking API URL and is generally recommended when you are familiar with the template data source configuration and only want to override a subset of parameters.
  • When you only want to provide parameter values that differ from the template data source and are ok with relying on the template data source for any unspecified connector parameters. E.g. Change only the Billing Project ID of a BigQuery data source configuration and use the template configuration for all other parameters.

Required parameters when ds.connector is set

If a data source's ds.connector parameter is specified, then all connector parameters designated as Required must be specified for the data source. If the data source's ds.connector parameter is unspecified, then all connector parameters, even those designated as required, can be treated as optional, unless otherwise stated.

Examples

Configures a report with a single BigQuery data source (ds0) and replaces the data source configuration in its entirety:

https://datastudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &