{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Formal gmaps code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this section, I'm just going to give you a sense of what gmaps can do.  Ideally, you'll be able to get your key up and running here, too.  Note that I'm leaving my key here for you to experiment with, but it will come down on Thursday morning."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I like to keep my API key, as well as any initial map information, up here in the topmost part of the code.  Since it is largely static, it keeps things neater, since the experimenting I'll do with the libraries and data, below, won't need to refer to these values as anything but variables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import gmaps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that gmaps comes complete with sample datasets -- you import those with \n",
    "\n",
    "    import gmaps.datasets\n",
    "\n",
    "See the documentation if you'd like to play with those."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "## THIS KEY WILL NOT WORK.  PLEASE INSERT YOUR OWN.\n",
    "myKey = \"AIzaSyDmG2EgRMnYktvV230d1u341Rsmn9IOeYE\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, `.configure()` is a **method**, a sort of custom-built function, buried inside the gmaps library.  This method is expecting one thing, apparently:  It needs you to assign a value to the variable `api_key`.  Easily done."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "gmaps.configure(api_key=myKey)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So... gmaps is really easy:  Sometimes you expect to have to do more, and then, voila, you're done.  In this case, after I've configured my gmaps object, I can tell it to create a default `.figure()` (figure is another word used in publishing for \"illustration\" or \"graphic\"... as in \"Consult figure 3\") and then assign that figure to the variable (in this example) `myMap`.  (Note that `myMap` is just my name for the variable, yours can be whatever.) The clever thing?  Every time we update some part of myMap, all of the maps on this page will update, as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "myMap = gmaps.figure()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, relying on the Jupyter notebook's penchant (after Python) for simply showing the value of a thing when we type out its name, just... type out its name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "e80f59d08f1d47c28b90a7ef65eb1870",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>Figure</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "Figure()"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "myMap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Awesome.  A fully functional google map object, centered on Geneva's Lac Léman.   But, you will say, I do not care to have anything to do with the Swiss.  They are, how do you say, '*de trop*'.  *D'accord.*  Let's set a new center by using the variable name that the `.figure()` method expects, 'center'.  In this case, we'll add it as a *tuple* -- that is, two values, of common association, jammed together for all eternity inside parentheses.  Like X and Y, or heading and velocity, or pitch and duration, etc.\n",
    "\n",
    "**Note that since we define a `center`, we also are obliged to define a `zoom level`** -- all of this is spelled out in Google's documentation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "myMap = gmaps.figure(center=(38.9072, -77.0369), zoom_level=11)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "105b3691b2db4985b19fe2d8fe47b1b5",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>Figure</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "Figure()"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "myMap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Awesome.  Let's add traffic.  Because:  Why not?  We're young.  Let's *live a little.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "myMap.add_layer(gmaps.traffic_layer())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The myMap object, courtesy of Google, has layers.  We've added a layer drawn out of the gmaps object, using a method called `.traffic_layer()`.  In fairness, that may seem like a lot to understand, but there aren't a thousand other choices.  And when you need to `.add_layer()`, well, you probably already know what kind of layer you intend to add, *ja*?  So let's see, *ma petite chou*, just what God has wrought."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "105b3691b2db4985b19fe2d8fe47b1b5",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>Figure</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "Figure()"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "myMap"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So... adding our own data is easy, as long as you do it the way Google wants it done.  In this case, that means ensuring your coordinates are stored in geojson format.  I've used a quick online program to translate a few points from an iPhone coordinate tracking CSV file into geojson.  Here's what one entry from that file looks like:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    {\n",
    "      \"type\": \"Feature\",\n",
    "      \"properties\": {},\n",
    "      \"geometry\": {\n",
    "        \"type\": \"Point\",\n",
    "        \"coordinates\": [\n",
    "          -76.632650,\n",
    "          38.596905\n",
    "        ]\n",
    "      }\n",
    "    }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is a bit tedious, but just remember, it is ultimately just JSON, so it should break apart fairly easily.  Using Jupyter's `json` library, here's the code I use to load in a small geojson file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "myCommuteMap = gmaps.figure(center=(38.9072, -77.0369), zoom_level=9)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(\"commute_sample.json\") as mygeojsonfile:\n",
    "    commute_geometry = json.load(mygeojsonfile)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "geojson_layer = gmaps.geojson_layer(commute_geometry)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "myCommuteMap.add_layer(geojson_layer)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "5e13e343d37e41db862d5f5c043eec11",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>Figure</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "Figure()"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "myCommuteMap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}