{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Accessing the NWIS Discharge data  - as an API\n",
    "In an earlier session, we used `urllib` and `pandas` to retrieve data from a static URL. Here we refine that procedure to again retrieve water flow data from the NWIS website. What's different this time, however, is that we examine the URL as a web service, dissecting it into its components (web service address and web service parameters). We also switch to using the Python `requests` package to handle the interaction, as it's slightly more user friendly than the `urllib` package. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The URL listing current discharge conditions in the Eno near Durham gage site is here: \n",
    "```html\n",
    "http://waterdata.usgs.gov/nwis/uv?cb_00060=on&cb_00065=on&format=rdb&site_no=02085070&period=1&begin_date=&end_date=\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you'll see in the example below, the `requests` package constructs a web service request with two parameters. The first is the full service address (`http://waterdata.usgs.gov/nwis/uv`), which is followed by the set of service parameters, passed as a Python dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#import packages\n",
    "import requests"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#dissect the URL into it's components, for easy comprehension -- and easy modification\n",
    "serviceURL = 'http://waterdata.usgs.gov/nwis/uv'\n",
    "parameters = {'cb_00060':'on',\n",
    "              'cb_00065':'on',\n",
    "              'format':'rdb',\n",
    "              'period':'1',\n",
    "              'site_no':'02085070',\n",
    "              'begin_date':'',\n",
    "              'end_date':''\n",
    "             }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ok, here we send the request, storing the response in a variable called `response`. The second line extacts the response as raw text into the variable `responseText`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Pass the url and its parameters to the server and get its response\n",
    "response = requests.get(serviceURL, parameters)\n",
    "responseText = response.text"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#What did we get? \n",
    "print(responseText)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you scroll all the way to the last line in the file, you get the most recent reading. We can use some Python to print out what this reading is... "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Convert the response text into a list of lines and print the second to last line\n",
    "responseLines = responseText.split('\\n')\n",
    "lastRecord = responseLines[-2].split('\\t')\n",
    "site = lastRecord[1]\n",
    "cfs = lastRecord[4]\n",
    "date = lastRecord[2]\n",
    "print(\"Site {0} recorded a discharge of {1} cfs on {2}\".format(site,cfs,date))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "► **EXERCISE**: The 3 code blocks below are copies of the ones above. Modify these code blocks to get data for site 02085039 (Eno River At Cole Mill Rd Nr Huckleberry Spring), and print out its most recent *gage height* (in feet):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#dissect the URL into it's components, for easy comprehension -- and easy modification\n",
    "serviceURL = 'http://waterdata.usgs.gov/nwis/uv'\n",
    "parameters = {'cb_00060':'on',\n",
    "              'cb_00065':'on',\n",
    "              'format':'rdb',\n",
    "              'period':'1',\n",
    "              'site_no':'02085070',\n",
    "              'begin_date':'',\n",
    "              'end_date':''\n",
    "             }"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Pass the url and its parameters to the server and get its response\n",
    "response = requests.get(serviceURL, parameters)\n",
    "responseText = response.text"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Convert the response text into a list of lines and print the second to last line\n",
    "responseLines = responseText.split('\\n')\n",
    "lastRecord = responseLines[-2].split('\\t')\n",
    "site = lastRecord[1]\n",
    "cfs = lastRecord[4]\n",
    "date = lastRecord[2]\n",
    "print(\"Site {0} recorded a discharge of {1} cfs on {2}\".format(site,cfs,date))"
   ]
  }
 ],
 "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}