{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c07f5a86",
   "metadata": {},
   "source": [
    "# External Data Sources\n",
    "\n",
    "> Abstract: Here we show short introductions to Python packages that provide access to various other data sources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c350841d",
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext watermark\n",
    "%watermark -i -v -p hapiclient"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6f79311",
   "metadata": {},
   "source": [
    "## HAPI (hapiclient)\n",
    "\n",
    "The [Heliophysics Data Application Programmer’s Interface (HAPI)](http://hapi-server.org/) specification provides a common framework being adopted by many data providers across heliophysics. The aim is to ease sharing of data between different services and support an interoperable ecosystem. All components are [developed openly on GitHub](https://github.com/hapi-server/) where you will find client software in various languages (MATLAB, Java, IDL etc.) to access data from HAPI servers. In this section we demonstrate how to use the Python package, [`hapiclient`](https://github.com/hapi-server/client-python), that provides very similar functionality to `viresclient`. For more examples, [see here](https://github.com/hapi-server/client-python-notebooks).\n",
    "\n",
    "To discover what servers and data are out there, try the [HAPI server browser](http://hapi-server.org/servers/). This lets you browse the catalogs and generate preview images of data as well as the Python script necessary to access the data yourself.\n",
    "\n",
    "Here is [an example](http://hapi-server.org/servers/#server=SSCWeb&dataset=iss&parameters=X_GEO&start=2020-01-01T00:00:00.00&stop=2020-01-02T00:00:00.00&return=script&format=python) of accessing the position of the ISS using the HAPI server provided by [NASA's Satellite Situation Center service (SSCWeb)](https://sscweb.gsfc.nasa.gov/):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b8e0e1d9",
   "metadata": {},
   "outputs": [],
   "source": [
    "from hapiclient import hapi\n",
    "\n",
    "server     = 'http://hapi-server.org/servers/SSCWeb/hapi';\n",
    "dataset    = 'iss';\n",
    "# Use parameters='' to request all data. Multiple parameters\n",
    "# can be requested using a comma-separated list, e.g., parameters='X_TOD,Y_TOD'\n",
    "parameters = 'X_GEO,Y_GEO,Z_GEO'; \n",
    "start      = '2020-01-01T00:00:00.00';\n",
    "stop       = '2020-01-02T00:00:00.00';\n",
    "\n",
    "data, meta = hapi(server, dataset, parameters, start, stop)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b888fae0",
   "metadata": {},
   "source": [
    "Data are automatically loaded as a [NumPy structured array](https://numpy.org/doc/stable/user/basics.rec.html) and metadata as a dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "82e401cc",
   "metadata": {},
   "outputs": [],
   "source": [
    "data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66bffbef",
   "metadata": {},
   "outputs": [],
   "source": [
    "meta"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "deb4899a",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "`hapiclient` also provides tools for intelligent automatic plotting of data with the `hapiplot` package. `hapiplot` is currently not installed but we can patch it in on-the-fly and use it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2e09af0f",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install \"git+https://github.com/hapi-server/plot-python@f95ce860d456dd9278a62897d6f83d416c988273\" --quiet\n",
    "\n",
    "from hapiplot import hapiplot"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1119a42c-1733-49be-beb4-2370637fe0b0",
   "metadata": {},
   "source": [
    "(NB: We are using a more recent development version of hapiplot, rather than what is on PyPI)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4aeea673",
   "metadata": {},
   "outputs": [],
   "source": [
    "hapiplot(data, meta);"
   ]
  }
 ],
 "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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}