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
Authenticate to the Earth Engine servers:
ee.Authenticate()
Initialize the API:
ee.Initialize()
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()
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.
Folium and
ipyleaflet provide
interactive map handling, while charting can be done with
Matplotlib,
Altair, or
seaborn, to name a few. See examples
in the
Earth Engine in Colab setup notebook.