The Earth Engine Python API can be deployed in a Google Colaboratory notebook.
Colab notebooks are [Jupyter](https://jupyter.org/) notebooks that run in the
cloud and are highly integrated
with Google Drive, making them easy to set up, access, and share. If you are
unfamiliar with Google Colab or Jupyter notebooks, please spend some time
exploring the [Colab welcome site](https://colab.research.google.com/).

The following sections describe deploying Earth Engine in Google Colab and
visualizing maps and charts using third‑party Python packages.

> [!NOTE]
> **Note:** Installing the Earth Engine API and authenticating are necessary steps each time you begin working with a Colab notebook. This guide demonstrates setup and testing with a new Colab notebook, but the process applies to shared and saved notebooks as well. If you don't have Earth Engine access, please [register](https://console.cloud.google.com/earth-engine).

## Open a Colab notebook

Notebooks can be opened from either Google Drive or the Colaboratory interface.

### New notebook

### Google Drive

Open [Google Drive](https://drive.google.com) and create a new file.

- *New \> More \> Colaboratory*
- Right click in a folder and select *More \> Colaboratory* from the context menu.

### Colab interface

Visit the [Colab site](https://colab.research.google.com/)
and create a new file.

- *File \> New \> New Python 3 notebook*
- If you have interacted with Colab previously, visiting the above linked site will provide you with a file explorer where you can start a new file using the dropdown menu at the bottom of the window.

### Existing notebook

Existing notebook files (.ipynb) can be opened from Google Drive and the Colab
interface.

### Google Drive

Colab notebooks can exist in various folders in
[Google Drive](https://drive.google.com) depending on where notebooks files
were created. Notebooks created in Google Drive will exist in the folder they
were created or moved to. Notebooks created from the Colab interface will
default to a folder called 'Colab Notebooks' which is automatically added to
the 'My Drive' folder of your Google Drive when you start working with Colab.

Colab files can be identified by a yellow 'CO' symbol and '.ipynb' file
extension. Open files by either doubling clicking on them and selecting
*Open with \> Colaboratory* from the button found at the top of the resulting
page or by right clicking on a file and selecting *Open with \> Colaboratory*
from the file's context menu.

### Colab interface

Opening notebooks from the
[Colab interface](https://colab.research.google.com/) allows you to access
existing files from Google Drive, GitHub, and local hardware. Visiting the
Colab interface after initial use will result in a file explorer modal
appearing. From the tabs at the top of the file explorer, select a source and
navigate to the *.ipynb* file you wish to open. The file explorer can also be
accessed from the Colab interface by selecting *File \> Open notebook* or using
the *Ctrl+O* keyboard combination.

## Import API and get credentials

This section demonstrates how to import the Earth Engine Python API and
authenticate access. This content is also available as a Colab notebook:

|---|---|
| [![Colab logo](https://developers.google.com/static/earth-engine/images/colab_logo_32px.png) Run in Google Colab](https://colab.research.google.com/github/google/earthengine-community/blob/master/guides/linked/ee-api-colab-setup.ipynb) | [![GitHub logo](https://developers.google.com/static/earth-engine/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/google/earthengine-community/blob/master/guides/linked/ee-api-colab-setup.ipynb) |

The Earth Engine API is included by default in Google Colaboratory so requires
only importing and authenticating. These steps must be completed for each new
Colab session or if you restart your Colab kernel or if your Colab virtual
machine is recycled due to inactivity.

### Import the API

Run the following cell to import the API into your session.

```python
import ee
```

### Authenticate and initialize

Run the `ee.Authenticate` function to authenticate your access to
Earth Engine servers and `ee.Initialize` to initialize it. Add a code
cell, enter the following lines, edit the project, and run the cell.

```python
# Trigger the authentication flow.
ee.Authenticate()

# Initialize the library.
ee.Initialize(project='my-project')
```

You'll be asked to authorize access to your Earth Engine account. Follow the
instructions printed to the cell to complete this step.

### Test the API

Test the API by printing the elevation of Mount Everest. Note that before using
the API you must initialize it. Run the following Python script in a new cell.

```python
# Print the elevation of Mount Everest.
dem = ee.Image('NASA/NASADEM_HGT/001')
xy = ee.Geometry.Point([86.9250, 27.9881])
elev = dem.sample(xy, 30).first().get('elevation').getInfo()
print('Mount Everest elevation (m):', elev)
```

## Map visualization

`ee.Image` objects can be displayed to notebook output cells. The following two
examples demonstrate displaying a static image and an interactive map.

### Static image

The `IPython.display` module contains the `Image` function, which can display
the results of a URL representing an image generated from a call to the Earth
Engine `getThumbUrl` function. The following script will display a thumbnail
of a global elevation model.

```python
# Import libraries.
import ee
from IPython.display import Image

# Trigger the authentication flow.
ee.Authenticate()

# Initialize the library.
ee.Initialize(project='my-project')

# Import a DEM and display a thumbnail of it.
dem = ee.Image('NASA/NASADEM_HGT/001').select('elevation')
Image(url=dem.updateMask(dem.gt(0))
  .getThumbUrl({'min': 0, 'max': 4000, 'dimensions': 512,
                'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5']}))
```

### Interactive map

The [`folium`](https://python-visualization.github.io/folium/)
package can be used to display `ee.Image` objects on an interactive
[Leaflet](https://leafletjs.com/) map. Folium has no default
method for handling tiles from Earth Engine, so one must be defined
and added to the `folium.Map` module before use.

The following script provides an example of adding a method for handing Earth
Engine tiles and using it to display an elevation model to a Leaflet map.

```python
# Import libraries.
import ee
import folium

# Trigger the authentication flow.
ee.Authenticate()

# Initialize the library.
ee.Initialize(project='my-project')

# Define a method for displaying Earth Engine image tiles to folium map.
def add_ee_layer(self, ee_image_object, vis_params, name):
  map_id_dict = ee.Image(ee_image_object).getMapId(vis_params)
  folium.raster_layers.TileLayer(
    tiles = map_id_dict['tile_fetcher'].url_format,
    attr = "Map Data © https://earthengine.google.com/",
    name = name,
    overlay = True,
    control = True
  ).add_to(self)

# Add EE drawing method to folium.
folium.Map.add_ee_layer = add_ee_layer

# Fetch an elevation model.
dem = ee.Image('NASA/NASADEM_HGT/001').select('elevation')
# Set visualization parameters.
vis_params = {
  'min': 0,
  'max': 4000,
  'palette': ['006633', 'E5FFCC', '662A00', 'D8D8D8', 'F5F5F5']}

# Create a folium map object.
my_map = folium.Map(location=[20, 0], zoom_start=3)

# Add the elevation model to the map object.
my_map.add_ee_layer(dem.updateMask(dem.gt(0)), vis_params, 'DEM')

# Add a layer control panel to the map.
my_map.add_child(folium.LayerControl())

# Display the map.
display(my_map)
```

## Chart visualization

Some Earth Engine functions produce tabular data that can be plotted by
data visualization packages such as `matplotlib`. The following example
demonstrates the display of tabular data from Earth Engine as a scatter
plot. See [Charting in Colaboratory](https://colab.sandbox.google.com/notebooks/charts.ipynb)
for more information.

```python
# Import libraries.
import ee
import matplotlib.pyplot as plt

# Trigger the authentication flow.
ee.Authenticate()

# Initialize the Earth Engine module.
ee.Initialize(project='my-project')

# Fetch a Landsat TOA image.
img = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_034033_20000913')

# Select Red and NIR bands, scale them, and sample 500 points.
samp_fc = img.select(['B3','B4']).sample(scale=30, numPixels=500)

# Arrange the sample as a list of lists.
samp_dict = samp_fc.reduceColumns(ee.Reducer.toList().repeat(2), ['B3', 'B4'])
samp_list = ee.List(samp_dict.get('list'))

# Save server-side ee.List as a client-side Python list.
samp_data = samp_list.getInfo()

# Display a scatter plot of Red-NIR sample pairs using matplotlib.
plt.scatter(samp_data[0], samp_data[1], alpha=0.2)
plt.xlabel('Red', fontsize=12)
plt.ylabel('NIR', fontsize=12)
plt.show()
```