Scriptable widget example with API call

scriptable_api_widget_example.js

// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: green; icon-glyph: database;
// A basic widget to demonstrate how to display the result of an API

// Initialize the widget
const widget = new ListWidget();


// We can use a variable to control multiple properties, in this case the widget padding
const padding = 2;
widget.setPadding(padding, padding, padding, padding);


// We define a new variable "data" to store the response from our API
const data = await loadDataFromAPI();


// Build the dynamic part of the widget once all of our async calls have finished
await buildWidget(data);


// This function defines the layout of our widget's API response section.
async function buildWidget(data) {
	
	// Everything in a widget is displayed in a stack. This stack defines the header.
	const headerStack = widget.addStack(); // Initialize the stack
	headerStack.setPadding(0, 0, 25, 0); // Set some padding on the bottom of the stack
	const headerText = headerStack.addText("My API Widget"); // Add some text to the stack
	headerText.font = Font.mediumSystemFont(14); // Define a font on the text
  
  // Initialize a new stack to contain the API value
  const apiResponseStack = widget.addStack();
  apiResponseStack.setPadding(padding, padding, padding, padding);

  
  // We add text to the stack that contains the API response
  const apiResponseText = apiResponseStack.addText(data); // Add the text to the stack
  apiResponseText.font = Font.mediumSystemFont(18); // Set the text font size
  apiResponseText.textColor = Color.green(); // Set the text color
}


// This function contains our API call
async function loadDataFromAPI() {
  const URL = `https://api.sampleapis.com/switch/games`; // This is the URL of our API
  const apiRequest = new Request(URL); // We create a Request to load data from the URL
  const apiResponse = await apiRequest.loadJSON(); // We then parse the result of the request
  
  // console.log() is a function that logs information to the console. The result of
  // this function is not visible in the widget, but you can see it by clicking on the
  // console button in the bottom right. It's useful to examine the result of the API
  // request.
  //console.log(apiResponse);
  
  // If you look at the console, you can see our API returns a lot of data. We
  // only want to return a single string, so we assign a variable with the
  // part of the response we want to keep and then return that.
  //
  // apiResponse is an array (list) of objects (list with named entries).
  // We are grabbing the "name" property from the fourth item in the list.
  const returnValue = apiResponse[3].name;
  
  return returnValue;
}


// Assign the widget
Script.setWidget(widget);

// Calling Script.complete() signals to Scriptable that the script have finished running.
// This can speed up the execution, in particular when running the script from Shortcuts or using Siri.
Script.complete()