Skip to content

API

Connect Looker Studio

Build Looker Studio reports on your remake numbers: score, Visibility, times cited and share of voice, run by run. Every account gets the feed. An agency reports on its brands, everyone else on their websites.

Before you start

  • An API key: the connector signs in with your key. An account holds 5 live keys at most.
  • A Google account: you deploy the connector from Google Apps Script.
  • Finished runs: the feed reports stored runs, so each brand or website you want in a report needs at least one.

On the Connections tab of Integrations, you see a Looker Studio tile under Automations. Its pill reads Connected while a live key named Looker Studio exists, and its button then reads Manage and opens Your AI. The tile's Setup guide link opens this page.

Create a key for Looker

The quickest way is the tile's Connect button:

  1. On Integrations, under Automations, click Connect on the Looker Studio tile.
  2. Your new key, named Looker Studio, is shown once. Click Show or Copy and store it.
  3. Click Open the setup guide for the steps in Google's tools, then Done — I saved it.

You can also make the key by hand:

  1. Open Your AI and go to API keys.
  2. Under Create a key, type a name such as Looker Studio.
  3. Click Create key.
  4. Click Copy and store your key. It is shown once.

Name it exactly Looker Studio and the tile reads Connected.

Looker shares your account's call limit with your other keys and connected apps. See the 120-a-minute limit.

Deploy the connector

You do this once per account.

  1. Open script.google.com and create a new project.
  2. Paste the Code.js file below into the default Code.gs file, replacing what is there.
  3. In Project Settings (the gear icon), tick Show "appsscript.json" manifest file in editor.
  4. Paste the appsscript.json file below over the file that appears.
  5. Click Deploy › Test deployments and copy the Head Deployment ID.
  6. Open this address with your ID in place:

    https://lookerstudio.google.com/datasources/create?connectorId=<DEPLOYMENT_ID>
    

A head deployment changes with every edit. For an ID that stays put, use Deploy › New deployment instead and copy that ID.

Sign the connector in

  1. In Looker Studio, authorize the connector.
  2. For Username, enter https://app.tryremake.com.
  3. For Password, paste your key, which starts with hf_.
  4. Add the data source to a report.

The key is checked as you enter it, so a typo fails at once. Each Looker user on the data source enters their own key.

The connector files

You copy each file into your Apps Script project. The connector reads its field list from the feed, so your reports and the feed always agree.

Code.js, the connector

Code.js, the connector:

/**
 * The remake Looker Studio connector.
 *
 * A community connector is a small Apps Script project: getAuthType,
 * setCredentials, getConfig, getSchema, getData. This one reads the two
 * /v1/looker endpoints with the same hf_ key every other client uses.
 * The field list is fetched live, so the fields here can never disagree
 * with the fields the feed returns. The one thing the script knows by
 * field name is how Looker should combine each number across rows
 * (ROLLUPS below).
 *
 * Every account reads the feed, agency or business: the rows are the
 * key owner's own brands or websites, nobody else's.
 *
 * Deploy steps and field meanings live at
 * https://app.tryremake.com/docs/public-api/looker-studio/
 */

var DEFAULT_SITE = 'https://app.tryremake.com';
var HELP_URL = DEFAULT_SITE + '/docs/public-api/looker-studio/';
var PAGE_SIZE = 200;              // the feed's max page size
var MAX_SLEEP_MS = 60 * 1000;     // one Retry-After wait, capped

// Property keys the framework convention expects.
var PROP_SITE = 'dscc.username';
var PROP_KEY = 'dscc.password';

// --- auth -----------------------------------------------------------------

function getAuthType(request) {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.newAuthTypeResponse()
      .setAuthType(cc.AuthType.USER_PASS)
      .setHelpUrl(HELP_URL)
      .build();
}

/**
 * The username is the site address (app.tryremake.com, or your own host
 * if you run one); the password is the key from Your AI. Both are
 * validated against /v1/me before they are stored, so a typo never
 * becomes a report that fails later.
 */
function setCredentials(request) {
  var creds = request.userPass || {};
  var site = normalizeSite_(creds.username);
  var key = (creds.password || '').trim();
  if (!site || !key || !keyWorks_(site, key)) {
    return {errorCode: 'INVALID_CREDENTIALS'};
  }
  PropertiesService.getUserProperties()
      .setProperty(PROP_SITE, site)
      .setProperty(PROP_KEY, key);
  return {errorCode: 'NONE'};
}

function isAuthValid() {
  var site = PropertiesService.getUserProperties().getProperty(PROP_SITE);
  var key = PropertiesService.getUserProperties().getProperty(PROP_KEY);
  return !!(site && key && keyWorks_(site, key));
}

function resetAuth() {
  PropertiesService.getUserProperties()
      .deleteProperty(PROP_SITE)
      .deleteProperty(PROP_KEY);
}

function isAdminUser() {
  return false;   // every connector user is their own admin here
}

// --- config -----------------------------------------------------------------

function getConfig(request) {
  var cc = DataStudioApp.createCommunityConnector();
  return cc.getConfig()
      .setDateRangeRequired(true)
      .build();
}

// --- schema -------------------------------------------------------------------

function getSchema(request) {
  var cc = DataStudioApp.createCommunityConnector();
  var fields = cc.getFields();
  apiSchema_().fields.forEach(function(f) {
    addField_(fields, cc, f);
  });
  return {schema: fields.build()};
}

// The feed's dataType → Apps Script's FieldType name. Google's list has
// no STRING (text is TEXT), and a semantic type such as
// YEAR_MONTH_DAY_SECOND is itself a FieldType: Apps Script has no
// separate setSemanticType.
var FIELD_TYPES = {STRING: 'TEXT', NUMBER: 'NUMBER', BOOLEAN: 'BOOLEAN'};

// How Looker combines a number across rows. Google's default for a
// metric is SUM, which is wrong for a score, a percentage or a rank:
// those average; the three counts add up. A metric not listed here keeps
// Google's default.
var ROLLUPS = {
  score: 'AVG', visibility_rate: 'AVG', share_of_voice: 'AVG', brand_rank: 'AVG',
  asked: 'SUM', citations: 'SUM', brand_mentions: 'SUM'
};

/** One API field dict → one connector field, every field typed. */
function addField_(fields, cc, f) {
  var semantics = f.semantics || {};
  var typeName = semantics.semanticType || FIELD_TYPES[f.dataType];
  var type = typeName ? cc.FieldType[typeName] : undefined;
  if (type === undefined) {
    throw userError_('The feed sent a field this connector cannot read (' +
                     f.name + '). Update the connector from the guide.',
                     'unknown type ' + (typeName || f.dataType) + ' on ' + f.name);
  }
  var field = (semantics.conceptType === 'METRIC')
      ? fields.newMetric() : fields.newDimension();
  field.setId(f.name)
      .setName(f.label)
      .setDescription(f.description)
      .setType(type);
  if (semantics.conceptType === 'METRIC' && ROLLUPS.hasOwnProperty(f.name)) {
    var rollup = cc.AggregationType[ROLLUPS[f.name]];
    if (rollup === undefined) {
      throw userError_('The feed sent a field this connector cannot read (' +
                       f.name + '). Update the connector from the guide.',
                       'unknown aggregation ' + ROLLUPS[f.name] + ' on ' + f.name);
    }
    field.setAggregation(rollup);
  }
  return field;
}

// --- data ---------------------------------------------------------------------

/**
 * Pages the feed until `total` rows are collected, then returns only
 * the fields the report asked for, in the order it asked for them.
 * The date range (when the report has one) rides as start/end.
 */
function getData(request) {
  var cc = DataStudioApp.createCommunityConnector();
  var schema = apiSchema_();
  var byName = {};
  schema.fields.forEach(function(f) { byName[f.name] = f; });

  // A name the schema does not have is dropped from the columns AND the
  // rows, so every value stays under its own column.
  var asked = (request.fields || []).map(function(f) { return f.name; });
  var names = asked.length
      ? asked.filter(function(name) { return byName.hasOwnProperty(name); })
      : schema.fields.map(function(f) { return f.name; });

  var fields = cc.getFields();
  names.forEach(function(name) {
    addField_(fields, cc, byName[name]);
  });

  var rows = [];
  var offset = 0;
  var total = Infinity;
  while (rows.length < total) {
    var page = apiGet_(dataPath_(request, offset));
    (page.items || []).forEach(function(item) {
      rows.push({values: names.map(function(name) {
        return valueFor_(byName[name], item[name]);
      })});
    });
    total = page.total || 0;
    if (!page.items || !page.items.length) {
      break;
    }
    offset += page.items.length;
  }

  // Older Looker releases may ask for a slice by hand; newer ones page
  // the request themselves.
  if (request.pagination && typeof request.pagination.startRow === 'number') {
    var end = request.pagination.startRow +
        (request.pagination.rowCount || rows.length);
    rows = rows.slice(request.pagination.startRow, end);
  }
  if (request.scriptParams && request.scriptParams.sampleExtraction) {
    rows = rows.slice(0, 10);   // the field-preview peek
  }

  return {schema: fields.build(), rows: rows};
}

/**
 * run_date arrives as "2026-02-05T06:00:00+00:00"; the YEAR_MONTH_DAY_
 * SECOND semantic wants "20260205060000". The offset is dropped, never
 * digit-stripped — the digits before it are the UTC moment the run
 * started. Numbers pass through; nulls land as the field's zero/blank.
 */
function valueFor_(field, value) {
  if (field === undefined) {
    return '';
  }
  if (value === null || value === undefined) {
    return field.dataType === 'NUMBER' ? 0 : '';
  }
  if (field.semantics && field.semantics.semanticType === 'YEAR_MONTH_DAY_SECOND') {
    var digits = String(value).slice(0, 19).replace(/[^0-9]/g, '');
    return digits.length === 14 ? digits : String(value);
  }
  return value;
}

function dataPath_(request, offset) {
  var params = ['limit=' + PAGE_SIZE, 'offset=' + offset];
  var range = request.dateRange || {};
  if (range.startDate) {
    params.push('start=' + encodeURIComponent(range.startDate));
  }
  if (range.endDate) {
    params.push('end=' + encodeURIComponent(range.endDate));
  }
  return '/looker/data?' + params.join('&');
}

// --- the API itself ----------------------------------------------------------

function apiSchema_() {
  return apiGet_('/looker/schema');
}

function apiGet_(path) {
  var body = fetchWithRetry_(path);
  try {
    return JSON.parse(body);
  } catch (err) {
    throw userError_('The feed sent something we could not read. Try the ' +
                     'report again.', path + ' -> not JSON');
  }
}

function fetchWithRetry_(path) {
  var site = PropertiesService.getUserProperties().getProperty(PROP_SITE);
  var key = PropertiesService.getUserProperties().getProperty(PROP_KEY);
  if (!site || !key) {
    throw userError_('Connect the data source first: the site address and ' +
                     'API key are entered in Looker Studio’s authorize ' +
                     'step.', path);
  }
  var options = {
    headers: {Authorization: 'Bearer ' + key},
    muteHttpExceptions: true
  };
  var response = UrlFetchApp.fetch(site + '/v1' + path, options);
  var code = response.getResponseCode();
  if (code === 429) {
    // The account's calls for the minute are used (reading is free, with
    // a limit per account); the feed says how long to wait.
    var wait = parseInt(headerValue_(response.getHeaders(), 'Retry-After') || '5', 10);
    Utilities.sleep(Math.min(Math.max(wait * 1000, 1000), MAX_SLEEP_MS));
    response = UrlFetchApp.fetch(site + '/v1' + path, options);
    code = response.getResponseCode();
  }
  if (code !== 200) {
    var message = 'The feed answered ' + code + '.';
    try {
      message = JSON.parse(response.getContentText()).error.message || message;
    } catch (ignored) {}
    throw userError_(message, path + ' → ' + code);
  }
  return response.getContentText();
}

/** A header by name, whatever its letter case (HTTP/2 sends lower case). */
function headerValue_(headers, name) {
  var wanted = name.toLowerCase();
  for (var k in headers) {
    if (headers.hasOwnProperty(k) && k.toLowerCase() === wanted) {
      return headers[k];
    }
  }
  return null;
}

function keyWorks_(site, key) {
  try {
    var response = UrlFetchApp.fetch(site + '/v1/me', {
      headers: {Authorization: 'Bearer ' + key},
      muteHttpExceptions: true
    });
    return response.getResponseCode() === 200;
  } catch (err) {
    return false;   // an unreachable site is not a working key
  }
}

function normalizeSite_(raw) {
  var site = (raw || '').trim().replace(/\/+$/, '');
  if (!site) {
    return '';
  }
  if (!/^https?:\/\//i.test(site)) {
    site = 'https://' + site;
  }
  return site;
}

function userError_(text, debugText) {
  return DataStudioApp.createCommunityConnector()
      .newUserError()
      .setText(text)
      .setDebugText(debugText || text)
      .throwException();
}
appsscript.json, the manifest

appsscript.json, the manifest:

{
  "timeZone": "Etc/UTC",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ],
  "dataStudio": {
    "name": "remake",
    "logoUrl": "https://app.tryremake.com/static/brand/remake-icon-512.png",
    "company": "remake",
    "companyUrl": "https://www.tryremake.com",
    "addonUrl": "https://app.tryremake.com/docs/public-api/looker-studio/",
    "supportUrl": "https://app.tryremake.com/docs/public-api/looker-studio/",
    "description": "Report remake client data in Looker Studio: score, AI visibility, citations and share of voice, one row per stored run and brand."
  }
}

The fields

The feed has one row per tracked site, stored run and brand. A tracked site is a brand or website on your list with a finished run. Looker's field names call it the client.

Your own website joins from its free run, so it is in the feed once that run finishes.

On an agency account, brands at Prospect or Pitched wait outside the feed and join once you convert them to a client. Deleted brands and websites leave it.

The tracked site comes first in each run, then its 5 most-named rivals. Those are the rivals named in the most answers across the stored runs. Rivals are businesses only: a city, region or country an answer names is left out, and a rival you added yourself is always included.

All 13 fields
Field in Looker Kind What it holds
Client domain Dimension The tracked site's domain.
Client Dimension The tracked site's name, or its domain when it has none.
Run date Dimension When the run started, in UTC.
Run number Dimension 1 is the oldest stored run in the feed.
Brand Dimension The tracked site itself, or a rival's name.
Brand role Dimension client or competitor.
Score Metric The run's Overall score, 0 to 100.
Visibility % Metric The share of the run's answers that named the tracked site.
Answers asked Metric Prompts times AI models in the run.
Times cited Metric Pages cited across the run's answers, each page once per answer.
Mentions Metric Answers in the run that named this brand.
Share of voice % Metric This brand's share of every brand mention in the run.
League rank Metric 1 is the most-named brand in the run.

Score, Visibility %, Answers asked and Times cited belong to the run. They repeat on every brand row of that run. Filter Brand role to client before you total them.

By default, Looker averages Score, Visibility %, Share of voice % and League rank across rows. It adds up Answers asked, Times cited and Mentions.

The feed holds each tracked site's last 100 finished runs. Rivals you hid stay hidden. The report's date range picks runs by the day they started, both ends included.

A new run or a change can take up to a minute to show in the feed.

The 120-a-minute limit

Your account answers 120 calls in any 60 seconds, across all its keys and connected apps. Every time your report asks for data, the connector reads all matching rows, 200 per call.

Say you track 20 brands or websites with 100 runs each. With 5 rivals per run, that is 12,000 rows, or 60 calls. Two charts asking at once pass 120 calls.

Past the limit, the connector waits as long as we ask, from 1 second up to a minute, then tries once more. If that try fails too, the chart shows the error. If your account is big:

  • Narrow the date range: fewer runs mean fewer calls.
  • Use fewer charts per page: each chart can ask on its own.

What it costs

Nothing. Reading the feed is free, and so is every call the connector makes.

Each time a chart asks for data, the connector checks your key, reads the field list once and reads the rows, 200 per call. In the example above, one chart's refresh is about 62 calls. Those calls count toward the limit above.

Check it worked

  • The data source lists 13 fields, from Client domain to League rank.
  • A table of Client, Run date and Visibility %, filtered to the client role, shows one row per run.
  • Under API keys on Your AI, your key shows when it was last used.

FAQ

Why were my credentials refused?

Check the username first: it must be https://app.tryremake.com. Then check that your key is live under API keys on Your AI, not revoked.

Can the connector change anything in my account?

No. It only reads the feed. It can't start runs or edit settings, and it never spends credit.

Why doesn't Run number start at 1 in my date range?

Run number counts every stored run, including runs outside your range. A run keeps its number when you narrow the range.