notebooks/HUC Feature Translation Service Examples-updated-20210804.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![](https://img.shields.io/badge/PO.DAAC-Contribution-%20?color=grey&labelColor=blue)\n",
    "\n",
    "> From the PO.DAAC Cookbook, to access the GitHub version of the notebook, follow [this link](https://github.com/podaac/tutorials/blob/master/notebooks/HUC%20Feature%20Translation%20Service%20Examples-updated-20210804.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Search by HUC Example\n",
    "\n",
    "#### *Authors: Alireza Farahmand, Cassandra Nickles, PO.DAAC*\n",
    "\n",
    "## Summary\n",
    "This notebook will geospatially search using the PO.DAAC *HUC Feature Translation Service (FTS)*, previewing (viusualizing) the queried region of interest (the  Upper Tuolumne River Basin in the San Joaquin River Basin in California's Sierra Nevada Mountains), and using FTS results to query NASA data. This is a programmatic approach to using the 'Advanced Search -> River Reach' query in the [Earthdata Search GUI](https://search.earthdata.nasa.gov/search).\n",
    "\n",
    "## Requirements\n",
    "### 1. Compute environment \n",
    "This tutorial can be run in the following environments:\n",
    "- **Local compute environment** e.g. laptop, server: this tutorial can be run on your local machine\n",
    "- **AWS instance running in us-west-2**: NASA Earthdata Cloud data in S3 can be directly accessed via temporary credentials; this access is limited to requests made within the US West (Oregon) (code: `us-west-2`) AWS region.\n",
    "\n",
    "### 2. Earthdata Login\n",
    "\n",
    "An Earthdata Login account is required to access data, as well as discover restricted data, from the NASA Earthdata system. Thus, to access NASA data, you need Earthdata Login. Please visit https://urs.earthdata.nasa.gov to register and manage your Earthdata Login account. This account is free to create and only takes a moment to set up.\n",
    "\n",
    "### Learning Objectives\n",
    "1. use the FTS-HUC API (https://fts.podaac.earthdata.nasa.gov/) to define geographic region of interest (query by partial or exact HUC or HUC region name)\n",
    "2. visualize query \n",
    "3. use coordinates returned by FTS to query Sentinel-1 data, by polygon or bounding box.\n",
    "\n",
    "**Resources**\n",
    "USGS Hydrologic unit map to help identifiy region of interest (e.g. HUC value or name) can be found here: https://water.usgs.gov/GIS/regions.html\n",
    "\n",
    "### Import libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "import requests\n",
    "import json\n",
    "from shapely.geometry import box, Polygon\n",
    "import matplotlib.pyplot as plt \n",
    "import geopandas as gpd\n",
    "import numpy as np\n",
    "import earthaccess"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search Feature Translation Service for Partial Region Matches\n",
    "\n",
    "If you are unsure what the corresponding HUC is for your region of interest, you can query the FTS for _partial_ region matches, by setting `EXACT = FALSE`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    \"status\": \"200 OK\",\n",
      "    \"time\": \"5.954 ms.\",\n",
      "    \"hits\": 3,\n",
      "    \"search on\": {\n",
      "        \"parameter\": \"region\",\n",
      "        \"exact\": false,\n",
      "        \"polygon_format\": \"\",\n",
      "        \"page_number\": 1,\n",
      "        \"page_size\": 100\n",
      "    },\n",
      "    \"results\": {\n",
      "        \"San Joaquin\": {\n",
      "            \"USGS Polygon\": {\n",
      "                \"Object URL\": \"https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/180400.zip\",\n",
      "                \"Source\": \"ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip\"\n",
      "            },\n",
      "            \"Bounding Box\": \"-121.93679916804501,36.36688239563472,-118.65438684397327,38.757297326299295\",\n",
      "            \"Convex Hull Polygon\": \"-120.63835246068544,36.36688239563472,-120.63808719818587,36.3669077091763,-118.73841884071788,37.07942819140368,-118.67420150956752,37.106490572611676,-118.6735564366519,37.10721677469388,-118.66992847311582,37.11265112260213,-118.65448236168146,37.14116804130782,-118.65438684397327,37.14146941734907,-118.65439289188998,37.14204016109818,-118.66449457312427,37.26170858174572,-118.76220691672262,37.45668952727641,-119.3277000731365,38.0651666159153,-119.68023816217266,38.44035645491624,-119.68779037986923,38.44773399761311,-119.84793537962065,38.5975748484222,-119.85336387752892,38.602501526539584,-119.85360401398685,38.60263670362269,-119.96183540965222,38.66278904519601,-119.96190132840212,38.662814343112586,-120.44062253078403,38.74564163360907,-120.48902702862557,38.753198735680655,-120.5539957670664,38.757297326299295,-120.99357654242573,38.71330113157592,-121.07883122250172,38.679223455587135,-121.0804450745826,38.678464784754965,-121.08111498187321,38.67810103163055,-121.5306744270087,38.43261620596991,-121.53113729471636,38.432277129928764,-121.8533769712995,38.059398593007586,-121.93679916804501,37.85678621415542,-121.02024189030101,36.55629579221568,-121.01674177780643,36.551948971389095,-121.00775647573704,36.54095870369781,-121.00754228094576,36.54077855369809,-120.90553311860407,36.477056078797034,-120.90373942485684,36.476002641298635,-120.73774029490619,36.387480222686065,-120.73704381990729,36.387168219561545,-120.63835246068544,36.36688239563472\",\n",
      "            \"Visvalingam Polygon\": \"-120.54009506083798,38.751263262767,-120.64081991068161,38.70357532638269,-120.71727710431293,38.70154573055248,-120.74424469072943,38.67445884830289,-120.82514061977054,38.69750556180878,-120.85090918535553,38.634815070239426,-120.85764353951174,38.6677095441467,-120.96138979351736,38.674692672260846,-120.99357654242573,38.71330113157592,-121.0041938840759,38.682131000374284,-121.08583462874088,38.67462685351097,-121.08290462249539,38.62664741087707,-121.13917907969972,38.62357320671521,-121.2089503806331,38.49669539128712,-121.27717303990221,38.476062632985816,-121.26259156388318,38.44828171636226,-121.30028969090802,38.438934230960115,-121.32968337940406,38.39078809249321,-121.3599304720654,38.390321332077235,-121.44111079277275,38.43287303096952,-121.53153281971572,38.431799249721166,-121.51200092287104,38.3990511351887,-121.52198663431386,38.33135239571044,-121.49836688747553,38.271607430178165,-121.5407886280347,38.202546845910376,-121.6015964498153,38.14619380537283,-121.56855837590825,38.097723677323074,-121.66657562158946,38.09834799503045,-121.6994337861218,38.051017879478934,-121.74477304125975,38.03062196596892,-121.82191980051499,38.02152160869139,-121.86590229836338,37.98235407021048,-121.86986600564887,37.929583865084055,-121.93679916804501,37.85678621415542,-121.83044241300178,37.83564997147988,-121.73909092251853,37.760126577847075,-121.65209140390357,37.75944488930651,-121.65894963201794,37.70730379459576,-121.61490015812797,37.67537787797863,-121.62601494873576,37.621678591603654,-121.54111389574251,37.52994497299608,-121.50439590934116,37.525883816752355,-121.46914160210423,37.48928770118414,-121.45782723962179,37.39582026382925,-121.41146298448541,37.388361478424144,-121.40667140011789,37.314010806664555,-121.45952651357749,37.284674128585095,-121.39474167826137,37.15006367462735,-121.36483071268282,37.184255913115976,-121.33036383565297,37.167644427725065,-121.28572767738893,37.18259941936856,-121.24031638058443,37.158712379822305,-121.21668344207944,37.12189013821279,-121.231344697265,37.0835010684807,-121.20818868167595,37.061546638306424,-121.24711760557386,37.03114826752028,-121.24579035974261,36.988509275919796,-121.21167625146222,36.95729284888495,-121.23447995559349,36.92657608434928,-121.19828302127468,36.914258812493415,-121.15294869113671,36.865306701111024,-121.1143471828633,36.769056561677075,-121.04964033921374,36.75343970336803,-121.00617919865618,36.76372240960205,-120.95985347476977,36.720116577378064,-120.99658496742109,36.62860115564513,-121.03185423090798,36.58366134425654,-121.00807903927824,36.54150738807198,-120.83248069892579,36.471554128805565,-120.74546076156088,36.39178235497104,-120.68716579706802,36.39413058205071,-120.63835246068544,36.36688239563472,-120.6130646732247,36.441495923643856,-120.65738012628094,36.45709164132802,-120.66078854919232,36.51874457144066,-120.64111663047282,36.53968963494981,-120.66577184918458,36.58187674217595,-120.63374172840093,36.64829444832287,-120.5664488316304,36.71118111072525,-120.48434472967449,36.748263084626046,-120.44305652348856,36.749373372124296,-120.35291486008686,36.786035749150756,-120.23388445714659,36.767794575220705,-120.09885247506452,36.77904516791159,-119.97666310754585,36.8328416803281,-119.812517053634,36.84792405842967,-119.75333349122587,36.86578132194364,-119.69273040277824,36.92774011559749,-119.62802316329538,36.92294028747989,-119.57222072588195,36.95061687285363,-119.51664880721825,36.95427249159792,-119.46285424792671,36.981914174888345,-119.383642975133,37.05806398310352,-119.2715441169737,37.09415164138085,-119.20212414312311,37.10217027886836,-119.18784042960363,37.143694729845606,-119.0858305964286,37.176455095419726,-118.98052836534208,37.185962293321666,-118.89614518838971,37.208425149536765,-118.82732031245484,37.18283535165983,-118.73841884071788,37.07942819140368,-118.71628753554387,37.10699850281924,-118.67420150956752,37.106490572611676,-118.65448236168146,37.14116804130782,-118.68439308246838,37.24133370261069,-118.66449457312427,37.26170858174572,-118.71612671679412,37.328646110808506,-118.74006027092366,37.316221957702794,-118.78637329272675,37.343784711826686,-118.79007416876266,37.39395630133214,-118.7583354854786,37.444366181462215,-118.79668088958579,37.489443694933925,-118.84989162804482,37.47656995224554,-118.9163347623167,37.5501889677563,-118.99876110906376,37.569233157310066,-119.03902598191792,37.60352632600683,-119.03232058505336,37.62993357596582,-119.06525219021057,37.68462583317262,-119.12706784115625,37.73496690601115,-119.20027055354262,37.73524533309404,-119.2162143024762,37.71411237687687,-119.26841790031187,37.73950751954578,-119.20108320354137,37.801137019450096,-119.21512584414461,37.87042564434256,-119.19927543166921,37.88483115890352,-119.30948290962311,37.94616478068332,-119.30533157629623,38.02416955035392,-119.34927245018639,38.08565116171684,-119.54763344883679,38.14419101891764,-119.62908996641869,38.196015076128845,-119.61295248831874,38.2614448656106,-119.65148469659226,38.28643111453016,-119.62837932891978,38.349732117556925,-119.68113032050456,38.40217269768385,-119.68023816217266,38.44035645491624,-119.7679873151614,38.48571382776248,-119.77203659015515,38.518283566253615,-119.83374104110106,38.55282589953333,-119.85360401398685,38.60263670362269,-119.92262494617142,38.60820715882238,-119.96190132840212,38.662814343112586,-120.01568027831865,38.665510678525095,-120.06113182303977,38.63065420878752,-120.12165386565414,38.61454576089585,-120.1460215124913,38.64340277022609,-120.23913430193011,38.62996324108025,-120.24664128108515,38.65589799312335,-120.36064677465816,38.70485176492235,-120.39097328086109,38.70561956804619,-120.44062253078403,38.74564163360907,-120.54009506083798,38.751263262767\",\n",
      "            \"HUC\": \"180400\"\n",
      "        },\n",
      "        \"San Joaquin 2\": {\n",
      "            \"USGS Polygon\": {\n",
      "                \"Object URL\": \"https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/1804.zip\",\n",
      "                \"Source\": \"ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip\"\n",
      "            },\n",
      "            \"Bounding Box\": \"-121.93679916804501,36.36688239563472,-118.65438684397327,38.757297326299295\",\n",
      "            \"Convex Hull Polygon\": \"-120.63835246068544,36.36688239563472,-120.63808719818587,36.3669077091763,-118.73841884071788,37.07942819140368,-118.67420150956752,37.106490572611676,-118.6735564366519,37.10721677469388,-118.66992847311582,37.11265112260213,-118.65448236168146,37.14116804130782,-118.65438684397327,37.14146941734907,-118.65439289188998,37.14204016109818,-118.66449457312427,37.26170858174572,-118.76220691672262,37.45668952727641,-119.3277000731365,38.0651666159153,-119.68023816217266,38.44035645491624,-119.68779037986923,38.44773399761311,-119.84793537962065,38.5975748484222,-119.85336387752892,38.602501526539584,-119.85360401398685,38.60263670362269,-119.96183540965222,38.66278904519601,-119.96190132840212,38.662814343112586,-120.44062253078403,38.74564163360907,-120.48902702862557,38.753198735680655,-120.5539957670664,38.757297326299295,-120.99357654242573,38.71330113157592,-121.07883122250172,38.679223455587135,-121.0804450745826,38.678464784754965,-121.08111498187321,38.67810103163055,-121.5306744270087,38.43261620596991,-121.53113729471636,38.432277129928764,-121.8533769712995,38.059398593007586,-121.93679916804501,37.85678621415542,-121.02024189030101,36.55629579221568,-121.01674177780643,36.551948971389095,-121.00775647573704,36.54095870369781,-121.00754228094576,36.54077855369809,-120.90553311860407,36.477056078797034,-120.90373942485684,36.476002641298635,-120.73774029490619,36.387480222686065,-120.73704381990729,36.387168219561545,-120.63835246068544,36.36688239563472\",\n",
      "            \"Visvalingam Polygon\": \"-120.54009506083798,38.751263262767,-120.64081991068161,38.70357532638269,-120.71727710431293,38.70154573055248,-120.74424469072943,38.67445884830289,-120.82514061977054,38.69750556180878,-120.85090918535553,38.634815070239426,-120.85764353951174,38.6677095441467,-120.96138979351736,38.674692672260846,-120.99357654242573,38.71330113157592,-121.0041938840759,38.682131000374284,-121.08583462874088,38.67462685351097,-121.08290462249539,38.62664741087707,-121.13917907969972,38.62357320671521,-121.2089503806331,38.49669539128712,-121.27717303990221,38.476062632985816,-121.26259156388318,38.44828171636226,-121.30028969090802,38.438934230960115,-121.32968337940406,38.39078809249321,-121.3599304720654,38.390321332077235,-121.44111079277275,38.43287303096952,-121.53153281971572,38.431799249721166,-121.51200092287104,38.3990511351887,-121.52198663431386,38.33135239571044,-121.49836688747553,38.271607430178165,-121.5407886280347,38.202546845910376,-121.6015964498153,38.14619380537283,-121.56855837590825,38.097723677323074,-121.66657562158946,38.09834799503045,-121.6994337861218,38.051017879478934,-121.74477304125975,38.03062196596892,-121.82191980051499,38.02152160869139,-121.86590229836338,37.98235407021048,-121.86986600564887,37.929583865084055,-121.93679916804501,37.85678621415542,-121.83044241300178,37.83564997147988,-121.73909092251853,37.760126577847075,-121.65209140390357,37.75944488930651,-121.65894963201794,37.70730379459576,-121.61490015812797,37.67537787797863,-121.62601494873576,37.621678591603654,-121.54111389574251,37.52994497299608,-121.50439590934116,37.525883816752355,-121.46914160210423,37.48928770118414,-121.45782723962179,37.39582026382925,-121.41146298448541,37.388361478424144,-121.40667140011789,37.314010806664555,-121.45952651357749,37.284674128585095,-121.39474167826137,37.15006367462735,-121.36483071268282,37.184255913115976,-121.33036383565297,37.167644427725065,-121.28572767738893,37.18259941936856,-121.24031638058443,37.158712379822305,-121.21668344207944,37.12189013821279,-121.231344697265,37.0835010684807,-121.20818868167595,37.061546638306424,-121.24711760557386,37.03114826752028,-121.24579035974261,36.988509275919796,-121.21167625146222,36.95729284888495,-121.23447995559349,36.92657608434928,-121.19828302127468,36.914258812493415,-121.15294869113671,36.865306701111024,-121.1143471828633,36.769056561677075,-121.04964033921374,36.75343970336803,-121.00617919865618,36.76372240960205,-120.95985347476977,36.720116577378064,-120.99658496742109,36.62860115564513,-121.03185423090798,36.58366134425654,-121.00807903927824,36.54150738807198,-120.83248069892579,36.471554128805565,-120.74546076156088,36.39178235497104,-120.68716579706802,36.39413058205071,-120.63835246068544,36.36688239563472,-120.6130646732247,36.441495923643856,-120.65738012628094,36.45709164132802,-120.66078854919232,36.51874457144066,-120.64111663047282,36.53968963494981,-120.66577184918458,36.58187674217595,-120.63374172840093,36.64829444832287,-120.5664488316304,36.71118111072525,-120.48434472967449,36.748263084626046,-120.44305652348856,36.749373372124296,-120.35291486008686,36.786035749150756,-120.23388445714659,36.767794575220705,-120.09885247506452,36.77904516791159,-119.97666310754585,36.8328416803281,-119.812517053634,36.84792405842967,-119.75333349122587,36.86578132194364,-119.69273040277824,36.92774011559749,-119.62802316329538,36.92294028747989,-119.57222072588195,36.95061687285363,-119.51664880721825,36.95427249159792,-119.46285424792671,36.981914174888345,-119.383642975133,37.05806398310352,-119.2715441169737,37.09415164138085,-119.20212414312311,37.10217027886836,-119.18784042960363,37.143694729845606,-119.0858305964286,37.176455095419726,-118.98052836534208,37.185962293321666,-118.89614518838971,37.208425149536765,-118.82732031245484,37.18283535165983,-118.73841884071788,37.07942819140368,-118.71628753554387,37.10699850281924,-118.67420150956752,37.106490572611676,-118.65448236168146,37.14116804130782,-118.68439308246838,37.24133370261069,-118.66449457312427,37.26170858174572,-118.71612671679412,37.328646110808506,-118.74006027092366,37.316221957702794,-118.78637329272675,37.343784711826686,-118.79007416876266,37.39395630133214,-118.7583354854786,37.444366181462215,-118.79668088958579,37.489443694933925,-118.84989162804482,37.47656995224554,-118.9163347623167,37.5501889677563,-118.99876110906376,37.569233157310066,-119.03902598191792,37.60352632600683,-119.03232058505336,37.62993357596582,-119.06525219021057,37.68462583317262,-119.12706784115625,37.73496690601115,-119.20027055354262,37.73524533309404,-119.2162143024762,37.71411237687687,-119.26841790031187,37.73950751954578,-119.20108320354137,37.801137019450096,-119.21512584414461,37.87042564434256,-119.19927543166921,37.88483115890352,-119.30948290962311,37.94616478068332,-119.30533157629623,38.02416955035392,-119.34927245018639,38.08565116171684,-119.54763344883679,38.14419101891764,-119.62908996641869,38.196015076128845,-119.61295248831874,38.2614448656106,-119.65148469659226,38.28643111453016,-119.62837932891978,38.349732117556925,-119.68113032050456,38.40217269768385,-119.68023816217266,38.44035645491624,-119.7679873151614,38.48571382776248,-119.77203659015515,38.518283566253615,-119.83374104110106,38.55282589953333,-119.85360401398685,38.60263670362269,-119.92262494617142,38.60820715882238,-119.96190132840212,38.662814343112586,-120.01568027831865,38.665510678525095,-120.06113182303977,38.63065420878752,-120.12165386565414,38.61454576089585,-120.1460215124913,38.64340277022609,-120.23913430193011,38.62996324108025,-120.24664128108515,38.65589799312335,-120.36064677465816,38.70485176492235,-120.39097328086109,38.70561956804619,-120.44062253078403,38.74564163360907,-120.54009506083798,38.751263262767\",\n",
      "            \"HUC\": \"1804\"\n",
      "        },\n",
      "        \"San Joaquin Delta\": {\n",
      "            \"USGS Polygon\": {\n",
      "                \"Object URL\": \"https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/18040003.zip\",\n",
      "                \"Source\": \"ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip\"\n",
      "            },\n",
      "            \"Bounding Box\": \"-121.93679916804501,37.50128378554052,-120.83793204891731,38.21666854588847\",\n",
      "            \"Convex Hull Polygon\": \"-121.48401321978946,37.50128378554052,-121.48319938333242,37.501357755332094,-121.48196255312598,37.50148574804024,-121.05388696212378,37.76071366013787,-120.90450576548068,38.0272342086825,-120.90349268423222,38.02938314201248,-120.83793204891731,38.18877460322341,-120.83800179891722,38.1976922021679,-120.83898908849903,38.19987750528952,-121.02443172883619,38.21666854588847,-121.02474798300238,38.21663954068015,-121.02495458821039,38.216620591721835,-121.61499185396116,38.10789443147394,-121.6671072070053,38.09826675128056,-121.84538162652024,38.06328592216818,-121.85283117130035,38.05978179300695,-121.8533769712995,38.059398593007586,-121.93679916804501,37.85678621415542,-121.56421756653998,37.54766027817686,-121.54682447177532,37.53336393132406,-121.54584872802684,37.53266251257514,-121.54544794886078,37.532376185492296,-121.54202411449108,37.53037829903707,-121.49308462915042,37.502441020955416,-121.48639323541079,37.501483144915255,-121.48560074791203,37.501374500123745,-121.48401321978946,37.50128378554052\",\n",
      "            \"Visvalingam Polygon\": \"-121.02143199238253,38.21228919277024,-121.03881544131383,38.21370070526808,-121.05832012565855,38.19822062820873,-121.07285287251102,38.19676138550267,-121.11744717765015,38.17114820429242,-121.14022114948978,38.168721211587865,-121.15031440780746,38.15854012306204,-121.20154061397795,38.143356763710585,-121.27375955553254,38.116192127294426,-121.32007884504395,38.108511572097996,-121.33525729293706,38.09480684191095,-121.35392083665806,38.08854727525397,-121.41605480843663,38.087353247130864,-121.44424249485121,38.08399005338606,-121.4631167833636,38.071604213821956,-121.4724672395991,38.08759970546379,-121.50203907184482,38.091632609624185,-121.5035856697591,38.072714664861905,-121.51886918848538,38.089077872128144,-121.53291849575527,38.091567440874314,-121.56947503215684,38.08615950442436,-121.5702684009056,38.09822388148899,-121.60393055710335,38.10898488355559,-121.63051299143712,38.10154624398382,-121.6371124122602,38.08992846796019,-121.66657562158946,38.09834799503045,-121.68644943926694,38.08549239192541,-121.68354131427145,38.067767361744586,-121.6994337861218,38.051017879478934,-121.74477304125975,38.03062196596892,-121.80058061825645,38.025494545143545,-121.82947484737826,38.03754110345818,-121.83790479528182,38.06236660550297,-121.8533769712995,38.059398593007586,-121.83359162133019,38.0236317357714,-121.82191980051499,38.02152160869139,-121.8452383838121,37.99565135456487,-121.86590229836338,37.98235407021048,-121.87389402439265,37.949298472345106,-121.88361340562756,37.94069631819184,-121.86986600564887,37.929583865084055,-121.87272500251947,37.917601039061026,-121.88853686499493,37.912210873444394,-121.93679916804501,37.85678621415542,-121.88209073375492,37.84099142667992,-121.86810714523494,37.85399849645137,-121.85208152546818,37.83929578814087,-121.83044241300178,37.83564997147988,-121.8066090526221,37.81308303505659,-121.7922590016027,37.80782963818973,-121.76324145268939,37.7858900934321,-121.76527957768621,37.7773995799036,-121.73909092251853,37.760126577847075,-121.70685220486024,37.77253795491117,-121.69044629863572,37.761101645553936,-121.65209140390357,37.75944488930651,-121.66449931638431,37.74842932369859,-121.6507850361973,37.735751545593246,-121.65918360805927,37.72781387164724,-121.65894963201794,37.70730379459576,-121.63536538726288,37.70130697273004,-121.63448013830595,37.689717726914694,-121.61490015812797,37.67537787797863,-121.60974490188602,37.64429441552687,-121.6227430268658,37.63603342387307,-121.62601494873576,37.621678591603654,-121.61450599042024,37.59930529893006,-121.58214772276216,37.58058849166747,-121.5660067644539,37.54927187400773,-121.54111389574251,37.52994497299608,-121.50439590934116,37.525883816752355,-121.49308462915042,37.502441020955416,-121.48138812291859,37.505721846992,-121.46184374690722,37.53450626882233,-121.44088779485645,37.54675186776166,-121.42484409071466,37.54751497713545,-121.42580857821315,37.564976893775,-121.38028850640882,37.586133978117175,-121.36222241581186,37.603589127048394,-121.31597830859198,37.6093966551644,-121.2544957930624,37.65727026654844,-121.22158270248849,37.67257598423299,-121.22429523477598,37.68152568213577,-121.2057427212631,37.69569779461375,-121.16857574007076,37.70748815501213,-121.14110785782174,37.729918075810644,-121.11848947660684,37.73365946955482,-121.10911928703808,37.7484026966153,-121.09223503081427,37.74791053724107,-121.09480595685193,37.760903828887535,-121.05617153503692,37.76043123409664,-121.09747076830615,37.76801436220984,-121.15035315884904,37.79415341529426,-121.18449382754608,37.82583186628676,-121.19699943377668,37.826716714202064,-121.2195945576999,37.85136148083046,-121.26523294929575,37.87824116933041,-121.2947732367499,37.913431269275804,-121.271524724286,37.93996951090128,-121.19155812336845,37.95833420253945,-121.11637632452681,37.95492616608641,-121.10437461621211,37.957914906706776,-121.05944651211519,37.95597624525141,-121.0339739194464,37.94209255568967,-121.0166917559315,37.94320716193795,-121.00221693720397,37.95548945983552,-120.97566607266185,37.96720422856731,-120.97877787890707,37.989337251449626,-120.9583201601888,37.98447010979055,-120.940789375841,37.99810579518606,-120.92829857481871,38.01908881702849,-120.90450576548068,38.0272342086825,-120.91396404254931,38.035717584710994,-120.91473279150648,38.05371388572473,-120.95564168727628,38.05178600656103,-120.98212063202686,38.064245121125055,-121.03830712152296,38.03886609408113,-121.06709473606162,38.018101445155025,-121.1009083245508,38.00855445246151,-121.130640501588,38.008583444128135,-121.20277275251772,37.95955794732919,-121.28034443156395,37.99378153581773,-121.26629757012745,38.004894071217166,-121.2374627691305,38.01277404724658,-121.21825716395199,38.036504297209774,-121.1927208462833,38.05271741697629,-121.17248860464804,38.05317975343388,-121.1349351203313,38.074925166941796,-121.1088929182884,38.065759808622715,-121.08234508395464,38.050340206563305,-121.07683546104653,38.075894660690324,-121.06335145898413,38.08001638672556,-121.05341488399955,38.103619159605614,-121.02532235904312,38.11545590229554,-121.02185200800687,38.141849487671266,-120.99854338616802,38.13813815330201,-120.96777642579912,38.14682469287186,-120.9602597226858,38.1365514095545,-120.9325378352288,38.152037275155465,-120.90481372589687,38.15161844286445,-120.90117972173584,38.163558659512546,-120.8795133332278,38.16931939075363,-120.83793204891731,38.18877460322341,-120.83898908849903,38.19987750528952,-120.85724504159566,38.19074097717868,-120.87978625510237,38.18972461780527,-120.89379082070565,38.19927907508213,-120.9222689144114,38.1909182750951,-120.94590735812471,38.20575099590542,-120.97285543933293,38.20184120424483,-121.02143199238253,38.21228919277024\",\n",
      "            \"HUC\": \"18040003\"\n",
      "        }\n",
      "    }\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "# Querying partial matches with region \"San Joaquin\"\n",
    "# This \"partial\" match is anything that BEGINS with the region specified.\n",
    "\n",
    "REGION = \"San Joa\"\n",
    "EXACT = False\n",
    "\n",
    "# Query Feature Translation Service and parse JSON response\n",
    "r = requests.get(\"https://fts.podaac.earthdata.nasa.gov/region/{}?exact={}\".format(REGION, EXACT))\n",
    "\n",
    "# Load response from FTS\n",
    "response = r.json()\n",
    "\n",
    "# Print all elements in HUC database that partially matches with region \"San Jo\"\n",
    "print(json.dumps(response, indent = 4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search Feature Translation Service for Exact HUC Matches\n",
    "\n",
    "Here we can set a HUC ID, or hydrologic unit code, and use this to query the HUC FTS. By defining the parameter _EXACT = True_, we tell the query to not search for partial matches.\n",
    "\n",
    "Based on the partial name response in the previous step, we can now do an exact search for San Joaquin River Basin, using its HUC ID (1804)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\"San Joaquin\"\n"
     ]
    }
   ],
   "source": [
    "# Querying exact matches for HUC \"1804\" = San Joaquin River Basin\n",
    "\n",
    "HUC = \"1804\"\n",
    "EXACT = True\n",
    "\n",
    "# Query Feature Translation Service and parse JSON response\n",
    "r = requests.get(\"https://fts.podaac.earthdata.nasa.gov/huc/{}?exact={}\".format(HUC, EXACT))\n",
    "\n",
    "# Load response from FTS\n",
    "response = r.json()\n",
    "\n",
    "# Print only the region name from the query results of the HUC database\n",
    "print(json.dumps(response[\"results\"][\"1804\"][\"Region Name\"], indent = 4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search Feature Translation Service for Exact HUC and Named Region Matches\n",
    "\n",
    "What if we are interested in the Toulumne River Basin within the San Joaquin main basin? We can search directly for that basin as well. If we already know an exact region name or HUC in USGS's Watershed Boundary Dataset (WBD), we can use this or the name of the basin, or search partially like we did above. Below is an example of searching by exact match using HUC ID (e.g. `18040009`) that could be modified to search  by region name (\"Upper Tuolumne\")."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    \"status\": \"200 OK\",\n",
      "    \"time\": \"1.659 ms.\",\n",
      "    \"hits\": 1,\n",
      "    \"search on\": {\n",
      "        \"parameter\": \"HUC\",\n",
      "        \"exact\": true,\n",
      "        \"polygon_format\": \"\",\n",
      "        \"page_number\": 1,\n",
      "        \"page_size\": 100\n",
      "    },\n",
      "    \"results\": {\n",
      "        \"18040009\": {\n",
      "            \"USGS Polygon\": {\n",
      "                \"Object URL\": \"https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/18040009.zip\",\n",
      "                \"Source\": \"ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip\"\n",
      "            },\n",
      "            \"Bounding Box\": \"-121.17476593797784,37.57291785522102,-119.19927543166921,38.22952896670182\",\n",
      "            \"Convex Hull Polygon\": \"-121.105517801627,37.57291785522102,-120.51777999837259,37.58160878749919,-119.26845687218679,37.73942430183757,-119.26095827844847,37.741190162251485,-119.26079495969867,37.74128122475133,-119.25581474616479,37.7450598684955,-119.25563206491506,37.74520087891193,-119.25521361804067,37.745555179953044,-119.20452512020273,37.79316755800414,-119.20311483687158,37.794898117376476,-119.20297581291345,37.79511513091779,-119.20108320354137,37.801137019450096,-119.20096521291657,37.803876760070864,-119.19927543166921,37.88483115890352,-119.19931234937746,37.885001276611604,-119.20064394937538,37.88738135160793,-119.31090541587093,38.044980644071586,-119.3277000731365,38.0651666159153,-119.32796109605277,38.06544024091488,-119.34908448143665,38.08655395234041,-119.62508146642494,38.22905559795254,-119.65624842470987,38.22952896670182,-119.65829346949835,38.22947615316025,-119.79473757241158,38.21799358859471,-119.99491475022586,38.196920114669126,-120.38613654232694,38.056378609678916,-121.15444382863438,37.62884831659255,-121.15500076925849,37.6284224540932,-121.15993039529252,37.62332076451776,-121.16822139007132,37.61386883849076,-121.17452907235321,37.605445134337174,-121.17462853797804,37.60522817287921,-121.17469632131127,37.60502320725453,-121.17471004943627,37.60496802808791,-121.17476593797784,37.604743358296616,-121.17472602131124,37.60443736142207,-121.1743974786034,37.603737121839856,-121.17385444318757,37.603213931215635,-121.12495024430518,37.575249448967384,-121.1206057318119,37.57340581772024,-121.1184699109819,37.573299354178744,-121.105517801627,37.57291785522102\",\n",
      "            \"Visvalingam Polygon\": \"-119.65612154137676,38.229472830243594,-119.65887392887248,38.21611789588928,-119.68748882882807,38.20072575945488,-119.74423195478164,38.21583016359807,-119.79473757241158,38.21799358859471,-119.80777226405803,38.20387888444998,-119.83634931818034,38.19900379279085,-119.8794751608217,38.205164957364616,-119.92926093053609,38.1903575073876,-119.95874486382365,38.194300821964816,-119.9915583491894,38.18745202718378,-119.99491475022586,38.196920114669126,-120.05974666158357,38.15445730952666,-120.10528053234623,38.13442047414111,-120.12843912918527,38.10262073148215,-120.20521266552441,38.056065841971076,-120.26427926855774,38.061807551337154,-120.34283367885251,38.04442165553081,-120.36616220485797,38.05864021280041,-120.38138515275097,38.04379106074015,-120.39399451523144,38.00852514516987,-120.41557226103123,38.00413815246833,-120.4432863495299,37.97081393481176,-120.45616958284324,37.92842260675252,-120.46878266719864,37.921885701554345,-120.4624829120001,37.891430354726594,-120.479954646348,37.871879250590325,-120.48053337030541,37.82415609128935,-120.5431307066666,37.84913992354228,-120.55227857644405,37.86382160997783,-120.57047251079081,37.845455260006304,-120.5664340514221,37.82240133087544,-120.59755003054045,37.81161053401718,-120.64595511379866,37.78181727677179,-120.67580313979397,37.7973594465393,-120.7399643115694,37.77691864136273,-120.75337800946522,37.73604807163446,-120.78855502295232,37.75464512473059,-120.82306428227372,37.739964848711736,-120.82298294894053,37.72367104352867,-120.84114918537068,37.706087340431,-120.8673865186633,37.69917305085835,-120.87598703427494,37.68470263317249,-120.91724289983591,37.65975447800287,-120.94840845082916,37.657548763422994,-121.0014800642885,37.642007069697115,-121.06141474752877,37.632796530128076,-121.15500076925849,37.6284224540932,-121.17472602131124,37.60443736142207,-121.15475178384224,37.60555392496201,-121.12649717971942,37.5761612791743,-121.105517801627,37.57291785522102,-121.06195388086127,37.58432554999496,-121.051833277752,37.59549621664428,-120.9623811789325,37.616090631195675,-120.93801052688701,37.61182627286894,-120.86057590200721,37.62129079368759,-120.85730386034561,37.613155902033554,-120.78087282192257,37.61414406661538,-120.73817309594716,37.63053679471494,-120.70606299078867,37.6253131207647,-120.65312547628753,37.630845649922776,-120.64372085026048,37.617530275985075,-120.59897548366325,37.61838293640045,-120.58566304618392,37.6280897895104,-120.55437374519079,37.61949203744041,-120.53035751501977,37.62416281034979,-120.52267756711501,37.58373637916253,-120.47482846302262,37.59087335206817,-120.45815308909016,37.620518593688814,-120.4371221932895,37.63718915616295,-120.3849402642038,37.635048797832894,-120.3755883360933,37.65339462697108,-120.39417890064777,37.66818361028146,-120.392313883984,37.68359100504921,-120.3559603048738,37.67552716860342,-120.32610607262848,37.648966585311314,-120.30639988828403,37.66573735924362,-120.3455439350983,37.72512544352645,-120.31539807993676,37.733894229971156,-120.28665821956469,37.72927809560332,-120.28245683519623,37.74541342682829,-120.26069274460497,37.73358365601331,-120.25387803732389,37.749232223697334,-120.200135472824,37.76372567054983,-120.17357968640687,37.79608365070794,-120.12741327606187,37.78170633927192,-120.08906888341306,37.81273366005712,-120.07891344384547,37.82866939649068,-120.05533048450707,37.812757440265386,-120.02518823247055,37.81132716005931,-119.96359235131615,37.78073240906514,-119.94507216905322,37.76542058617224,-119.90693944932076,37.75781682576735,-119.86549272230178,37.77222938512,-119.85359450461186,37.758767389307536,-119.83160174943771,37.76963435595735,-119.80589665676928,37.75608133722835,-119.75060675164673,37.77341942574316,-119.7359645225028,37.78635874968137,-119.6978660861036,37.78960109342637,-119.64907657576265,37.81516770484501,-119.65722697262504,37.83230492565173,-119.59708603105173,37.86135878810666,-119.58892104668939,37.88872669535584,-119.57247042275657,37.8998297015886,-119.53527651760601,37.90190377762701,-119.49696578120711,37.86409281310239,-119.47533168332404,37.85892923602705,-119.45447817606475,37.871394138091034,-119.44539026566218,37.858937875610366,-119.4045319969756,37.85021429541558,-119.40293857510306,37.833821247524384,-119.37314428244099,37.83849664855876,-119.35155096789117,37.82452854545545,-119.3552763335104,37.812805713182,-119.32340220126821,37.79368655279501,-119.29229722319144,37.762878678884476,-119.2876598648653,37.74535544245333,-119.26052065344913,37.74159433725089,-119.24428567430766,37.76834668616766,-119.22055414726117,37.77924966531742,-119.20108320354137,37.801137019450096,-119.21738830351609,37.8183151860901,-119.20449054936944,37.82981189961396,-119.21625690560114,37.847411426669964,-119.21512584414461,37.87042564434256,-119.19927543166921,37.88483115890352,-119.23787860140095,37.911280908862466,-119.26486444510903,37.91263911719369,-119.26807310656238,37.92880876300194,-119.30948290962311,37.94616478068332,-119.31574230232172,37.96621302648555,-119.30533157629623,38.02416955035392,-119.34927245018639,38.08565116171684,-119.35845034913046,38.08266815651314,-119.39810467927725,38.1068175096006,-119.43127595110076,38.11332130542388,-119.4403859021283,38.09636985024184,-119.46399499479998,38.09838383773871,-119.4692413104168,38.12798441894279,-119.48819819267908,38.132729004352086,-119.50246159786525,38.159339980352456,-119.50459633952858,38.140964939755975,-119.54763344883679,38.14419101891764,-119.54624260196397,38.15397065015242,-119.5773162810824,38.15780512931315,-119.57980050712018,38.17791634178195,-119.62908996641869,38.196015076128845,-119.62508146642494,38.22905559795254,-119.65612154137676,38.229472830243594\",\n",
      "            \"Region Name\": \"Upper Tuolumne\"\n",
      "        }\n",
      "    }\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "# Querying exact matches with HUC \"18040009\" = Upper Tuolumne\n",
    "\n",
    "HUC = \"18040009\" #or REGION = \"Upper Tuolumne\"\n",
    "EXACT = True\n",
    "\n",
    "# Query Feature Translation Service and parse JSON response\n",
    "# If using region, Note the change in endpoint must go from \"/huc\" to \"/region\" and the .format() must change from HUC to REGION\n",
    "r = requests.get(\"https://fts.podaac.earthdata.nasa.gov/huc/{}?exact={}\".format(HUC, EXACT))\n",
    "\n",
    "# Load response from FTS\n",
    "response = r.json()\n",
    "\n",
    "# Print all elements in HUC database that exactly match HUC \"18040009\"\n",
    "print(json.dumps(response, indent = 4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Visualize the Response from the HUC Feature Translation Service"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Function for Visualization\n",
    "\n",
    "Below is a function created specifically to visualize the output of the HUC Feature Translation Service. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "def visualize(fts_response):\n",
    "    \n",
    "    regions = []\n",
    "    bounding_boxes = []\n",
    "    convex_hull_polygons = []\n",
    "    visvalingam_polygons = []\n",
    "    for element in fts_response['results']:\n",
    "        for heading in fts_response['results'][element]:\n",
    "            if heading == \"Bounding Box\":\n",
    "                bounding_boxes.append([float(e) for e in fts_response['results'][element][heading].split(\",\")])\n",
    "            elif heading == \"Convex Hull Polygon\":\n",
    "                convex_hull_polygons.append([float(e) for e in fts_response['results'][element][heading].split(\",\")])\n",
    "            elif heading == \"Visvalingam Polygon\":\n",
    "                visvalingam_polygons.append([float(e) for e in fts_response['results'][element][heading].split(\",\")])\n",
    "            elif heading == \"HUC\":\n",
    "                regions.append(\"Region Name: \" + element + \"\\n\" + \"HUC: \" + fts_response['results'][element][heading])\n",
    "            elif heading == \"Region Name\":\n",
    "                regions.append(\"Region Name: \" + fts_response['results'][element][heading] + \"\\n\" + \"HUC: \" + element)\n",
    "            else:\n",
    "                continue\n",
    "\n",
    "    bounding_boxes = [box(e[0], e[1], e[2], e[3]) for e in bounding_boxes]\n",
    "    convex_hull_polygons = [Polygon(np.asarray(polygon).reshape(-1,2)) for polygon in convex_hull_polygons]\n",
    "    visvalingam_polygons = [Polygon(np.asarray(polygon).reshape(-1,2)) for polygon in visvalingam_polygons]\n",
    "    \n",
    "    for i in range(len(bounding_boxes)):\n",
    "        ax = gpd.GeoSeries(bounding_boxes[i]).plot(alpha=0.2, cmap='Pastel1', figsize=(10,10))\n",
    "        gpd.GeoSeries(convex_hull_polygons[i]).plot(ax = ax, cmap='Pastel2')\n",
    "        gpd.GeoSeries(visvalingam_polygons[i]).plot(alpha=0.5, ax=ax, cmap='viridis')\n",
    "\n",
    "        plt.title(regions[i])\n",
    "        plt.show()\n",
    "            "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualization\n",
    "\n",
    "We can take that response and pass it to the _visualize()_ function created above. The pink polygon is *Bounding Box*, the green is *Convex Hull Polygon* and the purple color is  *Visvalingam Polygon*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA0MAAAFTCAYAAAD7idddAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjcuMSwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/bCgiHAAAACXBIWXMAAA9hAAAPYQGoP6dpAACHa0lEQVR4nO3deXhU1f0/8PedfbLMZE/IQgJhDRBQXAguiIKKG66tVgW/dWldqrW2P/e1RVRqq7Ut2rphtaUiUlxxQcANEBWUnYQkhOzLJJl9vef3R8jAkIRkkkkmM/N+PU8eyJ07Z85chsm8c875HEkIIUBERERERBRjFOHuABERERERUTgwDBERERERUUxiGCIiIiIiopjEMERERERERDGJYYiIiIiIiGISwxAREREREcUkhiEiIiIiIopJDENERERERBSTGIaIiIiIiCgmMQwRUdR59dVXIUmS/0ulUmHEiBG48sorUVpaOuiPf8YZZ+CMM84Y9Mc5WmVlpf85L1++vMvtjzzyCCRJQnNz85D3bbBIkoTbbrut29veeustSJKE9evXD22nQuC6664LeA339HXdddeF/HELCgpC2iYR0XCmCncHiIgGyyuvvIIJEybA6XTiq6++wqJFi7Bu3Trs2bMHycnJg/a4f//73wet7b66//77cdlll0GtVoe7K9QPDz74IH75y1/6v//+++9x66234vHHH8fs2bP9x9PT08PRPSKiqMEwRERRa/LkyTjhhBMAdIzW+Hw+PPzww/jf//6H//u//xu0xy0qKhq0tvti3rx5+PDDD/H888/jV7/6VVj7Qsfm8Xj8o5dHKiwsRGFhof97p9MJABg7dixmzJgxpH0kIopmnCZHRDGjMxg1NDQEHP/2229x0UUXISUlBTqdDscddxzefPPNLvf/8ssvUVJSAp1Oh5ycHDz44IN48cUXIUkSKisr/ed1N03OZDLhlltuQU5ODjQaDUaPHo37778fLpcr4LzOaV//+te/MHHiRMTFxWHq1Kl47733+vw8zzzzTJxzzjn4/e9/D4vFcsxzP/nkE8yfPx+5ubnQ6XQYM2YMfvGLX3SZStc5xe7HH3/EFVdcAaPRiJSUFPzmN7+B1+vF3r17ce655yIxMREFBQV46qmnujyW2WzGb3/7W4waNQoajQY5OTn49a9/DZvN1ufnNlBnnHEGJk+ejC+++AIzZsyAXq/3/1v6fD7/eZ1TDp966iksWrQII0eOhE6nwwknnIC1a9d2abe0tBQ/+9nPkJGRAa1Wi4kTJ+Jvf/tbwDnr16+HJEn417/+hbvuugs5OTnQarUoKyvr13Pp/Dc5Wuc00SNfk7Is46mnnsKECROg1WqRkZGBBQsWoLq6+piP0XkdXn311S63SZKERx55pEt/+vsa6bw+//nPf3D//fcjOzsbBoMBc+bMwd69e7s8/qeffoqzzjoLBoMBcXFxOOWUU7r9tyEiOhaGISKKGRUVFQCAcePG+Y+tW7cOp5xyCtra2vD8889j9erVmDZtGn76058GfAD88ccfMXfuXNjtdixbtgzPP/88vv/+eyxatKjXx3U6nZg9ezZee+01/OY3v8H777+Pa665Bk899RQuvfTSLue///77+Otf/4rHHnsMK1euREpKCi655BKUl5f3+bk++eSTaG5uxpIlS4553v79+1FSUoKlS5fi448/xkMPPYTNmzfj1FNPhcfj6XL+T37yE0ydOhUrV67EjTfeiD//+c+48847cfHFF+P888/HqlWrcOaZZ+Luu+/G22+/7b+f3W7HrFmzsGzZMtx+++348MMPcffdd+PVV1/FRRddBCGE/9zOD9WDtdanvr4eV155Ja6++mqsXr0al19+Of7whz/gjjvu6HLuX//6V6xZswbPPPMMXn/9dSgUCsybNw8bN270n7Nr1y6ceOKJ2LFjB55++mm89957OP/883H77bfj0Ucf7dLmvffei6qqKjz//PN49913kZGRMSjP80g333wz7r77bsydOxfvvPMOfv/732PNmjWYOXNmyNeQ9fc10um+++7DgQMH8OKLL+If//gHSktLceGFFwaE1ddffx1nn302DAYDli1bhjfffBMpKSk455xzGIiIKDiCiCjKvPLKKwKA2LRpk/B4PMJisYg1a9aIrKwscfrppwuPx+M/d8KECeK4444LOCaEEBdccIEYMWKE8Pl8QgghrrjiChEfHy+ampr85/h8PlFUVCQAiIqKCv/xWbNmiVmzZvm/f/755wUA8eabbwY8xpNPPikAiI8//th/DIDIzMwUZrPZf6y+vl4oFAqxePHiYz7viooKAUAsWbJECCHE1VdfLeLj40VdXZ0QQoiHH35YAAh4DkeSZVl4PB5x4MABAUCsXr3af1vnfZ9++umA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F7/5zW8gyzKefPJJmM3mgHVYzz77LE499VScdtppuPnmm1FQUACLxYKysjK8++67+Oyzz0JwBbs677zzkJKSguuvvx6PPfYYVCoVXn31VRw8eDDgvPHjx+Omm27Cc88956+GV1lZiQcffBB5eXm48847e3wMSZJwzTXX4OWXX0ZhYSGmTp2Kb775Bv/+978H5Tn1RUJCAp577jksXLgQJpMJl19+OTIyMtDU1IQffvgBTU1NWLp0adj6R0SRhWGIiGLKr371K3/Z6quuugqzZ8/GN998g0WLFuHXv/41WltbkZqaiqKiooDiCFOnTsUnn3yC3/72t1iwYAGSk5Nx7bXXYtasWbj77rthNBp7fEydTod169bh/vvvx5IlS9DU1IScnBz89re/xcMPPzzozzkuLg6PPPIIbrrppoDjarUa7777Lu644w784he/gEqlwpw5c/Dpp592CQUDFR8fjy+++AJPPPEE/vGPf6CiogJ6vR4jR47EnDlz/KMcQMeIm8/nCyi33ZPCwkJ88803ePTRR/HII4+gqakJCQkJOOmkk/DJJ5/4R0WOlJWVhb/97W/47W9/i+3btyMlJQX33Xdft4UmbrvtNjidTtx+++1obGzEpEmT8P777+OUU07xn1NUVITvv/8ev//97/HAAw+gsbERSUlJGDt2LM4777z+XbA+MBgMWLNmDX7961/jmmuuQVJSEm644QbMmzcPN9xwQ8C5S5cuRWFhIV566SX87W9/g9FoxLnnnovFixd3u0btSE8//TSAjpFVq9WKM888E++9917Av9lQu+aaazBy5Eg89dRT+MUvfgGLxYKMjAxMmzatS6EIIqJjkURfftoQEVG3zj77bFRWVmLfvn3h7gr1wRlnnIHm5mbs2LHjmOdVVlZi1KhRWLJkSY/FNYiIKPJxZIiIqI9+85vf4LjjjkNeXh5MJhPeeOMNfPLJJ3jppZfC3TUiIiLqB4YhIqI+8vl8eOihh1BfXw9JklBUVIR//etfuOaaa8LdNSIiIuoHTpMjIiIiIqKY1HP5IyIiIiIioijGMEREFEVeffVVSJKEb7/9ttvbL7jggi5VwCRJ6nG/lrfeeguSJGH9+vVdbnv33Xdx4YUXIjMzExqNBikpKTjrrLPwxhtvwOPx9Kv/r732Gq688kqMHz8eCoXimBXLtm7diosvvhjZ2dmIi4vDhAkT8Nhjj8Fut3c59/vvv8ecOXOQkJCApKQkXHrppSgvLz9mX3bt2gWtVtvj9WxsbMR1112HtLQ0xMXFoaSkBGvXru22rU8//RQlJSWIi4tDWloarrvuOjQ2NnY5z+Px4NFHH0VBQQG0Wi0mTJiA5557rts233jjDRx33HHQ6XRIS0vDz372sy5ltYmI6NgYhoiIKChCCPzf//0fLrroIsiyjD/96U/49NNPsWzZMkydOhW33HIL/v73v/er7X/961/YuXMnTjrpJBQWFvZ43q5duzBz5kxUVlbimWeewXvvvYcrr7zSXzL9SHv27MEZZ5wBt9uNN998Ey+//DL27duH0047DU1NTd227/P58POf/9y/we7RXC4XzjrrLKxduxbPPvssVq9ejczMTJx77rnYsGFDwLkbNmzAvHnzkJmZidWrV+PZZ5/Fp59+irPOOgsulyvg3FtuuQWLFy/Grbfeio8++giXXHIJ7rjjji6bAj/33HO45pprcMIJJ2D16tV48sknsX79epx22mlobW3t8boREdFRBBERRY1XXnlFABBbtmzp9vbzzz9f5OfnBxwDIG699dZuz1+xYoUAINatW+c/9uSTTwoA4tFHH+32PnV1deKLL77oV/99Pt8x+9rp/vvvFwBEWVlZwPGbbrpJABAmk8l/7IorrhBpaWmivb3df6yyslKo1Wrx//7f/+u2/SVLloicnBzx7LPPdns9//a3vwkA4uuvv/Yf83g8oqioSJx00kkB55544omiqKhIeDwe/7GvvvpKABB///vf/cd27NghJEkSjz/+eMD9b7zxRqHX60VLS4sQQgin0ymMRqO48MILA877+uuvBQBx3333dfuciIioK44MERFRn3k8Hjz55JOYMGECHnzwwW7PycrKwqmnntqv9hWKvv1YUqvVANBls9ukpCQoFApoNBoAgNfrxXvvvYfLLrsMBoPBf15+fj5mz56NVatWdWm7tLQUDz30EP7+978H3OdIq1atwvjx41FSUuI/plKpcM011+Cbb75BTU0NAKCmpgZbtmzBtddeC5XqcAHXmTNnYty4cQGP/7///c8/6nak//u//4PD4cCaNWsAADt27EB7e3uXDV1LSkqQkpKClStX9nDViIjoaAxDRERRyOfzwev1dvkSAywg+u2338JkMmH+/PmQJKlP97nuuusgSRIqKysH9NhHWrhwIZKSknDzzTejvLwcFosF7733Hl544QXceuutiI+PBwDs378fDocDxcXFXdooLi5GWVkZnE6n/5gQAjfccAMuuOACXHTRRT0+/o4dO3psEwB27tzpP+/I40efe+Tmrzt27EB6ejqysrK6bbPzXLfbDQDQarVd2tRqtSgtLQ14TkRE1DOGISKiKDRjxgyo1eouXx988MGA2q2qqgIAjBo1qs/3USqVUCqVfQ5PfVFQUICNGzdix44dKCwshMFgwIUXXoiFCxfi2Wef9Z/X0tICAEhJSenSRkpKCoQQAWts/va3v2H79u09Fi04st2e2jzycXt7/M7bj9VmfHw8NBqN/9zO4hJfffVVwHn79+9HXV0dZFnmuiEioj7ipqtERFHotddew8SJE7scv/POO4e84thLL72El156KaRtVlZW+ivZvfXWW0hPT8fmzZvxhz/8AVartcvjHSuIdd524MAB3HvvvXjmmWeQmZnZax/60mZv5/b1vCNvS0lJwdVXX43XXnsNJ554Iq644gpUV1fjpptuglKphM/n6/N0QyKiWMcwREQUhSZOnIgTTjihy3Gj0dglDHV+gO6O1+sFcHiNzsiRIwEAFRUVoexu0O655x6YzWZs27bNPyXu9NNPR1paGn7+859jwYIFmDVrFlJTUwEgYASmk8lkgiRJSEpKAgDceuutmDx5Mi677DK0tbUBgL9Mt9VqRXt7u3+NUmpqao9tAodHgnp7/CNHglJTU7Ft27Yu59lsNrjd7oBzly5dCiEEbrnlFvzyl7+EQqHAtddei8zMTHz00Uf+xyUiomPjr46IiGJcZmamf8H/0TqPd46UnHDCCUhJScHq1asHvP5oILZt24aioiJ/EOp04oknAji8vqawsBB6vR7bt2/v0sb27dsxZswY6HQ6/302bdqE5ORk/9ett94KAJg9ezby8/P9950yZUqPbQLA5MmTA/7s6dzO2zvbbGpqQn19/THbBDqmzv3rX/9Cc3MzfvjhBzQ0NODVV1/F3r17MXPmzIBiDURE1DOGISKiGDdnzhysW7euy547QgisWLECBQUFGDNmDICOEaK7774be/bswe9///tu22tsbOyyniXUsrOzsXPnTlit1oDjGzduBADk5uYC6KjwduGFF+Ltt9+GxWLxn1dVVYV169bh0ksv9R9bvnw51q1bF/B19913AwCef/55vPfee/5zL7nkEuzZswebN2/2H/N6vXj99ddx8sknIzs7GwCQk5ODk046Ca+//nrA6NumTZuwd+/egMfvLEqxbNmygOf06quvQq/X49xzz+1yHZKTk1FcXIy0tDS888472Lt3L+64444+XkUiIuI+Q0REUaQ/+wyVlZWJ5ORkMWrUKPHCCy+Izz77TPz73/8Ws2fPFgqFQrz11lsB58uyLK677joBQJx//vnijTfeEJ9//rl49913xe9+9zthNBrFM8884z//5z//uVAqlaKysrLX/u/cuVOsWLFCrFixQkyfPl2kp6f7v9+5c6f/vNWrVwtJksSMGTPEf//7X7F27VqxaNEikZCQIIqKioTL5fKfu3v3bpGQkCBOP/108cEHH4i3335bTJ48WWRnZ4vGxsZ+XU+n0ykmTZok8vLyxBtvvCE++eQTcckllwiVSiXWr18fcO66deuESqUSl1xyifjkk0/EG2+8IfLy8sTkyZOF0+kMOPeGG24QWq1WLFmyRKxfv17cd999QpIksWjRooDz3nrrLfGXv/xFfPLJJ+Ldd98Vd911l1CpVOKXv/xlr9eYiIgOYxgiIooi/QlDQghRWloqrrnmGjFixAihUqlEUlKSOPvss8XatWt7fKzVq1eL888/X6SnpwuVSiWSk5PF7NmzxfPPPx8QRhYuXCgAiIqKil77//DDDwsA3X49/PDDAed+9tln4uyzzxZZWVlCr9eLcePGibvuuks0Nzd3affbb78VZ511loiLixMGg0FcfPHFXTZs7c6xrmd9fb1YsGCBSElJETqdTsyYMUN88skn3bbz8ccfixkzZgidTidSUlLEggULRENDQ5fz3G63ePjhh8XIkSOFRqMR48aNE3/5y1+6nLdq1Soxbdo0ER8fL/R6vTjhhBPESy+9JGRZ7vU5ERHRYZIQYZz0TUREREREFCZcM0RERERERDGJYYiIiIiIiGISwxAREREREcUkhiEiIiIiIopJDENERERERBSTGIaIiIiIiCgmMQwREREREVFMUoW7A6EiyzJqa2uRmJgISZLC3R0iIiIiIgoTIQQsFguys7OhUPQ8/hM1Yai2thZ5eXnh7gYREREREQ0TBw8eRG5ubo+3R00YSkxMBNDxhA0GQ5h7Q0RERERE4WI2m5GXl+fPCD2JmjDUOTXOYDAwDBERERERUa/L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",
      "text/plain": [
       "<Figure size 1000x1000 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "#visualize FTS response\n",
    "visualize(response)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Query Data by Bounding Box\n",
    "\n",
    "We can use results obtained from the FTS to then directly and automatically query on data using the earthaccess Python library. We use the bounding box representing Upper Tuolumne River Basin extracted from the response above, and search for granules available from the SWOT mission, as an example. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "pycharm": {
     "is_executing": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Granules found: 84\n"
     ]
    }
   ],
   "source": [
    "shortname = 'SWOT_L2_HR_Raster_2.0' # SWOT Raster files\n",
    "HUC = \"18040009\"\n",
    "\n",
    "# Obtain bounding box from response\n",
    "bbox = response['results'][HUC]['Bounding Box']\n",
    "bbox_vals = []\n",
    "for val in bbox.split(','): bbox_vals.append(float(val)) #transform string into values\n",
    "\n",
    "# Query data by bounding box\n",
    "results = earthaccess.search_data(short_name=shortname, bounding_box=(bbox_vals[0],bbox_vals[1],bbox_vals[2],bbox_vals[3]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Query Data by Polygon\n",
    "\n",
    "Instead of querying via bounding box from the FTS response, we can extract the polygon of the region and use this to query.  \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Granules found: 70\n"
     ]
    }
   ],
   "source": [
    "shortname = 'SWOT_L2_HR_Raster_2.0' # SWOT Raster files\n",
    "HUC = \"18040009\"\n",
    "\n",
    "#obtain polygon from response\n",
    "polygon_v = response['results'][HUC]['Visvalingam Polygon']\n",
    "\n",
    "#transform string into list of values\n",
    "polygon_vals = []\n",
    "for val in polygon_v.split(','): polygon_vals.append(float(val)) \n",
    "#change list to correct tuple format to input into earthaccess query\n",
    "it = iter(polygon_vals)\n",
    "poly = [(x, next(it)) for x in it]\n",
    "\n",
    "# Query by polygon\n",
    "results = earthaccess.search_data(short_name=shortname, polygon=poly)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Check with Earthdata Search\n",
    "\n",
    "To find granules in [Earthdata Search](https://search.earthdata.nasa.gov/search), we need to first search for the collection. You can search for 'SWOT L2 Raster 2.0' in the top left corner to find the Soil Mositure dataset. Earthdata allows you to do an Advanced seach over a HUC region. You can search by HUC ID or HUC region. In our case, let's search for \"HUC Region\" and \"Upper Tuolumne\" . \n",
    "\n",
    "![Advanced Search](../images/SWOT_HUC_advanced_search.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we can locate the total number of granules from the search which matches with the one we identified.\n",
    "\n",
    "Also, our search in Earth Data has a unique url with a project ID. This url corresponds to *SWOT Raster* granules within the Upper Tuolumne: \n",
    "\n",
    "https://search.earthdata.nasa.gov/search/granules?projectId=3520324655\n",
    "\n",
    "![Earthdata Granules](../images/SWOT_EDS.png)"
   ]
  }
 ],
 "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.8.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}