{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python package for NAIF WebGeoCalc API\n",
    "======================================\n",
    "\n",
    "In december 2018, [JPL/NAIF](https://naif.jpl.nasa.gov/naif/webgeocalc.html)\n",
    "announced an **experimental**\n",
    "[API RESTful interface](https://naif.jpl.nasa.gov/naif/WebGeocalc_announcement.pdf)\n",
    "for their new \n",
    "[WebGeocalc server](https://wgc2.jpl.nasa.gov:8443/webgeocalc)\n",
    "(which make online SPICE calculations).\n",
    "[Documentation](https://wgc2.jpl.nasa.gov:8443/webgeocalc/documents/api-info.html)\n",
    "and [JavaScript examples](https://wgc2.jpl.nasa.gov:8443/webgeocalc/example/perform-calculation.html)\n",
    "are already available.\n",
    "\n",
    "This package is an **early attempt** to provide a Python interface to\n",
    "make SPICE calculation through this API.\n",
    "\n",
    "\n",
    "Disclaimer\n",
    "----------\n",
    "This project is not supported or endorsed by either JPL, NAIF or NASA.\n",
    "The code is provided *\"as is\"*, use at your own risk."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Use WebGeoCalc API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'https://wgc2.jpl.nasa.gov:8443/webgeocalc/api'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from webgeocalc import API\n",
    "\n",
    "API.url"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default API endpoint can be defined with the `WGC_URL` global environment variable.\n",
    "If it is not present, the `API` will fallback to the [JPL endpoint](https://wgc2.jpl.nasa.gov:8443/webgeocalc/api/).\n",
    "\n",
    "You can also use the ESA webgeocalc server:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'http://spice.esac.esa.int/webgeocalc/api'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from webgeocalc import ESA_API\n",
    "\n",
    "ESA_API.url"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get kernel sets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<KernelSetDetails> Solar System Kernels (id: 1),\n",
       " <KernelSetDetails> Latest Leapseconds Kernel (id: 2),\n",
       "...\n",
       " <KernelSetDetails> Ground Stations Kernels (id: 4),\n",
       "...\n",
       " <KernelSetDetails> SPICE Class -- Binary PCK Lesson Kernels (Earth) (id: 39)]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "kernel_sets = API.kernel_sets() # /kernel-sets\n",
    "kernel_sets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Kernel set object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "kernel_set = kernel_sets[0]\n",
    "int(kernel_set) # kernelSetId"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Solar System Kernels'"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "str(kernel_set) # Caption"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Generic kernels for planets, satellites, and some asteroids covering from 1950-01-01 to 2050-01-01.'"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "kernel_set.description # Get kernel attribute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['caption', 'sclkId', 'description', 'kernelSetId', 'missionId'])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "kernel_set.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_values(['Solar System Kernels', '0', 'Generic kernels for planets, satellites, and some asteroids covering from 1950-01-01 to 2050-01-01.', '1', 'gen'])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "kernel_set.values()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'caption': 'Solar System Kernels',\n",
       " 'sclkId': '0',\n",
       " 'description': 'Generic kernels for planets, satellites, and some asteroids covering from 1950-01-01 to 2050-01-01.',\n",
       " 'kernelSetId': '1',\n",
       " 'missionId': 'gen'}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dict(kernel_set.items())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get a kernel set by it's `id` or `caption name`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<KernelSetDetails> Solar System Kernels (id: 1)"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# By ID\n",
    "API.kernel_set(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<KernelSetDetails> Solar System Kernels (id: 1)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# By full caption name\n",
    "API.kernel_set('Solar System Kernels')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<KernelSetDetails> Solar System Kernels (id: 1)"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Not case sensitive\n",
    "API.kernel_set('solar system kernels')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<KernelSetDetails> Solar System Kernels (id: 1)"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Search by partial name\n",
    "API.kernel_set('Solar')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Handling errors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Too many kernel sets contains 'Cassini' in their names:\n",
      " - Cassini Huygens\n",
      " - SPICE Class -- CASSINI Remote Sensing Lesson Kernels\n"
     ]
    }
   ],
   "source": [
    "from webgeocalc.errors import TooManyKernelSets, KernelSetNotFound\n",
    "\n",
    "# More than one kernel found\n",
    "try:\n",
    "    API.kernel_set('Cassini')\n",
    "except TooManyKernelSets as err:\n",
    "    print(err)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Kernel set 'Missing kernel' not found\n"
     ]
    }
   ],
   "source": [
    "# Kernel not found\n",
    "try:\n",
    "    API.kernel_set('Missing kernel')\n",
    "except KernelSetNotFound as err:\n",
    "    print(err)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get bodies"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<BodyData> CASSINI (id: -82),\n",
       " <BodyData> CAS (id: -82),\n",
       "...\n",
       " <BodyData> SOLAR SYSTEM BARYCENTER (id: 0)]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bodies = API.bodies(5) # /kernel-set/{kernelSetId}/bodies\n",
    "# or\n",
    "API.bodies('Cassini Huygens')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Body `id`: -82 and `name`: CASSINI\n"
     ]
    }
   ],
   "source": [
    "body = bodies[0]\n",
    "print(f\"Body `id`: {int(body)} and `name`: {str(body)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get frames"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<FrameData> CASSINI_SATURN_SKR4N_LOCK (id: -82982),\n",
       "...\n",
       " <FrameData> IAU_TITAN (id: 10044),\n",
       "...\n",
       " <FrameData> ITRF93 (id: 13000)]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "frames = API.frames(5) # /kernel-set/{kernelSetId}/frames\n",
    "# or\n",
    "API.frames('Cassini Huygens')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_items([('id', -82905), ('name', 'CASSINI_KSO'), ('centerBodyID', 699), ('frameClass', 5)])"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "frames[58].items()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Instruments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<InstrumentData> CASSINI_CIRS_RAD (id: -82898),\n",
       "...\n",
       " <InstrumentData> CASSINI_ISS_NAC (id: -82360),\n",
       "...\n",
       " <InstrumentData> CASSINI_SRU-A (id: -82001)]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "instruments = API.instruments(5) # /kernel-set/{kernelSetId}/intruments\n",
    "# or\n",
    "API.instruments('Cassini Huygens')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Body `id`: -82898 and `name`: CASSINI_CIRS_RAD\n"
     ]
    }
   ],
   "source": [
    "print(f\"Body `id`: {int(instruments[0])} and `name`: {str(instruments[0])}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "**Next:** [Make a calculation](calculation.ipynb)"
   ]
  }
 ],
 "metadata": {
  "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}