In this codelab, we'll introduce you to one of the easiest ways to write code that accesses Google developer technologies, all by leveraging one of the mainstream web development languages, JavaScript. Using Google Apps Script, you will write code to extract an address sitting in a cell in a Google Sheet, generate a Google Map based on that address, and send the map as an attachment to yourself or a friend using Gmail. The best part? It'll really only be 4 lines of code!

What you'll learn

What you'll need

How will you use this codelab/tutorial?

Read it through only Read it and complete the exercises

How would rate your experience with G Suite developer tools & APIs?

Novice Intermediate Proficient

Now that you know what this codelab is about, what are you going to exactly?

  1. Learn a bit about Apps Script... enough to get you going
  2. Create a new Google Sheets spreadsheet
  3. Enter a street address in the spreadsheet's top-left cell (A1)
  4. Learn how to enter the script editor for any document
  5. Edit Apps Script code, save, and run it
  6. Use Gmail to see the fruits of your labor!

Let's get started!

What is Google Apps Script?

Google Apps Script has a development environment that may be completely different from what you're used to. With Apps Script, you:

NOTE: It is, for the most part, outside of the scope of this codelab to teach you Apps Script. There are plenty of online resources to help you with this. The official documentation features an overview with quickstarts, tutorials, and videos as well. Our goal is to get you comfortable creating Apps Script code and become familiar with not only its development environment, but also to give you an idea of the types of applications you can build with it.

Apps Script applications come in one of two forms:

  1. Bound—meaning it's forever (and only) tied to one Google document (Doc, Sheet, Slide, Site, or Form)
  2. Standalone—an independent script not tied to any G Suite documents

Bound and standalone apps can also be published to expose more broadly:

Your first Apps Script app will be bound to a Google Sheet, so let's create a new spreadsheet!

Enter a street address in a new Google Sheet by following these instructions:

  1. Create a new Google Sheet from this convenience link (sheets.google.com/create), or alternatively, go to your Google Drive (drive.google.com) and click New > Google Sheets > Blank spreadsheet


  2. On the blank spreadsheet, go to the first cell in the upper left-hand corner (A1). It will be in column A and row 1. Now enter an address in that cell—pick any worldwide valid street address with a targeted location such as postal code or city and state/province. Here is an example of entering an address in New York City:

That's all you have to do in the Sheet. Now we're ready to enter the editor and write some code!

Now that you have a new Google Sheet, it's time to edit its bound script. Follow these instructions:

Open the script editor

Select Tools from the menu bar then click on Script editor.


What you see now in your desktop browser is the code editor for the bound script:

A default function named myFunction() is automatically-created for you, and you're dropped into the editor to start coding. That's it... you're now ready to write your application!

Editing/replacing the (template) code

The "template" code you're given is empty and doesn't do much, so let's replace that with our application. Copy the code you see below, replacing everything in the editor window with the lines below. Believe it or not, this is the entire application!

function sendMap() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var address = sheet.getRange('A1').getValue();
  var map = Maps.newStaticMap().addMarker(address);
  GmailApp.sendEmail('friend@example.com', 'Map', 'See below.', {attachments:[map]});
}

To restriction this app to only being able to access this Sheet we're working with (as opposed to all of a user's Sheets), you can add this annotation as a file-level comment for the peace of mind of your users:

/**
* @OnlyCurrentDoc
*/

Other than this optional annotation, the best part is that the 4 lines of sendMap() make up the entire app! Of course, we need to replace the fake email address (friend@example.com) with one of yours. Did you notice when replaced the code in the editor, a red asterisk showed up to the left of the file name?

That just means you've edited the file which now needs to be saved. You'll see it every time you have an unsaved edit.

Save the code

  1. Save and name your project (call it anything you like—for example, "Hello Maps!"). Save the file by going to the menu bar and selecting File > Save.



    Alternatively, you can click the small disk icon or CTRL-s (PCs, Linux) or Command-s (Mac). If you haven't named your project yet, you must do so before you can proceed.
  1. Once named and saved, let's run it! There are several options here too. Since we renamed the function to sendMap(), select Run > Run function > sendMap:



    Alternatively, click on the "run" triangle icon and ensure the function to run is sendMap().
  2. One of the Apps Script features developers appreciate is that you don't have to write the authorization code. Although Apps Script manages this, users (of your app) still need to grant permission (for this script) to access your Sheet and be able to send email through Gmail on your behalf. The first auth dialog looks like this:


  3. Click Review Permissions. Now you'll get a warning stating your app hasn't been verified yet. (If you were to launch this publicly, you would go through the formal process of getting your app vetted and verified.) Since we're only testing this app, you are the developer (and hopefully you trust yourself), it's okay to proceed by selecting Advanced here. Once you get under the fold, click your app marked with (unsafe) next to it, and confirm by entering the full word "continue". All these steps are illustrated in the graphic (for a different app & developer) below:

    To read more about keeping our users safe and what developers need to do to verify their apps, check out this blog post where we got the above image.
  4. Now you'll get the real OAuth2 dialog window asking for permission to access your Sheet as well as send email on your behalf:
  5. After you grant permission, the script will run to completion. You won't see any visual cues other than knowing your script has completed when the tiny yellow execution dialog disappears.
  6. Now check the email account where you sent your message, and you should find a message with Subject "Map" and a message body that looks like this:

  7. When you open the attachment in the email message, you should get a Google Map with a pin on the address you entered into the Sheet (try other addresses!):

Isn't that cool?!? Just think about it... you have four lines of code that access three different Google products in a meaningful way, even though it's not a complete application by itself. If you're unfamiliar with JavaScript or Apps Script, the code should be readable enough that you should have a rough idea as to how it works, and perhaps what Apps Script can accomplish for you!

The code featured in this codelab is also available at its GitHub repo at github.com/googlecodelabs/apps-script-intro. (We aim to keep this codelab in-sync with the repo.) Below are additional resources to help you dig deeper into the material covered in this codelab as well as explore other ways of accessing Google developer tools programmatically.

Documentation

Related and general videos

News & updates

Other codelabs

Introductory

Intermediate

Reference apps

This optional section is be used as self-study after the session concludes to fill-in any gaps which may have arose or for further research.

Since this application is so short, there's no overall code structure we can discuss. Instead, we can just walk through line-by-line and review this app which touches three different Google products in just four lines of code!

  1. This is a normal JavaScript function declaration for sendMap().
function sendMap() {
  1. The first line of code calls the Spreadsheet Service accessible from Apps Script via the SpreadsheetApp object. The returned sheet is assigned to a variable of the same name. The getActiveSheet() method does exactly what it says it does—it returns a "handle" to the current sheet that is active in the user interface (UI).
  var sheet = SpreadsheetApp.getActiveSheet();
  1. With the sheet object, reference the cell range (of a single cell) in A1 notation with getRange(). A "range" is a group of cells, including just a single one like ours... cell A1, the one we entered the address in. Now let's fetch what's inside that range of cells with the getValue() call, and assigned to the address variable upon return. Try adding more addresses and reading from different cells.
  var address = sheet.getRange('A1').getValue();
  1. The 3rd line of code connects to the Google Maps Service via the Maps object. As soon as we have access to the Maps Service, we request a new static map be created via newStaticMap(). You can then put a "pin" dropped on the address we pulled from the Sheet by using the addMarker() method.
  var map = Maps.newStaticMap().addMarker(address);
  1. The last line uses the Gmail Service (via the MailApp object), calling its sendEmail() method, to send the email which includes both the text "See below." and the map image as an attachment.
  GmailApp.sendEmail('friend@example.com', 'Map', 'See below.', {attachments:[map]});
}