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.

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.

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:

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:

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

Create vs Add

It can sometimes be useful to have the same data source in multiple reports so updates to the data source affect all reports together. When creating a report with the Linking API, you can re-add a datasource from your template report by ensuring all the following conditions are met:

1. The data source is reusable (see embedded vs reusable data sources)
2. The url does not reference the data source by alias
3. The url does not use a wildcard alias (see Data source alias wildcard)

When a new data source is created with the Linking API, it uses the credentials of the user that clicked the url. That means the user must have access to the underlying data or the connection won't work. By re-adding the data source to the newly generated report, you can preserve its credentials so users can continue accessing data in their new reports.

Data source alias wildcard

To apply a Linking API parameter to multiple data sources, the wildcard alias ds.* can be used in place of the data source alias.

This can be useful for removing repetitive parameters from your url. For example, if you have a template with three BigQuery data sources attached, and you want to replace the projectId and datasetId in each one, but preserve the tableId, you could write it as:

  https://datastudio.google.com/reporting/create?
  c.reportId=7890
  &ds.ds1.projectId=client-project
  &ds.ds1.datasetId=client-dataset
  &ds.ds2.projectId=client-project
  &ds.ds2.datasetId=client-dataset
  &ds.ds3.projectId=client-project
  &ds.ds3.datasetId=client-dataset

Or, with the ds.* wildcard, you can use this equivalent url:

  https://datastudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset

Parameters provided to the Linking API that don't use the ds.* wildcard are given precedence over ones that are. In the example above, you can add a specific datasource alias to override the value from the wildcard.

  https://datastudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset
  &ds.ds1.datasetId=client-dataset

More generally, the order of parameter precedence is:

1. A parameter given with specific alias (ds.ds1.datasetId)
2. A parameter provided using the wildcard (ds.*.datasetId)
3. A value derived from the template datasource, if ds.connector is not provided (see Replace vs update)
4. The default value for the parameter, if it is optional.

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.

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.

CUSTOM queries

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

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

A CUSTOM_QUERY type configuration where the SQL statement of the template data source is updated using sqlReplace:

https://datastudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.sqlReplace=bigquery-public-data,new-project,samples,new-dataset

# The following shows a template query before and after sqlReplace is applied.
#
# Template data source custom query:
#   SELECT word, word_count FROM big-query-public-data.samples.shakespeare
#   INNER JOIN
#   SELECT word, word_count FROM big-query-public-data.samples.raleigh
#
# New data source custom query with sqlReplace applied:
#   SELECT word, word_count FROM new-project.new-dataset.shakespeare
#   INNER JOIN
#   SELECT word, word_count FROM new-project.new-dataset.raleigh

Cloud Spanner

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

Community Connectors

Example

Connect to a community connector with state and city configuration parameters:

https://datastudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=community
  &ds.ds5.connectorId=AqwqXxQshl94nJa0E0-1MsZXQL0DfCsJIMWk7dnx
  &ds.ds5.state=CA
  &ds.ds5.city=Sacramento

Google Analytics

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

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