Page Summary

outlined_flag

• Google Apps Script can interact with various web APIs using the UrlFetch service.

• For APIs requiring user authorization via OAuth, open source libraries for OAuth1 and OAuth2 are available.

• Working with JSON responses involves usinggetContentText() andJSON.parse(), while creating JSON payloads usesJSON.stringify().

• Handling XML responses and requests usesgetContentText() and the XmlService methods.

Google Apps Script can interact with APIs from all over the web. This guideshows how to work with different types of APIs in your scripts.

Connect to public APIs

You can use theUrlFetch service to makeAPI requests directly.

The following example uses theGitHub API tosearch for repositories with 100 or more stars that mention "Apps Script".This API request does not require authorization or an API key.

varquery='"Apps Script" stars:">=100"';varurl='https://api.github.com/search/repositories'+'?sort=stars'+'&q='+encodeURIComponent(query);varresponse=UrlFetchApp.fetch(url,{'muteHttpExceptions':true});Logger.log(response);

Make requests to services with OAuth

APIs that act on behalf of a user usually require authorization, often using theOAuth protocol. Apps Script doesn't provide built-insupport for the protocol, but there are open source libraries you can use toperform the OAuth flow and send the credentials with your requests:

• OAuth1 for Apps Script:Compatible with OAuth 1.0 and 1.0a.
• OAuth2 for Apps Script:Compatible with OAuth2.

Work with JSON

Working with JSON objects is similar to working with XML, except that parsing orencoding a JSON object is much easier.

If the API being requested returns a raw JSON response for a request, the JSONstring response can be accessed using the methodHTTPResponse.getContentText().Once this string is retrieved, simply callJSON.parse() on the string to get anative object representation.

//MakerequesttoAPIandgetresponsebeforethispoint.varjson=response.getContentText();vardata=JSON.parse(json);Logger.log(data.title);

Likewise, to make a string representation of a JavaScript object in order tomake a request, useJSON.stringify().

vardata={'entry':{'group':{'title':'Dog Skateboarding','description':'My dog gets some serious air'},'keywords':'dog, skateboard'}}varpayload=JSON.stringify(data);//MakerequesttoAPIwithpayloadafterthispoint.

Parse XML

If an external API returns a raw XML response for a request, you can access theXML response using the methodHTTPResponse.getContentText().

//MakerequesttoAPIandgetresponsebeforethispoint.varxml=response.getContentText();vardoc=XmlService.parse(xml);

When making XML requests to an API, construct the XML to send by usingtheXmlService methods.

varroot=XmlService.createElement('entry').setAttribute('keywords','dog, skateboard');vargroup=XmlService.createElement('group').setAttribute('title','Dog Skateboarding');.setAttribute('description','My dog gets some serious air');root.addContent(group);vardocument=XmlService.createDocument(root);varpayload=XmlService.getPrettyFormat().format(document);//MakerequesttoAPIwithpayloadafterthispoint.