notebooks/iceflow/2_api.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center>\n",
    "<img src='./img/nsidc_logo.png'/>\n",
    "\n",
    "# **IceFlow**\n",
    "### Point Cloud Data Access\n",
    "</center>\n",
    "\n",
    "---\n",
    "\n",
    "# Accessing Data using the IceFlow API\n",
    "\n",
    "This notebook shows how to access data programmatically using the *IceFlow* API and describes the parameters in more detail.<br>\n",
    "\n",
    "\n",
    "## API Parameters:\n",
    "\n",
    "### Selecting Data Sets\n",
    "\n",
    "* The ***datasets*** parameter allows to list all data set of interest. See the [introduction notebook](./0_introduction.ipynb) section 4 for more information on the available data sets.</br>\n",
    "Example: `'datasets': ['GLAH06', 'ATL06']`\n",
    "\n",
    "### Choosing Optional Corrections\n",
    "\n",
    "* The optional ***ITRF*** parameter allows you to choose an ITRF reference to which the data will be transformed via the published ITRF transformation parameters. This parameter is optional but must be used if you want to specify an epoch. Available values are: **ITRF2000, ITRF2008, ITRF2014**</br>\n",
    "Example: `'ITRF': '2014'`\n",
    "* The ***epoch*** parameter is optional and entered in decimal years to which the data will be transformed via the ITRF Plate Motion Model corresponding to ITRF. This parameter can only be used if the ***ITRF*** parameter is specified and set to either 2008 or 20014, as only ITRF2008 and ITRF2014 have a plate motion model. </br>\n",
    "Example: `'epoch': '2014.1'` (This specifies January 2014.)\n",
    "\n",
    "### Setting Temporal Extend\n",
    "\n",
    "You can set the range of dates over which to return data using the ***start*** and ***end*** parameters:\n",
    "* The ***start*** parameter accepts UTF datetime or simple YYYY-mm-dd formatted values</br>\n",
    "Example: `'start': '2003-01-01'`\n",
    "* The ***end*** parameter accepts UTF datetime or simple YYYY-mm-dd formatted values</br>\n",
    "Example: `'end': '2019-01-01'`\n",
    "\n",
    "### Setting Spatial Extend\n",
    "\n",
    "You can use one of the two available options (***polygon***,***bbox***) to make your spatial selection:\n",
    "\n",
    "* The ***Polygon*** parameter allows you to enter a counterclockwise closed array of latitude and longitude values ending with the same coordinate as the starting pair.</br>\n",
    "Example: `'polygon'='-50.5811,69.4995,-49.3726,69.7632,-48.6035,69.8291,-47.8345,69.4995,-47.6587,68.8843,-48.6255,68.3130,-49.8077,69.0601,-50.4449,68.9941,-50.5811,69.4995'` \n",
    "\n",
    "* The ***bbox*** parameter allows you to choose a WGS84 bounding box with min_lon, min_lat, max_lon, max_lat values.</br>\n",
    "Example: `'bbox': '-107.4515,-75.3695,-105.3794,-74.4563'` \n",
    "\n",
    "The following code is an example on how to order data with the *IceFlow* API, but first you have to log into EarthData:\n",
    "### NASA's Earthdata Credentials\n",
    "\n",
    "To access data using the *IceFlow* library it is necessary to log into [Earthdata Login](https://urs.earthdata.nasa.gov/). We showed you how to do this with a user interface in the [introduction](0_introduction.ipynb) and the [widget](1_widget.ipynb) notebooks. Here we show you how to do that programmatically. For that you have to change the values for `'username'`,`'password'`, and `'email'` to your personal Earthdata credentials before you run the next cell. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We import our API client and authenticate with our NASA Earthdata credentials\n",
    "from iceflow.client import IceflowClient\n",
    "import earthaccess\n",
    "ifc = IceflowClient()\n",
    "\n",
    "auth = earthaccess.login()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if ifc.authenticate(auth.username, auth.password, auth.user_profile[\"email_address\"]) is not None:\n",
    "    print('Authenticated with NASA Earthdata')\n",
    "else:\n",
    "    print('Login failed')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We use IceFlow to query CMR and get an idea of how many granules we'll be sub-setting.\n",
    "\n",
    "# Thwaites glacier ICESat/GLAS and ICESat-2\n",
    "my_params ={\n",
    "    'datasets': ['GLAH06', 'ATL06'],\n",
    "    'ITRF': '2014',\n",
    "    'epoch': '2014.1',\n",
    "    'start': '2003-01-01',\n",
    "    'end': '2019-01-01',\n",
    "    'bbox': '-107.4515,-75.3695,-105.3794,-74.4563'\n",
    "}\n",
    "granules = ifc.query_cmr(my_params)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we order the data, this is an asynchronous process. Asynchronous downloads allow concurrent requests to be queued and processed without the need for a continuous connection.  The maximum granule count per asynchronous request is 2000. When the order is complete.\n",
    "Now you can proceed to download the IceFlow data granule."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "orders = []\n",
    "# Uncomment the following line to place the orders!\n",
    "# orders = ifc.place_data_orders(my_params)\n",
    "orders"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# To check the order, you can run this cell:\n",
    "for order in orders:\n",
    "    status = ifc.check_order_status(order)\n",
    "    print(status)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Once all orders are complete you can download the data:\n",
    "for order in orders:\n",
    "    status = ifc.check_order_status(order)\n",
    "    if status['status'] == 'COMPLETE':\n",
    "        ifc.download_order(order)        "
   ]
  }
 ],
 "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.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}