Class UrlFetchApp

UrlFetchApp

Fetch resources and communicate with other hosts over the Internet.

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

Requests made using this service originate from a set pool of IP ranges. You can look up the full list of IP addresses if you need to whitelist or approve these requests.

This service requires the https://www.googleapis.com/auth/script.external_request scope. In most cases Apps Script automatically detects and includes the scopes a script needs, but if you are setting your scopes explicitly you must manually add this scope to use UrlFetchApp.

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 would be made if the operation was invoked.
getRequest(url, params)ObjectReturns the request that would be 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.
var response = UrlFetchApp.fetch("http://www.google.com/");
Logger.log(response.getContentText());

Parameters

NameTypeDescription
urlStringthe URL to fetch

Return

HTTPResponse — the HTTP response data


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.
var response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());
// Make a POST request with form data.
var resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
var formData = {
  'name': 'Bob Smith',
  'email': 'bob@example.com',
  'resume': resumeBlob
};
// Because payload is a JavaScript object, it will be interpreted as
// as form data. (No need to specify contentType; it will automatically
// default to either 'application/x-www-form-urlencoded'
// or 'multipart/form-data')
var options = {
  'method' : 'post',
  'payload' : formData
};
UrlFetchApp.fetch('https://httpbin.org/post', options);
// Make a POST request with a JSON payload.
var data = {
  'name': 'Bob Smith',
  'age': 35,
  'pets': ['fido', 'fluffy']
};
var options = {
  '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
paramsObjectoptional 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, or put. The default is get.
payloadStringthe payload (e.g. POST body) for the request. Certain HTTP methods (e.g. GET) do not accept a payload. It can be a string, a byte array, or a JavaScript object. A JavaScript object will be interpretted 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
validateHttpsCertificatesBooleanif this is set to false, the fetch will ignore any invalid certificates for HTTPS requests. The default is true.
followRedirectsBooleanif this is set to false, the fetch not automatically follow HTTP redirects; it will return the original HTTP response. The default is true.
muteHttpExceptionsBooleanif this is set to true, the fetch will not throw an exception if the response code indicates failure, and will instead return the HTTPResponse (default: false)
escapingBooleanif this is set to false, reserved characters in the URL will not be escaped (default: true)

Return

HTTPResponse — the http response data


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.
var resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
var formData1 = {
  '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')
var request1 = {
  'url': 'https://httpbin.org/post',
  'method' : 'post',
  'payload' : formData
};
// A request may also just be a URL.
var request2 = 'https://httpbin.org/get?key=value';
UrlFetchApp.fetchAll(request1, request2);

Parameters

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

Advanced parameters

NameTypeDescription
urlStringthe URL to fetch
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, or put. The default is get.
payloadStringthe payload (for example, POST body) for the request. Certain HTTP methods (for example, GET) do not accept a payload. It can be a string, a byte array, 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
validateHttpsCertificatesBooleanif set to false, the fetch ignores any invalid certificates for HTTPS requests. The default is true.
followRedirectsBooleanif this is set to false, the fetch not automatically follow HTTP redirects; it returns the original HTTP response. The default is true.
muteHttpExceptionsBooleanif this is set to true, the fetch does not throw an exception if the response code indicates failure, and instead returns the HTTPResponse (default: false)
escapingBooleanif this is set to false, reserved characters in the URL are not escaped (default: true)

Return

HTTPResponse[] — an array of http response data from each input request


getRequest(url)

Returns the request that would be 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.
var response = UrlFetchApp.getRequest("http://www.google.com/");
for(i in response) {
  Logger.log(i + ": " + response[i]);
}

Parameters

NameTypeDescription
urlStringthe URL to look up

Return

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


getRequest(url, params)

Returns the request that would be made if the operation were invoked.

This method does not actually issue the request.

Parameters

NameTypeDescription
urlStringthe url to look up
paramsObjectoptional 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, or put. The default is get.
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
validateHttpsCertificatesBooleanif this is set to false, the fetch will ignore any invalid certificates for HTTPS requests. The default is true.
followRedirectsBooleanif this is set to false, the fetch not automatically follow HTTP redirects; it will return the original HTTP response. The default is true.
muteHttpExceptionsBooleanif this is set to true, the fetch will not throw an exception if the response code indicates failure, and will instead return the HTTPResponse (default: false)
escapingBooleanif this is set to false, reserved characters in the URL will not be escaped (default: true)

Return

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

Send feedback about...

Apps Script
Apps Script
Need help? Visit our support page.