Exercise 1: Hello World and

Exploring Data Archive

Introduction
Google Earth Engine is available via a web-based JavaScript Application Program Interface (API) called
the Code Editor. This platform is where users can write and execute scripts to share and repeat
geospatial analysis and processing workflows. The Code Editor offers access to the full power of Earth
Engine. In this exercise, we will begin learning about the Code Editor platform and explore some basic
programming concepts, in JavaScript. Learning of fundamentals of coding and JavaScript is required to
use Earth Engine.

Table of Contents
Part 1: Introduction to the Code Editor API ..................................................................................... 2
Part 2: Working with Images............................................................................................................ 7
Part 3: Explore Data Available in Earth Engine .............................................................................. 14

RSAC | Exercise 1: Hello World and Exploring Data Archive | April 2016 1
Part 1: Introduction to the Code Editor API
In this exercise, we will use the Google Earth Engine Application Program Interface (API), or Code Editor.
This interface offers significantly more flexibility than Explorer and the ability to create complex and
customized analysis workflows. In the Code Editor we will write JavaScript code to access and analyze
data and download results.

A. Explore the JavaScript Code Editor API

1. In your Google Chrome web browser navigate to the following URL:
https://code.earthengine.google.com/
i. When/if prompted, allow the EE Code Editor to access your Google Account.
ii. This should take you to the Code Editor interface shown below.

2. Use the graphic above to guide you and click through the tabs in the upper left hand panel,
the Scripts and Documentation Panel.
i. Under the Scripts tab, note the wide variety of preloaded example scripts that
demonstrate capabilities and offer code that you can use for your analyses. You can take
a look at these to start to learn about what kinds of things Earth Engine can do. After you
create and save a script later in the day, it will be available here in your Private repository.
ii. Under the Docs tab, there is a searchable list of documentation for the predefined GEE
object types and methods. Note these are grouped and organized by object. Briefly
explore what kinds of methods (functions) are available in GEE.
(a) Select one of interest and click on it to see the information window with a
description of the methods and associated arguments (required and optional). Any
optional arguments are listed in italicized print. (The example scripts include

Exercise 1: Hello World and Exploring Data Archive 2

 examples of many of these methods, try searching for them using the scripts search
bar.)
3. Using the graphic above click through the tabs in the upper right hand panel where the
Inspector, Console, and Tasks tabs are located.
i. We will use the Inspector (similar to the familiar identify tool in ArcMap) to easily get
information about layers in the map at specified points in our map (specified by clicking in
the Map Panel).
ii. The Console will be used to return messages as our scripts run and print information
about our data, intermediate products and results. It will also record any diagnostic
messages, such as information about runtime errors.
iii. The Tasks tab is used to manage the exporting of data and results at the end of an
analysis.
4. Click on the Help button in the upper right and select Feature Tour to learn more about each
component of the API.
i. Click through the options in the Feature tour to become more familiar with each
component of the Code Editor.

B. Run an example script and review the results

1. Click on the Scripts tab in the left-hand panel and expand the Examples group.
2. Scroll down until you see the Image group. Click on the triangle to expand this group if
necessary.

3. Select the Normalized Difference script from the list of example scripts (stored within the
Image grouping). It will copy the script into your Code Editor panel.
4. The graphic below shows the script that should appear in the Code Editor panel (upper center
panel).

Exercise 1: Hello World and Exploring Data Archive 3

What is a script?
A script is a series of instructions that a computer follows to execute some process. It is like a recipe – a
set of instructions that a cook follows one by one to create a dish. In the Code Editor platform that we
are working in, the instructions are written as JavaScript statements. The computer follows these
statements step-by-step.
As scripts get more complicated, a better analogy is perhaps comparing the script to an employee
handbook or a car manual. There is a lot of information in there – but only a portion of it needs to be
followed at any point in time. For example, if an employee wanted to know what to do if a fire alarm was
going off – they certainly shouldn’t be reading the book from cover to cover. Scripts can be designed just
like handbooks and car manuals - to help a reader locate and act on specific pieces of information. In the
case of scripts, the reader is the computer, not the employee. And instead of tables of contents and
indices within books, the script design elements include things such as conditional statements.

5. Read the Normalized Difference script, line by line (or statement by statement), to see what it
is doing:
i. Lines 1 to 6 are notes, or comments, the creator included to describe the script. Line
comments are designated with the //, the double slashes at the beginning of the line.
Comments are ignored by the Code Editor when the script executes.
ii. Line 8 accomplishes two things. It declares a variable, called img. It then assigns a value
to this variable. The value is a MODIS image
ee.Image('MOD09GA/MOD09GA_005_2012_03_09').
iii. Line 9 does several things. It declares and assigns a value to a variable, called ndvi. It also
calls the Earth Engine NormalizedDifference method and applies it to the variable “img”
defined in the previous line. The bands “sur_refl_b02” and “sur_refl_b01” are specified as
inputs/arguments to that calculation. These two bands are the NIR and Red MODIS bands,
so the result of the calculation is a Normalized Difference Vegetation Index (NDVI) image.
This calculated NDVI image is what is being assigned to the ndvi variable.

Exercise 1: Hello World and Exploring Data Archive 4

 iv. Lines 10-12 declare a variable, palette, and assign to it an array that specifies a palette of
hexadecimal color codes for displaying the resulting NDVI image. The hexadecimal colors
range from white (FFFFFF) to browns (e.g., CE7E45) to yellows (e.g., FCD163) to greens
(e.g., 529400) to very dark (011301).

Note: You can read more about hexadecimal color codes here http://www.colorhexa.com/.

v. Line 14 centers the map to the area of interest. The parameters, the values inside the
brackets, are the longitude and latitude values for Kansas City, USA; the third value sets
the zoom level.

Exercise 1: Hello World and Exploring Data Archive 5

 vi. Lines 15-17 add data to the map output window (lower panel). Two images are added -
the img variable, which points to the original MODIS image, and the ndvi variable, which
points to the normalized difference image we created in line 9. We’ll discuss the addLayer
parameter settings a bit later in the day.
6. Click the Run button in the upper-right of the code editor to run the Normalized Difference
script.

i. You should see a MODIS image and the resulting NDVI image appear in the map output
window at the bottom of your screen.
7. Visually examine the results in the map output window using the map viewer tools.
i. Click or mouse-hover on the Layers button in the upper right hand corner of the Map
output panel at the bottom of your screen (shown in the following graphic).
ii. Toggle the NDVI layer on and off by unchecking and checking the box next to the NDVI
Layer.
iii. Click and drag the slider-bar back and forth to adjust the transparency of the NDVI layer
in order to view the MODIS image beneath the NDVI image (see following image, with
visualization parameter box).

Exercise 1: Hello World and Exploring Data Archive 6

 8. Use the Inspector Panel to explore the values in the resulting NDVI image.
i. Click on the Inspector tab in the upper right-hand panel.
(a) Hover your cursor over the map. Notice that your cursor has become a cross.

ii. Click anywhere on the map and observe the values that appear in the window under the
Inspector tab.
(a) These are the pixel values at this location for:
(i) The individual MODIS band values for the displayed bands appear under the
MODIS image name.
(ii) The computed NDVI values.

Part 2: Working with Images

A. Open a new script
1. Open the Code Editor webpage in Google Chrome, if it is not already open:
https://code.earthengine.google.com/
2. Click on the dropdown arrow adjacent to the Reset button and select Clear script.

Exercise 1: Hello World and Exploring Data Archive 7

 B. Create a variable representing a single Landsat 8 image
1. Use the code in the box below to create a variable representing an ee.Image object for a
2014 Landsat 8 image.
i. Copy and paste the code below into the Code Editor Code Editor.

// Get the image.

var LC8_image = ee.Image('LANDSAT/LC8_L1T_TOA/LC81290502015036LGN00');

Notes about JavaScript syntax: There’s a lot going on in just two lines. Take a closer look at the pieces of
this statement we’re loading into GEE (note, refer to the Appendices to learn more about JavaScript
syntax and some basic programming concepts).
1) Double forward slashes, //, are comment characters in JavaScript. These prevent text on that line from
executing. These are useful for creating notes in your code.
2) Variables are declared in JavaScript using the keyword var. Variables can be numbers, strings, objects,
object collections, etc. Variables are used to store information for use later on in the script. In the case of
the statement above, you are naming the variable LC8_image and using it to refer to the raster dataset
you are interested in analyzing.
3) ee.Image() is a GEE function that tells GEE that you want to load an image as an object (and in this
case, save it as a variable called ‘LC8_image’). In JavaScript, functions start with a letter and have a pair
of parentheses at the end. Functions often include inputs or parameters, which tell the function what to
do, and are specified inside of the parentheses. In this case, the parameter you are specifying inside the
parenthesis is the image ID.
A generalized version of the statement above is: ee.Image(‘image_id’). The ‘image_id’ is the image that
you would like to load ('LANDSAT/LC8_L1T_TOA/LC81290502015036LGN00') and set as the variable
(LC8_image).
4) The syntax for specifying the image ID in this function (ee.Image) is to surround the string of
characters (the image ID, 'LANDSAT/LC8_L1T_TOA/LC81290502015036LGN00') in quotes. The image id is
in quotes because the collection and image name together is a string. Strings are sets of characters that
in this example, name the specific dataset.
a. Landsat image ids for individual Landsat scenes can be found at glovis.usgs.gov. You will work
with this more in Exercise 3.
5) JavaScript statements end with a semicolon.

2. Run the code and observe the result.

i. Click the Run button and note that nothing happens in the map or the console. This code
merely creates the variable, nothing is printed or displayed.

C. Add the image to the Code Editor map

Exercise 1: Hello World and Exploring Data Archive 8

 1. Copy and paste, or type, the code below into your script. These additional lines will add the
Landsat image to the map panel. Add these lines below the code from the previous step. GEE
will execute the code (lines) sequentially when you hit Run.

//Add the image to the map.

Map.addLayer(LC8_image);

2. Run the code and review the result.

i. Click on the Run button. This time an image will load in the Map Output window. If you
are not zoomed into the USA, centered on Utah, you won’t see anything.
ii. Use your cursor to navigate (left click and drag) in the map view to Utah and find the
image you called. It would be nice if the script did this for us, next you will add that
statement into your script.

D. Center and Zoom the map window

Next you will add a statement to set the zoom factor and location on which to center the map output
window. The Map.centerObject() is a function that tells GEE where to position the map output window.

1. Copy and paste the two lines of code (below) underneath the four lines you already have in
the GEE code editor window. Click Run.

//center map on the tile

Map.centerObject(LC8_image, 8);

2. To zoom out, decrease the second input to a number less than 8. To zoom in more, increase
the second input parameter (try 10). Modify your statement so it looks like the two lines
below and click Run. What happened?
3. In the panel in the upper left, switch from the Scripts to the Docs tab. Type
Map.centerObject() into the Docs search bar. What is the range of the zoom parameter?

//center map on the tile

Map.centerObject(LC8_image, 10);

E. Explore the map window tools

1. Explore this image, the LC8_image ('LANDSAT/LC8_L1T_TOA/LC81290502015036LGN00'),
with the Code Editor map viewer tools.
i. You can zoom and pan using the tools on the left of the map output panel (shown in the
following graphic).

Exercise 1: Hello World and Exploring Data Archive 9

 ii. Use the Layers tool (on the right of the map output panel) to turn the image (Layer 1) on
or off (shown in following image).

Note: Even though you saved the LANDSAT/LC8_L1T_TOA/LC81290502015036LGN00 image as a

variable named LC8_image, the name of the image is labeled as Layer_1 by default in the Layers Legend
in the output map window. As you will see later, it is possible to change the name that appears in the
Layers tool to something that is more descriptive of the data being displayed.

iii. Swipe the transparency lever (the sliding bar to the right of the layer name in the
preceding image). This will make the ‘Layer 1’ transparent, revealing the base map
underneath.

F. Explore the Inspector window

1. Click on the Inspector Tab in the upper right hand corner of the Earth Engine Code Editor
interface. Your cursor will now change to a cross hairs when you place it in the map window.
2. Now click anywhere on the map using the Inspector, the cross hairs, to identify pixel values
for each band in your image at the selected location (refer to following graphic for example
output).

G. Change visualization parameters to improve the display

Now you can see the image, however the color parameters are not very well suited to this image. You
will change the visualization parameters next.

Exercise 1: Hello World and Exploring Data Archive 10

 1. Open the documentation for addLayer function in the Map group by clicking on the Docs tab
in the left panel in the Code Editor.
i. Expand the Map group and select Map.addLayer from the list (as illustrated below); or
ii. Search for Map.addLayer in the Filter methods… search bar.

2. Review the documentation that appears (shown above). This provides information about the
use and arguments for this function.
i. Notice that some input options (such as vis) are italicized in the documentation. This
means that these are optional parameters that can be specified or left out of the
Map.addLayer statement. If you want to skip an optional parameter use “undefined” as a
place holder. See the statement below for an example.

Map.addLayer(LC8_image,undefined, 'Landsat8scene');

Note: What we are most interested in here are the optional Feature Visualization Parameters, vis. In
this case the documentation is somewhat sparse. You can learn a bit more by opening up the
documentation for the ee.data.getMapId method. Hint, find the documentation for this method by
expanding the ee.data group. You can also search the example scripts to see working examples.

Exercise 1: Hello World and Exploring Data Archive 11

There are a number of options to include to adjust how images are displayed. The information in the
parenthesis following each option indicates how to format the information – e.g., which data type is
required (a number, strings, array, etc).
The inputs that are most commonly used to modify display settings include the following:
Bands: allows the user to specify which bands to render as red, green, and blue.
Min and max: sets the stretch range of the color gun. The range is dependent on the data type. For
example unsigned 16-bit imagery has a total range of 0 to 65,536. This option lets you set the display to
a subset of that range.
Palette: specifies the color palette used to display information. You will see how to use this option later
in the tutorial.
Naming convention (in the Layers Legend): you can specify the name that appears in the layers legend
here as well. We have named this layer ‘Landsat8scene’ in the code below.

Exercise 1: Hello World and Exploring Data Archive 12

Syntax: Most of these optional parameters are entered as a keys-value pair in a dictionary object. The
syntax is:
{vis_param1: number, number, number
vis_param2: 'string, string, string',
// or an array of strings like this:
vis_param2: ['string', 'string', 'string']}

1. Modify the Map.addLayer() function to display the image as a false color composite and
apply a stretch to improve the display. Modify the Map.addLayer() statement from the
previous steps to look like the code below. The statement below includes the optional
parameters for which bands to display (band 6, 5, and 4), specifies a stretch to improve the
visualization, and finally gives the image a display name.
2. Click Run and use the map tools to explore the result. Note that the name under the Layers
(legend) is now Landsat8scene.

// Add the image to map as a false color composite.

Map.addLayer(LC8_image,{bands:'B6,B5,B4',min: 0.05, max: 0.8,gamma:
1.6}, 'Landsat8scene');

Note: In the statement above, the names of the bands have been inserted for you already. If you wanted
to look them up yourself, you can use the print function (or the Inspector) to identify what the bands are
named (e.g., B6, B5, B4).

3. You can also specify the bands as strings in an array. Look at the statement below, it will do
the same thing as the statement above. Do you notice the difference in syntax, it’s rather
subtle?

// Add the image to map as a false color composite.

Map.addLayer(LC8_image,{bands:['B6', 'B5', 'B4'],min: 0.05, max:
0.8,gamma: 1.6}, 'Landsat8scene');

4. Copy and paste the following statement in your code editor. Then click Run.

print(LC8_image);

5. Now in the Console tab, click on the arrow next to Image LANDSAT/… to display the image
properties. Then click on the arrow next to bands: to display the band properties. This will
reveal the first band (indexed at 0) is called “B1”, the second (indexed at 1) is called “B2”, etc.
Refer to following graphic for an example (note: the numbers in the image will not align
perfectly, since this picture represents a scene from the USA).

Exercise 1: Hello World and Exploring Data Archive 13

Note: To learn about band combinations for viewing Landsat 8 and Landsat 5 or 7, check out this
comparison of Landsat bands: http://landsat.usgs.gov/L8_band_combos.php.

6. Click the Save button in the upper right of the Code Editor panel to save your example script
for future reference.
i. Name this script Visualize a Landsat 8 image.

Note: there are many more options for visualizing data in the map window, such as setting a mask or
mosaicking two data sets together. To read more about these advanced visualization options, visit the
Google Earth Engine Documentation at https://developers.google.com/earth-
engine/image_visualization#styled-layer-descriptors

Part 3: Explore Data Available in Earth Engine

1. In a web browser, such as Google Chrome, open the Google Earth Engine homepage:
https://earthengine.google.com/.
2. Click on Datasets in the upper right corner. This will give you a quick overview of some of the
data that is available in Earth Engine. Take a moment to read through the information on
imagery, geophysical data, climate and weather, and demographic data.

Exercise 1: Hello World and Exploring Data Archive 14