{"nbformat":4,"nbformat_minor":0,"metadata":{"colab":{"name":"Earth_Engine_REST_API_compute_table.ipynb","private_outputs":true,"provenance":[{"file_id":"https://github.com/google/earthengine-api/blob/master/python/examples/ipynb/Earth_Engine_REST_API_computation.ipynb","timestamp":1605024830392},{"file_id":"1roGESkJ-6YGl3Xod7WJ1q1DhofbDo_Jh","timestamp":1591133797094}],"collapsed_sections":[],"toc_visible":true,"authorship_tag":"ABX9TyN5qB96LKgraIuC+Vj2rORP"},"kernelspec":{"name":"python3","display_name":"Python 3"}},"cells":[{"cell_type":"code","metadata":{"id":"fSIfBsgi8dNK"},"source":["#@title Copyright 2020 Google LLC. { display-mode: \"form\" }\n","# Licensed under the Apache License, Version 2.0 (the \"License\");\n","# you may not use this file except in compliance with the License.\n","# You may obtain a copy of the License at\n","#\n","# https://www.apache.org/licenses/LICENSE-2.0\n","#\n","# Unless required by applicable law or agreed to in writing, software\n","# distributed under the License is distributed on an \"AS IS\" BASIS,\n","# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n","# See the License for the specific language governing permissions and\n","# limitations under the License."],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"aV1xZ1CPi3Nw"},"source":["<table class=\"ee-notebook-buttons\" align=\"left\"><td>\n","<a target=\"_blank\"  href=\"http://colab.research.google.com/github/google/earthengine-api/blob/master/python/examples/ipynb/Earth_Engine_REST_API_compute_table.ipynb\">\n","    <img src=\"https://www.tensorflow.org/images/colab_logo_32px.png\" /> Run in Google Colab</a>\n","</td><td>\n","<a target=\"_blank\"  href=\"https://github.com/google/earthengine-api/blob/master/python/examples/ipynb/Earth_Engine_REST_API_compute_table.ipynb\"><img width=32px src=\"https://www.tensorflow.org/images/GitHub-Mark-32px.png\" /> View source on GitHub</a></td></table>"]},{"cell_type":"markdown","metadata":{"id":"CrEM35gqHouU"},"source":["# Table computations with the Earth Engine REST API\n","\n","***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](https://developers.google.com/earth-engine/guides/getstarted).*\n","\n","The [Earth Engine REST API quickstart](https://developers.google.com/earth-engine/reference/Quickstart) shows how to access blocks of pixels from an Earth Engine asset.  The [compute pixels example](https://developers.google.com/earth-engine/Earth_Engine_REST_API_compute_image) demonstrates how to apply a computation to the pixels before obtaining the result.  This example demonstrates getting the mean of pixels in each image of an `ImageCollection` in each feature of a `FeatureCollection`.  Specifically, this is a `POST` request to the [`computeFeatures`](https://developers.google.com/earth-engine/reference/rest/v1beta/projects.table/computeFeatures) endpoint."]},{"cell_type":"markdown","metadata":{"id":"H2VOD2agf4Cm"},"source":["## Before you begin\n","\n","Follow [these instructions](https://developers.google.com/earth-engine/earthengine_cloud_project_setup#apply-to-use-earth-engine) to:\n","\n","1. Apply for Earth Engine\n","2. Create a Google Cloud project\n","3. Enable the Earth Engine API on the project\n","4. Create a service account\n","5. Give the service account project level permission to perform Earth Engine computations\n","\n","**Note**: To complete this tutorial, you will need a service account that is registered for Earth Engine access.  See [these instructions](https://developers.google.com/earth-engine/guides/service_account#register-the-service-account-to-use-earth-engine) to register a service account before proceeding."]},{"cell_type":"markdown","metadata":{"id":"OfMAA6YhPuFl"},"source":["## Authenticate to Google Cloud\n","\n","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."]},{"cell_type":"code","metadata":{"id":"FRm2HczTIlKe"},"source":["# INSERT YOUR PROJECT HERE\n","PROJECT = 'your-project'\n","\n","!gcloud auth login --project {PROJECT}"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"hnufOtSfP0jX"},"source":["## Obtain a private key file for your service account\n","\n","You should already have a service account registered to use Earth Engine.  If you don't, follow [these instructions](https://developers.google.com/earth-engine/service_account#create-a-service-account) 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."]},{"cell_type":"code","metadata":{"id":"tLxOnKL2Nk5p"},"source":["# INSERT YOUR SERVICE ACCOUNT HERE\n","SERVICE_ACCOUNT='your-service-account@your-project.iam.gserviceaccount.com'\n","KEY = 'key.json'\n","\n","!gcloud iam service-accounts keys create {KEY} --iam-account {SERVICE_ACCOUNT}"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"6QksNfvaY5em"},"source":["## Start an `AuthorizedSession` and test your credentials\n","\n","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."]},{"cell_type":"code","metadata":{"id":"h2MHcyeqLufx"},"source":["from google.auth.transport.requests import AuthorizedSession\n","from google.oauth2 import service_account\n","\n","credentials = service_account.Credentials.from_service_account_file(KEY)\n","scoped_credentials = credentials.with_scopes(\n","    ['https://www.googleapis.com/auth/cloud-platform'])\n","\n","session = AuthorizedSession(scoped_credentials)\n","\n","url = 'https://earthengine.googleapis.com/v1beta/projects/earthengine-public/assets/LANDSAT'\n","\n","response = session.get(url)\n","\n","from pprint import pprint\n","import json\n","pprint(json.loads(response.content))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"U7ZzzoW_HgZ5"},"source":["## Serialize a computation\n","\n","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.\n","\n","### Authenticate to Earth Engine\n","\n","Get Earth Engine scoped credentials from the service account.  Use them to initialize Earth Engine."]},{"cell_type":"code","metadata":{"id":"LdTW8sPQIsFx"},"source":["import ee\n","\n","# Get some new credentials since the other ones are cloud scope.\n","ee_creds = ee.ServiceAccountCredentials(SERVICE_ACCOUNT, KEY)\n","ee.Initialize(ee_creds)"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"Zb243CYTP48x"},"source":["### Define a computation\n","\n","Prototype a simple computation with the client API.  Note that the result of the computation is a `FeatureCollection`.\n","To check that the computation can succeed without errors, get a value from the first `Feature` (the mean NDVI in the polygon)."]},{"cell_type":"code","metadata":{"id":"S9fsJ4RtPr12"},"source":["# A collection of polygons.\n","states = ee.FeatureCollection('TIGER/2018/States')\n","maine = states.filter(ee.Filter.eq('NAME', 'Maine'))\n","\n","# Imagery: NDVI vegetation index from MODIS.\n","band = 'NDVI'\n","images = ee.ImageCollection('MODIS/006/MOD13Q1').select(band)\n","image = images.first()\n","\n","computation = image.reduceRegions(\n","  collection=maine, \n","  reducer=ee.Reducer.mean().setOutputs([band]), \n","  scale=image.projection().nominalScale()\n",")\n","\n","# Print the value to test.\n","print(computation.first().get(band).getInfo())"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"HLk-i3htLEBf"},"source":["### Serialize the expression graph\n","\n","This will create an object that represents the Earth Engine expression graph (specifically, an [`Expression`](https://developers.google.com/earth-engine/reference/rest/v1beta/Expression)).  In general, you should build these with one of the client APIs."]},{"cell_type":"code","metadata":{"id":"Mvbi4LuhV9BR"},"source":["# Serialize the computation.\n","serialized = ee.serializer.encode(computation)"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"Y_Lu1qq5GUTF"},"source":["## Send the request\n","\n","Make a `POST` request to the [`computeFeatures`](https://developers.google.com/earth-engine/reference/rest/v1beta/projects.table/computeFeatures) endpoint.  Note that the request contains the [`Expression`](https://developers.google.com/earth-engine/reference/rest/v1beta/Expression), which is the serialized computation."]},{"cell_type":"code","metadata":{"id":"_pbqvd48dT33"},"source":["import json\n","\n","url = 'https://earthengine.googleapis.com/v1beta/projects/{}/table:computeFeatures'\n","\n","response = session.post(\n","  url = url.format(PROJECT),\n","  data = json.dumps({'expression': serialized})\n",")\n","\n","import json\n","pprint(json.loads(response.content))"],"execution_count":null,"outputs":[]},{"cell_type":"markdown","metadata":{"id":"MPO7-O4qB16V"},"source":["The response contains the resultant `FeatureCollection` as GeoJSON, which can be consumed by other apps or processes."]}]}