planet_gee_delivery.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4bc346e2-8474-48ab-96fe-22aa6ab887f6",
   "metadata": {},
   "source": [
    "# Planet Order and Delivery to GEE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f52f1190-2d8d-44db-8c54-4ca92caaa459",
   "metadata": {},
   "source": [
    "*Notebook based on Planetlabs example notebooks for [GEE Delivery](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/gee-integration/gee-integration.ipynb) and the [Data API Introduction for Python](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/data-api-tutorials/planet_data_api_introduction.ipynb)*\n",
    "\n",
    "- *click [here](https://developers.planet.com/docs/apis/data/) for general info on the Planet API*\n",
    "- *click [here](https://developers.planet.com/docs/data/psscene/) for more info on the specifications of the PlanetScope Satellite products and the general order process*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1fc88d8f-db8c-4434-a1a3-e7bb46c7985a",
   "metadata": {},
   "source": [
    "**This notebook allows to:**\r",
    "- request a list of images fitting a specified filter (including AOI, date, cloud-filtering)\n",
    "- request images based on interval in days\n",
    "- build an order request for the selected images according to the Planet API\n",
    "- er\r\n",
    "Create the order  it del the images into an ImageCollection-asset in GoogleEarthEngineject"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38276b1c-d8a4-411e-bb2a-6446c7e0f72d",
   "metadata": {},
   "source": [
    "**Prerequisites:**\n",
    "- A Planet account with download quota\n",
    "- Planet's Python SDK 2.0 installed and initialized in your environment. Click [here](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/quick-start-guide/) for more info and instructions.\n",
    "- A GEE project for which access for the Planet service account is granted. Click [here](https://developers.planet.com/docs/integrations/gee/quickstart/) for more info on the set-up\n",
    "- An AOI for whih the images are requested - `AOI`\n",
    "- A pre-existing GEE ImageCollection into which the images will be saved - `planet_collection`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1100e88-85c9-4cb5-9900-92fa71e443a7",
   "metadata": {},
   "source": [
    "## Planet Ordering Set-up"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2c0176f3-d5d2-4996-b647-9be87c0e38af",
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "import os # to access environmental modules\n",
    "import requests # to create http-requests\n",
    "import pathlib\n",
    "import time\n",
    "\n",
    "from functions import gee_delivery\n",
    "from planet import Session, DataClient, OrdersClient\n",
    "\n",
    "# set Planet API key as environment variable (find it under \"My Account\"->\"My Settings\"\n",
    "os.environ['PL_API_KEY'] = 'YYOUR_PLANET_API_KEY'\n",
    "\n",
    "PLANET_API_KEY = os.getenv('PL_API_KEY')\n",
    "# Setup the API Key from the `PL_API_KEY` environment variable\n",
    "\n",
    "BASE_URL = \"https://api.planet.com/data/v1\"\n",
    "ORDERS_URL = 'https://api.planet.com/compute/ops/orders/v2' \n",
    "\n",
    "session = requests.Session()\n",
    "#setup a session\n",
    "\n",
    "session.auth = (PLANET_API_KEY, \"\")\n",
    "#authenticate session with user name and password, pass in an empty string for the password\n",
    "\n",
    "res = session.get(BASE_URL)\n",
    "#make a get request to the Data API\n",
    "\n",
    "print(res.status_code)\n",
    "# test response: if \"200\" is printed, everything is fine!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08698301-0127-487e-b952-b9d3983d2f6f",
   "metadata": {},
   "source": [
    "### GEE Set-up"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fd700673-9d3a-4138-9bde-ff0197017643",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Google Earth Engine configuration\n",
    "# Define cloud delivery location:\n",
    "delivery_config = {\n",
    "        \"google_earth_engine\": {\n",
    "            \"project\": 'YOUR_GEE_PROJECT',\n",
    "            \"collection\": 'YOUR_GEE_IMAGECOLLECTION'\n",
    "        }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb887c31-5aa8-4068-917c-23b5d55ccb58",
   "metadata": {},
   "source": [
    "## Definition of AOI\n",
    "--> definition based on the geojson-format (most easy to create either manually or via uploading a shapefile via [geojson.io](https://geojson.io/))\n",
    "\n",
    "--> needs to be one feature, so no feature collection is allowed! If there are multiple features, these should be merged into one single Multipolygon-object and make sure that the merged object represents a Feature and not a FeatureCollection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "89bf3137-1d06-45b9-98b7-147deac4fd6a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# AOI defined as GeoJSON Multipolygon \n",
    "# Asse_14\n",
    "AOI = {\n",
    "        \"type\": \"MultiPolygon\",\n",
    "        \"coordinates\": [\n",
    "          [\n",
    "            [\n",
    "              [\n",
    "                5.932147271831594,\n",
    "                43.88274922368918\n",
    "              ],\n",
    "              [\n",
    "                5.933146105910044,\n",
    "                43.8828473013746\n",
    "              ],\n",
    "              [\n",
    "                5.933850620352583,\n",
    "                43.88288746530249\n",
    "              ],\n",
    "              [\n",
    "                5.934764751977466,\n",
    "                43.88336458008824\n",
    "              ],\n",
    "              [\n",
    "                5.935933012801094,\n",
    "                43.88360093228329\n",
    "              ],\n",
    "              [\n",
    "                5.937854875571714,\n",
    "                43.884020068965164\n",
    "              ],\n",
    "              [\n",
    "                5.940543715539154,\n",
    "                43.88459525673816\n",
    "              ],\n",
    "              [\n",
    "                5.94101191647709,\n",
    "                43.88547817454796\n",
    "              ],\n",
    "              [\n",
    "                5.942478948052929,\n",
    "                43.88583489493644\n",
    "              ],\n",
    "              [\n",
    "                5.943223644470504,\n",
    "                43.885888442234915\n",
    "              ],\n",
    "              [\n",
    "                5.945890226296244,\n",
    "                43.886753509064754\n",
    "              ],\n",
    "              [\n",
    "                5.946826633930318,\n",
    "                43.88736435456463\n",
    "              ],\n",
    "              [\n",
    "                5.94818664003456,\n",
    "                43.887235050963824\n",
    "              ],\n",
    "              [\n",
    "                5.949426283272385,\n",
    "                43.88517048486347\n",
    "              ],\n",
    "              [\n",
    "                5.948895603509309,\n",
    "                43.88505014892855\n",
    "              ],\n",
    "              [\n",
    "                5.947789746681158,\n",
    "                43.88422964394466\n",
    "              ],\n",
    "              [\n",
    "                5.945591478783451,\n",
    "                43.88374360277061\n",
    "              ],\n",
    "              [\n",
    "                5.943027471393854,\n",
    "                43.88319514220395\n",
    "              ],\n",
    "              [\n",
    "                5.942273908191201,\n",
    "                43.883333367755384\n",
    "              ],\n",
    "              [\n",
    "                5.941440048978061,\n",
    "                43.88262880350126\n",
    "              ],\n",
    "              [\n",
    "                5.938809138039526,\n",
    "                43.88187074575775\n",
    "              ],\n",
    "              [\n",
    "                5.937721122004447,\n",
    "                43.88164338597718\n",
    "              ],\n",
    "              [\n",
    "                5.936619742388656,\n",
    "                43.881317813763886\n",
    "              ],\n",
    "              [\n",
    "                5.934809334287038,\n",
    "                43.88129553483517\n",
    "              ],\n",
    "              [\n",
    "                5.933444872556954,\n",
    "                43.88113948610663\n",
    "              ],\n",
    "              [\n",
    "                5.932686833660093,\n",
    "                43.88103689137755\n",
    "              ],\n",
    "              [\n",
    "                5.932147271831594,\n",
    "                43.88274922368918\n",
    "              ]\n",
    "            ]\n",
    "          ]\n",
    "        ]\n",
    "      }"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f571425-50c6-44bc-969c-306b0514fdd9",
   "metadata": {},
   "source": [
    "## Setting up image filter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7f885d4a-0405-46d8-ae4f-4b93829193df",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Daterange filter\n",
    "date_filter = {\n",
    "    \"type\": \"DateRangeFilter\", # Type of filter -> Date Range\n",
    "    \"field_name\": \"acquired\", # The field to filter on: \"acquired\" -> Date on which the \"image was taken\"\n",
    "    \"config\": {\n",
    "        \"gte\": \"2017-01-01T00:00:00.000Z\", # \"gte\" -> Greater than or equal to\n",
    "        \"lte\": \"2022-12-12T23:59:59.999Z\" # \"lte\" -> Lower than or equal to\n",
    "    }\n",
    "}\n",
    "\n",
    "# geometry filter on defined AOI\n",
    "geom_filter = {\n",
    "  \"type\": \"GeometryFilter\",\n",
    "  \"field_name\": \"geometry\",\n",
    "  \"config\": AOI\n",
    "}\n",
    "\n",
    "# quality assurance\n",
    "quality_filter = {\n",
    "        \"type\": \"StringInFilter\",\n",
    "        \"field_name\": \"quality_category\",\n",
    "        \"config\": [\"standard\"]\n",
    "      }\n",
    "\n",
    "# clear pixels (no clouds, haze, snow, shadow) pre-filtering (see https://developers.planet.com/docs/data/udm-2/)\n",
    "clear_filter = {\n",
    "  \"type\": \"RangeFilter\",\n",
    "  \"field_name\": \"clear_percent\",\n",
    "  \"config\": {\n",
    "    \"gte\": 70\n",
    "  }\n",
    "}\n",
    "\n",
    "# permission pre-filtering\n",
    "permission_filter = {\n",
    "  \"type\": \"PermissionFilter\",\n",
    "  \"config\": [\"assets:download\"]\n",
    "}\n",
    "\n",
    "# Setup an \"AND\" logical filter\n",
    "image_filter = {\n",
    "    \"type\": \"AndFilter\",\n",
    "    \"config\": [date_filter, geom_filter, quality_filter, clear_filter, permission_filter]\n",
    "}\n",
    "\n",
    "# Print the logical filter\n",
    "# p(and_filter)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "00eaf014-441e-4c23-8e0e-572d553c0368",
   "metadata": {},
   "source": [
    "## Requesting image IDs fitting the filter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59eaa043-9a1d-4232-a1c9-42e34f899b9b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# request all item ids from the images available with the filter \n",
    "item_ids = gee_delivery.request_itemids(satellite_product = \"PSScene\", img_filter = image_filter , planet_session = session, planet_baseURL = BASE_URL)\n",
    "\n",
    "# Print the total number of item IDs collected\n",
    "print(len(item_ids))\n",
    "\n",
    "# print all Item IDs collected\n",
    "print(item_ids)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22493521-b4cf-443b-af6f-4ae08d44cef6",
   "metadata": {},
   "source": [
    "### Filter images - include interval of 5 days for image selection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6b0610b4-57c3-4e9f-a4b6-48deba0a41f9",
   "metadata": {},
   "outputs": [],
   "source": [
    "### remove first item to which the access is not allowed\n",
    "# first put their names in the list\n",
    "to_be_removed = ['20180804_130350_0f06', '20181231_095928_1105', '20181231_095930_1105',\n",
    "                '20190927_125217_0f02', '20190927_125218_0f02', '20191112_125227_0f02',\n",
    "                '20200622_125202_0f4c', '20200811_102153_1105', '20201017_125301_0f4c',\n",
    "                '20201029_124806_0f02', '20201122_124807_0f02', '20210531_102841_1105', \n",
    "                '20210730_102828_1105', '20210816_102945_1105']\n",
    "\n",
    "# second, remove them from initial list\n",
    "item_ids_removed_unvalid = [item for item in item_ids if item not in to_be_removed]\n",
    "\n",
    "\n",
    "# Call the function to filter with interval\n",
    "filtered_image_ids = gee_delivery.filter_images_by_interval(image_ids = item_ids_removed_unvalid, interval_days = 5)\n",
    "\n",
    "# Print number and names of the selected image IDs\n",
    "print(len(filtered_image_ids), filtered_image_ids)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f7686d02-935f-429c-bb5b-63fbb38ff5fa",
   "metadata": {},
   "source": [
    "## Building the order request"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "089d7545-b285-4769-a1a0-5a326df9c719",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Product description for the order request, including image_ids from filter\n",
    "data_products = [\n",
    "    {\n",
    "        \"item_ids\":       filtered_image_ids,\n",
    "        \"item_type\":      'PSScene', # analytic surface reflectance 8-band multispectral band analytic_8b_sr_udm2\n",
    "        \"product_bundle\": 'analytic_sr_udm2'\n",
    "    }\n",
    "]\n",
    "\n",
    "tools = [\n",
    "    {\n",
    "      \"clip\": {\n",
    "        \"aoi\": AOI\n",
    "      }\n",
    "    },\n",
    "    {\n",
    "        \"harmonize\": {\n",
    "            \"target_sensor\": 'Sentinel-2'\n",
    "        }\n",
    "    }\n",
    "]\n",
    "\n",
    "# Build the final order request\n",
    "planet_order = {\n",
    "    \"name\":     '2017-22_asse14_order',\n",
    "    \"products\": data_products,\n",
    "    \"delivery\": delivery_config,\n",
    "    \"tools\":    tools\n",
    "}\n",
    "\n",
    "print(planet_order)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c686f7a2-1dcb-4397-8160-7b045d135346",
   "metadata": {},
   "source": [
    "## Placing the Order for Delivery to GEE"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9a9094ce-4644-4bf5-babb-2d4ae4ca8218",
   "metadata": {},
   "outputs": [],
   "source": [
    "# set content type to json\n",
    "headers = {'content-type': 'application/json'}\n",
    "\n",
    "# place order !\n",
    "response = requests.post(ORDERS_URL, data=json.dumps(planet_order), auth=session.auth, headers=headers)\n",
    "\n",
    "# print order infos\n",
    "response.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d85ebb18-409b-45d3-a81a-1f4ea6dccb70",
   "metadata": {},
   "source": [
    "### Check order state"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a062a557-3fa2-4b50-8f4d-751c67b9283b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# get link of order\n",
    "order_link = ORDERS_URL + '/' + response.json()['id']\n",
    "\n",
    "# print order state\n",
    "print(requests.get(order_link, auth=session.auth).json()['state'])"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}