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 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. 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 default report, provided by Data Studio, will 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.

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 default report template is used. See Using the default report template 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.

Example

https://datastudio.google.com/reporting/create?
  c.reportId=12345
  &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

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 unspecified, uses a default naming convention that includes the connector type and the time of creation (e.g. samples - 12/12/21, 10:53 PM).
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. Set to false to leave the data source fields unchanged from the template report. 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).

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 see a configuration error for the affected components.

If unspecified, defaults vary by connector type. Review the Connector reference for connector specific defaults in case you want to override the default behavior.
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
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare

The data source alias can be omitted when the report has a single data source. The URL above can be simplified to the following:

https://datastudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.datasourceName=MyNewDataSource
  &ds.connector=bigQuery
  &ds.type=TABLE
  &ds.projectId=bigquery-public-data
  &ds.datasetId=samples
  &ds.tableId=shakespeare

Configures a report with a single BigQuery data source (ds0) and updates only the billing project ID of the data source:

https://datastudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.billingProjectId=my-billing-project

Configures a report with two data sources, a BigQuery data source (ds0) and a Google Analytics data source (ds1). The BigQuery data source configuration is replaced in its entirety, while the Google Analytics configuration updates a single parameter and relies on the ds1 template data source for any unspecified connector parameters:

https://datastudio.google.com/reporting/create?
  c.reportId=7890
  &r.reportName=MyNewReportWithMultipleDataSources
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare
  &ds.ds1.viewId=92320289

Connector reference

The Linking API supports the following connectors and configurations. For each connector, the list of available data source parameters is provided.

BigQuery

The BigQuery connector supports two types of queries, a TABLE query, in which you provide the Table ID of the table to query and a CUSTOM_QUERY, in which you provide a SQL statement to query a table.

TABLE queries

The following parameters are applicable when type is set to TABLE and you provide the ID of the table to query.

Parameter name Description
ds.alias.connector
Optional. Set to bigQuery for the BigQuery connector.

If set, replaces the data source with the provided BigQuery configuration. See Replace vs update.
ds.alias.type
Required** The type of query. Set to TABLE.
ds.alias.projectId
Required** The Project ID of the table to query.
ds.alias.datasetId
Required** The Dataset ID of the table to query.
ds.alias.tableId
Required** The Table ID of the table to query.

Date sharded tables:
The * (wildcard character) or YYYYMMDD suffix is supported when querying date sharded tables.
If a table is identified as Google Analytics, Firebase Analytics, or Firebase Crashlytics, a default fields template will be selected unless one is specified. See the fields template table related parameters.
ds.alias.billingProjectId
Optional. The ID of the Project to use for billing. If not set, projectId will be used.
ds.alias.isPartitioned
Optional. Set to true if the table is partitioned and you want to use the partitioning column as a date range dimension. This is only applicable to time based partitioning (E.g. using a time based partitioning column or the _PARTITIONTIME pseudocolumn) and does not work for integer range partitioned tables. Defaults to false if unspecified. To learn more see Introduction to partitioned tables.
ds.alias.refreshFields
Optional. Defaults to true if unspecified. See refreshFields for details.
Fields template for Google Analytics, Firebase Analytics and Crashlytics

For tables identified as Google Analytics, Firebase Analytics, or Firebase Crashlytics, additional parameters are available to set the fields template. If unspecified, a default template will be selected.

Name Description
ds.alias.gaTemplateLevel
Optional. The Google Analytics fields template to use. Applicable only when a BigQuery export for Google Analytics table is being queried. One of ALL, SESSION, HITS. For Google Analytics tables, defaults to ALL if unspecified.
ds.alias.firebaseTemplateLevel
Optional. The Firebase Analytics fields template to use. Applicable only when a BigQuery export for Firebase Analytics table is being queried. Can only be set to EVENTS. For Firebase Analytics tables, defaults to EVENTS if unspecified.
ds.alias.crashlyticsTemplateLevel
The Firebase Crashlytics fields template to use. Can only be set to DEFAULT. Applicable only when a BigQuery export for Firebase Crashlytics table is being queried. For Firebase Crashlytics tables, defaults to DEFAULT if unspecified.

CUSTOM queries

The following parameters are applicable when type is set to CUSTOM_QUERY and you provide a SQL statement to query a table.

Parameter name Description
ds.alias.connector
Optional. Set to bigQuery for the BigQuery connector.

If set, replaces the data source with the provided BigQuery configuration. See Replace vs update.
ds.alias.type
Required** The type of query. Set to CUSTOM_QUERY.
ds.alias.sql
Required** The SQL query to run.
ds.alias.billingProjectId
Optional. The ID of the Project to use for billing. If not set, projectId will be used. If projectId is not set then the project of the queried table will be used.
ds.alias.refreshFields
Optional. Defaults to true if unspecified. See refreshFields for details.

Examples

A TABLE type configuration where the query is defined with a Table ID:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare
  &ds.ds0.billingProjectId=myProject

A TABLE type configuration to query a date sharded table using the wildcard character suffix:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=price-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=stock_*
  

A TABLE type configuration to query a date sharded table using the YYYYMMDD suffix:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=price-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=stock_YYYYMMDD
  

A TABLE type configuration to query a BigQuery Export for Google Analytics table, using the SESSION fields template:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=my-gabq-project
  &ds.ds0.datasetId=1234567
  &ds.ds0.tableId=ga_sessions_YYYYMMDD
  &ds.ds0.gaTemplateLevel=SESSION
  

A TABLE type configuration to query an ingestion time partitioned table and use the partitioning column as a date range dimension:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=acme-co-logs
  &ds.ds0.datasetId=logs
  &ds.ds0.tableId=logs_table
  &ds.ds0.isPartitioned=true

A CUSTOM_QUERY type configuration where they query is defined with a SQL statement:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=CUSTOM_QUERY
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.sql=SELECT%20word%2C%20word_count%20FROM%20%60bigquery-public-data.samples.shakespeare%60
  &ds.ds0.billingProjectId=myProject

A CUSTOM_QUERY type configuration where only the SQL statement is updated and the template data source is used for the rest of the configuration:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.sql=SELECT%20corpus%20FROM%20%60bigquery-public-data.samples.shakespeare%60

Cloud Spanner

Parameter name Description
ds.alias.connector
Optional. Set to cloudSpannerfor the Cloud Spanner connector.

If set, replaces the data source with the provided Cloud Spanner configuration. See Replace vs update.
ds.alias.projectId
Required** The Project ID.
ds.alias.instanceId
Required** The instance ID.
ds.alias.databaseId
Required** The Database ID.
ds.alias.sql
Required** The SQL query to run.
ds.alias.refreshFields
Optional. Defaults to true if unspecified. See refreshFields for details.

Example

A Cloud Spanner configuration with a SQL statement:

https://datastudio.google.com/reporting/create?
  c.reportId=456def
  &ds.ds1.connector=cloudSpanner
  &ds.ds1.projectId=myProject
  &ds.ds1.instanceId=production
  &ds.ds1.datasetId=transactions
  &ds.ds1.sql=SELECT%20accountId%2C%20date%2C%20revenue%20FROM%20sales%3B

Google Analytics

Parameter name Description
ds.alias.connector
Optional. Set to googleAnalytics for the Google Analytics connector.

If set, replaces the data source with the provided Google Analytics configuration. See Replace vs update.
ds.alias.accountId
Required** The Account ID.
ds.alias.propertyId
Required** The Property ID.
ds.alias.viewId
The View ID.
Required** for Universal Analytics properties.
Do not set for Google Analytics 4 properties.
ds.alias.refreshFields
Optional. Defaults to false if unspecified. See refreshFields for details.

Examples

A Google Analytics configuration for a Universal Analytics property:

https://datastudio.google.com/reporting/create?
  c.reportId=789ghi
  &ds.ds2.connector=googleAnalytics
  &ds.ds2.accountId=54516992
  &ds.ds2.propertyId=UA-54516992-1
  &ds.ds2.viewId=92320289

A Google Analytics configuration for a Google Analytics 4 property:

https://datastudio.google.com/reporting/create?
  c.reportId=789ghi
  &ds.ds2.connector=googleAnalytics
  &ds.ds2.accountId=54516992
  &ds.ds2.propertyId=213025502

Google Cloud Storage

Parameter name Description
ds.alias.connector
Optional. Set to googleCloudStorage Google Cloud Storage connector.

If set, replaces the data source with the provided Google Cloud Storage configuration. See Replace vs update.
ds.alias.pathType
Required** The path type. Use FILE to select a single file or FOLDER to select all files for the given path.
ds.alias.path
Required** The file path (e.g. MyBucket/MyData/MyFile.csv) if pathType is FILE or the folder path (e.g. *MyBucket/MyData) if pathType is FOLDER.
ds.alias.refreshFields
Optional. Defaults to true if unspecified. See refreshFields for details.

Example

A Google Cloud Storage configuration for a single file:

https://datastudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FILE
  &ds.ds50.path=MyBucket%2FMyData%2FMyFile.csv

A Google Cloud Storage configuration for all files in the path:

https://datastudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FOLDER
  &ds.ds50.path=MyBucket%2FMyData

Google Sheets

Parameter name Description
ds.alias.connector
Optional. Set to googleSheets for the Google Sheets connector.

If set, replaces the data source with the provided Google Sheets configuration. See Replace vs update.
ds.alias.spreadsheetId
Required** The spreadsheet ID.
ds.alias.worksheetId
Required** The worksheet ID.
ds.alias.hasHeader
Optional. Set to true to use the first row as headers. Defaults to true if unspecified. Column headers must be unique. Columns with empty headers will not be added to the data source.
ds.alias.includeHiddenCells
Optional. Set to true to include hidden cells. Defaults to true if unspecified.
ds.alias.includeFilteredCell
Optional. Set to true to include filtered cells. Defaults to true if unspecified.
ds.alias.range
Optional. Range, e.g. A1:B52.
ds.alias.refreshFields
Optional. Defaults to true if unspecified. See refreshFields for details.

Examples

A Google Sheets configuration:

https://datastudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437

A Google Sheets configuration with the first row used as headers and hidden and filtered cells included:

https://datastudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437
  &ds.ds3.hasHeader=true
  &ds.ds3.includeHiddenCells=true
  &ds.ds3.includeFilteredCells=true

A Google Sheets configuration with a range (A1:D20):

https://datastudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437
  &ds.ds3.range=A1%3AD20

Google Surveys

Parameter name Description
ds.alias.connector
Optional. Set to googleSurveys Google Surveys connector.

If set, replaces the data source with the provided Google Surveys configuration. See Replace vs update.
ds.alias.surveyId
Required** A Survey ID or a comma separated list of Survey IDs. If set to a list of Survey IDs, each survey should be of the same survey type.
ds.alias.surveyType
Optional. Sets the survey type. Can be one of SURVEY or STUDY. Defaults to SURVEY if unspecified.
ds.alias.refreshFields
Optional. Defaults to false if unspecified. See refreshFields for details.

Example

A Google Surveys configuration for a single survey:

https://datastudio.google.com/reporting/create?
  c.reportId=131415mno
  &ds.ds4.connector=googleSurveys
  &ds.ds4.surveyId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k

A Google Surveys configuration for multiple surveys:

https://datastudio.google.com/reporting/create?
  c.reportId=131415mno
  &ds.ds4.connector=googleSurveys
 &ds.ds4.surveyIds=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k,bcDhK8bfS9eUdKhe8rP98T

Search Console

Parameter name Description
ds.alias.connector
Optional. Set to searchConsole for the Search Console connector.

If set, replaces the data source with the provided Search Console configuration. See Replace vs update.
ds.alias.siteUrl
Required** The site URL. For a Domain property, prefix with sc-domain\:.
ds.alias.tableType
Required** Sets the table type. Can be one of SITE_IMPRESSION or URL_IMPRESSION.
ds.alias.searchType
Required** Sets the search type. Can be one of WEB, IMAGE, VIDEO or NEWS.
ds.alias.refreshFields
Optional. Defaults to false if unspecified. See refreshFields for details.

Example

A Search Console configuration for a URL-prefix property:

https://datastudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=searchConsole
  &ds.ds5.siteUrl=https%3A%2F%2Fwww.example.com%2Fwelcome
  &ds.ds5.tableType=SITE_IMPRESSION
  &ds.ds5.searchType=WEB

A Search Console configuration for a Domain property:

https://datastudio.google.com/reporting/create?
  c.reportId=161718pqr
  ds.ds5.connector=searchConsole
  &ds.ds5.siteUrl=sc-domain%3Aexample.com
  &ds.ds5.tableType=SITE_IMPRESSION
  &ds.ds5.searchType=WEB

Template permissions

To ensure the best user experience for users, it's important to correctly set report access permissions for your template report and associated data sources. The permissions required are dependent on whether the report template uses embedded vs reusable data sources and whether the Linking API configuration is set to replace or update a data source configuration.

The following table provides the recommended data source access for the optimal user experience based on the template data sources and Linking API configuration:

Data source type Linking API configuration for data source Recommendation for data source permissions Notes
Embedded Replace N/A - View access will be inherited from report. If user has view access to the template report, they will automatically have view access to any embedded data source.
Embedded Update N/A - View access will be inherited from report. If user has view access to the template report, they will automatically have view access to any embedded data source.
Reusable Replace User's do not need view access. Since the data source configuration is being replaced in its entirety via the Linking API, view access is not required.
Reusable Update User's require view access. View access to the data source is required for the Linking API to be able to read and use the configuration from the template data source. If the users does not have view access they will receive an error when loading the report.

Using the default report template

The default report template has a single embedded data source and is automatically used when the reportId control parameter it not included in a Linking API URL. You do not need to include a data source alias when specifying data source parameters for the default report template.

The following is an example Linking API URL that uses the default report template with a Google Sheets connector configuration:

https://datastudio.google.com/reporting/create?
  ds.connector=googleSheets
  &ds.spreadsheetId=12345
  &ds.worksheetId=0

Finding IDs and aliases

Report ID

To find the report ID:

  1. Open the report you want to use as a template. Inspect the URL of the report. The part between reporting/ and /page is the report ID. For example, in the following URL, 0B_U5RNpwhcE6SF85TENURnc4UjA is the report ID:
https://datastudio.google.com/reporting/0B_U5RNpwhcE6SF85TENURnc4UjA/page/1M
Browser address bar showing the URL of a Data Studio report.
            Report ID is highlighted.
Find the Report ID in the report URL.

Data source alias

A report can have multiple data sources. A data source should be referenced by its alias.

To find a data source alias:

  1. Edit the report.
  2. From the toolbar, select Resource > Manage added data sources.
  3. Examine the Alias column to find alias information for each data source.

You can edit alias names to ensure backwards compatibility when a Data Source is added or removed.

A list of Data Sources in the Data Source resource management page.
            The Alias column is highlighted.
Find the data source alias in the Data sources management page.

Connector type

A report can have multiple data sources, each created by configuring a connector. To find the connector type used to create a data source:

  1. Edit the report.
  2. From the toolbar, select Resource > Manage added data sources.
  3. Examine the Connector Type column to identify the connector used to create a data source.
A list of Data Sources in the Data Source resource management page.
            The Connector Type column is highlighted.
Find the data source connector type in the Data sources management page.

Troubleshooting configuration issues

  • Use the debug dialog to review the Linking API configuration as interpreted by Data Studio. It can help to debug problems with the API.
    • When an error is encountered during the parsing of the Linking API URL, a dialog will automatically be displayed with details about the error.
    • When an error occurs and no dialog is automatically displayed, look for the info button towards the top right of the report. Click for additional debug information.
      An info button to learn how a report was created.
    • If no info button is available, you can enable the button by appending the &c.explain=true parameter to the end of any Linking API URL.
  • Ensure you have the correct template permissions set for the data source types and Linking API configuration. See Template permissions for details.
  • If you are updating a data source configuration from a data source template, review the template data source configuration and the Linking API configuration to ensure they are compatible. When performing an update vs replacement it's possible to set an invalid configuration with undefined behavior. See Replace vs update for details.

Feedback and support

Use the Issue Tracker to report Linking API issues or to provide feedback. See Support for general resources on getting help and asking questions.

Changelog

2022-06-15

  • Out of beta
    • The Integration API has been renamed to Linking API.
    • Linking API is out of beta.
  • Added the pageId control parameter to allow linking to a specific report page.
  • Added the mode control parameter to set the report state to View or Edit mode on load.
  • Data sources configurations can now be replaced entirely or partially updated. This behavior is determined by whether the ds.connector parameter is set. See Replace vs update for details.
  • A default template is now used if a report template is not provide using the c.reportId parameter.
  • Added the ds.refreshFields data source parameter. This allows you to control whether data source fields are refreshed when loading a data source configuration.
  • BigQuery connector
    • projectId is not required when type is set to CUSTOM_QUERY.
    • When billingProjectId is not set then the billing project will fallback to projectId or the project of the queried table.
    • Added support for date partitioned tables. Set the isPartitioned parameter to true to use the partition field as a date range dimension.
    • Added support for querying date partitioned tables using the wildcard character or YYYYMMDD table suffix.
    • Added support for querying Google Analytics, Firebase Analytics, or Crashlytics tables and selecting a fields tempalate.
  • Google Sheets
    • hasHeader defaults to true, consistent with the web UI default.
    • includeHiddenAndFilteredCell split into includeHiddenCells and
    • includeFilteredCells. Both now default to true, consistent with the web UI default.
  • Search Console connector
    • Renamed the propertyType parameter to searchType.
  • Surveys connector
    • surveyId now accepts a single survey ID or a comma-separated list of survey IDs.

2021-12-16

  • Initial release of the Integration API.
    • Supports linking to an existing report and setting the report name.
    • Multiple data sources can be configured and each data source name can be set.
    • Support for the following connector types: BigQuery, Cloud Spanner, Google Analytics, Google Cloud Storage, Google Sheets, Google Surveys, Search Console.