Your First API Call with Google Apps Script UrlFetchApp Guide

by

📘 Lesson 1 — Your First API Call with Google Apps Script (UrlFetchApp Guide)

Blog Post #1 in the Apps Script + APIs + Gemini Series

Working with APIs is one of the most important skills you can learn as a Google Apps Script developer. Whether you’re building dashboards, automating workflows, or integrating AI tools like Gemini, everything starts with understanding how to make a simple HTTP request.

In this lesson, you’ll learn:

  • How to call an external API using UrlFetchApp
  • How to inspect API responses
  • How to handle errors gracefully
  • How to log data effectively
  • Practical exercises to build confidence

Let’s begin.

🔧 What You’ll Build

You’ll create a simple Apps Script function that fetches data from a public “Random Joke” API. This is a no-auth API — perfect for learning without complications.

📍 Step 1 — Create a New Apps Script Project

You can create a new script through:

Option A: Google Sheets

  1. Open a new Google Sheet
  2. Extensions → Apps Script

Option B: script.new

Visit: https://script.new

Delete any boilerplate code so you can start fresh.

🧠 Step 2 — Make Your First API Call

Copy/paste the following code into your script:

/**
 * Lesson 1: Call a public API and log the result.
 */
function callJokeApi() {
  // 1. URL of the public API
  var url = 'https://official-joke-api.appspot.com/jokes/random';

  // 2. Request options
  var options = {
    method: 'get',
    muteHttpExceptions: true
  };

  // 3. Send HTTP GET request
  var response = UrlFetchApp.fetch(url, options);

  // 4. Read status + body
  var statusCode = response.getResponseCode();
  var body = response.getContentText();

  // 5. Log output
  Logger.log('Status: ' + statusCode);
  Logger.log('Raw Response: ' + body);
}

🔍 Step 3 — Run the Script

  1. Click Run → callJokeApi
  2. Accept the permissions
  3. Click View → Logs

You should see something like:

Status: 200
Raw Response: {"type":"general","setup":"Why ...","punchline":"..."}

📘 Understanding the Code (Line by Line)

URL

var url = 'https://official-joke-api.appspot.com/jokes/random';

This is the API endpoint. It returns one random joke in JSON format.

Request Options

muteHttpExceptions: true

Allows you to see full error messages instead of Apps Script throwing an exception.

Fetch the API

var response = UrlFetchApp.fetch(url, options);

This is the core API call. It returns a HTTPResponse object.

Reading the Response

var status = response.getResponseCode();
var body = response.getContentText();
  • status tells you if it succeeded (200 OK)
  • body is the raw string returned by the server

🧪 Exercises to Practice

Exercise 1 — Call a Different API

Replace the joke API with ANY public API (cat facts, weather, Pokemon, etc.).

Examples:

https://catfact.ninja/fact
https://dog.ceo/api/breeds/image/random

Log the results.

Exercise 2 — Break the URL on Purpose

Change the URL to something invalid:

https://official-joke-api.appspot.com/jokes/ranDOM123

Then:

  • Log the status code
  • Display a helpful error
  • Observe how the API handles invalid requests

Exercise 3 — Pretty-Print JSON

Modify the logger line:

Logger.log(JSON.stringify(JSON.parse(body), null, 2));

This formats JSON nicely so you can see the structure clearly.

💡 Pro Tips for Beginners

Tip 1 — Always Log Responses

APIs vary. Before writing complex code, inspect the real response.

Tip 2 — Use try {} for Error Handling

As your code grows, wrap your calls:

try {
  // API code
} catch (err) {
  Logger.log('Error: ' + err.message);
}

Tip 3 — Start with Simple Public APIs

Stay away from OAuth APIs until comfortable with basic requests.

View Post(opens in a new tab)

🎉 What’s Next?

In Lesson 2, you’ll:

  • Parse JSON data
  • Extract fields
  • Write API results directly into Google Sheets
  • Generate Docs output from API responses