Class UrlFetchApp

  • UrlFetchApp enables scripts to communicate with external hosts and access web resources by fetching URLs using HTTP and HTTPS requests.

  • Requests made by UrlFetchApp originate from a specific set of Google IP ranges, which may need to be allowlisted.

  • Thehttps://www.googleapis.com/auth/script.external_request scope is required to use UrlFetchApp.

  • Key methods includefetch() for single requests,fetchAll() for multiple requests, andgetRequest() to inspect request details without issuing them.

UrlFetchApp

Fetch resources and communicate with other hosts over the Internet.

This service allows scripts to communicate with other applications or access other resourceson the web by fetching URLs. A script can use the URL Fetch service to issue HTTP and HTTPSrequests and receive responses. The URL Fetch service uses Google's network infrastructure forefficiency and scaling purposes.

Requests made using this service originate from a set pool of IP ranges. You canlook up the full list of IP addresses ifyou need to allowlist or approve these requests.

This service requires thehttps://www.googleapis.com/auth/script.external_requestscope. In most cases Apps Script automatically detects and includes the scopes a script needs,but if you aresetting your scopesexplicitly you must manually add this scope to useUrlFetchApp.

See also

Methods

MethodReturn typeBrief description
fetch(url)HTTPResponseMakes a request to fetch a URL.
fetch(url, params)HTTPResponseMakes a request to fetch a URL using optional advanced parameters.
fetchAll(requests)HTTPResponse[]Makes multiple requests to fetch multiple URLs using optional advanced parameters.
getRequest(url)ObjectReturns the request that is made if the operation was invoked.
getRequest(url, params)ObjectReturns the request that is made if the operation were invoked.

Detailed documentation

fetch(url)

Makes a request to fetch a URL.

This works over HTTP as well as HTTPS.

// The code below logs the HTML code of the Google home page.constresponse=UrlFetchApp.fetch('http://www.google.com/');Logger.log(response.getContentText());

Parameters

NameTypeDescription
urlStringThe URL to fetch. The URL can have up to 2,082 characters.

Return

HTTPResponse — The HTTP response data.

Authorization

Scripts that use this method require authorization with one or more of the followingscopes:

  • https://www.googleapis.com/auth/script.external_request

fetch(url, params)

Makes a request to fetch a URL using optional advanced parameters.

This works over HTTP as well as HTTPS.

// Make a GET request and log the returned content.constresponse=UrlFetchApp.fetch('http://www.google.com/');Logger.log(response.getContentText());
// Make a POST request with form data.constresumeBlob=Utilities.newBlob('Hire me!','text/plain','resume.txt');constformData={name:'Bob Smith',email:'bob@example.com',resume:resumeBlob,};// Because payload is a JavaScript object, it is interpreted as// as form data. (No need to specify contentType; it automatically// defaults to either 'application/x-www-form-urlencoded'// or 'multipart/form-data')constoptions={method:'post',payload:formData,};UrlFetchApp.fetch('https://httpbin.org/post',options);
// Make a POST request with a JSON payload.constdata={name:'Bob Smith',age:35,pets:['fido','fluffy'],};constoptions={method:'post',contentType:'application/json',// Convert the JavaScript object to a JSON string.payload:JSON.stringify(data),};UrlFetchApp.fetch('https://httpbin.org/post',options);

Parameters

NameTypeDescription
urlStringThe URL to fetch. The URL can have up to 2,082 characters.
paramsObjectThe optional JavaScript object specifying advanced parameters as defined below.

Advanced parameters

NameTypeDescription
contentTypeStringthe content type (defaults to 'application/x-www-form-urlencoded'). Another example of content type is 'application/xml; charset=utf-8'.
headersObjecta JavaScript key/value map of HTTP headers for the request
methodStringthe HTTP method for the request:get,delete,patch,post, orput. The default isget.
payloadStringthe payload (that is, the POST body) for the request. Certain HTTP methods (for example, GET) do not accept a payload. It can be a string, a byte array, a blob, or a JavaScript object. A JavaScript object is interpreted as a map of form field names to values, where the values can be either strings or blobs.
useIntranetBooleanDeprecated. This instructs fetch to resolve the specified URL within the intranet linked to your domain through (deprecated)SDC
validateHttpsCertificatesBooleanIffalse the fetch ignores any invalid certificates for HTTPS requests. The default istrue.
followRedirectsBooleanIffalse the fetch doesn't automatically follow HTTP redirects; it returns the original HTTP response. The default istrue.
muteHttpExceptionsBooleanIftrue the fetch doesn't throw an exception if the response code indicates failure, and instead returns theHTTPResponse. The default isfalse.
escapingBooleanIffalse reserved characters in the URL aren't escaped. The default istrue.

Return

HTTPResponse — The HTTP response data.

Authorization

Scripts that use this method require authorization with one or more of the followingscopes:

  • https://www.googleapis.com/auth/script.external_request

fetchAll(requests)

Makes multiple requests to fetch multiple URLs using optional advanced parameters.

This works over HTTP as well as HTTPS.

// Make both a POST request with form data, and a GET request.constresumeBlob=Utilities.newBlob('Hire me!','text/plain','resume.txt');constformData={name:'Bob Smith',email:'bob@example.com',resume:resumeBlob,};// Because payload is a JavaScript object, it is interpreted as// as form data. (No need to specify contentType; it defaults to either// 'application/x-www-form-urlencoded' or 'multipart/form-data')constrequest1={url:'https://httpbin.org/post',method:'post',payload:formData,};// A request may also just be a URL.constrequest2='https://httpbin.org/get?key=value';UrlFetchApp.fetchAll([request1,request2]);

Parameters

NameTypeDescription
requestsObject[]An array of either URLs or JavaScript objects specifying requests as defined below.

Advanced parameters

NameTypeDescription
urlStringthe URL to fetch. The URL can have up to 2,082 characters.
contentTypeStringthe content type (defaults to 'application/x-www-form-urlencoded'). Another example of content type is 'application/xml; charset=utf-8'.
headersObjecta JavaScript key/value map of HTTP headers for the request
methodStringthe HTTP method for the request:get,delete,patch,post, orput. The default isget.
payloadStringthe payload (that is, the POST body) for the request. Certain HTTP methods (for example, GET) do not accept a payload. It can be a string, a byte array, a blob, or a JavaScript object. A JavaScript object is interpreted as a map of form field names to values, where the values can be either strings or blobs.
useIntranetBooleanDeprecated. This instructs fetch to resolve the specified URL within the intranet linked to your domain through (deprecated)SDC
validateHttpsCertificatesBooleanIffalse the fetch ignores any invalid certificates for HTTPS requests. The default istrue.
followRedirectsBooleanIffalse the fetch doesn't automatically follow HTTP redirects; it returns the original HTTP response. The default istrue.
muteHttpExceptionsBooleanIftrue, the fetch doesn't throw an exception if the response code indicates failure, and instead returns theHTTPResponse. The default isfalse.
escapingBooleanIffalse, reserved characters in the URL are not escaped. The default istrue.

Return

HTTPResponse[] — An array of HTTP response data from each input request.

Authorization

Scripts that use this method require authorization with one or more of the followingscopes:

  • https://www.googleapis.com/auth/script.external_request

getRequest(url)

Returns the request that is made if the operation was invoked.

This method does not actually issue the request.

// The code below logs the value for every key of the returned map.constresponse=UrlFetchApp.getRequest('http://www.google.com/');for(constiinresponse){Logger.log(`${i}:${response[i]}`);}

Parameters

NameTypeDescription
urlStringThe URL to look up. The URL can have up to 2,082 characters.

Return

Object — A map of Field Name to Value. The map has at least the following keys:url,method,contentType,payload, andheaders.

Authorization

Scripts that use this method require authorization with one or more of the followingscopes:

  • https://www.googleapis.com/auth/script.external_request

getRequest(url, params)

Returns the request that is made if the operation were invoked.

This method does not actually issue the request.

Parameters

NameTypeDescription
urlStringThe URL to look up. The URL can have up to 2,082 characters.
paramsObjectAn optional JavaScript object specifying advanced parameters as defined below.

Advanced parameters

NameTypeDescription
contentTypeStringthe content type (defaults to 'application/x-www-form-urlencoded'). Another example of content type is 'application/xml; charset=utf-8'.
headersObjecta JavaScript key/value map of HTTP headers for the request
methodStringthe HTTP method for the request:get,delete,patch,post, orput. The default isget.
payloadStringthe payload (that is, the POST body) for the request. Certain HTTP methods (for example, GET) do not accept a payload. It can be a string, a byte array, a blob, or a JavaScript object. A JavaScript object is interpreted as a map of form field names to values, where the values can be either strings or blobs.
useIntranetBooleanDeprecated. This instructs fetch to resolve the specified URL within the intranet linked to your domain through (deprecated)SDC
validateHttpsCertificatesBooleanIffalse the fetch ignores any invalid certificates for HTTPS requests. The default istrue.
followRedirectsBooleanIffalse the fetch doesn't automatically follow HTTP redirects; it returns the original HTTP response. The default istrue.
muteHttpExceptionsBooleanIftrue the fetch doesn't throw an exception if the response code indicates failure, and instead returns theHTTPResponse. The default isfalse.
escapingBooleanIffalse reserved characters in the URL aren't be escaped. The default istrue.

Return

Object — A map of Field Name to Value. The map has at least the following keys:url,method,contentType,payload, andheaders.

Authorization

Scripts that use this method require authorization with one or more of the followingscopes:

  • https://www.googleapis.com/auth/script.external_request

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-12-02 UTC.