geonames_api.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Working with APIs in Python\n",
    "\n",
    "Making API requests in Python can be really simple. There's a low-level module called urllib that can also make the kinds of web requests that we want, but it's not as friendly as the `requests` module, which we'll be using."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Authentication\n",
    "\n",
    "You'll have to authenticate each request to Geonames with your username. Other APIs may require a key or token of some kind, but GeoNames has some very simple authentication, which makes things easy for us. You can sign up for a username [here](http://www.geonames.org/login)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "USERNAME = 'cdc43339' # Enter your own username here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Query Parameters\n",
    "\n",
    "We're going to be using the same base URL for all of our requests, but we're also going to want to use several different query parameters to search through the GeoNames database. We have a full list of available parameters [here](), but for now we're going to set up the simplest keyword search, using a Python dictionary to contain our parameter / value pairs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "url = \"http://api.geonames.org/searchJSON\"\n",
    "Q = {\n",
    "    'q':'Cambridge',\n",
    "    'username':USERNAME\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Refresher on Dictionaries\n",
    "\n",
    "Python dictionaries are sets of key / value pairs, where a value can be accessed by its key. You're essentially naming a value in a container, so you can easily call it up later.\n",
    "\n",
    "Dictionaries have very fast lookups, so you can get a value from its key very quickly, no matter how large the dictionary is. However, they are also unordered, so if you iterate through all of the key / value pairs in the dictionary, there's no guarantee that they'll be in the same order.\n",
    "\n",
    "We're just going to be looking up data in dictionaries, so here's a quick refresher on the syntax:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Cambridge'"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Q['q']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'cdc43339'"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Q['username'] # This also works when we've set the value to another variable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "Q['q'] = 'Somerville' # You can also set the value of a key like you would a variable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Making a Request\n",
    "\n",
    "We have a base url, and we have our query parameters in a dictionary, so now we can make our request, like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "R = requests.get(url,params=Q)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Formatted parameters\n",
    "\n",
    "That request has created a request object, which contains not only the data that we get from GeoNames, but information on the request we sent, like the URL that it used. Notice that requests has turned our query parameter dictionary into a GET request at the end of our URL.\n",
    "\n",
    "If you've been working with API requests or web scraping before, you might be used to seeing URLs get constructed like this:\n",
    "\n",
    "```python\n",
    "url = \"http://api.geonames.org/searchJSON?q=\" + query + \"&username=\" + username\n",
    "```\n",
    "\n",
    "If you have, I'm sure you'll appreciate how much simpler this is, especially when dealing with more query parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'http://api.geonames.org/searchJSON?q=Somerville&username=cdc43339'"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "R.url"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Taking a look at the results\n",
    "\n",
    "Request objects have a built-in method, `.json()`, which converts a JSON file received as a response to a request from a string of text that happens to be in this data format into Python native data structures, like lists, dictionaries, numbers and strings. We can use this method to see a pretty friendly view of what we've gotten as a response to our request."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'geonames': [{'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4951257,\n",
       "   'lat': '42.3876',\n",
       "   'lng': '-71.0995',\n",
       "   'name': 'Somerville',\n",
       "   'population': 80318,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminName1': '',\n",
       "   'countryCode': 'AQ',\n",
       "   'countryId': '6697173',\n",
       "   'countryName': 'Antarctica',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'ISL',\n",
       "   'fcodeName': 'island',\n",
       "   'geonameId': 6625691,\n",
       "   'lat': '-65.37611',\n",
       "   'lng': '-64.30702',\n",
       "   'name': 'Somerville Island',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville, islote'},\n",
       "  {'adminCode1': '07',\n",
       "   'adminCodes1': {'ISO3166_2': 'VIC'},\n",
       "   'adminName1': 'Victoria',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPLX',\n",
       "   'fcodeName': 'section of populated place',\n",
       "   'geonameId': 2149128,\n",
       "   'lat': '-38.21667',\n",
       "   'lng': '145.16667',\n",
       "   'name': 'Somerville',\n",
       "   'population': 7015,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '02',\n",
       "   'adminCodes1': {'ISO3166_2': 'NSW'},\n",
       "   'adminName1': 'New South Wales',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'L',\n",
       "   'fclName': 'parks,area, ...',\n",
       "   'fcode': 'PRK',\n",
       "   'fcodeName': 'park',\n",
       "   'geonameId': 8160913,\n",
       "   'lat': '-33.7818',\n",
       "   'lng': '151.0846',\n",
       "   'name': 'Somerville Park',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Park'},\n",
       "  {'adminCode1': '08',\n",
       "   'adminCodes1': {'ISO3166_2': 'WA'},\n",
       "   'adminName1': 'Western Australia',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'L',\n",
       "   'fclName': 'parks,area, ...',\n",
       "   'fcode': 'PRK',\n",
       "   'fcodeName': 'park',\n",
       "   'geonameId': 8857322,\n",
       "   'lat': '-32.05889',\n",
       "   'lng': '115.835',\n",
       "   'name': 'Somerville Park',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Park'},\n",
       "  {'adminCode1': '00',\n",
       "   'adminName1': '',\n",
       "   'countryCode': 'SB',\n",
       "   'countryId': '2103350',\n",
       "   'countryName': 'Solomon Islands',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'PT',\n",
       "   'fcodeName': 'point',\n",
       "   'geonameId': 2103344,\n",
       "   'lat': '-8.69267',\n",
       "   'lng': '157.5469',\n",
       "   'name': 'Somerville Point',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Point'},\n",
       "  {'adminCode1': 'NJ',\n",
       "   'adminCodes1': {'ISO3166_2': 'NJ'},\n",
       "   'adminName1': 'New Jersey',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPLA2',\n",
       "   'fcodeName': 'seat of a second-order administrative division',\n",
       "   'geonameId': 5104774,\n",
       "   'lat': '40.57427',\n",
       "   'lng': '-74.60988',\n",
       "   'name': 'Somerville',\n",
       "   'population': 12202,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '08',\n",
       "   'adminCodes1': {'ISO3166_2': 'ON'},\n",
       "   'adminName1': 'Ontario',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'L',\n",
       "   'fclName': 'parks,area, ...',\n",
       "   'fcode': 'AREA',\n",
       "   'fcodeName': 'area',\n",
       "   'geonameId': 6151206,\n",
       "   'lat': '44.70012',\n",
       "   'lng': '-78.71627',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '10',\n",
       "   'adminCodes1': {'ISO3166_2': 'QC'},\n",
       "   'adminName1': 'Quebec',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'PT',\n",
       "   'fcodeName': 'point',\n",
       "   'geonameId': 6108496,\n",
       "   'lat': '46.91683',\n",
       "   'lng': '-78.96631',\n",
       "   'name': 'Pointe Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Pointe Somerville'},\n",
       "  {'adminCode1': 'TX',\n",
       "   'adminCodes1': {'ISO3166_2': 'TX'},\n",
       "   'adminName1': 'Texas',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4732809,\n",
       "   'lat': '30.34604',\n",
       "   'lng': '-96.5283',\n",
       "   'name': 'Somerville',\n",
       "   'population': 1383,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'ME',\n",
       "   'adminCodes1': {'ISO3166_2': 'ME'},\n",
       "   'adminName1': 'Maine',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4978976,\n",
       "   'lat': '44.30924',\n",
       "   'lng': '-69.48893',\n",
       "   'name': 'Somerville',\n",
       "   'population': 529,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'IN',\n",
       "   'adminCodes1': {'ISO3166_2': 'IN'},\n",
       "   'adminName1': 'Indiana',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4265011,\n",
       "   'lat': '38.27644',\n",
       "   'lng': '-87.37779',\n",
       "   'name': 'Somerville',\n",
       "   'population': 288,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'TN',\n",
       "   'adminCodes1': {'ISO3166_2': 'TN'},\n",
       "   'adminName1': 'Tennessee',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPLA2',\n",
       "   'fcodeName': 'seat of a second-order administrative division',\n",
       "   'geonameId': 4658802,\n",
       "   'lat': '35.2437',\n",
       "   'lng': '-89.35007',\n",
       "   'name': 'Somerville',\n",
       "   'population': 3094,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'OH',\n",
       "   'adminCodes1': {'ISO3166_2': 'OH'},\n",
       "   'adminName1': 'Ohio',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4525006,\n",
       "   'lat': '39.56311',\n",
       "   'lng': '-84.63856',\n",
       "   'name': 'Somerville',\n",
       "   'population': 286,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'ME',\n",
       "   'adminCodes1': {'ISO3166_2': 'ME'},\n",
       "   'adminName1': 'Maine',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADM3',\n",
       "   'fcodeName': 'third-order administrative division',\n",
       "   'geonameId': 4978978,\n",
       "   'lat': '44.28956',\n",
       "   'lng': '-69.47771',\n",
       "   'name': 'Town of Somerville',\n",
       "   'population': 553,\n",
       "   'toponymName': 'Town of Somerville'},\n",
       "  {'adminCode1': '10',\n",
       "   'adminCodes1': {'ISO3166_2': '14'},\n",
       "   'adminName1': 'Saint Catherine',\n",
       "   'countryCode': 'JM',\n",
       "   'countryId': '3489940',\n",
       "   'countryName': 'Jamaica',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 3488490,\n",
       "   'lat': '18.13333',\n",
       "   'lng': '-77.05',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '08',\n",
       "   'adminCodes1': {'ISO3166_2': 'ON'},\n",
       "   'adminName1': 'Ontario',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'H',\n",
       "   'fclName': 'stream, lake, ...',\n",
       "   'fcode': 'LK',\n",
       "   'fcodeName': 'lake',\n",
       "   'geonameId': 6151214,\n",
       "   'lat': '49.8543',\n",
       "   'lng': '-95.04728',\n",
       "   'name': 'Somerville Lake',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Lake'},\n",
       "  {'adminCode1': '03',\n",
       "   'adminCodes1': {'ISO3166_2': 'MB'},\n",
       "   'adminName1': 'Manitoba',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'H',\n",
       "   'fclName': 'stream, lake, ...',\n",
       "   'fcode': 'LK',\n",
       "   'fcodeName': 'lake',\n",
       "   'geonameId': 6151215,\n",
       "   'lat': '58.3414',\n",
       "   'lng': '-101.69326',\n",
       "   'name': 'Somerville Lake',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Lake'},\n",
       "  {'adminCode1': '11',\n",
       "   'adminCodes1': {'ISO3166_2': 'SK'},\n",
       "   'adminName1': 'Saskatchewan',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'H',\n",
       "   'fclName': 'stream, lake, ...',\n",
       "   'fcode': 'LK',\n",
       "   'fcodeName': 'lake',\n",
       "   'geonameId': 6151216,\n",
       "   'lat': '59.50018',\n",
       "   'lng': '-105.05065',\n",
       "   'name': 'Somerville Lake',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Lake'},\n",
       "  {'adminCode1': '10',\n",
       "   'adminCodes1': {'ISO3166_2': 'QC'},\n",
       "   'adminName1': 'Quebec',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 6106079,\n",
       "   'lat': '45.08754',\n",
       "   'lng': '-74.4249',\n",
       "   'name': 'Plage-Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Plage-Somerville'},\n",
       "  {'adminCode1': 'AL',\n",
       "   'adminCodes1': {'ISO3166_2': 'AL'},\n",
       "   'adminName1': 'Alabama',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4090853,\n",
       "   'lat': '34.47338',\n",
       "   'lng': '-86.7987',\n",
       "   'name': 'Somerville',\n",
       "   'population': 716,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'VA',\n",
       "   'adminCodes1': {'ISO3166_2': 'VA'},\n",
       "   'adminName1': 'Virginia',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4786488,\n",
       "   'lat': '38.52179',\n",
       "   'lng': '-77.60943',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '08',\n",
       "   'adminCodes1': {'ISO3166_2': 'WA'},\n",
       "   'adminName1': 'Western Australia',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'ISL',\n",
       "   'fcodeName': 'island',\n",
       "   'geonameId': 2079488,\n",
       "   'lat': '-21.96434',\n",
       "   'lng': '114.4868',\n",
       "   'name': 'Somerville Island',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Island'},\n",
       "  {'adminCode1': 'TX',\n",
       "   'adminCodes1': {'ISO3166_2': 'TX'},\n",
       "   'adminName1': 'Texas',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADM3',\n",
       "   'fcodeName': 'third-order administrative division',\n",
       "   'geonameId': 7174466,\n",
       "   'lat': '30.346',\n",
       "   'lng': '-96.53109',\n",
       "   'name': 'City of Somerville',\n",
       "   'population': 1376,\n",
       "   'toponymName': 'City of Somerville'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADM3',\n",
       "   'fcodeName': 'third-order administrative division',\n",
       "   'geonameId': 4951267,\n",
       "   'lat': '42.39072',\n",
       "   'lng': '-71.10131',\n",
       "   'name': 'City of Somerville',\n",
       "   'population': 75754,\n",
       "   'toponymName': 'City of Somerville'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4955085,\n",
       "   'lat': '42.39593',\n",
       "   'lng': '-71.12255',\n",
       "   'name': 'West Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'West Somerville'},\n",
       "  {'adminCode1': 'IN',\n",
       "   'adminCodes1': {'ISO3166_2': 'IN'},\n",
       "   'adminName1': 'Indiana',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADMD',\n",
       "   'fcodeName': 'administrative division',\n",
       "   'geonameId': 7165421,\n",
       "   'lat': '38.27838',\n",
       "   'lng': '-87.37736',\n",
       "   'name': 'Town of Somerville',\n",
       "   'population': 293,\n",
       "   'toponymName': 'Town of Somerville'},\n",
       "  {'adminCode1': 'OH',\n",
       "   'adminCodes1': {'ISO3166_2': 'OH'},\n",
       "   'adminName1': 'Ohio',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADMD',\n",
       "   'fcodeName': 'administrative division',\n",
       "   'geonameId': 7167457,\n",
       "   'lat': '39.56353',\n",
       "   'lng': '-84.63956',\n",
       "   'name': 'Village of Somerville',\n",
       "   'population': 281,\n",
       "   'toponymName': 'Village of Somerville'},\n",
       "  {'adminCode1': 'AL',\n",
       "   'adminCodes1': {'ISO3166_2': 'AL'},\n",
       "   'adminName1': 'Alabama',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADMD',\n",
       "   'fcodeName': 'administrative division',\n",
       "   'geonameId': 7172575,\n",
       "   'lat': '34.46512',\n",
       "   'lng': '-86.7875',\n",
       "   'name': 'Town of Somerville',\n",
       "   'population': 724,\n",
       "   'toponymName': 'Town of Somerville'},\n",
       "  {'adminCode1': 'TN',\n",
       "   'adminCodes1': {'ISO3166_2': 'TN'},\n",
       "   'adminName1': 'Tennessee',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADMD',\n",
       "   'fcodeName': 'administrative division',\n",
       "   'geonameId': 7172576,\n",
       "   'lat': '35.23403',\n",
       "   'lng': '-89.38035',\n",
       "   'name': 'Town of Somerville',\n",
       "   'population': 3094,\n",
       "   'toponymName': 'Town of Somerville'},\n",
       "  {'adminCode1': '14',\n",
       "   'adminCodes1': {'ISO3166_2': 'NU'},\n",
       "   'adminName1': 'Nunavut',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'ISL',\n",
       "   'fcodeName': 'island',\n",
       "   'geonameId': 6151213,\n",
       "   'lat': '74.73485',\n",
       "   'lng': '-96.18496',\n",
       "   'name': 'Somerville Island',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Island'},\n",
       "  {'adminCode1': 'TX',\n",
       "   'adminCodes1': {'ISO3166_2': 'TX'},\n",
       "   'adminName1': 'Texas',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'L',\n",
       "   'fclName': 'parks,area, ...',\n",
       "   'fcode': 'PRK',\n",
       "   'fcodeName': 'park',\n",
       "   'geonameId': 4705073,\n",
       "   'lat': '30.31021',\n",
       "   'lng': '-96.62886',\n",
       "   'name': 'Lake Somerville State Park',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Lake Somerville State Park'},\n",
       "  {'adminCode1': 'TX',\n",
       "   'adminCodes1': {'ISO3166_2': 'TX'},\n",
       "   'adminName1': 'Texas',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'L',\n",
       "   'fclName': 'parks,area, ...',\n",
       "   'fcode': 'PRK',\n",
       "   'fcodeName': 'park',\n",
       "   'geonameId': 4732813,\n",
       "   'lat': '30.33271',\n",
       "   'lng': '-96.75498',\n",
       "   'name': 'Somerville Wildlife Management Area',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Wildlife Management Area'},\n",
       "  {'adminCode1': 'TX',\n",
       "   'adminCodes1': {'ISO3166_2': 'TX'},\n",
       "   'adminName1': 'Texas',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'H',\n",
       "   'fclName': 'stream, lake, ...',\n",
       "   'fcode': 'RSV',\n",
       "   'fcodeName': 'reservoir(s)',\n",
       "   'geonameId': 4732812,\n",
       "   'lat': '30.32549',\n",
       "   'lng': '-96.52747',\n",
       "   'name': 'Somerville Lake',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Lake'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 4951262,\n",
       "   'lat': '42.38732',\n",
       "   'lng': '-71.09616',\n",
       "   'name': 'Somerville High School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville High School'},\n",
       "  {'adminCode1': 'NJ',\n",
       "   'adminCodes1': {'ISO3166_2': 'NJ'},\n",
       "   'adminName1': 'New Jersey',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADM3',\n",
       "   'fcodeName': 'third-order administrative division',\n",
       "   'geonameId': 5104779,\n",
       "   'lat': '40.56962',\n",
       "   'lng': '-74.60928',\n",
       "   'name': 'Borough of Somerville',\n",
       "   'population': 12098,\n",
       "   'toponymName': 'Borough of Somerville'},\n",
       "  {'adminCode1': 'ENG',\n",
       "   'adminCodes1': {'ISO3166_2': 'ENG'},\n",
       "   'adminName1': 'England',\n",
       "   'countryCode': 'GB',\n",
       "   'countryId': '2635167',\n",
       "   'countryName': 'United Kingdom',\n",
       "   'fcl': 'A',\n",
       "   'fclName': 'country, state, region,...',\n",
       "   'fcode': 'ADM4',\n",
       "   'fcodeName': 'fourth-order administrative division',\n",
       "   'geonameId': 7297525,\n",
       "   'lat': '52.04147',\n",
       "   'lng': '-1.93328',\n",
       "   'name': 'Aston Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Aston Somerville'},\n",
       "  {'adminCode1': 'WY',\n",
       "   'adminCodes1': {'ISO3166_2': 'WY'},\n",
       "   'adminName1': 'Wyoming',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'VAL',\n",
       "   'fcodeName': 'valley',\n",
       "   'geonameId': 5838920,\n",
       "   'lat': '44.26998',\n",
       "   'lng': '-106.12558',\n",
       "   'name': 'Somerville Draw',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Draw'},\n",
       "  {'adminCode1': '08',\n",
       "   'adminCodes1': {'ISO3166_2': 'ON'},\n",
       "   'adminName1': 'Ontario',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'ISL',\n",
       "   'fcodeName': 'island',\n",
       "   'geonameId': 6151210,\n",
       "   'lat': '46.1834',\n",
       "   'lng': '-79.54964',\n",
       "   'name': 'Somerville Island',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Island'},\n",
       "  {'adminCode1': '03',\n",
       "   'adminCodes1': {'ISO3166_2': 'MB'},\n",
       "   'adminName1': 'Manitoba',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'ISL',\n",
       "   'fcodeName': 'island',\n",
       "   'geonameId': 6151211,\n",
       "   'lat': '55.27205',\n",
       "   'lng': '-101.23325',\n",
       "   'name': 'Somerville Island',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Island'},\n",
       "  {'adminCode1': '02',\n",
       "   'adminCodes1': {'ISO3166_2': 'BC'},\n",
       "   'adminName1': 'British Columbia',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'H',\n",
       "   'fclName': 'stream, lake, ...',\n",
       "   'fcode': 'LK',\n",
       "   'fcodeName': 'lake',\n",
       "   'geonameId': 6151217,\n",
       "   'lat': '50.53111',\n",
       "   'lng': '-120.35167',\n",
       "   'name': 'Somerville Lake',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Lake'},\n",
       "  {'adminCode1': 'MI',\n",
       "   'adminCodes1': {'ISO3166_2': 'MI'},\n",
       "   'adminName1': 'Michigan',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'AIRP',\n",
       "   'fcodeName': 'airport',\n",
       "   'geonameId': 5010336,\n",
       "   'lat': '42.94178',\n",
       "   'lng': '-85.48583',\n",
       "   'name': 'Somerville Airport',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Airport'},\n",
       "  {'adminCode1': '08',\n",
       "   'adminCodes1': {'ISO3166_2': 'WA'},\n",
       "   'adminName1': 'Western Australia',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPLX',\n",
       "   'fcodeName': 'section of populated place',\n",
       "   'geonameId': 8349422,\n",
       "   'lat': '-30.76979',\n",
       "   'lng': '121.45438',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'AL',\n",
       "   'adminCodes1': {'ISO3166_2': 'AL'},\n",
       "   'adminName1': 'Alabama',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'BLDG',\n",
       "   'fcodeName': 'building(s)',\n",
       "   'geonameId': 11524086,\n",
       "   'lat': '34.47289',\n",
       "   'lng': '-86.79838',\n",
       "   'name': 'Somerville Courthouse (historical)',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Courthouse (historical)'},\n",
       "  {'adminCode1': 'L',\n",
       "   'adminCodes1': {'ISO3166_2': 'L'},\n",
       "   'adminName1': 'Leinster',\n",
       "   'countryCode': 'IE',\n",
       "   'countryId': '2963597',\n",
       "   'countryName': 'Ireland',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'EST',\n",
       "   'fcodeName': 'estate(s)',\n",
       "   'geonameId': 2961404,\n",
       "   'lat': '53.63139',\n",
       "   'lng': '-6.51167',\n",
       "   'name': 'Somerville House',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville House'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4935509,\n",
       "   'lat': '42.38673',\n",
       "   'lng': '-71.0839',\n",
       "   'name': 'East Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'East Somerville'},\n",
       "  {'adminCode1': 'NJ',\n",
       "   'adminCodes1': {'ISO3166_2': 'NJ'},\n",
       "   'adminName1': 'New Jersey',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 5104777,\n",
       "   'lat': '40.57816',\n",
       "   'lng': '-74.6121',\n",
       "   'name': 'Somerville High School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville High School'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 4953407,\n",
       "   'lat': '42.40454',\n",
       "   'lng': '-71.11978',\n",
       "   'name': 'Tufts University',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Tufts University'},\n",
       "  {'adminName1': '',\n",
       "   'countryCode': 'JE',\n",
       "   'countryId': '3042142',\n",
       "   'countryName': 'Jersey',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'HTL',\n",
       "   'fcodeName': 'hotel',\n",
       "   'geonameId': 7117966,\n",
       "   'lat': '49.18532',\n",
       "   'lng': '-2.17063',\n",
       "   'name': 'somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'somerville'},\n",
       "  {'adminCode1': 'MS',\n",
       "   'adminCodes1': {'ISO3166_2': 'MS'},\n",
       "   'adminName1': 'Mississippi',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4446529,\n",
       "   'lat': '33.79206',\n",
       "   'lng': '-90.26564',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'CT',\n",
       "   'adminCodes1': {'ISO3166_2': 'CT'},\n",
       "   'adminName1': 'Connecticut',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4843222,\n",
       "   'lat': '41.98287',\n",
       "   'lng': '-72.48786',\n",
       "   'name': 'Somersville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somersville'},\n",
       "  {'adminCode1': 'OH',\n",
       "   'adminCodes1': {'ISO3166_2': 'OH'},\n",
       "   'adminName1': 'Ohio',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 5173379,\n",
       "   'lat': '40.40006',\n",
       "   'lng': '-83.41103',\n",
       "   'name': 'Summersville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Summersville'},\n",
       "  {'adminCode1': 'WY',\n",
       "   'adminCodes1': {'ISO3166_2': 'WY'},\n",
       "   'adminName1': 'Wyoming',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'PLN',\n",
       "   'fcodeName': 'plain(s)',\n",
       "   'geonameId': 5838924,\n",
       "   'lat': '44.26776',\n",
       "   'lng': '-106.11919',\n",
       "   'name': 'Somerville Flats',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Flats'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 7143129,\n",
       "   'lat': '42.3788',\n",
       "   'lng': '-71.0965',\n",
       "   'name': 'Prospect Hill Academy Charter School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Prospect Hill Academy Charter School'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'HSP',\n",
       "   'fcodeName': 'hospital',\n",
       "   'geonameId': 7143328,\n",
       "   'lat': '42.3901',\n",
       "   'lng': '-71.1094',\n",
       "   'name': 'Cambridge Health Alliance-Somerville Hospital',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Cambridge Health Alliance-Somerville Hospital'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SQR',\n",
       "   'fcodeName': 'square',\n",
       "   'geonameId': 4934583,\n",
       "   'lat': '42.39593',\n",
       "   'lng': '-71.12116',\n",
       "   'name': 'Davis Square',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Davis Square'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'HSP',\n",
       "   'fcodeName': 'hospital',\n",
       "   'geonameId': 4951264,\n",
       "   'lat': '42.39011',\n",
       "   'lng': '-71.1094',\n",
       "   'name': 'Cambridge Health Alliance Somerville Campus',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Cambridge Health Alliance Somerville Campus'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4952743,\n",
       "   'lat': '42.39676',\n",
       "   'lng': '-71.087',\n",
       "   'name': 'Ten Hills',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Ten Hills'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SQR',\n",
       "   'fcodeName': 'square',\n",
       "   'geonameId': 4953625,\n",
       "   'lat': '42.37954',\n",
       "   'lng': '-71.09616',\n",
       "   'name': 'Union Square',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Union Square'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'DAM',\n",
       "   'fcodeName': 'dam',\n",
       "   'geonameId': 4928966,\n",
       "   'lat': '42.3949',\n",
       "   'lng': '-71.07518',\n",
       "   'name': 'Amelia Earhart Dam',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Amelia Earhart Dam'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'MALL',\n",
       "   'fcodeName': 'mall',\n",
       "   'geonameId': 4929348,\n",
       "   'lat': '42.39537',\n",
       "   'lng': '-71.08339',\n",
       "   'name': 'Assembly Square Mall Shopping Center',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Assembly Square Mall Shopping Center'},\n",
       "  {'adminCode1': '04',\n",
       "   'adminCodes1': {'ISO3166_2': 'QLD'},\n",
       "   'adminName1': 'Queensland',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'HMSD',\n",
       "   'fcodeName': 'homestead',\n",
       "   'geonameId': 2149130,\n",
       "   'lat': '-20.18333',\n",
       "   'lng': '142.71668',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'PO',\n",
       "   'fcodeName': 'post office',\n",
       "   'geonameId': 4951265,\n",
       "   'lat': '42.3801',\n",
       "   'lng': '-71.09366',\n",
       "   'name': 'Somerville Post Office',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Post Office'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 4955087,\n",
       "   'lat': '42.40621',\n",
       "   'lng': '-71.12589',\n",
       "   'name': 'West Somerville Neighborhood School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'West Somerville Neighborhood School'},\n",
       "  {'adminCode1': 'ME',\n",
       "   'adminCodes1': {'ISO3166_2': 'ME'},\n",
       "   'adminName1': 'Maine',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4968472,\n",
       "   'lat': '44.26091',\n",
       "   'lng': '-69.46004',\n",
       "   'name': 'Jones Corner',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Jones Corner'},\n",
       "  {'adminCode1': 'ME',\n",
       "   'adminCodes1': {'ISO3166_2': 'ME'},\n",
       "   'adminName1': 'Maine',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4977709,\n",
       "   'lat': '44.30979',\n",
       "   'lng': '-69.4581',\n",
       "   'name': 'Sandhill Corner',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Sandhill Corner'},\n",
       "  {'adminCode1': 'ME',\n",
       "   'adminCodes1': {'ISO3166_2': 'ME'},\n",
       "   'adminName1': 'Maine',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4961879,\n",
       "   'lat': '44.28868',\n",
       "   'lng': '-69.47865',\n",
       "   'name': 'Crummett Mountain',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Crummett Mountain'},\n",
       "  {'adminCode1': 'ME',\n",
       "   'adminCodes1': {'ISO3166_2': 'ME'},\n",
       "   'adminName1': 'Maine',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4971251,\n",
       "   'lat': '44.32393',\n",
       "   'lng': '-69.44542',\n",
       "   'name': 'Marrs Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Marrs Hill'},\n",
       "  {'adminCode1': '02',\n",
       "   'adminCodes1': {'ISO3166_2': 'BC'},\n",
       "   'adminName1': 'British Columbia',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'ISL',\n",
       "   'fcodeName': 'island',\n",
       "   'geonameId': 6151212,\n",
       "   'lat': '54.7387',\n",
       "   'lng': '-130.28',\n",
       "   'name': 'Somerville Island',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Island'},\n",
       "  {'adminCode1': 'WV',\n",
       "   'adminCodes1': {'ISO3166_2': 'WV'},\n",
       "   'adminName1': 'West Virginia',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPLA2',\n",
       "   'fcodeName': 'seat of a second-order administrative division',\n",
       "   'geonameId': 4824027,\n",
       "   'lat': '38.28122',\n",
       "   'lng': '-80.8526',\n",
       "   'name': 'Summersville',\n",
       "   'population': 3478,\n",
       "   'toponymName': 'Summersville'},\n",
       "  {'adminCode1': 'PA',\n",
       "   'adminCodes1': {'ISO3166_2': 'PA'},\n",
       "   'adminName1': 'Pennsylvania',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 5212875,\n",
       "   'lat': '40.96062',\n",
       "   'lng': '-79.65394',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'PA',\n",
       "   'adminCodes1': {'ISO3166_2': 'PA'},\n",
       "   'adminName1': 'Pennsylvania',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 5212876,\n",
       "   'lat': '40.05178',\n",
       "   'lng': '-75.15129',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '10',\n",
       "   'adminCodes1': {'ISO3166_2': 'QC'},\n",
       "   'adminName1': 'Quebec',\n",
       "   'countryCode': 'CA',\n",
       "   'countryId': '6251999',\n",
       "   'countryName': 'Canada',\n",
       "   'fcl': 'H',\n",
       "   'fclName': 'stream, lake, ...',\n",
       "   'fcode': 'BAY',\n",
       "   'fcodeName': 'bay',\n",
       "   'geonameId': 5890220,\n",
       "   'lat': '45.08589',\n",
       "   'lng': '-74.42955',\n",
       "   'name': 'Baie de Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Baie de Somerville'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'BLDG',\n",
       "   'fcodeName': 'building(s)',\n",
       "   'geonameId': 7144275,\n",
       "   'lat': '42.39084',\n",
       "   'lng': '-71.09125',\n",
       "   'name': 'Somerville Fire Department Station 1 Headquarters',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Fire Department Station 1 Headquarters'},\n",
       "  {'adminCode1': 'AL',\n",
       "   'adminCodes1': {'ISO3166_2': 'AL'},\n",
       "   'adminName1': 'Alabama',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'CH',\n",
       "   'fcodeName': 'church',\n",
       "   'geonameId': 4090855,\n",
       "   'lat': '34.43565',\n",
       "   'lng': '-86.82445',\n",
       "   'name': 'Somerville Church of God',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Church of God'},\n",
       "  {'adminCode1': 'AL',\n",
       "   'adminCodes1': {'ISO3166_2': 'AL'},\n",
       "   'adminName1': 'Alabama',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 4090858,\n",
       "   'lat': '34.59343',\n",
       "   'lng': '-86.97167',\n",
       "   'name': 'Somerville Road Elementary School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Road Elementary School'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'BLDG',\n",
       "   'fcodeName': 'building(s)',\n",
       "   'geonameId': 4936408,\n",
       "   'lat': '42.39178',\n",
       "   'lng': '-71.1108',\n",
       "   'name': 'Somerville Fire Department Station 7',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Fire Department Station 7'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'BLDG',\n",
       "   'fcodeName': 'building(s)',\n",
       "   'geonameId': 4936411,\n",
       "   'lat': '42.38466',\n",
       "   'lng': '-71.11133',\n",
       "   'name': 'Somerville Fire Department Station 4',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Fire Department Station 4'},\n",
       "  {'adminCode1': 'TN',\n",
       "   'adminCodes1': {'ISO3166_2': 'TN'},\n",
       "   'adminName1': 'Tennessee',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'CMTY',\n",
       "   'fcodeName': 'cemetery',\n",
       "   'geonameId': 4658807,\n",
       "   'lat': '36.58282',\n",
       "   'lng': '-86.66583',\n",
       "   'name': 'Somerville Cemetery',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Cemetery'},\n",
       "  {'adminCode1': 'NJ',\n",
       "   'adminCodes1': {'ISO3166_2': 'NJ'},\n",
       "   'adminName1': 'New Jersey',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 7157842,\n",
       "   'lat': '40.5806',\n",
       "   'lng': '-74.61785',\n",
       "   'name': 'Immaculata High School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Immaculata High School'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4932625,\n",
       "   'lat': '42.38787',\n",
       "   'lng': '-71.10894',\n",
       "   'name': 'Central Hall',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Central Hall'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4933312,\n",
       "   'lat': '42.40482',\n",
       "   'lng': '-71.12728',\n",
       "   'name': 'Clarendon Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Clarendon Hill'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4947909,\n",
       "   'lat': '42.40037',\n",
       "   'lng': '-71.11644',\n",
       "   'name': 'Powder House Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Powder House Hill'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4948041,\n",
       "   'lat': '42.38176',\n",
       "   'lng': '-71.09339',\n",
       "   'name': 'Prospect Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Prospect Hill'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4951767,\n",
       "   'lat': '42.38843',\n",
       "   'lng': '-71.10922',\n",
       "   'name': 'Spring Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Spring Hill'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4955985,\n",
       "   'lat': '42.39537',\n",
       "   'lng': '-71.0995',\n",
       "   'name': 'Winter Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Winter Hill'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4955986,\n",
       "   'lat': '42.39593',\n",
       "   'lng': '-71.09894',\n",
       "   'name': 'Winter Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Winter Hill'},\n",
       "  {'adminCode1': 'NJ',\n",
       "   'adminCodes1': {'ISO3166_2': 'NJ'},\n",
       "   'adminName1': 'New Jersey',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'HSP',\n",
       "   'fcodeName': 'hospital',\n",
       "   'geonameId': 5104769,\n",
       "   'lat': '40.56863',\n",
       "   'lng': '-74.59595',\n",
       "   'name': 'Somerset Medical Center',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerset Medical Center'},\n",
       "  {'adminCode1': 'NJ',\n",
       "   'adminCodes1': {'ISO3166_2': 'NJ'},\n",
       "   'adminName1': 'New Jersey',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 5099442,\n",
       "   'lat': '40.57312',\n",
       "   'lng': '-74.62037',\n",
       "   'name': 'Immaculate Conception School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Immaculate Conception School'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'T',\n",
       "   'fclName': 'mountain,hill,rock,... ',\n",
       "   'fcode': 'MT',\n",
       "   'fcodeName': 'mountain',\n",
       "   'geonameId': 4930328,\n",
       "   'lat': '42.3876',\n",
       "   'lng': '-71.08005',\n",
       "   'name': 'Mount Benedict',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Mount Benedict'},\n",
       "  {'adminCode1': '02',\n",
       "   'adminCodes1': {'ISO3166_2': 'NSW'},\n",
       "   'adminName1': 'New South Wales',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'FRM',\n",
       "   'fcodeName': 'farm',\n",
       "   'geonameId': 2149129,\n",
       "   'lat': '-35.8',\n",
       "   'lng': '146.35',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '08',\n",
       "   'adminCodes1': {'ISO3166_2': 'NC'},\n",
       "   'adminName1': 'Northern Cape',\n",
       "   'countryCode': 'ZA',\n",
       "   'countryId': '953987',\n",
       "   'countryName': 'South Africa',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'FRM',\n",
       "   'fcodeName': 'farm',\n",
       "   'geonameId': 954142,\n",
       "   'lat': '-27.98333',\n",
       "   'lng': '22.11667',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': '10',\n",
       "   'adminCodes1': {'ISO3166_2': 'NW'},\n",
       "   'adminName1': 'North-West',\n",
       "   'countryCode': 'ZA',\n",
       "   'countryId': '953987',\n",
       "   'countryName': 'South Africa',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'FRM',\n",
       "   'fcodeName': 'farm',\n",
       "   'geonameId': 954143,\n",
       "   'lat': '-26.17412',\n",
       "   'lng': '27.22277',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'TX',\n",
       "   'adminCodes1': {'ISO3166_2': 'TX'},\n",
       "   'adminName1': 'Texas',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'R',\n",
       "   'fclName': 'road, railroad ',\n",
       "   'fcode': 'TRL',\n",
       "   'fcodeName': 'trail',\n",
       "   'geonameId': 4704830,\n",
       "   'lat': '30.30493',\n",
       "   'lng': '-96.63942',\n",
       "   'name': 'Lake Somerville Trailway',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Lake Somerville Trailway'},\n",
       "  {'adminCode1': 'UT',\n",
       "   'adminCodes1': {'ISO3166_2': 'UT'},\n",
       "   'adminName1': 'Utah',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPLX',\n",
       "   'fcodeName': 'section of populated place',\n",
       "   'geonameId': 5781648,\n",
       "   'lat': '40.5205',\n",
       "   'lng': '-111.8566',\n",
       "   'name': 'Somerville in Draper',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville in Draper'},\n",
       "  {'adminCode1': 'NY',\n",
       "   'adminCodes1': {'ISO3166_2': 'NY'},\n",
       "   'adminName1': 'New York',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 5138687,\n",
       "   'lat': '44.28312',\n",
       "   'lng': '-75.55661',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'PA',\n",
       "   'adminCodes1': {'ISO3166_2': 'PA'},\n",
       "   'adminName1': 'Pennsylvania',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 5193711,\n",
       "   'lat': '40.60954',\n",
       "   'lng': '-75.59519',\n",
       "   'name': 'Hillside',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Hillside'},\n",
       "  {'adminCode1': 'NY',\n",
       "   'adminCodes1': {'ISO3166_2': 'NY'},\n",
       "   'adminName1': 'New York',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 6332500,\n",
       "   'lat': '40.59556',\n",
       "   'lng': '-73.7975',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'NJ',\n",
       "   'adminCodes1': {'ISO3166_2': 'NJ'},\n",
       "   'adminName1': 'New Jersey',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'SCH',\n",
       "   'fcodeName': 'school',\n",
       "   'geonameId': 5104778,\n",
       "   'lat': '40.57208',\n",
       "   'lng': '-74.61376',\n",
       "   'name': 'Somerville Middle School',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville Middle School'},\n",
       "  {'adminCode1': '07',\n",
       "   'adminCodes1': {'ISO3166_2': 'VIC'},\n",
       "   'adminName1': 'Victoria',\n",
       "   'countryCode': 'AU',\n",
       "   'countryId': '2077456',\n",
       "   'countryName': 'Australia',\n",
       "   'fcl': 'S',\n",
       "   'fclName': 'spot, building, farm',\n",
       "   'fcode': 'RSTN',\n",
       "   'fcodeName': 'railroad station',\n",
       "   'geonameId': 8828816,\n",
       "   'lat': '-38.22542',\n",
       "   'lng': '145.17569',\n",
       "   'name': 'Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Somerville'}],\n",
       " 'totalResultsCount': 332}"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "R.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Changing our request\n",
    "\n",
    "Looking at the response, the Somerville in Massachusetts seems to be at the top of the pile. That's great for us, but sometimes you actually are looking for \"Paris, TX\" and not \"Paris, France\". In that case, you'll want to narrow your results. Let's try that with our request.\n",
    "\n",
    "We can specify the country we're talking about, and we can also specify the state abbreviation under \"adminCode1\", which is a general purpose place to put abbreviation for things like states and provinces. Finally, we can specify the kind of place that we want with \"featureCode\" set to \"PPL\" for \"populated place\", so we don't get various entries like schools and economic regions.\n",
    "\n",
    "All of these parameters are being drawn from the [GeoNames search API documentation](http://www.geonames.org/export/geonames-search.html), but it's also useful to look at the search results that you receive for filtering ideas. Usually, the information that tells you that a result is irrelevant to your query is information that you can put into a filter. That's how I found the \"adminCode1\" and \"featureCode\" parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'adminCode1': 'MA',\n",
       " 'country': 'US',\n",
       " 'featureCode': 'PPL',\n",
       " 'q': 'Somerville',\n",
       " 'username': 'cdc43339'}"
      ]
     },
     "execution_count": 39,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Q['country'] = 'US'\n",
    "Q['adminCode1'] = 'MA' \n",
    "Q['featureCode'] = 'PPL' # These keys didn't exist until we set them to something! We can create keys this way.\n",
    "Q"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [],
   "source": [
    "R = requests.get(url,params=Q)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'http://api.geonames.org/searchJSON?q=Somerville&username=cdc43339&country=US&adminCode1=MA&featureCode=PPL'"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "R.url"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'geonames': [{'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4951257,\n",
       "   'lat': '42.3876',\n",
       "   'lng': '-71.0995',\n",
       "   'name': 'Somerville',\n",
       "   'population': 80318,\n",
       "   'toponymName': 'Somerville'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4955085,\n",
       "   'lat': '42.39593',\n",
       "   'lng': '-71.12255',\n",
       "   'name': 'West Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'West Somerville'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4952743,\n",
       "   'lat': '42.39676',\n",
       "   'lng': '-71.087',\n",
       "   'name': 'Ten Hills',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Ten Hills'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4935509,\n",
       "   'lat': '42.38673',\n",
       "   'lng': '-71.0839',\n",
       "   'name': 'East Somerville',\n",
       "   'population': 0,\n",
       "   'toponymName': 'East Somerville'},\n",
       "  {'adminCode1': 'MA',\n",
       "   'adminCodes1': {'ISO3166_2': 'MA'},\n",
       "   'adminName1': 'Massachusetts',\n",
       "   'countryCode': 'US',\n",
       "   'countryId': '6252001',\n",
       "   'countryName': 'United States',\n",
       "   'fcl': 'P',\n",
       "   'fclName': 'city, village,...',\n",
       "   'fcode': 'PPL',\n",
       "   'fcodeName': 'populated place',\n",
       "   'geonameId': 4955986,\n",
       "   'lat': '42.39593',\n",
       "   'lng': '-71.09894',\n",
       "   'name': 'Winter Hill',\n",
       "   'population': 0,\n",
       "   'toponymName': 'Winter Hill'}],\n",
       " 'totalResultsCount': 5}"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "R.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Try it out!\n",
    "\n",
    "Now it's your turn. Try limiting your search to a particular part of the state of Massachusetts! You can always look back at the [API Documentation](http://www.geonames.org/export/geonames-search.html) for ideas.\n",
    "\n",
    "*Hint: [this website](http://boundingbox.klokantech.com/) might be of assistance. I've found the DublinCore output to be pretty readable.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'adminCode1': 'MA',\n",
       " 'country': 'US',\n",
       " 'featureCode': 'PPL',\n",
       " 'q': 'Somerville',\n",
       " 'username': 'cdc43339'}"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Q"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with our results\n",
    "\n",
    "We can set up our results as their own object that we can work with. Don't worry, you're not re-requesting the data every time you work with the request object \"R\", the online request gets made once when the object is created, and from then on, the request object is just information about that request stored in memory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = R.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict"
      ]
     },
     "execution_count": 47,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(result)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'adminCode1': 'MA',\n",
       " 'adminCodes1': {'ISO3166_2': 'MA'},\n",
       " 'adminName1': 'Massachusetts',\n",
       " 'countryCode': 'US',\n",
       " 'countryId': '6252001',\n",
       " 'countryName': 'United States',\n",
       " 'fcl': 'P',\n",
       " 'fclName': 'city, village,...',\n",
       " 'fcode': 'PPL',\n",
       " 'fcodeName': 'populated place',\n",
       " 'geonameId': 4951257,\n",
       " 'lat': '42.3876',\n",
       " 'lng': '-71.0995',\n",
       " 'name': 'Somerville',\n",
       " 'population': 80318,\n",
       " 'toponymName': 'Somerville'}"
      ]
     },
     "execution_count": 48,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "result['geonames'][0] # Here is the first response, since list slicing starts counting from 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(result['geonames'][0]['lat'], result['geonames'][0]['lng']) # Prints the lat and the long from the first result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Making a function\n",
    "\n",
    "That's all well and good, but if we had to write all that code for every lat/long pair that we wanted to get, we wouldn't be saving ourselves any time. However, we can create a function to do our search for us, and return the information that we're interested in.\n",
    "\n",
    "If you're still pretty new to Python, you may not have made many functions, so we'll go over the basics.\n",
    "\n",
    "When you set up a function, you start with something like this:\n",
    "\n",
    "```python\n",
    "def somefunction(argument1, argument2, argument3=None):\n",
    "```\n",
    "\n",
    "This says \"I'm making a function called `somefunction`, and when you run this function, you can specify some parameters that I'm going to calll `argument1`, `argument2`, and `argument3`. Also, you don't have to specify `argument3`. It'll default to `None` if you don't specify it.\"\n",
    "\n",
    "Within the context of your function, you can do whatever you want with those inputs. In our case, we're using them to make an API request. The code inside is up to you, the important thing is that you end with a `return` statement. That's what makes your function spit out something. In our case, we want the latitude and longitude back from our function.\n",
    "\n",
    "You'll notice that we're returning two values, separated by a comma, but not enclosed by anything. When you do that in a return statement, Python interprets that as \"return a tuple\", which is a kind of container, very similar to a list, but not set up to be modifiable. We can get away with using this very simple data container, so we'll use it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def search_us_place(placename,state_abbrev):\n",
    "    url = \"http://api.geonames.org/searchJSON\"\n",
    "    Q = {\n",
    "        'q':placename,\n",
    "        'country':'US',\n",
    "        'username':USERNAME,\n",
    "        'adminCode1':state_abbrev\n",
    "    }\n",
    "    results = requests.get(url,params=Q).json()\n",
    "    top_result = results['geonames'][0]\n",
    "    return top_result['lat'], top_result['lng']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "test = search_us_place('Worcester','MA')\n",
    "print(type(test))\n",
    "print(test)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Try it out!\n",
    "\n",
    "Try making your own function to get some data that is of interest to you. If you want an idea to implement, imagine that you have a lot of location names in English, and you want to get the Mandarin names. How would you write a function that returns those names from a search query in English?\n",
    "\n",
    "Don't forget to check the [documentation,](http://www.geonames.org/export/geonames-search.html) and you might have to do a bit of Googling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def myfunc():\n",
    "    return 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Applying our function to a dataset\n",
    "\n",
    "Now that we have a function to give us lat/long pairs from a city name and state, we can actually apply it to a dataset. I've prepared a small dataset: a list of botanical gardens and arboretums in Massachusetts ([from Wikipedia](https://en.wikipedia.org/wiki/List_of_botanical_gardens_and_arboretums_in_Massachusetts)). \n",
    "\n",
    "The way I like to do that is with the Pandas module in Python. Pandas is a module that has a lot of tools for working with tabular data, and is a favorite among data scientists. We're using it today because it makes working with CSV files really really easy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Don't panic...\n",
    "\n",
    "This cell is going to produce an error. Take a look at the error message and our csv file to see if you can figure out what the problem is. You can look ahead to the next cell for the fix, but that'd be cheating!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df = pd.read_csv('botanical_gardens.csv')\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv('botanical_gardens.csv',sep='\\t') # Working file opener with separator as tabs\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Being nice to APIs\n",
    "\n",
    "A lot of APIs, especially smaller APIs, aren't built to withstand a bunch of users hammering away at them as fast as their processors will allow. APIs like some of Google's have explicit rate limits, some of which are quite high, because the back ends are so robust. For our purposes, we'll go nice and easy with a 1 second delay between requests.\n",
    "\n",
    "You'll also notice that there are some new print statements. If you're going to be running a function a whole bunch of times, it's good to get feedback on where it is in its loop, and so if things go wrong, you know where they went wrong."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import time\n",
    "\n",
    "def search_us_place(placename,state_abbrev):\n",
    "    url = \"http://api.geonames.org/searchJSON\"\n",
    "    Q = {\n",
    "        'q':placename,\n",
    "        'country':'US',\n",
    "        'username':USERNAME,\n",
    "        'adminCode1':state_abbrev\n",
    "    }\n",
    "    print('making request for {}, {}'.format(placename,state_abbrev))\n",
    "    R = requests.get(url,params=Q)\n",
    "    print(R.url)\n",
    "    results = R.json()\n",
    "    top_result = results['geonames'][0]\n",
    "    print('got result for {}, {}'.format(placename,state_abbrev))\n",
    "    time.sleep(1)\n",
    "    return top_result['lat'], top_result['lng']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "search_us_place('Boston','MA') # Now we'll run this new function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Applying functions to our csv\n",
    "\n",
    "Another nice thing about pandas is how efficiently the library applies functions to dataframes. We want to apply our function to the spreadsheet. Since all of our data is in the same state, we can send `'MA'` as the state abbreviation every time.\n",
    "\n",
    "We can accomplish that with a lambda function, which is just an anonymous function to use in a place where you need a function, but you don't think you'll need to reuse that function. We're using it to apply a function with a consistent parameter, but you can use it for simpler things like adding a number or a prefix to a column.\n",
    "\n",
    "We're setting the results of that function to the variable `latLngs`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "latLngs = df.City.apply(lambda x: search_us_place(x,'MA'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What is our output?\n",
    "\n",
    "If you look at our `latLngs` output, you'll notice that it's pretty similar to other columns in our existing dataframe. That's because it's the same sort of thing, except that our lat/longs are still tuples. We could have a column of tuples, but wouldn't it be nice to have two columns, one for latitude and one for longitude?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "latLngs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.City"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Zip up the results\n",
    "\n",
    "You'll find a more detailed explanation of why this works at the bottom of this notebook, but for now, just know that this is a way to set multiple columns from output like what we have from applying our function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df['lat'],df['lng'] = zip(*latLngs)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Saving the results\n",
    "\n",
    "Saving a csv file is incredibly easy, you can do it with just a filename. However, it does add the index as an extra column of numbers, which we don't need in our dataset, so I'm choosing to omit that."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.to_csv('botanical_gardens_with_location.csv',index=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Try it out!\n",
    "\n",
    "Using the function that you made earlier, add a new column (or columns!) to our dataframe, then save it with an appropriate filename."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Put your code here, adding more cells as needed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Data enriched!\n",
    "\n",
    "That's it, we've gone through the whole process of using an API to enrich data in python. To review, we:\n",
    "\n",
    "* Explored the API we wanted to use\n",
    "* Built a function to make a request we wanted\n",
    "* Imported our csv data\n",
    "* Ran our function on our dataset\n",
    "* Saved our outpu\n",
    "\n",
    "Whatever API you use to enrich a dataset, you can typically use some variation of this workflow. I recommend using a notebook like this one, especially for early explorations, so you can leave a record of your exploration process, and re-use portions of code elsewhere."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Reverse the flow!\n",
    "\n",
    "We can also use APIs to add data from our datasets to a website, too.\n",
    "\n",
    "Here, we'll use the API for Omeka. Omeka is a content management system, like WordPress, but focused on making the collections of libraries, archives, and museums more easily accessible on the web. It's built around the concept of items, and focuses on describing those items, collecting them sensibly, and incorporating them into online narratives.\n",
    "\n",
    "The site we'll be using is the site that we use for testing our Omeka service here: http://testing.omeka-dev.fas.harvard.edu/\n",
    "\n",
    "You'll find documentation for the API here: http://omeka.readthedocs.io/en/latest/Reference/api/index.html\n",
    "\n",
    "Our goal for this portion will be to use the documentation and what we've already learned to create items in Omeka representing each of the places in our dataframe.\n",
    "\n",
    "Before we get started on that, we'll want to see how the API represents items, so we can copy that when creating new ones."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "omeka_api_key = '' # We'll give you a key to use for the site"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# We're not using the key yet, since we're just viewing public information\n",
    "R = requests.get('http://demo.omeka.fas.harvard.edu/api/items/36')\n",
    "demo_item = R.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "demo_item"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## New function!\n",
    "\n",
    "Since making items isn't exactly intuitive, let's make a quick function to construct items from dictionaries. We're relying on some things specific to this site, namely the IDs of each element, and for a more general solution we'd want to do something more nuanced than hord coding those IDs into our workflow. For now, though, this is a workable solution"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def make_item(element_texts):\n",
    "    \"\"\"\n",
    "    Takes a dictionary with format {element_id:element_text, ...}\n",
    "    \"\"\"\n",
    "    base_item = {\n",
    "        'element_texts':[],\n",
    "        'featured': False,\n",
    "        'public': True,\n",
    "    }\n",
    "    for _id, text in element_texts.items():\n",
    "        element = {\n",
    "            'element': { 'id': int(_id) },\n",
    "            'text': text,\n",
    "            'html': True\n",
    "        }\n",
    "        base_item['element_texts'].append(element)\n",
    "    return base_item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "test = {\n",
    "    50: 'A Test Item',\n",
    "    41: \"The description of the test item. It might be a bit longer, which is fine since it won't be used as a page title or anything.\"\n",
    "}\n",
    "test_item = make_item(test)\n",
    "print(test_item)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## POST new data\n",
    "\n",
    "Now that we have content to upload, let's take a look at how we'll do that. We're using a different method of sending data to the url, you'll notice. We're POSTing data, which usually means we're adding something new. We can still use our `params` argument, but our data is in our `json` argument.\n",
    "\n",
    "The `requests` module has this as a convenient parameter, so you don't have to turn your dictionary into a string to use it as a data payload. Since this is such a common task, `requests` has built it into this method call so we can just use the dictionary object we've created.\n",
    "\n",
    "We'll still get a response, but in this case, we'll get a representation of the item that we just created, as long as it was created successfully. We know this from the documentation, which tells us what response to expect from each kind of query we can send to the items API endpoint."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "R = requests.post('http://demo.omeka.fas.harvard.edu/api/items',json=test_item, params={'key':omeka_api_key})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "R.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Functions in functions\n",
    "\n",
    "We can make another function to take a dictionary that represents our item in a pretty convenient way and add that directly to Omeka. We're using the function that we made to create an item within this function, so we don't have to add that functionality to this function too. We might want to keep these functions separate, in case we want to use the `make_item` function on its own for some other purpose, like creating several items and then adding them all at once.\n",
    "\n",
    "The second function is designed to go from a single row from our spreadsheet directly to the creation of an Item in Omeka. You can change the items that you add by changing this function. In fact, I encourage you to do so, since we'll all be adding items, and it'll be hard to tell which ones are yours. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def add_item_to_omeka(element_texts):\n",
    "    item = make_item(element_texts)\n",
    "    R = requests.post('http://demo.omeka.fas.harvard.edu/api/items',json=item, params={'key':omeka_api_key})\n",
    "    return R.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def row_to_omeka(row):\n",
    "    title = row['Name']\n",
    "    description = \"Located in {}, MA ({},{})\".format(row['City'],row['lat'],row['lng'])\n",
    "    element_texts = {\n",
    "        '50': title,\n",
    "        '41': description,\n",
    "        '39': 'Your name here!'\n",
    "    }\n",
    "    response = add_item_to_omeka(**element_texts)\n",
    "    return response"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.apply(row_to_omeka,axis=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Addendum: The zip() function\n",
    "\n",
    "In case you're curious, this is how that funky line we used to assign multiple columns worked:\n",
    "\n",
    "```python\n",
    "df['lat'],df['lng'] = zip(*latLngs)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `zip()` function returns what's called a \"generator\" object, which is a Python object that won't show you its contents, but rather contains instructions to quickly generate those contents on the fly. You'll find something similar with the `range()` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "print(zip([1,2],[3,4],[5,6],[7,8]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, to look inside, we have to iterate through and print the contents. Notice that I'm providing these lists as individual arguments. Zip takes as many arguments as you care to give it, through the `*args` keyword in its function definition. This means that there will be a list `args` in the function that something happens to. In this case, we're taking the first value of each list, and making one tuple from those values, and taking the second value and making another list. This will work no matter how many items are in each list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for z in zip([1,2],[3,4],[5,6],[7,8]):\n",
    "    print(z)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may be thinking \"Great! I have a list of lists, I'll just put that in as my argument!\"\n",
    "\n",
    "Let's see what happens when you do that:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "test = [[1,2],[3,4],[5,6],[7,8]]\n",
    "for z in zip(test):\n",
    "    print(z)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That doesn't look like what we want. What we did in that line was to pass the whole list as a single argument, when what we wanted was to pass each list item as its own argument, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for z in zip(test[0],test[1],test[2],test[3]):\n",
    "    print(z)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, that would be a lot of typing for a long list. Fortunately, we can prefix our list with `*`, to do just what we want, and pass our entire list directly to the function's `*args` keyword."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for z in zip(*test):\n",
    "    print(z)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But how does that help our problem? Well, our collection of lat/long coordinates is iterable in the same way that a list is, so in this case we can use it in the same way. This next block is just a demonstration of that iterability."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for ll in latLngs:\n",
    "    print(ll)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And now, we have all of the pieces together, so we can see that the output of our `zip()` function is in fact two tuples, each with one of our desired columns of data. Since they're each the same length as our dataframe (being derived from it), we can turn them into new columns just by setting the new columns equal to them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "for z in zip(*latLngs):\n",
    "    print(z)"
   ]
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}