examples/Getting_Started_GBDXtools.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Original Author: Matthew Gregor*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quickstart Guide to GBDX"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For this tutorial, we'll use the latest version of gbdxtools, a python module for GBDX. This Quickstart walks through searching for imagery, ordering, navigating the workflow system, and access your output data from the workflow. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Authorized"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from gbdxtools import Interface\n",
    "gbdx = Interface()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Search the GBDX catalog"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can search the GBDX catalog by spatial area, by date range, or by both. Use \"types\" to search by a single type or multiple types. Use filters to refine your data set.\n",
    "\n",
    "Let's search for acquisitions in a subsection of San Francisco, collected between March 1, 2015 and March 1, 2016, with cloud cover of less than 10%, and an off-nadir angle of less than 20."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "searchAreaWkt = \"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\"\n",
    "startDate = \"2017-01-01T00:00:00.000Z\"\n",
    "endDate = \"2018-09-01T23:59:59.999Z\"\n",
    "types = [\"DigitalGlobeAcquisition\"]\n",
    "filters = [\"sensorPlatformName = WORLDVIEW03_VNIR AND cloudCover < 20 AND offNadirAngle < 10\"]\n",
    "results = gbdx.catalog.search(searchAreaWkt=searchAreaWkt,\n",
    "                        startDate=startDate,\n",
    "                        endDate=endDate,\n",
    "                        types=types,\n",
    "                        filters=filters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running a search returns a list of metadata items as dictionaries."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Place an order and check its status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ordering function lets you order imagery and check your order's status. To place an order, you'll need a list of one or more acquisition catalog IDs. You can get the catalog IDs from the search example above:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "catalogids =    [\n",
    "  \"103001005275AC00\",\n",
    "  \"103001004046DC00\",\n",
    "  \"10504100106AA800\",\n",
    "  \"1020010030936B00\",\n",
    "  \"104001000680BA00\",\n",
    "  \"102001003648FC00\",\n",
    "  \"1010010012956800\"\n",
    " ]\n",
    "order_id = gbdx.ordering.order(catalogids)\n",
    "print(order_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This request will return an order ID, and order information about each catalog ID. Save the order_id. You'll use it to check the status of your order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gbdx.ordering.status(order_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This request will return an order ID, and order information about each catalog ID. Save the order_id. You'll use it to check the status of your order."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Submit a task and run a workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A workflow chains together a series of tasks and runs them in the specified order. Running a workflow means creating a series of Task objects with their inputs and outputs and passing them to the Workflow fuction as a list.\n",
    "\n",
    "`Note: All tasks require inputs.\n",
    "When a task requires a GBDX S3 location as an input, find the location in the Order response. Location will only be displayed when the state = delivered.`\n",
    "\n",
    "For this tutorial, we'll create and run a workflow with one simple task (Getting_Started):\n",
    "\n",
    "`Getting_Started: a simple task that only requires \"your_name\" as an input, and outputs a .txt file.`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create and run a workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Define and run your workflow:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Getting_Started = gbdx.Task(\"Getting_Started\", your_name=\"Your Name\")\n",
    "workflow = gbdx.Workflow([ Getting_Started ])\n",
    "workflow.savedata(Getting_Started.outputs.data, location='getting_started_output')\n",
    "workflow.execute()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This workflow example shows the input and output values of the Getting_Started task."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How to find your account ID/prefix"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The GBDX S3 location is the GBDX S3 bucket name and the Prefix name. GBDX uses your account ID as the prefix and \"gbd=customer-data\" as the bucket."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gbdx.s3.info"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Access the output data from a workflow"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To access the information in your customer S3 bucket do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gbdx.s3.download(location='getting_started_output/hello_world.txt', local_dir='output/location')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Inside this folder, you'll find a txt file called Hello_World.txt. Open the file to see this successful result!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## More on GBDX Tasks and Workflows"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See the documentation here: https://gbdxdocs.digitalglobe.com/docs/workflow-api-course"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3-notebooks",
   "language": "python",
   "name": "python3-notebooks"
  },
  "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.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}