Looker Studio Custom Connector Guide

Looker Studio Custom Connector Guide

Learn how to build, deploy, and maintain Looker Studio custom connectors so you can query any data source directly from Google’s free BI tool.

Definition

A Looker Studio custom connector (formerly Google Data Studio community connector) is a piece of code written in Google Apps Script that implements Google’s Connector API. When installed in a Looker Studio report, the connector authenticates to an external data source, builds a schema, and requests data so that Looker Studio can model and visualize it just like a built-in Google connector.

Why Custom Connectors Matter for Data Engineering

Modern analytics stacks rarely live exclusively inside Google’s ecosystem. Teams need dashboards that combine in-app product metrics, third-party SaaS data, and operational databases. Custom connectors let engineers expose any data—whether it’s a public REST API, an on-premise SQL database, or a vendor without an official connector—directly to business users in Looker Studio. The result is fewer CSV exports, less manual ETL, and faster, self-service insights.

How a Custom Connector Works

1. Apps Script Project

You create a standalone Apps Script project inside Google Apps Script IDE. The project defines at least six mandatory functions (getConfig, getAuthType, isAuthValid, getSchema, getData, and resetAuth), plus optional helpers.

2. Authentication Flow

The connector specifies an auth type—None, OAuth2, or User-name/Password. OAuth2 is most common. The connector stores user tokens in PropertiesService and refreshes them automatically.

3. Configuration Phase

When a user adds the connector to Looker Studio, the getConfig function runs, presenting UI fields (e.g., API key, account ID) that tailor the connector to the user’s data.

4. Schema Discovery

getSchema returns an array of fields with IDs, names, and data types. This is how Looker Studio knows what dimensions and metrics are available.

5. Data Fetching

During report rendering, Looker Studio calls getData with user-selected fields, date ranges, and pagination rules. Your code translates that request into API calls or SQL queries, maps results back to Looker Studio’s response format, and returns data.

Step-by-Step Build Guide

Step 1 — Bootstrap the Project

Open script.google.com ➜ New Project ➜ Rename to MyCustomConnector. Enable the Data Studio API advanced service.

Step 2 — Set Up OAuth2 (if needed)

Add the OAuth2 library (1B7F8cGaea4CRuJF-KZwWx0iDHzysAafu). Configure the provider endpoints and scopes:

function getOAuthService() {
return OAuth2.createService('VendorAPI')
.setAuthorizationBaseUrl('https://vendor.com/oauth/authorize')
.setTokenUrl('https://vendor.com/oauth/token')
.setClientId(CLIENT_ID)
.setClientSecret(CLIENT_SECRET)
.setScope('read_metrics');
}

Step 3 — Implement Mandatory Functions

function getConfig() {
var cc = DataStudioApp.createConfig();
cc.newTextInput().setId('accountId').setName('Account ID').setHelpText('Enter your Vendor account ID');
return cc.build();
}

function getAuthType() {
return {type: 'OAUTH2'}; // or NONE / USER_PASS
}

function isAuthValid() {
return getOAuthService().hasAccess();
}

function getSchema(request) {
return {schema: [
{name: 'date', label: 'Date', dataType: 'DATE', semantics: {conceptType: 'DIMENSION'}},
{name: 'sessions', label: 'Sessions', dataType: 'NUMBER', semantics: {conceptType: 'METRIC'}}
]};
}

function getData(request) {
var requestedFields = request.fields.map(function(f){ return f.name; });
var rows = fetchVendorData(request);
return {schema: getSchema().schema, rows: rows};
}


Step 4 — Deploy

Publish ➜ Deploy from manifest… ➜ Set Add-on type to Data Studio Connector. Set OAuth consent screen, scopes, and add authorized domains. Click Deploy. Looker Studio users can now find the connector under Community Connectors.

Practical Example

Suppose you need to visualize GitHub issues in Looker Studio. GitHub offers a REST API but not a native connector. A custom connector can:

1. Prompt for a personal access token and repo owner/name.
2. Call https://api.github.com/repos/{owner}/{repo}/issues.
3. Return fields like issue_number, title, state, created_at.
4. Drive a dashboard of open vs. closed issues over time.

Best Practices

Cache Aggressively

API quotas can be tight. Use CacheService to store responses for commonly requested date ranges.

Respect Quotas with Pagination

Looker Studio may request up to 10,000 rows. Implement pagination and request.configParams.pageSize to stay within API limits.

Use Numeric IDs for Field Names

Field IDs should not change once users have built reports. Store stable machine IDs internally and display friendly labels.

Automate Unit Tests

Use clasp (Command Line Apps Script) to pull code locally and run Jest/Mocha tests for schema and data-format validation.

Common Mistakes and How to Fix Them

1. Ignoring Date Range Handling

Why it’s wrong: Hard-coding dates forces users to create multiple connectors for different ranges.
Fix: Always honor request.dateRange and translate it into API parameters (e.g., start_date, end_date).

2. Returning Variable Schemas

Why it’s wrong: If getSchema changes based on user selections, reports break when fields disappear.
Fix: Return a superset schema and let request.fields filter columns at runtime.

3. Storing Secrets in Code

Why it’s wrong: Hard-coded API keys can leak in version control.
Fix: Use PropertiesService.getScriptProperties() to store secrets, or prompt users via getConfig.

Galaxy and Custom Connectors

While Looker Studio custom connectors run in Apps Script rather than SQL, Galaxy can still help when the upstream data source is a SQL database. You can prototype and optimize SQL queries in Galaxy’s lightning-fast editor, then embed those queries inside your connector’s getData function or expose them via a REST API your connector consumes. Galaxy’s AI Copilot can also document column semantics that map to Looker Studio field metadata.

Complete Code Example

/**
* GitHub Issues Looker Studio Connector
* Author: Example
*/

var GITHUB_API = 'https://api.github.com/repos/';

function getAuthType() {
return {type: 'NONE'}; // GitHub PAT is passed as config param
}

function getConfig() {
var cc = DataStudioApp.createConfig();
cc.setDateRangeRequired(false);
cc.newTextInput().setId('owner').setName('Repository Owner').setHelpText('e.g. galaxyhq');
cc.newTextInput().setId('repo').setName('Repository Name').setHelpText('e.g. galaxy');
cc.newTextInput().setId('token').setName('GitHub Personal Access Token');
return cc.build();
}

function getSchema() {
var fields = [
{name: 'number', label: 'Issue #', dataType: 'NUMBER', semantics: {conceptType: 'DIMENSION'}},
{name: 'state', label: 'State', dataType: 'TEXT', semantics: {conceptType: 'DIMENSION'}},
{name: 'title', label: 'Title', dataType: 'TEXT', semantics: {conceptType: 'DIMENSION'}},
{name: 'created', label: 'Created At', dataType: 'YEAR_MONTH_DAY', semantics: {conceptType: 'DIMENSION'}},
{name: 'closed', label: 'Closed At', dataType: 'YEAR_MONTH_DAY', semantics: {conceptType: 'DIMENSION'}},
];
return {schema: fields};
}

function getData(request) {
var owner = request.configParams.owner;
var repo = request.configParams.repo;
var token = request.configParams.token;
var endpoint = GITHUB_API + owner + '/' + repo + '/issues?per_page=100&state=all';
var headers = {Authorization: 'token ' + token, 'User-Agent': 'looker-connector'};
var response = UrlFetchApp.fetch(endpoint, {headers: headers});
var json = JSON.parse(response.getContentText());
var requested = request.fields.map(function(f){ return f.name; });
var rows = json.map(function(issue){
return {values: [issue.number, issue.state, issue.title, issue.created_at.substr(0,10), issue.closed_at ? issue.closed_at.substr(0,10) : '']};
});
return {schema: getSchema().schema, rows: rows};
}


Frequently Asked Questions

How do I share a custom connector within my organization?

You can deploy it as Unlisted and whitelist specific domains, or publish it publicly in the Connector Gallery after Google’s review.

Can I monetize a Looker Studio custom connector?

Yes. Many vendors (e.g., Supermetrics) sell connectors via subscription. You handle billing externally and gate premium features with OAuth scopes or config parameters.

Is Galaxy useful when working with Looker Studio custom connectors?

Absolutely—if your connector queries a SQL database, develop and optimize those SQL statements in Galaxy, then embed them or expose them via an API your connector calls.

What are the quota limits for community connectors?

Apps Script imposes an execution time limit of 30 seconds per call and a 6-minute daily quota per user. Paginate and cache to stay under these ceilings.