Run in Google Colab
View source on GitHub
Note: The REST API contains new and advanced features that may not be suitable for all users. If you are new to Earth Engine, please get started with the JavaScript guide.
The Earth Engine REST API quickstart shows how to access blocks of pixels from an Earth Engine asset. Suppose you want to apply a computation to the pixels before obtaining the result. This guide shows how to prototype a computation with one of the client libraries, serialize the computation graph and use the REST API to obtain the computed result. Making compute requests through the REST API corresponds to a POST request to one of the compute endpoints, for example computePixels, computeFeatures, or the generic value.compute. Specifically, this example demonstrates getting a median composite of Sentinel-2 imagery in a small region.
Before you begin
Follow these instructions to:
- Apply for Earth Engine
- Create a Google Cloud project
- Enable the Earth Engine API on the project
- Create a service account
- Give the service account project level permission to perform Earth Engine computations
Note: To complete this tutorial, you will need a service account that is registered for Earth Engine access. See these instructions to register a service account before proceeding.
Authenticate to Google Cloud
The first thing to do is login so that you can make authenticated requests to Google Cloud. You will set the project at the same time. Follow the instructions in the output to complete the sign in.
# INSERT YOUR PROJECT HERE
PROJECT = 'your-project'
!gcloud auth login --project {PROJECT}
Obtain a private key file for your service account
You should already have a service account registered to use Earth Engine. If you don't, follow these instructions to get one. Copy the email address of your service account into the following cell. (The service account must already be registered to use Earth Engine). In the following cell, the gsutil command line is used to generate a key file for the service account. The key file will be created on the notebook VM.
# INSERT YOUR SERVICE ACCOUNT HERE
SERVICE_ACCOUNT='your-service-account@your-project.iam.gserviceaccount.com'
KEY = 'key.json'
!gcloud iam service-accounts keys create {KEY} --iam-account {SERVICE_ACCOUNT}
Start an AuthorizedSession and test your credentials
Test the private key by using it to get credentials. Use the credentials to create an authorized session to make HTTP requests. Make a GET request through the session to check that the credentials work.
from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account
credentials = service_account.Credentials.from_service_account_file(KEY)
scoped_credentials = credentials.with_scopes(
['https://www.googleapis.com/auth/cloud-platform'])
session = AuthorizedSession(scoped_credentials)
url = 'https://earthengine.googleapis.com/v1beta/projects/earthengine-public/assets/LANDSAT'
response = session.get(url)
from pprint import pprint
import json
pprint(json.loads(response.content))
Serialize a computation
Before you can send a request to compute something, the computation needs to be put into the Earth Engine expression graph format. The following demonstrates how to obtain the expression graph.
Authenticate to Earth Engine
Get Earth Engine scoped credentials from the service account. Use them to initialize Earth Engine.
import ee
# Get some new credentials since the other ones are cloud scope.
ee_creds = ee.ServiceAccountCredentials(SERVICE_ACCOUNT, KEY)
ee.Initialize(ee_creds)
Define a computation
Prototype a simple computation with the client API. Note that the result of the computation is an Image.
coords = [
-121.58626826832939,
38.059141484827485,
]
region = ee.Geometry.Point(coords)
collection = ee.ImageCollection('COPERNICUS/S2')
collection = collection.filterBounds(region)
collection = collection.filterDate('2020-04-01', '2020-09-01')
image = collection.median()
Serialize the expression graph
This will create an object that represents the Earth Engine expression graph (specifically, an Expression). In general, you should build these with one of the client APIs.
serialized = ee.serializer.encode(image)
Create the desired projection (WGS84) at the desired scale (10 meters for Sentinel-2). This is just to discover the desired scale in degrees, the units of the projection. These scales will be used to specify the affine transform in the request.
# Make a projection to discover the scale in degrees.
proj = ee.Projection('EPSG:4326').atScale(10).getInfo()
# Get scales out of the transform.
scale_x = proj['transform'][0]
scale_y = -proj['transform'][4]
Send the request
Make a POST request to the computePixels endpoint. Note that the request contains the Expression, which is the serialized computation. It also contains a PixelGrid. The PixelGrid contains dimensions for the desired output and an AffineTransform in the units of the requested coordinate system. Here the coordinate system is geographic, so the transform is specified with scale in degrees and geographic coordinates of the upper left corner of the requested image patch.
import json
url = 'https://earthengine.googleapis.com/v1beta/projects/{}/image:computePixels'
url = url.format(PROJECT)
response = session.post(
url=url,
data=json.dumps({
'expression': serialized,
'fileFormat': 'PNG',
'bandIds': ['B4','B3','B2'],
'grid': {
'dimensions': {
'width': 640,
'height': 640
},
'affineTransform': {
'scaleX': scale_x,
'shearX': 0,
'translateX': coords[0],
'shearY': 0,
'scaleY': scale_y,
'translateY': coords[1]
},
'crsCode': 'EPSG:4326',
},
'visualizationOptions': {'ranges': [{'min': 0, 'max': 3000}]},
})
)
image_content = response.content
If you are running this in a notebook, you can display the results using the IPython image display widget.
# Import the Image function from the IPython.display module.
from IPython.display import Image
Image(image_content)