02-geocoding-module.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction to geocoding and plotting using HTRC Analytics, Geopy and Cartopy\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this notebook, the goal is to introduce you to geolocation and plotting locations generated from Named Entity Recognition (NER) using Python, HathiTrust data and HathiTrust Research Center (HTRC) tools. The main focus will be to take the output of [HTRC's built-in Named Entity Recognizer ](https://analytics.hathitrust.org/statisticalalgorithms) algorithm run over a workset, and use it to geocode and plot locations. The NER algorithm's output is very useful for this, as it does the NER step and tagging for you, without any need for code. However, should you be interested, at the end of the notebook, there is a further section on recreating the NER steps over full text data directly using the [Natural Language Toolkit (NLTK)](https://www.nltk.org/). This notebook will help you:\n",
    "\n",
    "1. Load the output CSV of the NER algorithm in HTRC Analytics into a [Pandas](https://pandas.pydata.org/) DataFrame and extract locations;\n",
    "2. Use the library [GeoPy](https://geopy.readthedocs.io/en/stable/) to geocode each location; and\n",
    "3. Use a mapping library, [Cartopy](https://scitools.org.uk/cartopy/docs/latest/), to plot geographic data using MatPlotLib.\n",
    "\n",
    "First, there are some libraries we must import into this notebook in order to use them later:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopy, time\n",
    "import cartopy.crs as ccrs\n",
    "import cartopy.feature as cfeature\n",
    "import matplotlib.pyplot as plt\n",
    "import pandas as pd\n",
    "import nltk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing NER data from HTRC Analytics\n",
    "\n",
    "Now, let's load in the result of our NER algorithm run in HTRC Analytics: a CSV of entities, the volume and page of their appearance, and their entity type. We'll then import this as a Pandas DataFrame, and import and use a library that will let us randomly shuffle the order (index) of each row in the table:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "from sklearn.utils import shuffle\n",
    "\n",
    "entities = open('entities-modern-traveller.csv','r')\n",
    "ent_df = pd.read_csv(entities)\n",
    "\n",
    "ent_df = shuffle(ent_df)\n",
    "\n",
    "print(ent_df.shape)\n",
    "ent_df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we see that the CSV was loaded correctly and get to see what our data looks like. Our entities are tagged with strings in the `type` column, so we need to go through our data and pull out the entities that are tagged as \"LOCATION\" in this colummn. If we want to be inclusive, with small adjustments to our code we could also pull out other types, such as \"ORGANIZATION\" in the interest of not losing any positives. However, we'll focus just on locations today."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extracting and geocoding locations from our entities CSV\n",
    "   To extract only the entities tagged as locations in this file, we can simply use a `for` loop and the Pandas method `.iterrows()` which will let us use the index of the DataFrame to loop through the data, but still individually call any columns in which we're interested. Here, we want to extract the entity name for each entity with the value `LOCATION` in the `type` column. Eventually, we'll end with a new list of only place names (`place_list`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "place_list = []\n",
    "\n",
    "for i, r in ent_df.iterrows():\n",
    "    name = r['entity']\n",
    "    ner_type = r['type']\n",
    "    if ner_type == 'LOCATION':\n",
    "        place_list.append(name)\n",
    "    else:\n",
    "        continue\n",
    "        \n",
    "print(f'Found {len(place_list)} locations.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Geopy allows for a number of different types of geocoders to be initialized and called, such as Google Maps, Bing Maps, Nominatim, etc. Each may have different requirements for their use, however, such as Google Maps, which requires an API key. In order to avoid this, we'll use Nominatim, which doesn't require a key and is built on the [OpenStreetMap](https://www.openstreetmap.org) data, which is crowdsourced, open and free.\n",
    "\n",
    "First we'll initialize a geocoder using Nominatim (and for easier referencing later, name it `api`) and then test it by feeding it an address to geocode. \n",
    "\n",
    "**Replace the text in quotes in line 3 with any address and run the cell:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "api = geopy.geocoders.Nominatim(user_agent='my-application') # initializing Nominatim as our geocoding engine.\n",
    "    \n",
    "# If you can't think of an address to add, try: 671 Lincoln Ave, Winnetka, IL\n",
    "result, (lat, lng) = api.geocode('ADD AN ADDRESS HERE!')\n",
    "print(result)\n",
    "print(lat, lng)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now use all of the built-in methods that geopy has for geocoders by only calling api + the method syntax.\n",
    "\n",
    "You'll notice three variables are being retrieved from the geocode: \n",
    "\n",
    "* `result`: the place name of the geolocation\n",
    "* `lat`: the latitude for the geolocation\n",
    "* `lng`: the longitude for the geolocation\n",
    "\n",
    "This syntax is handy, as it also assigns the output from the geocoder to variables (`result`, `lat`, `lng`) instantly.\n",
    "\n",
    "We could also feed the geocoder a place name and see if it can generate an address and coordinates instead of the inverse.\n",
    "\n",
    "**Try this for yourself by filling in a place name below:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result, (lat,lng) = api.geocode('PLACE NAME')\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For place names with some specificity, this is a workable method of geocoding (and in fact is what we'll be doing to geocode the locations we extract from our CSV!). However, you should remember that as the place name becomes more ambiguous, the geocoder may not necessarily throw an error, but instead assume and retrieve the wrong location.\n",
    "\n",
    "**Can you think of an example of an ambiguous place name? Try geocoding it in the code block below**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result, (lat,lng) = api.geocode('PLACE NAME')\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We've been asking geopy to geocode individual places and return information thus far. But in order to plot our locations, we must also include an intermediate step to extract and compile the coordinates of the locations in our CSV into a new list, `place_coord`, that we will use in subsequent steps. For this activity, we are only taking the first 75 places in our list and geocoding them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "place_coord = []\n",
    "\n",
    "for placename in place_list[:75]:\n",
    "    # time.sleep(1)\n",
    "    try:\n",
    "        fullname, (lat, lng) = api.geocode(placename)\n",
    "        # print(placename + \":  \" + fullname)\n",
    "        # print(lat, lng)\n",
    "        place_coord.append((lng, lat))\n",
    "    except:\n",
    "        print('Could not find: ' + placename)\n",
    "        \n",
    "print(f\"Found {len(place_coord)} locations.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two notes on the above:\n",
    "* The code above has an optional rest command in the loop (commented out) in case you want to be a friendly and cautious API user and ensure you are not overloading the servers of the API provider. Nominatim doesn't require this time buffer, so I've omitted in the interest of saving time.\n",
    "\n",
    "\n",
    "* Print statements are included in this loop. We're using these to identify entities that aren't found, which is helpful to evlauate accuracy. When an NER algorithm encounters vague text, like a human, it will make a guess at what it thinks is the most correct answer. Thus, there are bound to be some incorrectly assigned locations or some that are not found when geocoding. There may also be entities that were incorrectly tagged as locations or incorrectly tagged altogether. Print statements allow for a spot-check on anything that might be going wrong, and possibly some information about why. However, if this workflow is expanded to look at many volumes, they may become quite unwieldy to include.\n",
    "\n",
    "Ok, back to results!\n",
    "\n",
    "What do the results look like? How many locations were found? Do any of the locations that were found look like false matches? Do you see any explanation for why, if so? If entities were not found, can you think of a reason why?\n",
    "\n",
    "Remember: when working with text and with such a large list of entities, there will almost always be edge cases where something doesn't work as intended or expected. Each researcher may have a different opinion about how to handle these cases. One may want to make sure all outliers are identifieda and included, and another may prefer to omit them. For this exercise it's okay for these locations to be omitted."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting our locations using Cartopy\n",
    "Now that we have place names and coordinates, we need only plot them. We'll use Cartopy, a specialized library for plotting geographic data using matplotlib. In addition to using much of the same syntax as matplotlib, Cartopy has some nice built-in features that we'll show below. Of course, any plotting library or method could be substituted once you have a list of coordinates. For Cartopy in Jupyter, it works best for inline graphics if you initialize the figure first, with set dimensions, and then generate the data to be plotted on it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(figsize=(20, 20))\n",
    "ax = fig.add_subplot(111, projection=ccrs.PlateCarree()) # choosing a Plate Carree map projection as our base\n",
    "# ax.stock_img()\n",
    "ax.coastlines(resolution='10m') # picking the highest resolution coastlines to show\n",
    "# ax.set_global() # this shows the entire global map on our plot as compared to a scaled subset that covers all points\n",
    "\n",
    "for lon, lat in place_coord:\n",
    "    plt.scatter(lon, lat, s=15, color='red', transform=ccrs.PlateCarree()) # 's' is the parameter that determines size of points on plot\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Success! Our map (a [Plate Carree](https://en.wikipedia.org/wiki/Equirectangular_projection) projection) now has each of the 48 locations found in our 47-volume adventure novel workset plotted. We can experiment with different views by choosing a different projection, changing the color/resolution of certain parameters, or by disabling others. For instance, what do you think happens if you comment out (to do so, use `command` + `/` while the text is highlighted), the `ax.set_global()` line? Were your expectations right? What do you think will happen if we do the same with `ax.stock_img()`?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As mentioned earlier, Cartopy has a lot of built-in options to produce different types of map graphics in python. Below are some of the ones I found interesting, but more can be found in the Cartopy documentation linked at the top of the notebook. \n",
    "\n",
    "**Try adding in colors for certain features, or including features that are commented out (remove the preceding `#`) and running the block below:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(figsize=(20, 20))\n",
    "ax = fig.add_subplot(111, projection=ccrs.PlateCarree())\n",
    "# ax.stock_img()\n",
    "ax.coastlines(resolution='10m')\n",
    "# ax.set_global()\n",
    "\n",
    "for lon, lat in place_coord:\n",
    "    plt.scatter(lon, lat, color='ADD A COLOR', transform=ccrs.PlateCarree())\n",
    "\n",
    "# Cartopy allows you to download non-standard datasets from Natural Earth (http://www.naturalearthdata.com/) \n",
    "# to include in our plot, such as the highest resolution representation of rivers:\n",
    "\n",
    "# rivers_10m = cfeature.NaturalEarthFeature('physical', 'rivers_lake_centerlines', '10m')\n",
    "\n",
    "# ax.add_feature(cfeature.OCEAN)\n",
    "ax.add_feature(cfeature.LAND, edgecolor='black', facecolor=cfeature.COLORS['land'])\n",
    "# ax.add_feature(cfeature.LAKES, edgecolor='ADD A COLOR')\n",
    "# ax.add_feature(rivers_10m, facecolor='none', edgecolor='b')\n",
    "ax.add_feature(cfeature.BORDERS)\n",
    "ax.add_feature(cfeature.COASTLINE)\n",
    "ax.add_feature(cfeature.STATES)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Optional Additional Activity: Replicating this process for full text data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To reproduce this process and output without a list or CSV of entities already in hand, we can use the [Natural Language Toolkit (NLTK)](https://www.nltk.org/), which runs best over full text documents. However, we must first also pre-process our text to give the best chance for accurate NER. In this instance, we're going to tokenize and tag each token with a part of speech."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nltk.download('punkt')\n",
    "nltk.download('averaged_perceptron_tagger')\n",
    "\n",
    "sample_string = 'I live in Champaign, but I often travel to Chicago, Istanbul, and London.'\n",
    "words = nltk.word_tokenize(sample_string)\n",
    "tagged = nltk.pos_tag(words)\n",
    "print(tagged)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see now that we have a list with our tokens and their part-of-speech (POS) tags (which are based on the [Penn Treebank POS tags](https://www.clips.ua.ac.be/pages/mbsp-tags)), which can be fed directly into NLTK's built-in named entity classifier, `nltk.ne_chunk()`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nltk.download('maxent_ne_chunker')\n",
    "nltk.download('words')\n",
    "\n",
    "sample_chunked = nltk.ne_chunk(tagged)\n",
    "# sample_chunked.draw()\n",
    "print(sample_chunked)\n",
    "print(type(sample_chunked))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Above, you can see the actual named entities that the classifier is tagging, as well as the type of the output object: `<class 'nltk.tree.Tree'>` which you can probably tell is an NLTK Tree. If you'd like to see the drawn tree, you can un-comment the print statement in the above code, and the tree will be drawn in a new, pop-up window.\n",
    "\n",
    "This type of object is specific to NLTK, so we'll need to think about how we can take the tree of entities and end up with a list of the desired class of entities we'd like, here roughly defined as place names. In order to extrsact locations, a less granular entity tag than NLTK uses, we'll need to write a function to identify the items in an NLTK tree with the type 'GPE' (geo-political entity) or 'ORGANIZATION' (or other tags, as appropriate). This function takes an NLTK Tree object as input, which minimzes steps in finding the entities we're interested in:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The code here is adapted from Ted Underwood, who himself worked off a Stack Overflow answer by alvas:\n",
    "# http://stackoverflow.com/questions/31836058/nltk-named-entity-recognition-to-a-python-list\n",
    "\n",
    "def get_placenames(parsed_tree):\n",
    "    prev = None\n",
    "    continuous_chunk = []\n",
    "    current_chunk = []\n",
    "    for node in parsed_tree:\n",
    "        if type(node) == nltk.Tree and (node.label() == \"GPE\" or node.label() == 'ORGANIZATION'):\n",
    "            current_chunk.append(\" \".join([token for token, pos in node.leaves()]))\n",
    "        elif current_chunk:\n",
    "            named_entity = \" \".join(current_chunk)\n",
    "            if named_entity not in continuous_chunk:\n",
    "                continuous_chunk.append(named_entity)\n",
    "                current_chunk = []\n",
    "        else:\n",
    "            continue\n",
    "    return continuous_chunk\n",
    "\n",
    "print(get_placenames(sample_chunked))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I'd encourage you to go through the function and see if you can identify what is happening at each step, but roughly, this function takes a parsed NLTK tree as an input, and then navigates through each node on the tree looking for entities with labels of a given type that we are defining (line 9), here `GPE` or `ORGANIZATION` which can both be used for locations (though remember that *all* tags are <100% reliable, since they are generated using trained classifiers).\n",
    "\n",
    "Now that we habve a function that will find and extract particular types of entities from an NLTK tree, we can test it out on a block of text, here an excerpt from Herman Melville's *Moby Dick*, which nicely lends itself to NER:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "text = ' '.join([\"I stuffed a shirt or two into my old carpet-bag, tucked it \",\n",
    "        \"under my arm, and started for Cape Horn and the Pacific. Quitting \",\n",
    "        \"the good city of old Manhatto, I duly arrived in New Bedford. \",\n",
    "        \"It was a Saturday night in December. Much was I disappointed \",\n",
    "        \"upon learning that the little packet for Nantucket had already sailed, \",\n",
    "        \"and that no way of reaching that place would offer, till the following \",\n",
    "        \"Monday. As most young candidates for the pains and penalties of whaling \",\n",
    "        \"stop at this same New Bedford, thence to embark on their voyage, it may \",\n",
    "        \"as well be related that I, for one, had no idea of so doing. For \",\n",
    "        \"my mind was made up to sail in no other than a Nantucket craft, \",\n",
    "        \"because there was a fine, boisterous something about everything \",\n",
    "        \"connected with that famous old island, which amazingly pleased me. \",\n",
    "        \"Besides though New Bedford has of late been gradually monopolising \",\n",
    "        \"the business of whaling, and though in this matter poor old Nantucket \",\n",
    "        \"is now much behind her, yet Nantucket was her great original - the Tyre \",\n",
    "        \"of this Carthage;—the place where the first dead American whale was \",\n",
    "        \"stranded. Where else but from Nantucket did those aboriginal whalemen, \",\n",
    "        \"the Red-Men, first sally out in canoes to give chase to the Leviathan? \",\n",
    "        \"And where but from Nantucket, too, did that first adventurous little sloop \",\n",
    "        \"put forth, partly laden with imported cobblestones - so goes the story - \",\n",
    "        \"to throw at the whales, in order to discover when they were nigh enough \",\n",
    "        \"to risk a harpoon from the bowsprit?\"])\n",
    "\n",
    "sentences = nltk.sent_tokenize(text)\n",
    "\n",
    "# Though it's a bit counterintuitive, given that we join the lines above into one chunk of text, before we \n",
    "# proceed to word_tokenize, we break the block of text into a list of sentences. The tagging and chunking \n",
    "# processes tend to work better on strings that are single sentences.\n",
    "\n",
    "# Then we loop through the sentences, tagging and chunking each one, extracting placenames, and adding those \n",
    "# to a growing list of moby_places. Note that \"extend\" is like \"append\" but appends all the elements of a list \n",
    "# rather than a single one, which is useful for this task since we have potentially multiple entities we're\n",
    "# interested in for each chunk.\n",
    "\n",
    "moby_places = []\n",
    "\n",
    "for s in sentences:\n",
    "    words = nltk.word_tokenize(s)\n",
    "    tagged = nltk.pos_tag(words)\n",
    "    namedEnt = nltk.ne_chunk(tagged)\n",
    "    chunks = get_placenames(namedEnt)\n",
    "    moby_places.extend(chunks)\n",
    "\n",
    "print('\\nPLACENAMES: ')\n",
    "print(moby_places)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Success! Well, sort of. See anything strange with the above place names? This is a good time to add another friendly reminder that classifiers *will* make mistakes!\n",
    "\n",
    "With a list of place names, we can now pick up a similar workflow to the one demonstrated with the HTRC NER output file, and geocode our locations by name using Geopy. This step should look familiar!:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "allcoordinates = []\n",
    "\n",
    "for placename in moby_places:\n",
    "    time.sleep(1)\n",
    "    try:\n",
    "        fullname, (lat, lng) = api.geocode(placename)\n",
    "        print(placename + \":  \" + fullname)\n",
    "        print(lat, lng)\n",
    "        allcoordinates.append((lng, lat))\n",
    "    except:\n",
    "        print('Could not find: ' + placename)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Above, we see Geopy's best guess as to what each place name is referring to. Any strange or unexpected results?\n",
    "\n",
    "We can also pilot this process for a sample sentence, here the same sentence we used in our first cell in this section to generate POS tags to feed into NLTK. Feel free to modify the sentence and see what the results look like. Are all of the locations found? Any unexpcted results? If so, any ideas why?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We can also try this for our sample sentence:\n",
    "\n",
    "sample_sentences = ['I live in Champaign, but I often travel to Chicago, Istanbul, and London.']\n",
    "sample_places = []\n",
    "\n",
    "for s in sample_sentences:\n",
    "    words = nltk.word_tokenize(s)\n",
    "    tagged = nltk.pos_tag(words)\n",
    "    # print(tagged)\n",
    "    namedEnt = nltk.ne_chunk(tagged)\n",
    "    # print(namedEnt)\n",
    "    chunks = get_placenames(namedEnt)\n",
    "    sample_places.extend(chunks)\n",
    "    \n",
    "print(sample_places)\n",
    "\n",
    "sample_coord = []\n",
    "\n",
    "for placename in sample_places:\n",
    "    time.sleep(1)\n",
    "    try:\n",
    "        fullname, (lat, lng) = api.geocode(placename)\n",
    "        print(placename + \":  \" + fullname)\n",
    "        print(lat, lng)\n",
    "        sample_coord.append((lng, lat))\n",
    "    except:\n",
    "        print('Could not find: ' + placename)\n",
    "        \n",
    "print(sample_coord)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again, with a list of place names and coordinates, we can call on our old electronic friend Cartopy to generate a map and plot the locations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(figsize=(15, 15))\n",
    "ax = fig.add_subplot(111, projection=ccrs.PlateCarree())\n",
    "# ax.stock_img()\n",
    "ax.coastlines(resolution='10m')\n",
    "ax.set_global()\n",
    "\n",
    "for lon, lat in sample_coord:\n",
    "    plt.scatter(lon, lat, s=35, color='red', transform=ccrs.PlateCarree())\n",
    "    \n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Success, and this time without the \"sort of!\"\n",
    "\n",
    "If you want to try again or want to explore some of the options with Cartopy (check out the [Cartopy documentation](https://scitools.org.uk/cartopy/docs/latest/index.html) for more information on the full set of features and functionality), try out geocoding and plotting other locations. Here is another example using a list of English Premier League team stadia:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# try substituting other locations in this list and see what results you get!\n",
    "\n",
    "pl_stadia = ['Anfield', 'Goodison Park', 'Old Trafford', 'City of Manchester Stadium', 'Carrow Road', \n",
    "             'Bramall Lane','Emirates Stadium','Stamford Bridge', 'London Stadium', \"St. James' Park\",\n",
    "             'Dean Court', 'Falmer Stadium', 'King Power Stadium', 'Molineux Stadium', \"Southampton FC\",\n",
    "             'Selhurst Park', 'Tottenham Hotspur Stadium', 'Turf Moor', 'Vicarage Road', 'Villa Park']\n",
    "\n",
    "pl_coord = []\n",
    "\n",
    "for placename in pl_stadia:\n",
    "    time.sleep(1)\n",
    "    try:\n",
    "        fullname, (lat, lng) = api.geocode(placename)\n",
    "        print(placename + \":  \" + fullname)\n",
    "        print(lat, lng)\n",
    "        pl_coord.append((lng, lat))\n",
    "    except:\n",
    "        print('Could not find: ' + placename)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since we know a bit more about our data this time, we can try out a few of Cartopy's advanced features:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "fig = plt.figure(figsize=(15, 15))\n",
    "ax = fig.add_subplot(111, projection=ccrs.PlateCarree())\n",
    "# ax.stock_img()\n",
    "# ax.set_global()\n",
    "\n",
    "for lon, lat in pl_coord:\n",
    "    plt.scatter(lon, lat, color='red', alpha=1, transform=ccrs.PlateCarree())\n",
    "\n",
    "    \n",
    "rivers_10m = cfeature.NaturalEarthFeature('physical', 'rivers_lake_centerlines', '10m')\n",
    "ocean_10m = cfeature.NaturalEarthFeature('physical', 'ocean', '10m')\n",
    "land_10m = cfeature.NaturalEarthFeature('physical', 'land', '10m')\n",
    "\n",
    "ax.add_feature(ocean_10m, facecolor='blue')\n",
    "ax.add_feature(land_10m, edgecolor = 'black', facecolor='none')\n",
    "ax.add_feature(rivers_10m, facecolor='none', edgecolor='blue')\n",
    "ax.add_feature(cfeature.BORDERS)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More information on available features is available at the previously linked Cartopy documentation. Cartopy has some built-in support for a few external feature sources as well, including [Natural Earth](https://www.naturalearthdata.com/) features."
   ]
  }
 ],
 "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}