Get Started with Earth Engine

This Get Started guide is intended as a quick way to start programming with the Earth Engine
JavaScript API. For an introductory look at JavaScript and more in-depth exercises with the
Earth Engine API, see the tutorials. For suggestions on JavaScript coding style, see the
Google JavaScript Style Guide.

Google Earth Engine allows users to run algorithms on georeferenced imagery and vectors
stored on Google's infrastructure. The Google Earth Engine API provides a library of
functions which may be applied to data for display and analysis. Earth Engine's public data
catalog contains a large amount of publicly available imagery and vector datasets. Private
assets can also be created in users' personal folders.

How to use these docs

The Earth Engine documentation is primarily structured by data type. For example, the left
side navigation contains links to sections or pages about important data types such as Image,
ImageCollection, Feature, FeatureCollection, Geometry, Reducer, Chart, Join and
Array. This guide only describes only enough about these types to get you started. There are
also sections for machine learning, specialized or sensor specific algorithms (e.g. Landsat
algorithms), public facing apps, data (asset) management and important details about Earth
Engine internal workings. Before diving in to any of that, start here!

The Code Editor

The Code Editor is an interactive environment for developing Earth Engine applications
(Figure 1). The center panel provides a JavaScript code editor. Above the editor are buttons to
save the current script, run it, and clear the map. The Get Link button generates a unique
URL for the script in the address bar. The map in the bottom panel contains the layers added
by the script. At the top is a search box for datasets and places. The left panel contains code
examples, your saved scripts, a searchable API reference and an asset manager for private
data. The right panel has an inspector for querying the map, an output console, and a manager
for long-running tasks. The help button help in the upper right contains links to this Guide and
other resources for getting help. Learn more from the Code Editor guide and the Get Help
guide.
Figure 1. The Earth Engine Code Editor at code.earthengine.google.com

Opening and running code in the Code Editor

The steps below demonstrate how to open Earth Engine and execute a custom script that
displays an image. For best results, you may want to install the latest version of Chrome,
Google’s web browser, available here.
 1. Open the Earth Engine Code Editor here: code.earthengine.google.com. If you have
not already, you will need to enable access by logging in using a registered Google
account.
2. Navigate to the Scripts tab located on the far left of the Code Editor. There you will
find a collection of example scripts that access, display, and analyze Earth Engine
data.
3. Under “Image Collection,” select the “Filtered Composite” example. You will see a
script appear in the center console. Press the Run button to execute the script. The
Filtered Composite example selects Landsat 7 images that intersect or are within the
boundaries of Colorado and Utah. It then displays a true color composite of the
selected images. The samples introduce you to commonly used methods, such as
filter(), clip(), and Map.addLayer().

Earth Engine data structures

The two most fundamental geographic data structures in Earth Engine are Image and Feature
corresponding to raster and vector data types, respectively. Images are composed of bands and
a dictionary of properties. Features are composed of a Geometry and a dictionary of
properties. A stack of images (e.g. an image time series) is handled by an ImageCollection.
A collection of features is handled by a FeatureCollection. Other fundamental data
structures in Earth Engine include Dictionary, List, Array, Date, Number and String
(learn more about basic data types from this tutorial. It is important to remember that these are
all server-side objects and are not manipulated the same way as client-side JavaScript objects
are (learn more).

Earth Engine algorithms

There are several ways to run operations in the API:

 Calling methods that are attached to objects.

 Calling algorithms.
 Calling Code Editor specific functions.
 Defining new functions.

The Docs tab of the Code Editor lists the methods of each API class. For example, the Image
class has an add() method:

var image3 = image1.add(image2);

This method adds the bands of image2 to the bands of image1. The ee.Algorithms category
contains a list of currently supported algorithms for specialized or domain specific processing.
For example, to create topographic layers from an input Digital Elevation Model (DEM):

var terrainImage = ee.Algorithms.Terrain(dem);

Code Editor specific functions include the Map and Export methods, which control how
layers are added to the map panel or exported to Google Drive, respectively. Functions can
also be created in JavaScript using

var myFunction = function(args) {

  // do something
  return something;
};

As illustrated in the Mapping section, user defined functions are useful for creating custom
functionality or modifying the elements of a collection using:

var collection2 = collection1.map(aFunction);

The following sections illustrate these concepts for various simple use cases.

Notation used in the guides:

Static methods called on an Earth Engine class (for example ee.Image) are written as
Image.staticMethod(). Methods called on an instance of a class are written as
image.instanceMethod(). The lowercase image means that a variable named image refers
to an instance of the ee.Image class.

‘Hello world!’ JavaScript

Printing out information to the console is a basic task for getting information about an object,
displaying the numeric result of a computation, displaying object metadata or helping with
debugging. The iconic ‘Hello World!’ example in the Code Editor is:

print('Hello world!');

Copy this line into the code editor of the Code Editor and click Run. Note that the output is
displayed in the Console tab, on the right of the Code Editor. For a more remote sensing
relevant example, the following prints the metadata of a Landsat 8 image:

print(ee.Image('LANDSAT/LC08/C01/T1/LC08_044034_20140318'));

Carefully inspect the output in the console to see metadata available for Landsat images.

Adding data to the map

In addition to printing information to the console, adding data to the Map is the way to
visualize geographic data. Use Map.addLayer() to do that. In the following example, an
Image is instantiated (how to find these images is covered later) using ee.Image(), added to
the map with Map.addLayer() and the map is centered over the image:

// Load an image.
var image = ee.Image('LANDSAT/LC08/C01/T1/LC08_044034_20140318');

// Center the map on the image.

Map.centerObject(image, 9);

// Display the image.

Map.addLayer(image);

The second parameter of Map.centerObject() is a zoom level, where higher numbers

indicate larger scale (more zoomed in). The parameters for the Map functions are described in
depth in the API reference accessible from the Docs tab. If the appearance of the image is
unsatisfactory, configure the display parameters with an additional argument to
Map.addLayer(). For example:
// Load the image from the archive.
var image = ee.Image('LANDSAT/LC08/C01/T1/LC08_044034_20140318');

// Define visualization parameters in an object literal.

var vizParams = {bands: ['B5', 'B4', 'B3'], min: 5000, max: 15000, gamma:
1.3};

// Center the map on the image and display.

Map.centerObject(image, 9);
Map.addLayer(image, vizParams, 'Landsat 8 false color');

Observe that the visualization parameters are defined by an object literal, which includes a list
of bands to display, a minimum and maximum digital number and a gamma value. (Learn
more about Landsat bands here. Learn more about image visualization here).

Use Map.addLayer() to add features and feature collections to the map. For example,

var counties = ee.FeatureCollection('TIGER/2016/Counties');

Map.addLayer(counties, {}, 'counties');

Finding images, image collections and feature collections

Images, image collections, and feature collections are discoverable by searching the Earth
Engine Data Catalog. For example, entering ‘Landsat 8’ into the search field results in a list of
raster datasets. (The complete listing of Earth Engine datasets is at the Earth Engine Data
Catalog). Click on the dataset name to get a brief description, information about the temporal
availability, data provider and collection ID. Click the Import button to automatically create
an Imports section at the top of your script with a variable for this collection.

Alternatively, copy the collection ID and paste it into your code. For example, choose the first
result of the ‘Landsat 8’ search and copy the ID as follows:

var collection = ee.ImageCollection('LANDSAT/LC08/C01/T1');

Since this is a collection of many images spanning the Earth land surface, finding an
individual image in the collection requires filtering in order to narrow down the search.
Alternatively, the collection of images can be reduced to a single image using compositing
and mosaicking techniques. More on filtering and compositing (see Reducing) in the next
sections.

Feature collections are also available through the Data Catalog. Their representation is smaller
than image collections, but you will find international, census, watershed, and protected areas
boundaries, to name a few. Learn more about importing your own vector datasets here.

Filtering and Sorting

It is often necessary to filter a collection by space and/or time in order to limit the number of
results. For example, consider the task of sorting the Landsat 8 scene collection in order to
find a cloud-free scene for San Francisco. First, it’s necessary to define the region of interest.
A point is often useful for that. Activate the Inspector tab on the right side of the Code Editor
and click near the center of your area of interest, copy the coordinates from the Inspector tab,
then construct a Point using:

var point = ee.Geometry.Point(-122.262, 37.8719);

Construct start and end dates:

var start = ee.Date('2014-06-01');

var finish = ee.Date('2014-10-01');

Filter the Landsat 8 collection using the point and the dates, then sort using a metadata
property (discovered during inspection of the Landsat 8 scene metadata):

var filteredCollection = ee.ImageCollection('LANDSAT/LC08/C01/T1')

  .filterBounds(point)
  .filterDate(start, finish)
  .sort('CLOUD_COVER', true);

This collection can be safely printed and inspected. (If the collection has too many images,
printing it will either be very slow, time out, or return an error). Observe that the images in the
collection are a List stored in the ‘features’ property of the ImageCollection. The ID of any
image in the collection can be copied into the Image constructor as above. Alternatively, get
the first image (lowest cloud cover):

var first = filteredCollection.first();

Access the complete Earth Engine filtering functionality using filter() with an ee.Filter
as the argument. (The filterBounds() and filterDate() methods used above are
shortcuts). For example, the following creates a Filter, uses it to filter a
FeatureCollection and displays the result:

// Load a feature collection.

var featureCollection = ee.FeatureCollection('TIGER/2016/States');

// Filter the collection.

var filteredFC = featureCollection.filter(ee.Filter.eq('NAME',
'California'));

// Display the collection.

Map.addLayer(filteredFC, {}, 'California');

Band math
Perform mathematical operations on images using Image methods. This may include band
recombinations (spectral indices), image differencing or mathematical operations such as
multiplication by a constant. For example, compute the difference between Normalized
Difference Vegetation Index (NDVI) images 20 years apart:

// This function gets NDVI from Landsat 5 imagery.

var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.

var image1 = ee.Image('LANDSAT/LT05/C01/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C01/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.

var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);
// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);

Notice the use of a user defined function in this example. More on functions in the next
section.

Mapping (what to do instead of a for-loop)

Use map() to iterate over items in a collection. (For loops are NOT the right way to do that in
Earth Engine and should be avoided). The map() function can be applied to an
ImageCollection, a FeatureCollection or a List and accepts a function as its argument.
The argument of the function is an element of the collection over which it is mapped. This is
useful for modifying every element of the collection in the same way, for example adding. For
example, the following code adds an NDVI band to every image in an ImageCollection:

// This function gets NDVI from Landsat 8 imagery.

var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// Load the Landsat 8 raw data, filter by location and date.

var collection = ee.ImageCollection('LANDSAT/LC08/C01/T1')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the collection.

var ndviCollection = collection.map(addNDVI);

Another common task is adding a new property (or ‘attribute’ or ‘field’) to features in a
FeatureCollection. In the following example, the new property is a computation involving
two existing attributes:

// This function creates a new property that is the sum of two existing
properties.
var addField = function(feature) {
  var sum =
ee.Number(feature.get('property1')).add(feature.get('property2'));
  return feature.set({'sum': sum});
};

// Create a FeatureCollection from a list of Features.

var features = ee.FeatureCollection([
  ee.Feature(ee.Geometry.Point(-122.4536, 37.7403),
    {property1: 100, property2: 100}),
    ee.Feature(ee.Geometry.Point(-118.2294, 34.039),
    {property1: 200, property2: 300}),
]);

// Map the function over the collection.

var featureCollection = features.map(addField);

// Print a selected property of one Feature.

print(featureCollection.first().get('sum'));

// Print the entire FeatureCollection.

print(featureCollection);
Note the cast to ee.Number required for the property value to be recognized as a number in
order to use the add() method). The type of the collection can be changed by map(). For
example:

// This function returns the image centroid as a new Feature.

var getGeom = function(image) {
  return ee.Feature(image.geometry().centroid(), {foo: 1});
};

// Load a Landsat 8 collection.

var collection = ee.ImageCollection('LANDSAT/LC08/C01/T1')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the ImageCollection.

var featureCollection = ee.FeatureCollection(collection.map(getGeom));

// Print the collection.

print(featureCollection);

Note the added property (foo) for each feature created from the image centroid. In the final
line, the cast makes the resultant collection recognizable as a FeatureCollection.

Reducing
Reducing is the way to aggregate data over time, space, bands, arrays and other data
structures in Earth Engine. Various methods exist for this purpose in the API. For example, to
make a composite of an ImageCollection, use reduce() to reduce the images in the
collection to one Image. A simple example is creating the median composite of the five least
cloudy scenes in the Landsat 8 collection defined earlier:

// Load a Landsat 8 collection.

var collection = ee.ImageCollection('LANDSAT/LC08/C01/T1')
  // Filter by date and location.
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-01-01', '2014-12-31')
  // Sort by increasing cloudiness.
  .sort('CLOUD_COVER');

// Compute the median of each pixel for each band of the 5 least cloudy
scenes.
var median = collection.limit(5).reduce(ee.Reducer.median());

Reducing is also the way to get statistics of an image in the regions defined by a Feature or
FeatureCollection. Suppose the task is to compute the mean pixel values within an area of
interest. Use reduceRegion() for this purpose. For example:

// Load and display a Landsat TOA image.

var image = ee.Image('LANDSAT/LC08/C01/T1_TOA/LC08_044034_20140318');
Map.addLayer(image, {bands: ['B4', 'B3', 'B2'], max: 0.3});

// Create an arbitrary rectangle as a region and display it.

var region = ee.Geometry.Rectangle(-122.2806, 37.1209, -122.0554, 37.2413);
Map.addLayer(region);

// Get a dictionary of means in the region.  Keys are bandnames.

var mean = image.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: region,
  scale: 30
});

Learn more about reducers from the Reducers doc.

Masking
Every pixel in an ee.Image has both a value and a mask which ranges from 0 (no data) to 1.
Masked pixels (in which mask==0) are treated as no data. Pixels with 0 < mask ≤ 1 have a
value, but it is weighted by the mask for numerical computations.

You can make pixels transparent or exclude them from analysis using masks. Pixels are
masked when the mask value is zero. Continuing the image differencing example, use a mask
to display areas of increased and decreased NDVI over the difference interval:

// This function gets NDVI from Landsat 5 imagery.

var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.

var image1 = ee.Image('LANDSAT/LT05/C01/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C01/T1_TOA/LT05_044034_20100611');

// Compute NDVI from the scenes.

var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.

var ndviDifference = ndvi2.subtract(ndvi1);
// Load the land mask from the SRTM DEM.
var landMask = ee.Image('CGIAR/SRTM90_V4').mask();

// Update the NDVI difference mask with the land mask.

var maskedDifference = ndviDifference.updateMask(landMask);

// Display the masked result.

var vizParams = {min: -0.5, max: 0.5, palette: ['FF0000', 'FFFFFF',
'0000FF']};
Map.setCenter(-122.2531, 37.6295, 9);
Map.addLayer(maskedDifference, vizParams, 'NDVI difference');

In this example, note that the mask of the NDVI difference is updated by the land mask with
updateMask(). This sets the mask of the NDVI difference pixels to the land mask wherever
the NDVI difference mask is non-zero.

Masking is also useful for excluding data from the analysis. Consider the reduceRegion()
example from the Reducing section. Suppose the task is to compute a seasonal mean NDVI
for Santa Clara county, CA, excluding cloudy pixels. The following example demonstrates
multiple concepts: filtering, mapping, reducing and the use of a cloud mask:

// This function gets NDVI from a Landsat 8 image.

var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// This function masks cloudy pixels.

var cloudMask = function(image) {
  var clouds =
ee.Algorithms.Landsat.simpleCloudScore(image).select(['cloud']);
  return image.updateMask(clouds.lt(10));
};

// Load a Landsat collection, map the NDVI and cloud masking functions over
it.
var collection = ee.ImageCollection('LANDSAT/LC08/C01/T1_TOA')
  .filterBounds(ee.Geometry.Point([-122.262, 37.8719]))
  .filterDate('2014-03-01', '2014-05-31')
  .map(addNDVI)
  .map(cloudMask);

// Reduce the collection to the mean of each pixel and display.

var meanImage = collection.reduce(ee.Reducer.mean());
var vizParams = {bands: ['B5_mean', 'B4_mean', 'B3_mean'], min: 0, max:
0.5};
Map.addLayer(meanImage, vizParams, 'mean');

// Load a region in which to compute the mean and display it.

var counties = ee.FeatureCollection('TIGER/2016/Counties');
var santaClara = ee.Feature(counties.filter(ee.Filter.eq('NAME', 'Santa
Clara')).first());
Map.addLayer(santaClara);

// Get the mean of NDVI in the region.

var mean = meanImage.select(['nd_mean']).reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: santaClara.geometry(),
  scale: 30
});

// Print mean NDVI for the region.

mean.get('nd_mean').evaluate(function(val){
  print('Santa Clara spring mean NDVI:', val);
});