Working with URLs in Google Apps Script and Google Sheets

There is something so fitting about working with URLs in Google Apps Script and Google Spreadsheets. The cloud-based software works in the browser where, indeed, there are a lot of URLs to work with. Google Apps Script’s doPost, doGet, and UrlFetchApp make HTTP requests to URLs easy. Google Spreadsheets has similar functionality with IMPORTXML, IMPORTHTML, IMPORTFEED, and IMPORTDATA. If you work in web analytics, digital marketing, or especially SEO, chances are, you’ve stared at a big spreadsheet of URLs trying to figure out how to parse, check, or call the URLs quickly and easily. Luckily, there is a beautiful Javascript library that makes working with URLs just as quick and easy as you want it to be. This post will show how to import the URI.js javascript library from a third-party source (in this case GitHub) and use it in Google Spreadsheet custom functions. The demo should also help you use the library if you are working with a script that involves constructing REST API URLs.  

Introducing URI.js

URI.js is a very comprehensive javascript library for working with and manipulating URLs. It allows you to get specific parts of the URL, change them, and not have to worry if you’ve mashed up the original URL into a malformed mess. It even lets helps you determine if a URL qualifies as a URL or IP address. If you don’t know how handy this is, I’ve got some spreadsheets you can work on! To get a javascript library from GitHub to Google Apps Script, you can use RawGit to serve the library’s source file from GitHub. Then use the eval() command to make the library and its methods accessible to the Google Apps Script environment. The GitHub URL for URI.js is https://github.com/medialize/URI.js/blob/gh-pages/src/URI.js and when you enter that into RawGit, you get the usable source file at https://cdn.rawgit.com/medialize/URI.js/gh-pages/src/URI.js. Now to get the URI object and all of its handy methods just call eval like so:

eval('https://cdn.rawgit.com/medialize/URI.js/gh-pages/src/URI.js.')

Then the URI object is in Google Apps Script’s global scope. To use it just do something like URI.methodName(). To see all the methods in the library check out the API reference.  

URL Custom Functions for Google Apps Script

Here are a few wrapper functions to take advantage of the URI.js in Google Apps Script. There are other functionalities not included here so don’t be afraid to build on this! Just remember, you must use eval() (above) in order to load the library.

eval(UrlFetchApp.fetch('https://rawgit.com/medialize/URI.js/gh-pages/src/URI.js').getContentText());

// Get the URL protocol (eg. 'https' or 'http')
function urlProtocol(url){
  return URI(url).protocol()
}
  
// Get the URL hostname (eg. 'googleappscripting.com')
function urlHostname(url){
  return URI(url).hostname()
}

// Get the whole URL path (eg. '/some/directory/filename.png')
function urlPath(url){
  return URI(url).path()
}

// Get the URL directory (eg. '/some/directory')
function urlDirectory(url){
  return URI(url).directory()
}
    
// Get the URL file name (eg. 'filename.png')
function urlFilename(url){
  return URI(url).filename()
}

// Get the URL query string (eg. 'this=1&that=2')
// If a query string parameter is provided as the second argument
// then the function will return the value of that parameter
function urlQuery(url,param){
  if (param !== undefined){
    var queryMap = URI(url).query(true);
    return queryMap[param]
  }
  return URI(url).query()
}

// Get the URL hash (eg. '#section-two')
function urlHash(url){
  return URI(url).hash()
}

// Check to see if a URL is a fully qualified URL
function urlIsUrl(url){
  return URI(url).is('url')
}

// Check to see if a URL is a fully qualified IP Address
function urlIsIp(url){
    return URI(url).is('ip')
}


// Test function to ensure that each of the above functions do what they are supposed to do.
function testURI() {

  var testUrl = 'https://googleappscripting.com/some/test/page.html?this-is=helpful&it=works#rad';  
  var funcTests = [
    urlProtocol,
    urlHostname,
    urlDirectory,
    urlPath,
    urlFilename,
    urlQuery,
    urlHash,
    urlIsUrl,
    urlIsIp
  ]
  
  // Check that each function returns the expected value
  funcTests.forEach(function(test){
    Logger.log(test(testUrl))
  });
  
  // Extra check to see that the urlQuery function works with a query parameter argument
  Logger.log(urlQuery(testUrl,'it'));

}

The output of the logs for the function testURI should look like this:

[17-12-28 21:05:56:855 PST] https
[17-12-28 21:05:56:856 PST] googleappscripting.com
[17-12-28 21:05:56:857 PST] /some/test
[17-12-28 21:05:56:858 PST] /some/test/page.html
[17-12-28 21:05:56:859 PST] page.html
[17-12-28 21:05:56:860 PST] this-is=helpful&it=works
[17-12-28 21:05:56:860 PST] #rad
[17-12-28 21:05:56:862 PST] true
[17-12-28 21:05:56:863 PST] false
[17-12-28 21:05:56:864 PST] works

I hope this helps you clean up the internet. Leave a comment if you have any questions!