Fantasy football projections in Google Sheets and Excel

Google Sheets

Apps Script

Excel

Power Query

Auth

x-api-key header

Free plan

50 req/mo

Why can't I just paste the URL into IMPORTDATA?

Every GridIron request carries your key in the x-api-key header. The API does not read a key from the URL, which also keeps it out of browser history and shared links. Sheets' built-in IMPORTDATA and IMPORTXML can't send headers, so you need a short script. Excel's Power Query can send headers directly.

How do I pull projections into Google Sheets?

1. Get a free key and copy it from your dashboard.
2. In your sheet, open Extensions > Apps Script.
3. Paste the code below, put your key in setKey(), save, and click Run with setKey selected. Then remove the key from the code.
4. Back in the sheet, type =GRIDIRON_PROJECTIONS(8, "WR") in an empty cell.

// Extensions > Apps Script. Paste this, save, and run setKey() once.
const GRIDIRON_API = 'https://api.gridirondata.com/api/v1';

function setKey() {
  // Replace YOUR_KEY, run once, then delete the key from this line.
  PropertiesService.getScriptProperties().setProperty('GRIDIRON_API_KEY', 'YOUR_KEY');
}

/**
 * Weekly fantasy projections for one position, best first.
 * @param {number} week NFL week, 1-18 (the free plan covers the current week).
 * @param {string} position QB, RB, WR, TE, K or DST.
 * @param {string} scoring Optional: ppr (default), half or standard.
 * @return Player, team, projected points and injury status.
 * @customfunction
 */
function GRIDIRON_PROJECTIONS(week, position, scoring) {
  scoring = scoring || 'ppr';
  const cacheKey = ['proj', week, position, scoring].join(':');
  const cache = CacheService.getScriptCache();
  const cached = cache.get(cacheKey);
  if (cached) return JSON.parse(cached);

  const key = PropertiesService.getScriptProperties().getProperty('GRIDIRON_API_KEY');
  const url = GRIDIRON_API + '/projections/' + week +
      '?position=' + encodeURIComponent(position) + '&scoring=' + scoring;
  const res = UrlFetchApp.fetch(url, {
    headers: {'x-api-key': key},
    muteHttpExceptions: true
  });
  const body = JSON.parse(res.getContentText());
  if (res.getResponseCode() !== 200) {
    throw new Error((body.reason || res.getResponseCode()) + ': ' + body.error);
  }
  const rows = body.projections
    .sort(function (a, b) { return b.projected_points - a.projected_points; })
    .map(function (p) {
      return [p.player_name, p.team, p.projected_points, p.injury_status];
    });
  const table = [['Player', 'Team', 'Projected', 'Injury']].concat(rows);
  cache.put(cacheKey, JSON.stringify(table), 21600); // reuse for 6 hours
  return table;
}

The function fills four columns, best projection first. Example output; numbers change every week:

Player            Team  Projected  Injury
Ja'Marr Chase     CIN   21.4       ACTIVE
CeeDee Lamb       DAL   19.8       ACTIVE
Puka Nacua        LAR   0          OUT

Players who can't play this week (OUT, IR, bye) project 0. A few notes:

• Watch your quota. Each fresh call is one request. The script caches each result for 6 hours, so a sheet that recalculates doesn't burn your 50 free requests. One call per position covers a full lineup.
• Keep the key out of cells. Script properties are not visible in the sheet, but anyone who can edit the script can read them. Don't share edit access to the script with people who shouldn't use your key.
• Other weeks need Basic. On the free plan only the current week works; another week returns an error with reason basic_required, shown in the cell. Basic is $45 a year.

How do I pull projections into Excel?

1. In Excel for Windows, choose Data > Get Data > From Other Sources > Blank Query.
2. Click Advanced Editor, paste the query below and put your key in ApiKey.
3. If Excel asks how to connect, choose Anonymous. The key travels in the header.
4. Click Close & Load. Refresh pulls the latest numbers.

let
    ApiKey = "YOUR_KEY",
    Week = 8,
    Position = "WR",
    Response = Json.Document(
        Web.Contents(
            "https://api.gridirondata.com/api/v1",
            [
                RelativePath = "projections/" & Number.ToText(Week),
                Query = [position = Position, scoring = "ppr"],
                Headers = [#"x-api-key" = ApiKey]
            ]
        )
    ),
    Rows = Table.FromRecords(
        Response[projections],
        {"player_name", "team", "position", "projected_points", "injury_status"},
        MissingField.UseNull
    ),
    Sorted = Table.Sort(Rows, {{"projected_points", Order.Descending}})
in
    Sorted

The key is saved inside the workbook, so remove it before you send the file to anyone. Each refresh is one request per query.

What else can a spreadsheet pull?

The same pattern works for any endpoint; change the path and the columns.

A weekly sheet that checks every position on Tuesday and again on Sunday is roughly 50 to 100 requests a month, past the free cap. Basic gives 5,000 a month for $45 a year.

Frequently asked questions

Can I use IMPORTDATA or IMPORTJSON with the GridIron API?

Not directly. The key must go in the x-api-key header, and IMPORTDATA can't send headers. Use the Apps Script custom function on this page, which calls UrlFetchApp with the header.

Does this work on the free plan?

Yes, for the current NFL week's projections and player lookups. The free plan is 50 requests a month; the script caches results for 6 hours to save requests. Other weeks, stats, snaps and news need Basic ($45 a year).

Does the Excel version work on a Mac or Excel for the web?

The steps are written for Excel for Windows. Power Query features differ between Excel versions, so check that yours can create a blank query and use the Advanced Editor.

Is my API key safe in a spreadsheet?

Keep it out of cells. In Sheets, store it in script properties; in Excel, remove it from the query before you share the workbook. You can rotate a key from your dashboard.