Merge pull request planetlabs#213 from planetlabs/orders-sdk-example

add Notebook showing Orders creation & download with SDK

Author: mkshah605

jupyter-notebooks/orders/Planet_SDK_Orders_demo.ipynb

@@ -0,0 +1,236 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "bEcGVnFww2gV"
+   },
+   "source": [
+    "# Orders API & Planet SDK \n",
+    "\n",
+    "Getting started with Planet SDK and the Orders API."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "oA6ODbRP0mN9"
+   },
+   "source": [
+    "## Authentication\n",
+    "\n",
+    "The new SDK supports a couple different methods of authentication (and soon, will support OIDC / Okta token-based authentication as well). [Read more in the docs here](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/api/#planet.auth.Auth).\n",
+    "\n",
+    "For this example, I'll use the `getpass` tool to pass in my API key as a string to the `from_key` method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "nYHpseo0Qc3U"
+   },
+   "outputs": [],
+   "source": [
+    "from getpass import getpass\n",
+    "from planet import Auth\n",
+    "api_key = getpass('Enter your API key:')\n",
+    "\n",
+    "auth = Auth.from_key(api_key)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "MHZXLWT41Ccn"
+   },
+   "source": [
+    "# Demo"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "6z6I9B_636Ck"
+   },
+   "source": [
+    "## Building an Order request"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "9xOEqQiw5yid"
+   },
+   "source": [
+    "### Method 1: Old style\n",
+    "\n",
+    "With this method, you can build an Order request by directly using a blob of JSON -- similar to how you might have built an Order in the Python Client V1, or directly using the API via e.g., `requests`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "nh6waD-QzSh-"
+   },
+   "outputs": [],
+   "source": [
+    "request = {\n",
+    "  \"name\": \"test_order_sdk_method_1\",\n",
+    "  \"products\": [\n",
+    "    {\n",
+    "     \"item_ids\":[  \n",
+    "        \"20200922_183724_23_106a\",\n",
+    "        \"20200922_183722_17_106a\"\n",
+    "         ],\n",
+    "      \"item_type\": \"PSScene\",\n",
+    "      \"product_bundle\": \"analytic_udm2\"\n",
+    "    }\n",
+    "  ],\n",
+    "   \"tools\": [\n",
+    "    {\n",
+    "      \"reproject\": {\n",
+    "        \"projection\": \"EPSG:4326\",\n",
+    "        \"kernel\": \"cubic\"\n",
+    "      }\n",
+    "    }\n",
+    "  ]\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "1yCzN0Ag64wf"
+   },
+   "source": [
+    "### Method 2: New style\n",
+    "\n",
+    "In V2 ofthe SDK, you can also build an Order request object using the new `order_request` functionality -- here you can specify all Order details including products, bundles & fallback bundles, cloud delivery configuration, tools & toolchain operations, etc. [Read more in the docs here](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/api/#planet.order_request)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "FwFi1bktMY2u"
+   },
+   "outputs": [],
+   "source": [
+    "from planet import order_request\n",
+    "\n",
+    "item_ids = [\"20200922_183724_23_106a\", \"20200922_183722_17_106a\"]\n",
+    "\n",
+    "products = [\n",
+    "    order_request.product(item_ids, 'analytic_udm2', 'PSScene')\n",
+    "]\n",
+    "\n",
+    "tools = [\n",
+    "    order_request.reproject_tool(projection='EPSG:4326', kernel='cubic')\n",
+    "]\n",
+    "\n",
+    "request = order_request.build_request(\n",
+    "    'test_order_sdk_method_2', products=products, tools=tools)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "f_k8HHcL8gQ5"
+   },
+   "source": [
+    "## Create the Order\n",
+    "\n",
+    "Regardless of the method you use to build your order, the next step after building an Order is to send a \"create\" request to the Orders API.\n",
+    "\n",
+    "To do this, we'll create a `Session` to manage our communcation with Planet in general -- this will make use of that `auth` object we created earlier. Within the context of this Session, we'll create an Orders API-specific `client` to handle interactions with the Orders API."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "GCARBCQZMm2v"
+   },
+   "outputs": [],
+   "source": [
+    "from planet import Session, OrdersClient\n",
+    "\n",
+    "# an async Orders client to request order creation\n",
+    "async def main():\n",
+    "  async with Session(auth=auth) as sess:\n",
+    "    cl = OrdersClient(sess)\n",
+    "    order = await cl.create_order(request)\n",
+    "\n",
+    "# async magic to remember: \"async def\" to create a coroutine, then \"await\" to make it run\n",
+    "await main()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "xOyyXodY6cL0"
+   },
+   "source": [
+    "## Alternative: Create the Order, then monitor status until complete"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "5lFCwq1cNCda"
+   },
+   "outputs": [],
+   "source": [
+    "from planet import reporting, Session, OrdersClient\n",
+    "\n",
+    "# remember: \"async def\" to create the async coroutine\n",
+    "async def create_poll_and_download():\n",
+    "    async with Session(auth=auth) as sess:\n",
+    "        cl = OrdersClient(sess)\n",
+    "\n",
+    "        # Use \"reporting\" to manage polling for order status\n",
+    "        with reporting.StateBar(state='creating') as bar:\n",
+    "            # create order via Orders client\n",
+    "            order = await cl.create_order(request)\n",
+    "            bar.update(state='created', order_id=order['id'])\n",
+    "\n",
+    "            # poll...poll...poll...\n",
+    "            await cl.wait(order['id'], callback=bar.update_state)\n",
+    "\n",
+    "        # if we get here that means the order completed. Yay! Download the files.\n",
+    "        await cl.download_order(order['id'])\n",
+    "\n",
+    "# remember: \"await\" to run the thing\n",
+    "await create_poll_and_download()"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "collapsed_sections": [],
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}