Fetch data from web APIs

function previewRequest() {
  const baseUrl = 'https://example.com/api/requests';
  const query = 'status=open&limit=10';
  const request = UrlFetchApp.getRequest(baseUrl + '?' + query, {
    headers: { Accept: 'application/json' },
    method: 'get',
  });

  Logger.log(JSON.stringify(request, null, 2));
}

{
  "timeZone": "Etc/UTC",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

{
  "baseUrl": "https://example.com/api/requests",
  "query": {
    "status": "open",
    "limit": 10
  },
  "headers": {
    "Accept": "application/json"
  }
}

const FORECAST_DAYS = 7;
const FORECAST_LATITUDE = 52.52;
const FORECAST_LONGITUDE = 13.41;
const FORECAST_OWNER_MARKER = 'Owned by weather-import';

/**
 * A property-access view for validation, not a validated provider response.
 * Every data field remains unknown until the checks in forecastRows succeed.
 * @typedef {{daily?: {time?: unknown, temperature_2m_max?: unknown, temperature_2m_min?: unknown}|null, daily_units?: {temperature_2m_max?: unknown, temperature_2m_min?: unknown}|null}} ForecastCandidate
 */

function importForecastToSheet() {
  if (!Number.isInteger(FORECAST_DAYS) || FORECAST_DAYS < 1 || FORECAST_DAYS > 7) {
    throw new Error('Set FORECAST_DAYS to a whole number from 1 to 7.');
  }
  if (!Number.isFinite(FORECAST_LATITUDE) || Math.abs(FORECAST_LATITUDE) > 90 ||
      !Number.isFinite(FORECAST_LONGITUDE) || Math.abs(FORECAST_LONGITUDE) > 180) {
    throw new Error('Use numeric latitude from -90 to 90 and longitude from -180 to 180.');
  }

  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) {
    throw new Error('Open this project through Extensions > Apps Script in the practice spreadsheet.');
  }
  const sheet = spreadsheet.getSheetByName('Forecast');
  if (!sheet) {
    throw new Error('Create a blank tab named Forecast before running this function.');
  }
  const target = sheet.getRange('A1:C12');
  checkForecastDestination(target, sheet);

  const query = [
    'latitude=' + encodeURIComponent(FORECAST_LATITUDE),
    'longitude=' + encodeURIComponent(FORECAST_LONGITUDE),
    'daily=temperature_2m_max,temperature_2m_min',
    'temperature_unit=celsius',
    'timezone=auto',
    'forecast_days=' + FORECAST_DAYS
  ].join('&');
  const response = UrlFetchApp.fetch('https://api.open-meteo.com/v1/forecast?' + query, {
    method: 'get',
    headers: { Accept: 'application/json' },
    muteHttpExceptions: true,
    followRedirects: false
  });
  const statusCode = response.getResponseCode();
  if (statusCode !== 200) {
    throw new Error('The forecast service answered with status code ' + statusCode + '. No cells were written.');
  }
  const contentType = forecastHeader(response.getAllHeaders(), 'content-type');
  if (contentType.split(';')[0].trim().toLowerCase() !== 'application/json') {
    throw new Error('The forecast response was not application/json. No cells were written.');
  }
  const text = response.getContentText('UTF-8');
  if (text.length > 50000) {
    throw new Error('The forecast response exceeded the 50000-character parsing limit.');
  }
  /** @type {unknown} */
  let forecast;
  try {
    forecast = JSON.parse(text);
  } catch (error) {
    throw new Error('The forecast response was not valid JSON. No cells were written.');
  }

  const rows = forecastRows(forecast, FORECAST_DAYS);
  // Check again after the request in case the destination changed while it was pending.
  checkForecastDestination(target, sheet);
  target.setValues(rows);
  Logger.log('Wrote ' + FORECAST_DAYS + ' days of forecast.');
}

/**
 * @param {SpreadsheetApp.Range} target
 * @param {SpreadsheetApp.Sheet} sheet
 * @returns {void}
 */
function checkForecastDestination(target, sheet) {
  if (target.isPartOfMerge()) {
    throw new Error('Forecast!A1:C12 must not overlap merged cells.');
  }
  if (target.isBlank()) return;
  const markerCell = sheet.getRange('A12');
  if (markerCell.getValue() !== FORECAST_OWNER_MARKER || markerCell.getFormula() !== '') {
    throw new Error('Forecast!A1:C12 is not blank and has no valid ownership marker. Use a new practice sheet; do not clear existing data to bypass this check.');
  }
}

/**
 * @param {unknown} rawForecast
 * @param {number} expectedDays
 * @returns {Array<Array<string|number>>}
 */
function forecastRows(rawForecast, expectedDays) {
  // This view permits property probes; the original runtime checks still validate the value.
  const forecast = /** @type {ForecastCandidate|null|undefined} */ (rawForecast);
  if (!forecast || typeof forecast !== 'object' || Array.isArray(forecast) ||
      !forecast.daily || !forecast.daily_units) {
    throw new Error('The forecast response is missing daily data or units.');
  }
  const days = forecast.daily.time;
  const highs = forecast.daily.temperature_2m_max;
  const lows = forecast.daily.temperature_2m_min;
  if (!Array.isArray(days) || !Array.isArray(highs) || !Array.isArray(lows) ||
      days.length !== expectedDays || highs.length !== expectedDays || lows.length !== expectedDays) {
    throw new Error('The forecast arrays must each contain exactly ' + expectedDays + ' days.');
  }
  if (forecast.daily_units.temperature_2m_max !== '°C' ||
      forecast.daily_units.temperature_2m_min !== '°C') {
    throw new Error('The forecast temperature units must be Celsius.');
  }

  /** @type {Array<Array<string|number>>} */
  const rows = [['Date', 'High', 'Low']];
  let index = 0;
  /** @type {number|null} */
  let previousDay = null;
  while (index < expectedDays) {
    /** @type {unknown} */
    const day = days[index];
    /** @type {unknown} */
    const high = highs[index];
    /** @type {unknown} */
    const low = lows[index];
    if (typeof day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(day)) {
      throw new Error('Forecast day ' + (index + 1) + ' is not a YYYY-MM-DD date.');
    }
    const timestamp = Date.parse(day + 'T00:00:00Z');
    if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString().slice(0, 10) !== day ||
        (previousDay !== null && timestamp - previousDay !== 86400000)) {
      throw new Error('Forecast dates must be valid consecutive calendar days.');
    }
    if (!Number.isFinite(high) || !Number.isFinite(low) ||
        /** @type {number} */ (high) < /** @type {number} */ (low)) {
      throw new Error('Forecast day ' + (index + 1) + ' needs numeric high and low temperatures with high >= low.');
    }
    rows.push([day, /** @type {number} */ (high), /** @type {number} */ (low)]);
    previousDay = timestamp;
    index = index + 1;
  }
  // The fixed output area has room for seven days, even when fewer are requested.
  while (rows.length < 8) {
    rows.push(['', '', '']);
  }
  rows.push(['Weather data by Open-Meteo', 'https://open-meteo.com/', '']);
  rows.push(['Licence: CC BY 4.0', 'https://creativecommons.org/licenses/by/4.0/', '']);
  rows.push(['Selected daily highs/lows; Celsius; local dates', '', '']);
  rows.push([FORECAST_OWNER_MARKER, '', '']);
  return rows;
}

/**
 * @param {Record<string, string|string[]>} headers
 * @param {string} wantedName
 * @returns {string}
 */
function forecastHeader(headers, wantedName) {
  for (const name of Object.keys(headers)) {
    if (name.toLowerCase() === wantedName) {
      const value = headers[name];
      if (Array.isArray(value)) return value.join(', ');
      return String(value);
    }
  }
  return '';
}

{
  "timeZone": "Etc/UTC",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/spreadsheets.currentonly"
  ]
}

Wrote 7 days of forecast.

const TAG_MAX_PAGES = 2;
const TAG_MAX_ITEMS = 10;
const TAG_PAGE_SIZE = 5;
const TAG_ENDPOINT = 'https://api.github.com/repos/microsoft/TypeScript/tags';

/** @typedef {{name: string, commit: {sha: string}}} RepositoryTag */
/**
 * A property-access view only; name and SHA are unknown until readTagPage validates them.
 * @typedef {{name?: unknown, commit?: {sha?: unknown}|null}|null|undefined} TagCandidate
 */

function listPublicRepositoryTags() {
  if (!Number.isInteger(TAG_MAX_PAGES) || TAG_MAX_PAGES < 1 || TAG_MAX_PAGES > 3 ||
      !Number.isInteger(TAG_MAX_ITEMS) || TAG_MAX_ITEMS < 1 || TAG_MAX_ITEMS > 15 ||
      TAG_PAGE_SIZE !== 5) {
    throw new Error('Use 1-3 pages, 1-15 items, and a page size of 5.');
  }

  const progress = { httpAttempts: 0 };
  const tags = [];
  let pagesRead = 0;
  /** @type {string|null} */
  let url = TAG_ENDPOINT + '?per_page=' + TAG_PAGE_SIZE + '&page=1';
  let complete = false;
  let stopReason = '';
  /** @type {unknown} */
  let failure = null;

  try {
    while (url !== null) {
      if (pagesRead >= TAG_MAX_PAGES) {
        stopReason = 'page limit reached; more pages available';
        break;
      }
      if (tags.length >= TAG_MAX_ITEMS) {
        stopReason = 'item limit reached; more data available';
        break;
      }
      checkTagPageUrl(url, pagesRead + 1);
      const response = fetchTagPage(url, progress);
      const headers = response.getAllHeaders();
      const page = readTagPage(response, headers);
      const nextUrl = nextTagPageUrl(headers);
      if (nextUrl !== null) checkTagPageUrl(nextUrl, pagesRead + 2);

      const room = TAG_MAX_ITEMS - tags.length;
      for (const tag of page) {
        if (tags.length >= TAG_MAX_ITEMS) break;
        tags.push({ name: tag.name, sha: tag.commit.sha });
      }
      pagesRead = pagesRead + 1;
      if (page.length > room) {
        stopReason = 'item limit reached within a validated page';
        break;
      }
      url = nextUrl;
      if (url === null) {
        complete = true;
        stopReason = 'no next link reported';
      } else if (pagesRead < TAG_MAX_PAGES && tags.length < TAG_MAX_ITEMS &&
                 tagHeader(headers, 'x-ratelimit-remaining') === '0') {
        throw new Error('GitHub reports no requests remaining. ' + tagWaitDetails(headers));
      }
    }
  } catch (error) {
    failure = error;
    stopReason = String(error);
  }

  let resultLabel = 'partial';
  if (complete) resultLabel = 'complete';
  Logger.log('Repository: microsoft/TypeScript');
  Logger.log('Pages accepted: ' + pagesRead + '; HTTP attempts: ' + progress.httpAttempts);
  Logger.log('Tags collected: ' + tags.length);
  Logger.log('Result: ' + resultLabel + '; ' + stopReason);
  Logger.log('Tag names: ' + JSON.stringify(tags.map((tag) => tag.name)));
  if (failure !== null) throw failure;
}

/**
 * @param {string} url
 * @param {{httpAttempts: number}} progress
 * @returns {UrlFetchApp.HTTPResponse}
 */
function fetchTagPage(url, progress) {
  let attempt = 0;
  while (attempt < 3) {
    attempt = attempt + 1;
    progress.httpAttempts = progress.httpAttempts + 1;
    // Exceptions without an HTTP response are not automatically retried.
    const response = UrlFetchApp.fetch(url, {
      method: 'get',
      headers: {
        Accept: 'application/vnd.github+json',
        'X-GitHub-Api-Version': '2026-03-10',
        'User-Agent': 'apps-script-book-http-pagination'
      },
      muteHttpExceptions: true,
      followRedirects: false
    });
    const status = response.getResponseCode();
    const headers = response.getAllHeaders();
    if (status === 200) return response;

    if (status === 403 || status === 429 ||
        tagHeader(headers, 'retry-after') !== '' ||
        tagHeader(headers, 'x-ratelimit-remaining') === '0') {
      throw new Error('GitHub HTTP ' + status + '; no automatic retry. ' + tagWaitDetails(headers));
    }
    const transient = status === 500 || status === 502 || status === 503 || status === 504;
    if (!transient || attempt === 3) {
      throw new Error('GitHub HTTP ' + status + ' after ' + attempt + ' attempt(s) for this page. Requests stopped.');
    }
    // Only these read-only GET failures are retried: wait 1 second, then 2 seconds.
    Utilities.sleep(attempt * 1000);
  }
  throw new Error('The page attempt limit was reached.');
}

/**
 * @param {UrlFetchApp.HTTPResponse} response
 * @param {Record<string, string|string[]>} headers
 * @returns {RepositoryTag[]}
 */
function readTagPage(response, headers) {
  const contentType = tagHeader(headers, 'content-type').split(';')[0].trim().toLowerCase();
  if (contentType !== 'application/json' && contentType !== 'application/vnd.github+json') {
    throw new Error('GitHub returned an unexpected content type.');
  }
  const text = response.getContentText('UTF-8');
  if (text.length > 100000) {
    throw new Error('The GitHub response exceeded the 100000-character parsing limit.');
  }
  /** @type {unknown} */
  let page;
  try {
    page = JSON.parse(text);
  } catch (error) {
    throw new Error('GitHub returned invalid JSON.');
  }
  if (!Array.isArray(page) || page.length > TAG_PAGE_SIZE) {
    throw new Error('Expected an array containing at most five GitHub tags.');
  }
  for (const tag of /** @type {TagCandidate[]} */ (page)) {
    if (!tag || typeof tag !== 'object' || Array.isArray(tag) ||
        typeof tag.name !== 'string' || tag.name.length === 0 || tag.name.length > 256 ||
        !tag.commit || typeof tag.commit.sha !== 'string' ||
        !/^[0-9a-f]{40}$/.test(tag.commit.sha)) {
      throw new Error('A GitHub tag is missing its expected name or commit SHA.');
    }
  }
  return /** @type {RepositoryTag[]} */ (page);
}

/**
 * @param {Record<string, string|string[]>} headers
 * @returns {string|null}
 */
function nextTagPageUrl(headers) {
  const link = tagHeader(headers, 'link');
  if (link === '') return null;
  if (link.length > 8000) throw new Error('GitHub pagination headers exceeded this example\'s limit.');
  /** @type {string|null} */
  let next = null;
  for (const entry of link.split(',')) {
    const match = entry.trim().match(/^<([^<>]+)>;\s*rel="(next|prev|first|last)"$/);
    if (!match) throw new Error('GitHub returned an unsupported pagination link format.');
    if (match[2] === 'next') {
      if (next !== null) throw new Error('GitHub returned more than one next-page link.');
      next = match[1];
    }
  }
  return next;
}

/**
 * @param {string} url
 * @param {number} expectedPage
 * @returns {void}
 */
function checkTagPageUrl(url, expectedPage) {
  // GitHub may use this repository's numeric API path in pagination links.
  const namedPrefix = TAG_ENDPOINT + '?';
  const numericPrefix = 'https://api.github.com/repositories/20929025/tags?';
  let query;
  if (url.startsWith(namedPrefix)) {
    query = url.slice(namedPrefix.length);
  } else if (url.startsWith(numericPrefix)) {
    query = url.slice(numericPrefix.length);
  } else {
    throw new Error('Refusing a page URL outside the expected GitHub repository tags endpoint.');
  }
  const parameters = query.split('&');
  if (parameters.length !== 2) throw new Error('Refusing unexpected pagination query parameters.');
  /** @type {string|null} */
  let page = null;
  /** @type {string|null} */
  let pageSize = null;
  for (const parameter of parameters) {
    const pair = parameter.split('=');
    if (pair.length !== 2) throw new Error('Refusing a malformed pagination query.');
    if (pair[0] === 'page' && page === null) {
      page = pair[1];
    } else if (pair[0] === 'per_page' && pageSize === null) {
      pageSize = pair[1];
    } else {
      throw new Error('Refusing unknown or repeated pagination parameters.');
    }
  }
  if (page !== String(expectedPage) || pageSize !== String(TAG_PAGE_SIZE)) {
    throw new Error('Refusing a repeated, skipped or resized next page.');
  }
}

/**
 * @param {Record<string, string|string[]>} headers
 * @param {string} wantedName
 * @returns {string}
 */
function tagHeader(headers, wantedName) {
  for (const name of Object.keys(headers)) {
    if (name.toLowerCase() === wantedName) {
      const value = headers[name];
      if (Array.isArray(value)) return value.join(', ');
      return String(value);
    }
  }
  return '';
}

/**
 * @param {Record<string, string|string[]>} headers
 * @returns {string}
 */
function tagWaitDetails(headers) {
  const details = {
    retryAfterSeconds: tagHeader(headers, 'retry-after').slice(0, 80),
    remaining: tagHeader(headers, 'x-ratelimit-remaining').slice(0, 80),
    resetEpochSeconds: tagHeader(headers, 'x-ratelimit-reset').slice(0, 80)
  };
  return 'Rate headers: ' + JSON.stringify(details) +
    '. Honor Retry-After and any exhausted-budget reset before another run. ' +
    'For a secondary limit without those headers, wait at least one minute; do not repeatedly rerun. ' +
    'A 403 can also require a permission or policy fix.';
}

{
  "timeZone": "Etc/UTC",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

Repository: microsoft/TypeScript
Pages accepted: 2; HTTP attempts: 2
Tags collected: 10
Result: partial; page limit reached; more pages available