Lumirank API docs

Weekly share of voice in Google Sheets

An Apps Script that fills a Google Sheet with your weekly share of voice, and updates it every Monday.

  1. In your sheet, open Extensions > Apps Script.
  2. Open Project Settings > Script Properties and add LUMIRANK_API_KEY with a read key as its value. This keeps the key out of the sheet itself.
  3. Paste this script and run updateShareOfVoice once. Allow the access that it asks for.
function updateShareOfVoice() {
  const key = PropertiesService.getScriptProperties().getProperty('LUMIRANK_API_KEY');
  const day = (date) => Utilities.formatDate(date, 'UTC', 'yyyy-MM-dd');
  const end = new Date();
  const start = new Date(end.getTime() - 83 * 24 * 60 * 60 * 1000); // 12 weeks, the most is 90 days
  const url = 'https://api.lumirank.ai/v1/reports/brands?dimensions=week'
    + '&start_date=' + day(start) + '&end_date=' + day(end);
  const resp = UrlFetchApp.fetch(url, {
    headers: { Authorization: 'Bearer ' + key },
    muteHttpExceptions: true,
  });
  if (resp.getResponseCode() !== 200) {
    throw new Error(resp.getContentText());
  }
  const rows = JSON.parse(resp.getContentText()).data;
  const book = SpreadsheetApp.getActive();
  const sheet = book.getSheetByName('Share of voice') || book.insertSheet('Share of voice');
  const values = [['week', 'brand', 'share_of_voice', 'visibility', 'ranked', 'answers']].concat(
    rows.map((r) => [r.week, r.competitor_name, r.share_of_voice, r.visibility, r.ranked, r.answers]));
  sheet.clearContents();
  sheet.getRange(1, 1, values.length, values[0].length).setValues(values);
}
  1. Open Triggers and add a trigger for updateShareOfVoice. Set it to run on a timer, every week, on Monday after 12:00 UTC.

Format the share_of_voice and visibility columns as percentages. For a chart with 1 line per brand, make a pivot table with week as its rows and brand as its columns.

The 1st and the last week can have fewer than 7 days, because a week at the start or end of the date range counts only the days inside the range.