Here is a short script that tests if you have working installation:
import ee ee.Authenticate() ee.Initialize() print(ee.Image("NASA/NASADEM_HGT/001").get("title").getInfo())
Install options
If you are using Google Colab, the latest version of the Earth Engine Python client library has already been installed (via pip). Try the following notebook to get started with Earth Engine and Colab:
If you don't use Colab, the Earth Engine client library can be manually installed and updated on your system using conda (recommended) or pip:
Package import
The Python API package is called ee
. It must be imported and initialized for
each new Python session and script:
import ee
Authentication
Prior to using the Earth Engine Python client library, you need to authenticate (verify your identity) and use the resultant credentials to initialize the Python client. The following authentication flows may use Cloud projects to authenticate, and they're used for unpaid (free, noncommercial) use as well as paid use. See the Earth Engine Authentication and Initialization guide for troubleshooting and to learn more.
Colab or JupyterLab notebook
You can authenticate from within Colab or JupyterLab environments by executing the helper
function ee.Authenticate()
and following the instructions it generates.
Step-by-step instructions
- Browser: Notebook
- In a notebook code cell, run the following code to start an authentication flow
using the "notebook" mode.
import ee ee.Authenticate()
Click on the link in the cell output to open a Notebook Authenticator page in a new tab.
- In a notebook code cell, run the following code to start an authentication flow
using the "notebook" mode.
- Browser: Notebook Authenticator
- Verify that the correct user account is listed.
- Select a Google Cloud Project to use for Authentication. If you need to create a new project, we recommend the naming convention "ee-xyz" where xyz is your usual Earth Engine user name. (If you cannot select or create a Cloud Project, see the troubleshooting section below.)
- Click Generate Token.
- Browser: Account Selection
- You will be shown an account selection page. Click on the user account that you want to grant access from the notebook.
- Browser: Warning page
- A warning page is presented, indicating that Google did not create the app (i.e. the Colab code in the notebook). Click Continue to acknowledge.
- Browser: Consent Screen
- Indicate if you are willing to grant the requested scopes and click Continue.
- Browser: Authorization Code Screen
- Copy the authorization verification code/token.
- Browser: Notebook
- Switch back to the Colab tab, and paste the verification code/token into the code cell output.
- The cell output should indicate "Successfully saved authorization token."
- Proceed with initialization.
Command line
You can authenticate from a command line by executing the command
function earthengine authenticate
and following the instructions it generates.
This authentication flow requires installing the
Google Cloud Command Line Interface (gcloud)
on a machine that has a web browser.
Step-by-step instructions (local machine)
- Verify that gcloud is installed on the local machine.
- In a terminal, run
gcloud help
. If gcloud is not installed, follow these instructions to install gcloud.
- In a terminal, run
- Local Machine Terminal
- In a terminal, run
earthengine authenticate
. - The command output will indicate that gcloud is being used to fetch credentials.
- A browser window will open to an account selection page.
- In a terminal, run
- Browser: Account Selection
- Select the account you want to use for authentication.
- Browser: Consent Screen
- Indicate if you are willing to grant the requested scopes and click "Allow".
- Browser: Confirmation Screen
- The browser will show a page confirming that you are authenticated, and the
earthengine authenticate
command in your terminal window will report "Successfully saved authorization token."
- The browser will show a page confirming that you are authenticated, and the
- Proceed with initialization.
Step-by-step instructions (remote machine)
- Verify that gcloud is installed on the local machine and the remote
machine.
- In a terminal, run
gcloud help
. If gcloud is not installed, follow these instructions to install gcloud.
- In a terminal, run
- Remote Machine Terminal
- In a terminal, run
earthengine authenticate
. - The command output will indicate that gcloud is being used to fetch credentials.
- A
gcloud auth
command will be presented. Copy the entire command. Do not click the URL which is part of the command.
- In a terminal, run
- Local Machine Terminal
- Paste and run the
gcloud auth
command. - Read the warning, and indicate that you want to proceed. This will open up a local browser window.
- Paste and run the
- Browser: Account Selection
- Select the account you want to use for authentication.
- Browser: Consent Screen
- Indicate if you are willing to grant the requested scopes and click "Allow".
- Browser: Confirmation Screen
- The browser will show a page confirming that you are authenticated.
- Local Machine Terminal
- Copy the URL beginning with https://localhost: that appeared in the terminal.
- Remote Machine Terminal
- Paste the URL to answer the prompt "Enter the output of the above command:" and press enter.
- The terminal will report "Successfully saved authorization token."
- Proceed with initialization.
With a service account
If you are authenticating Python code that will run unattended, you may want to authenticate with a service account rather than a user account. See these docs for using service accounts with Earth Engine.
Initialization
The initialization step verifies that valid credentials have been created and populates the Python client library with methods that the backend server supports.
ee.Initialize()
If you are using the earthengine command line tool, it will initialize automatically.
Troubleshooting authentication issues
See the Troubleshooting section of the authentication docs.
Syntax
Both the Python and JavaScript APIs access the same server-side functionality, but client-side expressions (learn more about client vs. server) can vary because of language syntax differences. The following table includes a list of the common syntax differences you'll encounter when working with the Python API relative to the JavaScript API.
Property | JavaScript | Python |
---|---|---|
Function definition |
function myFun(arg) { return arg; } var myFun = function(arg) { return arg; }; |
def my_fun(arg): return arg |
Anonymous function mapping |
var foo = col.map(function(arg) { return arg; }); |
foo = col.map(lambda arg: arg) |
Variable definition |
var myVar = 'var'; |
my_var = 'var' |
Logical operators |
var match = such.and(that); var match = such.or(that); var match = such.not(that); |
match = such.And(that) match = such.Or(that) match = such.Not(that) |
Multi-line method chain |
var foo = my.really() .reallyLong() .methodChain(); |
foo = (my.really() .reallyLong() .methodChain()) |
Dictionary keys |
var dic = {'key': value}; var dic = {key: value}; |
dic = {'key': value} |
Dictionary object access |
var value = dic.key; var value = dic['key']; |
value = dic['key'] |
Function argument definition |
// Positional arguments. var foo = fun(argX, argY, argZ); // Keyword arguments object. var foo = fun({y: argY}); |
# Positional arguments. foo = fun(arg_x, arg_y, arg_z) # Keyword arguments dictionary. foo = fun(**{'y': arg_y}) # Keyword arguments. foo = fun(x=arg_x, z=arg_z) |
Boolean |
var t = true; var f = false; |
t = True f = False |
Null values |
var na = null; |
na = None |
Comment |
// |
# |
Date objects
Define and manipulate client-side date objects with the
datetime
module. Include the module in your script:
import datetime
Convert ee.Date
to client-side date:
ee_date = ee.Date('2020-01-01') py_date = datetime.datetime.utcfromtimestamp(ee_date.getInfo()['value']/1000.0)
Convert client-side date to ee.Date:
py_date = datetime.datetime.utcnow() ee_date = ee.Date(py_date)
Exporting data
Exporting data with the Python API requires the use of the ee.batch
module, which provides an interface to the
Export
functions. Pass parameter arguments as you would with the JavaScript API, minding the
differences noted in the syntax table above. Export tasks must be
started by calling the start()
method on a defined task. Query a task's status by
calling the status()
method on it. The following example demonstrates exporting
an ee.Image
object.
Create an export task:
task = ee.batch.Export.image.toDrive(image=my_image, # an ee.Image object. region=my_geometry, # an ee.Geometry object. description='mock_export', folder='gdrive_folder', fileNamePrefix='mock_export', scale=1000, crs='EPSG:4326')
Start an export task:
task.start()
Check export task status:
task.status()
The result of task.status()
is a dictionary containing information such as the
state of the task and its ID.
{ 'state': 'READY', 'description': 'my_export_task', 'creation_timestamp_ms': 1647567508236, 'update_timestamp_ms': 1647567508236, 'start_timestamp_ms': 0, 'task_type': 'EXPORT_IMAGE', 'id': '56TVJIZABUMTD5CJ5YHTMYK4', 'name': 'projects/earthengine-legacy/operations/56TVJIZABUMTX5CJ5HHTMYK4' }
You can monitor task progress using the state
field. See the Processing
Environments page for a
list of state
values and more information on
task lifecycle.
Printing objects
Printing an Earth Engine object in Python prints the serialized request for the object, not the object itself. Refer to the Client vs. server page to understand the reason for this.
Call getInfo()
on Earth Engine objects to get the desired object from the server
to the client:
# Load a Landsat image. img = ee.Image('LANDSAT/LT05/C01/T1_SR/LT05_034033_20000913') # Print image object WITHOUT call to getInfo(); prints serialized request instructions. print(img) # Print image object WITH call to getInfo(); prints image metadata. print(img.getInfo())Note that
getInfo()
is a synchronous operation, meaning execution of expressions
following the getInfo()
call are blocked until the result is returned to the client.
Additionally, requests for a lot of data or expensive computations can return an error and/or
hang. In general, the best practice is to
export your results,
and once complete, import them into a new script for further analysis.
UI objects
The Earth Engine ui
module is only available through the JavaScript API Code
Editor. Use third party libraries for UI elements in Python. Libraries such as
geemap,
Folium, and
ipyleaflet
provide interactive map display, while charting can be done with
Matplotlib,
Altair, or
seaborn, to name a few. See examples
in the
Earth Engine in Colab setup notebook for using geemap and Matplotlib.
Python in the Developer Guide
Python code is included throughout the Earth Engine Developer Guide. Where available,
code examples can be viewed by clicking on the "Colab (Python)" tab at the top of code blocks.
Guide pages may also include buttons at the top for running the page as a Colab notebook or
viewing on GitHub. Python code examples are intended to be run using
Google Colab. Interactive map and object exploration are
handled by the geemap
library. Both the Earth Engine Python client library and geemap
are preinstalled
in Colab.
Earth Engine setup
Running Python code requires that you import the Earth Engine library, authenticate, and initialize. The following commands are used in examples (see the Authentication and Initialization page for alternatives).
import ee ee.Authenticate() ee.Initialize()
Interactive exploration with geemap
The geemap
library is used
for displaying map tiles and printing rich representations of Earth Engine objects.
The library depends respectively on
ipyleaflet
and eerepr
for these features.
The geemap
library and its dependencies are preinstalled in Google Colab;
import it into each session.
import geemap.core as geemap
Geographic Earth Engine data classes, such as ee.Image
and
ee.FeatureCollection
, can be viewed using the geemap.Map
object.
First, define the map object. Then, add layers to it or alter its viewport.
# Initialize a map object. m = geemap.Map() # Define an example image. img = ee.Image.random() # Add the image to the map. m.add_layer(img, None, 'Random image') # Display the map (you can call the object directly if it is the final line). display(m)