{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "#### This demo is a brief overview of the documentation https://lets-plot.org/python/pages/geocoding.html" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:47.026820Z", "iopub.status.busy": "2024-04-17T07:26:47.026429Z", "iopub.status.idle": "2024-04-17T07:26:47.367951Z", "shell.execute_reply": "2024-04-17T07:26:47.367625Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).\n" ] } ], "source": [ "import shapely\n", "from IPython.display import display, Markdown\n", "\n", "from lets_plot import *\n", "from lets_plot.geo_data import *" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:47.381349Z", "iopub.status.busy": "2024-04-17T07:26:47.381131Z", "iopub.status.idle": "2024-04-17T07:26:47.383065Z", "shell.execute_reply": "2024-04-17T07:26:47.382883Z" } }, "outputs": [ { "data": { "text/html": [ "\n", "
\n", " \n", " " ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "LetsPlot.setup_html()" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:47.384117Z", "iopub.status.busy": "2024-04-17T07:26:47.383977Z", "iopub.status.idle": "2024-04-17T07:26:47.385679Z", "shell.execute_reply": "2024-04-17T07:26:47.385490Z" } }, "outputs": [], "source": [ "def run_catching(f):\n", " def colored(s):\n", " return Markdown('{}'.format(s))\n", " try:\n", " f()\n", " assert False, 'Error expected'\n", " except Exception as e:\n", " display(colored('{}'.format(e)))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Basic usage" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:47.386689Z", "iopub.status.busy": "2024-04-17T07:26:47.386548Z", "iopub.status.idle": "2024-04-17T07:26:47.655661Z", "shell.execute_reply": "2024-04-17T07:26:47.655347Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecentroidpositionlimit
0162050floridaFlorida[-81.664617414276, 28.0571937561035][-87.6348964869976, 25.1162923872471, -80.0309...[-87.6348964869976, 24.5230695605278, -80.0309...
1114690txTexas[-99.6829525269137, 31.1685702949762][-106.645845472813, 25.8370596170425, -93.5078...[-106.645845472813, 25.8370596170425, -93.5078...
\n", "
" ], "text/plain": [ " id state found name centroid \\\n", "0 162050 florida Florida [-81.664617414276, 28.0571937561035] \n", "1 114690 tx Texas [-99.6829525269137, 31.1685702949762] \n", "\n", " position \\\n", "0 [-87.6348964869976, 25.1162923872471, -80.0309... \n", "1 [-106.645845472813, 25.8370596170425, -93.5078... \n", "\n", " limit \n", "0 [-87.6348964869976, 24.5230695605278, -80.0309... \n", "1 [-106.645845472813, 25.8370596170425, -93.5078... " ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Level autodetection\n", "geocode(names=['florida', 'tx']).get_geocodes()\n", "\n", "# Result may contain the following columns:\n", "# id - for internal use. Only in geocodes DataFrame.\n", "# request - column with lowest administrative level. The request belongs to this level. Can be a city/county/state/country.\n", "# parents - if provided. Can be a county/state/country.\n", "# found name - name that found by geocoding.\n", "# geometry - only in geometry DataFrame.\n", "\n", "# Thanks to request column it's obvious that level was detected as state." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "code", "execution_count": 5, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:47.656928Z", "iopub.status.busy": "2024-04-17T07:26:47.656845Z", "iopub.status.idle": "2024-04-17T07:26:47.875328Z", "shell.execute_reply": "2024-04-17T07:26:47.875019Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecentroidpositionlimit
0162050floridaFlorida[-81.664617414276, 28.0571937561035][-87.6348964869976, 25.1162923872471, -80.0309...[-87.6348964869976, 24.5230695605278, -80.0309...
1114690txTexas[-99.6829525269137, 31.1685702949762][-106.645845472813, 25.8370596170425, -93.5078...[-106.645845472813, 25.8370596170425, -93.5078...
\n", "
" ], "text/plain": [ " id state found name centroid \\\n", "0 162050 florida Florida [-81.664617414276, 28.0571937561035] \n", "1 114690 tx Texas [-99.6829525269137, 31.1685702949762] \n", "\n", " position \\\n", "0 [-87.6348964869976, 25.1162923872471, -80.0309... \n", "1 [-106.645845472813, 25.8370596170425, -93.5078... \n", "\n", " limit \n", "0 [-87.6348964869976, 24.5230695605278, -80.0309... \n", "1 [-106.645845472813, 25.8370596170425, -93.5078... " ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Explicit level\n", "geocode_states(['florida', 'tx']).get_geocodes()" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:47.876563Z", "iopub.status.busy": "2024-04-17T07:26:47.876462Z", "iopub.status.idle": "2024-04-17T07:26:48.587938Z", "shell.execute_reply": "2024-04-17T07:26:48.587641Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecountrycentroidpositionlimit
0162050floridaFloridausa[-81.664617414276, 28.0571937561035][-87.6348964869976, 25.1162923872471, -80.0309...[-87.6348964869976, 24.5230695605278, -80.0309...
\n", "
" ], "text/plain": [ " id state found name country centroid \\\n", "0 162050 florida Florida usa [-81.664617414276, 28.0571937561035] \n", "\n", " position \\\n", "0 [-87.6348964869976, 25.1162923872471, -80.0309... \n", "\n", " limit \n", "0 [-87.6348964869976, 24.5230695605278, -80.0309... " ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecountrycentroidpositionlimit
01635164floridaFloridauruguay[-55.8642029687055, -33.7640165537596][-56.5363445878029, -34.4264329969883, -55.098...[-56.5363445878029, -34.4264329969883, -55.098...
\n", "
" ], "text/plain": [ " id state found name country \\\n", "0 1635164 florida Florida uruguay \n", "\n", " centroid \\\n", "0 [-55.8642029687055, -33.7640165537596] \n", "\n", " position \\\n", "0 [-56.5363445878029, -34.4264329969883, -55.098... \n", "\n", " limit \n", "0 [-56.5363445878029, -34.4264329969883, -55.098... " ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecentroidpositionlimit
0162050floridaFlorida[-81.664617414276, 28.0571937561035][-87.6348964869976, 25.1162923872471, -80.0309...[-87.6348964869976, 24.5230695605278, -80.0309...
\n", "
" ], "text/plain": [ " id state found name centroid \\\n", "0 162050 florida Florida [-81.664617414276, 28.0571937561035] \n", "\n", " position \\\n", "0 [-87.6348964869976, 25.1162923872471, -80.0309... \n", "\n", " limit \n", "0 [-87.6348964869976, 24.5230695605278, -80.0309... " ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Parameters can be change between searches\n", "florida = geocode_states('florida')\n", "\n", "display(florida.countries('usa').get_geocodes())\n", "display(florida.countries('uruguay').get_geocodes())\n", "display(florida.countries(None).get_geocodes())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Scope" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:48.589147Z", "iopub.status.busy": "2024-04-17T07:26:48.589075Z", "iopub.status.idle": "2024-04-17T07:26:48.834692Z", "shell.execute_reply": "2024-04-17T07:26:48.834367Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecentroidpositionlimit
01635164floridaFlorida[-55.8642029687055, -33.7640165537596][-56.5363445878029, -34.4264329969883, -55.098...[-56.5363445878029, -34.4264329969883, -55.098...
\n", "
" ], "text/plain": [ " id state found name centroid \\\n", "0 1635164 florida Florida [-55.8642029687055, -33.7640165537596] \n", "\n", " position \\\n", "0 [-56.5363445878029, -34.4264329969883, -55.098... \n", "\n", " limit \n", "0 [-56.5363445878029, -34.4264329969883, -55.098... " ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# str scope uses level autodetection.\n", "# NB: Florida in USA is the most relevant result.\n", "# We can't find Florida in Uruguay using only the name - parent (country or scope) is required.\n", "geocode_states('florida').scope('uruguay').get_geocodes()" ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:48.835886Z", "iopub.status.busy": "2024-04-17T07:26:48.835768Z", "iopub.status.idle": "2024-04-17T07:26:49.294822Z", "shell.execute_reply": "2024-04-17T07:26:49.294516Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecentroidpositionlimit
01635164floridaFlorida[-55.8642029687055, -33.7640165537596][-56.5363445878029, -34.4264329969883, -55.098...[-56.5363445878029, -34.4264329969883, -55.098...
\n", "
" ], "text/plain": [ " id state found name centroid \\\n", "0 1635164 florida Florida [-55.8642029687055, -33.7640165537596] \n", "\n", " position \\\n", "0 [-56.5363445878029, -34.4264329969883, -55.098... \n", "\n", " limit \n", "0 [-56.5363445878029, -34.4264329969883, -55.098... " ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Geocoder scope\n", "uruguay = geocode_countries('uruguay')\n", "geocode_states('florida').scope(uruguay).get_geocodes()" ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:49.296024Z", "iopub.status.busy": "2024-04-17T07:26:49.295927Z", "iopub.status.idle": "2024-04-17T07:26:49.297717Z", "shell.execute_reply": "2024-04-17T07:26:49.297560Z" } }, "outputs": [ { "data": { "text/markdown": [ "Unsupported 'scope' type. Expected 'str' or 'Geocoder' but was 'list'" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Scope is a singleton. Collections are not allowed.\n", "scope = ['uruguay']\n", "run_catching(\n", " lambda: geocode_states('florida').scope(scope).get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:49.298916Z", "iopub.status.busy": "2024-04-17T07:26:49.298772Z", "iopub.status.idle": "2024-04-17T07:26:49.547003Z", "shell.execute_reply": "2024-04-17T07:26:49.546719Z" } }, "outputs": [ { "data": { "text/markdown": [ "'scope' has 2 entries, but expected to have exactly 1" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Geocoder with more than one entry is not allowed too.\n", "scope = geocode_countries(['uruguay', 'usa'])\n", "run_catching(\n", " lambda: geocode_states('florida').scope(scope).get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 11, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:49.548140Z", "iopub.status.busy": "2024-04-17T07:26:49.548065Z", "iopub.status.idle": "2024-04-17T07:26:50.032575Z", "shell.execute_reply": "2024-04-17T07:26:50.032171Z" } }, "outputs": [ { "data": { "text/markdown": [ "Region is not found: worcester county" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/markdown": [ "Multiple objects (2) were found for worcester county:\n", "- Worcester County (United States, Maryland)\n", "- Worcester County (United States, Massachusetts)\n", "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# str scope can be ambiguous.\n", "run_catching(\n", " lambda: geocode_cities('worcester').scope('worcester county').get_geocodes()\n", ")\n", "\n", "# Let's geocode Worcester County in a way how the service does - using level detection without parents.\n", "# In fact Worcester County was found, but error message in case of parent ambiguity is not clear. We will improve it.\n", "run_catching(\n", " lambda: geocode_counties('worcester county').get_geocodes()\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Parents." ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:50.033702Z", "iopub.status.busy": "2024-04-17T07:26:50.033627Z", "iopub.status.idle": "2024-04-17T07:26:50.288817Z", "shell.execute_reply": "2024-04-17T07:26:50.288403Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecountystatecentroidpositionlimit
0119776warwickWarwickWorth Countygeorgia[-83.9205776783726, 31.8303624540567][-83.9291015267372, 31.8222776055336, -83.9120...[-83.9291015267372, 31.8222776055336, -83.9120...
1158851900worcesterWorcesterworcester countymassachusetts[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
\n", "
" ], "text/plain": [ " id city found name county state \\\n", "0 119776 warwick Warwick Worth County georgia \n", "1 158851900 worcester Worcester worcester county massachusetts \n", "\n", " centroid \\\n", "0 [-83.9205776783726, 31.8303624540567] \n", "1 [-71.8154652712922, 42.2678737342358] \n", "\n", " position \\\n", "0 [-83.9291015267372, 31.8222776055336, -83.9120... \n", "1 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "\n", " limit \n", "0 [-83.9291015267372, 31.8222776055336, -83.9120... \n", "1 [-71.8840424716473, 42.2100399434566, -71.7312... " ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Parents should have same length as names\n", "geocode_cities(['warwick', 'worcester'])\\\n", " .counties(['Worth County', 'worcester county'])\\\n", " .states(['georgia', 'massachusetts'])\\\n", " .get_geocodes()" ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:50.290039Z", "iopub.status.busy": "2024-04-17T07:26:50.289957Z", "iopub.status.idle": "2024-04-17T07:26:50.530151Z", "shell.execute_reply": "2024-04-17T07:26:50.529830Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namestatecountrycentroidpositionlimit
0119776warwickWarwickGeorgiaUSA[-83.9205776783726, 31.8303624540567][-83.9291015267372, 31.8222776055336, -83.9120...[-83.9291015267372, 31.8222776055336, -83.9120...
120971097worcesterWorcesterNoneUnited Kingdom[-2.2095610731112, 52.1965283900499][-2.2632023692131, 52.1616362035275, -2.157303...[-2.2632023692131, 52.1616362035275, -2.157303...
\n", "
" ], "text/plain": [ " id city found name state country \\\n", "0 119776 warwick Warwick Georgia USA \n", "1 20971097 worcester Worcester None United Kingdom \n", "\n", " centroid \\\n", "0 [-83.9205776783726, 31.8303624540567] \n", "1 [-2.2095610731112, 52.1965283900499] \n", "\n", " position \\\n", "0 [-83.9291015267372, 31.8222776055336, -83.9120... \n", "1 [-2.2632023692131, 52.1616362035275, -2.157303... \n", "\n", " limit \n", "0 [-83.9291015267372, 31.8222776055336, -83.9120... \n", "1 [-2.2632023692131, 52.1616362035275, -2.157303... " ] }, "execution_count": 13, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Parents can contain None items (e.g., countries with different administrative divisions).\n", "geocode_cities(['warwick', 'worcester'])\\\n", " .states(['Georgia', None])\\\n", " .countries(['USA', 'United Kingdom'])\\\n", " .get_geocodes()" ] }, { "cell_type": "code", "execution_count": 14, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:50.531187Z", "iopub.status.busy": "2024-04-17T07:26:50.531108Z", "iopub.status.idle": "2024-04-17T07:26:51.026959Z", "shell.execute_reply": "2024-04-17T07:26:51.026660Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idstatefound namecentroidpositionlimit
060759vermontVermont[-72.772353529363, 43.8718488067389][-73.4377402067184, 42.7269606292248, -71.4653...[-73.4377402067184, 42.7269606292248, -71.4653...
1161957georgiaGeorgia[-83.2514879869572, 32.6792977005243][-85.6052421033382, 30.3557570278645, -80.8400...[-85.6052421033382, 30.3557570278645, -80.8400...
\n", "
" ], "text/plain": [ " id state found name centroid \\\n", "0 60759 vermont Vermont [-72.772353529363, 43.8718488067389] \n", "1 161957 georgia Georgia [-83.2514879869572, 32.6792977005243] \n", "\n", " position \\\n", "0 [-73.4377402067184, 42.7269606292248, -71.4653... \n", "1 [-85.6052421033382, 30.3557570278645, -80.8400... \n", "\n", " limit \n", "0 [-73.4377402067184, 42.7269606292248, -71.4653... \n", "1 [-85.6052421033382, 30.3557570278645, -80.8400... " ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namestatecentroidpositionlimit
08898137worcesterWorcestervermont[-72.5724501055639, 44.4132962822914][-72.6543393731117, 44.3454243242741, -72.4935...[-72.6543393731117, 44.3454243242741, -72.4935...
1119776warwickWarwickgeorgia[-83.9205776783726, 31.8303624540567][-83.9291015267372, 31.8222776055336, -83.9120...[-83.9291015267372, 31.8222776055336, -83.9120...
\n", "
" ], "text/plain": [ " id city found name state \\\n", "0 8898137 worcester Worcester vermont \n", "1 119776 warwick Warwick georgia \n", "\n", " centroid \\\n", "0 [-72.5724501055639, 44.4132962822914] \n", "1 [-83.9205776783726, 31.8303624540567] \n", "\n", " position \\\n", "0 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "1 [-83.9291015267372, 31.8222776055336, -83.9120... \n", "\n", " limit \n", "0 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "1 [-83.9291015267372, 31.8222776055336, -83.9120... " ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Geocoder object can be used as parent. Number of entries should be same as the number of names.\n", "s = geocode_states(['vermont', 'georgia']).scope('usa')\n", "display(s.get_geocodes())\n", "\n", "# NB: Parent request will be present in result as a column.\n", "display(geocode_cities(['worcester', 'warwick']).states(s).get_geocodes())" ] }, { "cell_type": "code", "execution_count": 15, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:51.028211Z", "iopub.status.busy": "2024-04-17T07:26:51.028120Z", "iopub.status.idle": "2024-04-17T07:26:51.272236Z", "shell.execute_reply": "2024-04-17T07:26:51.271840Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcountyfound namestatecentroidpositionlimit
01425447Dakota CountyDakota CountyNE[-96.5715826334556, 42.4019493162632][-96.7274482548237, 42.2765184938908, -96.3566...[-96.7274482548237, 42.2765184938908, -96.3566...
11826825Nevada CountyNevada CountyAR[-93.2913903139467, 33.6979349702597][-93.4838207066059, 33.4403765201569, -93.1042...[-93.4838207066059, 33.4403765201569, -93.1042...
\n", "
" ], "text/plain": [ " id county found name state \\\n", "0 1425447 Dakota County Dakota County NE \n", "1 1826825 Nevada County Nevada County AR \n", "\n", " centroid \\\n", "0 [-96.5715826334556, 42.4019493162632] \n", "1 [-93.2913903139467, 33.6979349702597] \n", "\n", " position \\\n", "0 [-96.7274482548237, 42.2765184938908, -96.3566... \n", "1 [-93.4838207066059, 33.4403765201569, -93.1042... \n", "\n", " limit \n", "0 [-96.7274482548237, 42.2765184938908, -96.3566... \n", "1 [-93.4838207066059, 33.4403765201569, -93.1042... " ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# counties and states can be combined with scope. scope acts as a top level parent.\n", "geocode_counties(['Dakota County', 'Nevada County']).states(['NE', 'AR']).scope('USA').get_geocodes()" ] }, { "cell_type": "code", "execution_count": 16, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:51.273520Z", "iopub.status.busy": "2024-04-17T07:26:51.273429Z", "iopub.status.idle": "2024-04-17T07:26:51.275636Z", "shell.execute_reply": "2024-04-17T07:26:51.275441Z" } }, "outputs": [ { "data": { "text/markdown": [ "Invalid request: countries and scope can't be used simultaneously" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# scope can't be combined with countries - geocoding won't try to guess what level is it\n", "run_catching(\n", " lambda: geocode_counties('Nevada County').countries('usa').scope('Arizona').get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 17, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:51.276859Z", "iopub.status.busy": "2024-04-17T07:26:51.276715Z", "iopub.status.idle": "2024-04-17T07:26:51.278444Z", "shell.execute_reply": "2024-04-17T07:26:51.278282Z" } }, "outputs": [ { "data": { "text/markdown": [ "Invalid request: countries count(1) != names count(2)" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Parents and names should have same length\n", "run_catching(\n", " lambda: geocode_states(['florida', 'rivera']).countries('uruguay').get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 18, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:51.279574Z", "iopub.status.busy": "2024-04-17T07:26:51.279463Z", "iopub.status.idle": "2024-04-17T07:26:51.507886Z", "shell.execute_reply": "2024-04-17T07:26:51.507578Z" } }, "outputs": [ { "data": { "text/markdown": [ "Invalid request: countries count(1) != names count(2)" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Same for Geocoder\n", "countries = geocode_countries('uruguay')\n", "run_catching(\n", " lambda: geocode_states(['florida', 'rivera']).countries(countries).get_geocodes()\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Ignoring an ambiguity" ] }, { "cell_type": "code", "execution_count": 19, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:51.509179Z", "iopub.status.busy": "2024-04-17T07:26:51.509096Z", "iopub.status.idle": "2024-04-17T07:26:51.750556Z", "shell.execute_reply": "2024-04-17T07:26:51.750200Z" } }, "outputs": [ { "data": { "text/markdown": [ "Multiple objects (15) were found for warwick:\n", "- Warwick (United States, Georgia, Worth County)\n", "- Warwick (United States, New York, Orange County)\n", "- Warwick (United Kingdom, England, West Midlands, Warwickshire)\n", "- Warwick (United States, North Dakota, Benson County)\n", "- Warwick (United States, Oklahoma, Lincoln County)\n", "- Warwick (Canada, Ontario, Southwestern Ontario, Lambton County)\n", "- Warwick (United States, Massachusetts, Franklin County)\n", "- Warwick (United States, Rhode Island, Kent County)\n", "- Warwick (Canada, Arthabaska, Québec, Centre-du-Québec)\n", "- Warwick (Australia, Queensland)\n", "Multiple objects (5) were found for worcester:\n", "- Worcester (United States, Vermont, Washington County)\n", "- Worcester (United Kingdom, England, West Midlands, Worcestershire)\n", "- Worcester (South Africa, Western Cape, Cape Winelands District Municipality)\n", "- Worcester (United States, Massachusetts, Worcester County)\n", "- Worcester Township (United States, Pennsylvania, Montgomery County)\n", "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Ambiguous result generates an error:\n", "run_catching(\n", " lambda: geocode_cities(['warwick', 'worcester']).get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 20, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:51.751818Z", "iopub.status.busy": "2024-04-17T07:26:51.751706Z", "iopub.status.idle": "2024-04-17T07:26:51.991108Z", "shell.execute_reply": "2024-04-17T07:26:51.990665Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
0119776warwickWarwick[-83.9205776783726, 31.8303624540567][-83.9291015267372, 31.8222776055336, -83.9120...[-83.9291015267372, 31.8222776055336, -83.9120...
1176086warwickWarwick[-74.3590787617065, 41.2538411468267][-74.374563395977, 41.2334154546261, -74.33202...[-74.374563395977, 41.2334154546261, -74.33202...
2176448warwickWarwick[-1.58227695103754, 52.3015402257442][-1.78017809987068, 52.2137045860291, -1.40608...[-1.78017809987068, 52.2137045860291, -1.40608...
3181594warwickWarwick[-98.7057320814883, 47.8541030734777][-98.7164886295795, 47.8475135564804, -98.6948...[-98.7164886295795, 47.8475135564804, -98.6948...
4184249warwickWarwick[-96.9995924696813, 35.6883452832699][-97.0261216163635, 35.6740544736385, -96.9776...[-97.0261216163635, 35.6740544736385, -96.9776...
54072420warwickWarwick[-81.8960721893947, 43.0157359689474][-82.0060113072395, 42.9303230345249, -81.7887...[-82.0060113072395, 42.9303230345249, -81.7887...
6158818247warwickWarwick[-72.3365538645007, 42.667919844389][-72.4120393395424, 42.6094262301922, -72.2719...[-72.4120393395424, 42.6094262301922, -72.2719...
7158863860warwickWarwick[-71.4332938210472, 41.715542525053][-71.5189133584499, 41.6628210246563, -71.3564...[-71.5189133584499, 41.6293966770172, -71.3564...
8159726256warwickWarwick[-72.0051031618881, 45.952380001545][-72.0792764425278, 45.8764761686325, -71.9089...[-72.0792764425278, 45.8764761686325, -71.9089...
91817489924warwickWarwick[152.032703831792, -28.2163204997778][152.023720443249, -28.224236369133, 152.04168...[152.023720443249, -28.224236369133, 152.04168...
103049373warwickWarwick Township[-75.757813608352, 40.1801763474941][-75.8212745189667, 40.1465494930744, -75.6930...[-75.8212745189667, 40.1465494930744, -75.6930...
113521480warwickWarwick Township[-75.0764330968138, 40.2491855621338][-75.1225188374519, 40.2152167260647, -75.0345...[-75.1225188374519, 40.2152167260647, -75.0345...
129244563warwickWarwick Mountain[-63.3714760496144, 45.5978938937187][-63.4091444313526, 45.5644172430038, -63.3474...[-63.4091444313526, 45.5644172430038, -63.3474...
13158903676warwickWest Warwick[-71.5257788638961, 41.6969098895788][-71.5342850983143, 41.6620793938637, -71.4839...[-71.5342850983143, 41.6620793938637, -71.4839...
147997266warwickSainte-Élizabeth-de-Warwick[-72.1010115992802, 45.9195195883512][-72.1493585407734, 45.8681344985962, -72.0435...[-72.1493585407734, 45.8681344985962, -72.0435...
158898137worcesterWorcester[-72.5724501055639, 44.4132962822914][-72.6543393731117, 44.3454243242741, -72.4935...[-72.6543393731117, 44.3454243242741, -72.4935...
1620971097worcesterWorcester[-2.2095610731112, 52.1965283900499][-2.2632023692131, 52.1616362035275, -2.157303...[-2.2632023692131, 52.1616362035275, -2.157303...
1730670038worcesterWorcester[19.4459268450737, -33.6462374031544][19.4369441270828, -33.6537154018879, 19.45490...[19.4369441270828, -33.6537154018879, 19.45490...
18158851900worcesterWorcester[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
193076291worcesterWorcester Township[-75.3438698875367, 40.1926231384277][-75.4107637703419, 40.1558580994606, -75.2932...[-75.4107637703419, 40.1558580994606, -75.2932...
\n", "
" ], "text/plain": [ " id city found name \\\n", "0 119776 warwick Warwick \n", "1 176086 warwick Warwick \n", "2 176448 warwick Warwick \n", "3 181594 warwick Warwick \n", "4 184249 warwick Warwick \n", "5 4072420 warwick Warwick \n", "6 158818247 warwick Warwick \n", "7 158863860 warwick Warwick \n", "8 159726256 warwick Warwick \n", "9 1817489924 warwick Warwick \n", "10 3049373 warwick Warwick Township \n", "11 3521480 warwick Warwick Township \n", "12 9244563 warwick Warwick Mountain \n", "13 158903676 warwick West Warwick \n", "14 7997266 warwick Sainte-Élizabeth-de-Warwick \n", "15 8898137 worcester Worcester \n", "16 20971097 worcester Worcester \n", "17 30670038 worcester Worcester \n", "18 158851900 worcester Worcester \n", "19 3076291 worcester Worcester Township \n", "\n", " centroid \\\n", "0 [-83.9205776783726, 31.8303624540567] \n", "1 [-74.3590787617065, 41.2538411468267] \n", "2 [-1.58227695103754, 52.3015402257442] \n", "3 [-98.7057320814883, 47.8541030734777] \n", "4 [-96.9995924696813, 35.6883452832699] \n", "5 [-81.8960721893947, 43.0157359689474] \n", "6 [-72.3365538645007, 42.667919844389] \n", "7 [-71.4332938210472, 41.715542525053] \n", "8 [-72.0051031618881, 45.952380001545] \n", "9 [152.032703831792, -28.2163204997778] \n", "10 [-75.757813608352, 40.1801763474941] \n", "11 [-75.0764330968138, 40.2491855621338] \n", "12 [-63.3714760496144, 45.5978938937187] \n", "13 [-71.5257788638961, 41.6969098895788] \n", "14 [-72.1010115992802, 45.9195195883512] \n", "15 [-72.5724501055639, 44.4132962822914] \n", "16 [-2.2095610731112, 52.1965283900499] \n", "17 [19.4459268450737, -33.6462374031544] \n", "18 [-71.8154652712922, 42.2678737342358] \n", "19 [-75.3438698875367, 40.1926231384277] \n", "\n", " position \\\n", "0 [-83.9291015267372, 31.8222776055336, -83.9120... \n", "1 [-74.374563395977, 41.2334154546261, -74.33202... \n", "2 [-1.78017809987068, 52.2137045860291, -1.40608... \n", "3 [-98.7164886295795, 47.8475135564804, -98.6948... \n", "4 [-97.0261216163635, 35.6740544736385, -96.9776... \n", "5 [-82.0060113072395, 42.9303230345249, -81.7887... \n", "6 [-72.4120393395424, 42.6094262301922, -72.2719... \n", "7 [-71.5189133584499, 41.6628210246563, -71.3564... \n", "8 [-72.0792764425278, 45.8764761686325, -71.9089... \n", "9 [152.023720443249, -28.224236369133, 152.04168... \n", "10 [-75.8212745189667, 40.1465494930744, -75.6930... \n", "11 [-75.1225188374519, 40.2152167260647, -75.0345... \n", "12 [-63.4091444313526, 45.5644172430038, -63.3474... \n", "13 [-71.5342850983143, 41.6620793938637, -71.4839... \n", "14 [-72.1493585407734, 45.8681344985962, -72.0435... \n", "15 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "16 [-2.2632023692131, 52.1616362035275, -2.157303... \n", "17 [19.4369441270828, -33.6537154018879, 19.45490... \n", "18 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "19 [-75.4107637703419, 40.1558580994606, -75.2932... \n", "\n", " limit \n", "0 [-83.9291015267372, 31.8222776055336, -83.9120... \n", "1 [-74.374563395977, 41.2334154546261, -74.33202... \n", "2 [-1.78017809987068, 52.2137045860291, -1.40608... \n", "3 [-98.7164886295795, 47.8475135564804, -98.6948... \n", "4 [-97.0261216163635, 35.6740544736385, -96.9776... \n", "5 [-82.0060113072395, 42.9303230345249, -81.7887... \n", "6 [-72.4120393395424, 42.6094262301922, -72.2719... \n", "7 [-71.5189133584499, 41.6293966770172, -71.3564... \n", "8 [-72.0792764425278, 45.8764761686325, -71.9089... \n", "9 [152.023720443249, -28.224236369133, 152.04168... \n", "10 [-75.8212745189667, 40.1465494930744, -75.6930... \n", "11 [-75.1225188374519, 40.2152167260647, -75.0345... \n", "12 [-63.4091444313526, 45.5644172430038, -63.3474... \n", "13 [-71.5342850983143, 41.6620793938637, -71.4839... \n", "14 [-72.1493585407734, 45.8681344985962, -72.0435... \n", "15 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "16 [-2.2632023692131, 52.1616362035275, -2.157303... \n", "17 [19.4369441270828, -33.6537154018879, 19.45490... \n", "18 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "19 [-75.4107637703419, 40.1558580994606, -75.2932... " ] }, "execution_count": 20, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Ambiguous result can be converted to a matching result (e.g., for drawing on a map)\n", "geocode_cities(['warwick', 'worcester']).allow_ambiguous().get_geocodes()" ] }, { "cell_type": "code", "execution_count": 21, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:51.992190Z", "iopub.status.busy": "2024-04-17T07:26:51.992110Z", "iopub.status.idle": "2024-04-17T07:26:52.458075Z", "shell.execute_reply": "2024-04-17T07:26:52.457762Z" } }, "outputs": [ { "data": { "text/markdown": [ "No objects were found for foo.\n", "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/markdown": [ "Region is not found: foo" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Missing name gives an error\n", "run_catching(\n", " lambda: geocode_cities(names=['paris', 'worcester', 'foo']).get_geocodes()\n", ")\n", "\n", "# Missing parent also gives an error\n", "run_catching(\n", " lambda: geocode_cities('paris').countries('foo').get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 22, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:52.459153Z", "iopub.status.busy": "2024-04-17T07:26:52.459076Z", "iopub.status.idle": "2024-04-17T07:26:52.928734Z", "shell.execute_reply": "2024-04-17T07:26:52.928411Z" } }, "outputs": [ { "data": { "text/markdown": [ "Multiple objects (5) were found for worcester:\n", "- Worcester (United States, Vermont, Washington County)\n", "- Worcester (United Kingdom, England, West Midlands, Worcestershire)\n", "- Worcester (South Africa, Western Cape, Cape Winelands District Municipality)\n", "- Worcester (United States, Massachusetts, Worcester County)\n", "- Worcester Township (United States, Pennsylvania, Montgomery County)\n", "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/markdown": [ "Multiple objects (5) were found for worcester:\n", "- Worcester (United States, Vermont, Washington County)\n", "- Worcester (United Kingdom, England, West Midlands, Worcestershire)\n", "- Worcester (South Africa, Western Cape, Cape Winelands District Municipality)\n", "- Worcester (United States, Massachusetts, Worcester County)\n", "- Worcester Township (United States, Pennsylvania, Montgomery County)\n", "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# ignore_not_found() - ingore unknown names, keep everything else, including ambiguous names\n", "run_catching(\n", " lambda: geocode_cities(['paris', 'worcester', 'foo']).ignore_not_found().get_geocodes()\n", ")\n", "\n", "# Missing parent also gives an error\n", "run_catching(\n", " lambda: geocode_cities(['paris', 'worcester']).countries(['foo', None]).ignore_not_found().get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 23, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:52.929912Z", "iopub.status.busy": "2024-04-17T07:26:52.929838Z", "iopub.status.idle": "2024-04-17T07:26:53.400018Z", "shell.execute_reply": "2024-04-17T07:26:53.399610Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecountrycentroidpositionlimit
017807753parisParisfrance[2.32002815231681, 48.8587861508131][2.22412258386612, 48.8155750930309, 2.4697606...[2.22412258386612, 48.8155750930309, 2.4697606...
\n", "
" ], "text/plain": [ " id city found name country centroid \\\n", "0 17807753 paris Paris france [2.32002815231681, 48.8587861508131] \n", "\n", " position \\\n", "0 [2.22412258386612, 48.8155750930309, 2.4697606... \n", "\n", " limit \n", "0 [2.22412258386612, 48.8155750930309, 2.4697606... " ] }, "execution_count": 23, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# ignore_all_errors() - keep only exactly matched names\n", "geocode_cities(['paris', 'worcester', 'foo']).ignore_all_errors().get_geocodes()\n", "\n", "geocode_cities(['paris', 'worcester']).countries(['france', 'foo']).ignore_all_errors().get_geocodes()" ] }, { "cell_type": "code", "execution_count": 24, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:53.401215Z", "iopub.status.busy": "2024-04-17T07:26:53.401129Z", "iopub.status.idle": "2024-04-17T07:26:53.642465Z", "shell.execute_reply": "2024-04-17T07:26:53.642299Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
017807753parisParis[2.32002815231681, 48.8587861508131][2.22412258386612, 48.8155750930309, 2.4697606...[2.22412258386612, 48.8155750930309, 2.4697606...
18898137worcesterWorcester[-72.5724501055639, 44.4132962822914][-72.6543393731117, 44.3454243242741, -72.4935...[-72.6543393731117, 44.3454243242741, -72.4935...
220971097worcesterWorcester[-2.2095610731112, 52.1965283900499][-2.2632023692131, 52.1616362035275, -2.157303...[-2.2632023692131, 52.1616362035275, -2.157303...
330670038worcesterWorcester[19.4459268450737, -33.6462374031544][19.4369441270828, -33.6537154018879, 19.45490...[19.4369441270828, -33.6537154018879, 19.45490...
4158851900worcesterWorcester[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
53076291worcesterWorcester Township[-75.3438698875367, 40.1926231384277][-75.4107637703419, 40.1558580994606, -75.2932...[-75.4107637703419, 40.1558580994606, -75.2932...
\n", "
" ], "text/plain": [ " id city found name \\\n", "0 17807753 paris Paris \n", "1 8898137 worcester Worcester \n", "2 20971097 worcester Worcester \n", "3 30670038 worcester Worcester \n", "4 158851900 worcester Worcester \n", "5 3076291 worcester Worcester Township \n", "\n", " centroid \\\n", "0 [2.32002815231681, 48.8587861508131] \n", "1 [-72.5724501055639, 44.4132962822914] \n", "2 [-2.2095610731112, 52.1965283900499] \n", "3 [19.4459268450737, -33.6462374031544] \n", "4 [-71.8154652712922, 42.2678737342358] \n", "5 [-75.3438698875367, 40.1926231384277] \n", "\n", " position \\\n", "0 [2.22412258386612, 48.8155750930309, 2.4697606... \n", "1 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "2 [-2.2632023692131, 52.1616362035275, -2.157303... \n", "3 [19.4369441270828, -33.6537154018879, 19.45490... \n", "4 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "5 [-75.4107637703419, 40.1558580994606, -75.2932... \n", "\n", " limit \n", "0 [2.22412258386612, 48.8155750930309, 2.4697606... \n", "1 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "2 [-2.2632023692131, 52.1616362035275, -2.157303... \n", "3 [19.4369441270828, -33.6537154018879, 19.45490... \n", "4 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "5 [-75.4107637703419, 40.1558580994606, -75.2932... " ] }, "execution_count": 24, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# ignore_not_found() + allow_ambiguous() - see all ambiguous names without \"not found\" error\n", "geocode_cities(['paris', 'worcester', 'foo']).ignore_not_found().allow_ambiguous().get_geocodes()" ] }, { "cell_type": "code", "execution_count": 25, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:53.644054Z", "iopub.status.busy": "2024-04-17T07:26:53.643960Z", "iopub.status.idle": "2024-04-17T07:26:53.880973Z", "shell.execute_reply": "2024-04-17T07:26:53.880629Z" } }, "outputs": [ { "data": { "text/markdown": [ "No objects were found for foo, foo4, foo5, foo6, foo7, foo8, foo9, foo10, foo11, foo12 and (3) more.\n", "" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# List only 10 first distinct not found names\n", "run_catching(\n", " lambda: geocode_cities(['foo', 'foo', 'foo', 'foo4', 'foo5', 'foo6', 'foo7', 'foo8', 'foo9', 'foo10', 'foo11', 'foo12', 'foo13', 'foo14', 'foo15']).get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 26, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:53.882249Z", "iopub.status.busy": "2024-04-17T07:26:53.882132Z", "iopub.status.idle": "2024-04-17T07:26:54.108033Z", "shell.execute_reply": "2024-04-17T07:26:54.107840Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
\n", "
" ], "text/plain": [ "Empty DataFrame\n", "Columns: [id, city, found name, centroid, position, limit]\n", "Index: []" ] }, "execution_count": 26, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Empty DataFrame if no matching names left\n", "geocode_cities('worcester').ignore_all_errors().get_geocodes()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### `where()` function" ] }, { "cell_type": "code", "execution_count": 27, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:54.109140Z", "iopub.status.busy": "2024-04-17T07:26:54.109037Z", "iopub.status.idle": "2024-04-17T07:26:54.810703Z", "shell.execute_reply": "2024-04-17T07:26:54.810367Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
0158851900worcesterWorcester[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
\n", "
" ], "text/plain": [ " id city found name centroid \\\n", "0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] \n", "\n", " position \\\n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "\n", " limit \n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... " ] }, "execution_count": 27, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Take object closest to a place.\n", "boston = geocode_cities('boston')\n", "geocode_cities('worcester').where('worcester', closest_to=boston).get_geocodes()" ] }, { "cell_type": "code", "execution_count": 28, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:54.811856Z", "iopub.status.busy": "2024-04-17T07:26:54.811759Z", "iopub.status.idle": "2024-04-17T07:26:55.293383Z", "shell.execute_reply": "2024-04-17T07:26:55.293179Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
0158851900worcesterWorcester[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
\n", "
" ], "text/plain": [ " id city found name centroid \\\n", "0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] \n", "\n", " position \\\n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "\n", " limit \n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... " ] }, "execution_count": 28, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Take object closest to a coordinate.\n", "boston_coord = boston.get_centroids().geometry[0]\n", "geocode_cities('worcester').where('worcester', closest_to=boston_coord).get_geocodes()" ] }, { "cell_type": "code", "execution_count": 29, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:55.294566Z", "iopub.status.busy": "2024-04-17T07:26:55.294470Z", "iopub.status.idle": "2024-04-17T07:26:55.519573Z", "shell.execute_reply": "2024-04-17T07:26:55.519293Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
0158851900worcesterWorcester[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
\n", "
" ], "text/plain": [ " id city found name centroid \\\n", "0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] \n", "\n", " position \\\n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "\n", " limit \n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... " ] }, "execution_count": 29, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Or take object within rectangular area\n", "geocode_cities('worcester')\\\n", " .where('worcester', scope=shapely.geometry.box(-71.00, 42.00, -72.00, 43.00))\\\n", " .get_geocodes()" ] }, { "cell_type": "code", "execution_count": 30, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:55.520618Z", "iopub.status.busy": "2024-04-17T07:26:55.520521Z", "iopub.status.idle": "2024-04-17T07:26:55.985129Z", "shell.execute_reply": "2024-04-17T07:26:55.984938Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
0158851900worcesterWorcester[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
\n", "
" ], "text/plain": [ " id city found name centroid \\\n", "0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] \n", "\n", " position \\\n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "\n", " limit \n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... " ] }, "execution_count": 30, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Or by defining a query scope. In this case name from the scope will not go into the result DataFrame\n", "massachusetts = geocode_states('massachusetts')\n", "geocode_cities('worcester').where('worcester', scope=massachusetts).get_geocodes()" ] }, { "cell_type": "code", "execution_count": 31, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:55.986217Z", "iopub.status.busy": "2024-04-17T07:26:55.986110Z", "iopub.status.idle": "2024-04-17T07:26:56.212528Z", "shell.execute_reply": "2024-04-17T07:26:56.212248Z" }, "scrolled": true }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
0158851900worcesterWorcester[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
\n", "
" ], "text/plain": [ " id city found name centroid \\\n", "0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] \n", "\n", " position \\\n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "\n", " limit \n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... " ] }, "execution_count": 31, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Query scope also can be a string\n", "geocode_cities('worcester').where('worcester', scope='massachusetts').get_geocodes()" ] }, { "cell_type": "code", "execution_count": 32, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:56.213612Z", "iopub.status.busy": "2024-04-17T07:26:56.213511Z", "iopub.status.idle": "2024-04-17T07:26:56.686831Z", "shell.execute_reply": "2024-04-17T07:26:56.686333Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecountrycentroidpositionlimit
0158851900worcesterWorcesterUSA[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
120971097worcesterWorcesterUnited Kingdom[-2.2095610731112, 52.1965283900499][-2.2632023692131, 52.1616362035275, -2.157303...[-2.2632023692131, 52.1616362035275, -2.157303...
\n", "
" ], "text/plain": [ " id city found name country \\\n", "0 158851900 worcester Worcester USA \n", "1 20971097 worcester Worcester United Kingdom \n", "\n", " centroid \\\n", "0 [-71.8154652712922, 42.2678737342358] \n", "1 [-2.2095610731112, 52.1965283900499] \n", "\n", " position \\\n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "1 [-2.2632023692131, 52.1616362035275, -2.157303... \n", "\n", " limit \n", "0 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "1 [-2.2632023692131, 52.1616362035275, -2.157303... " ] }, "execution_count": 32, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Query scope overrides parents while keeping parents in a result dataframe.\n", "worcester_county=geocode_counties('Worcester County').states('massachusetts').countries('usa')\n", "\n", "geocode_cities(['worcester', 'worcester'])\\\n", " .countries(['USA', 'United Kingdom'])\\\n", " .where('worcester', country='USA', scope=worcester_county)\\\n", " .get_geocodes()" ] }, { "cell_type": "code", "execution_count": 33, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:56.687951Z", "iopub.status.busy": "2024-04-17T07:26:56.687845Z", "iopub.status.idle": "2024-04-17T07:26:56.939394Z", "shell.execute_reply": "2024-04-17T07:26:56.938965Z" } }, "outputs": [ { "data": { "text/markdown": [ "'scope' has 2 entries, but expected to have exactly 1" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Query scope should contain single object\n", "countries = geocode_countries(['usa', 'uruguay'])\n", "run_catching(\n", " lambda: geocode_states('florida').where('florida', scope=countries).get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 34, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:56.940444Z", "iopub.status.busy": "2024-04-17T07:26:56.940359Z", "iopub.status.idle": "2024-04-17T07:26:56.942538Z", "shell.execute_reply": "2024-04-17T07:26:56.942370Z" } }, "outputs": [ { "data": { "text/markdown": [ "worcester(county=worcester county, state=iowa, country=USA) is not found in names" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# NB: Parent is used only for searching exact row in request. \n", "# It doesn't modify any parent (neither existing or empty).\n", "run_catching(\n", " lambda: geocode_cities('worcester')\\\n", " .countries('USA')\\\n", " .where('worcester', country='USA', state='iowa', county='worcester county')\\\n", " .get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 35, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:56.943524Z", "iopub.status.busy": "2024-04-17T07:26:56.943448Z", "iopub.status.idle": "2024-04-17T07:26:57.157092Z", "shell.execute_reply": "2024-04-17T07:26:57.156777Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namecentroidpositionlimit
0158863860warwickWarwick[-71.4332938210472, 41.715542525053][-71.5189133584499, 41.6628210246563, -71.3564...[-71.5189133584499, 41.6293966770172, -71.3564...
1158903676warwickWest Warwick[-71.5257788638961, 41.6969098895788][-71.5342850983143, 41.6620793938637, -71.4839...[-71.5342850983143, 41.6620793938637, -71.4839...
\n", "
" ], "text/plain": [ " id city found name centroid \\\n", "0 158863860 warwick Warwick [-71.4332938210472, 41.715542525053] \n", "1 158903676 warwick West Warwick [-71.5257788638961, 41.6969098895788] \n", "\n", " position \\\n", "0 [-71.5189133584499, 41.6628210246563, -71.3564... \n", "1 [-71.5342850983143, 41.6620793938637, -71.4839... \n", "\n", " limit \n", "0 [-71.5189133584499, 41.6293966770172, -71.3564... \n", "1 [-71.5342850983143, 41.6620793938637, -71.4839... " ] }, "execution_count": 35, "metadata": {}, "output_type": "execute_result" } ], "source": [ "geocode_cities('warwick') \\\n", " .where('warwick', scope=shapely.geometry.box(-72, 41.5, -71, 42)) \\\n", " .allow_ambiguous() \\\n", " .get_geocodes()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Error handling" ] }, { "cell_type": "code", "execution_count": 36, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:57.158303Z", "iopub.status.busy": "2024-04-17T07:26:57.158205Z", "iopub.status.idle": "2024-04-17T07:26:57.388013Z", "shell.execute_reply": "2024-04-17T07:26:57.387720Z" } }, "outputs": [ { "data": { "text/markdown": [ "Region is not found: foo" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Failed to find parent\n", "run_catching(\n", " lambda: geocode_states('florida').countries('foo').get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 37, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:57.389096Z", "iopub.status.busy": "2024-04-17T07:26:57.388995Z", "iopub.status.idle": "2024-04-17T07:26:57.624270Z", "shell.execute_reply": "2024-04-17T07:26:57.624080Z" } }, "outputs": [ { "data": { "text/markdown": [ "Region is not found: worcester county" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# ambiguous parent - Worcester County. Better message required.\n", "run_catching(\n", " lambda : geocode_cities('worcester').counties('worcester county').scope('usa').get_geocodes()\n", ")" ] }, { "cell_type": "code", "execution_count": 38, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:57.625393Z", "iopub.status.busy": "2024-04-17T07:26:57.625300Z", "iopub.status.idle": "2024-04-17T07:26:57.836839Z", "shell.execute_reply": "2024-04-17T07:26:57.836574Z" } }, "outputs": [ { "data": { "text/markdown": [ "Invalid level for request with us-48. Should be STATE, but was COUNTY." ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# No us-48 at non-state level\n", "run_catching(\n", " lambda: geocode_counties('us-48').get_geocodes()\n", ")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Geocoding and geoms" ] }, { "cell_type": "code", "execution_count": 39, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:57.837888Z", "iopub.status.busy": "2024-04-17T07:26:57.837810Z", "iopub.status.idle": "2024-04-17T07:26:57.839615Z", "shell.execute_reply": "2024-04-17T07:26:57.839441Z" } }, "outputs": [], "source": [ "cities = geocode_cities(['boston', 'new york'])\n", "p = ggplot() + ggsize(300, 200)" ] }, { "cell_type": "code", "execution_count": 40, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:57.840604Z", "iopub.status.busy": "2024-04-17T07:26:57.840496Z", "iopub.status.idle": "2024-04-17T07:26:58.825628Z", "shell.execute_reply": "2024-04-17T07:26:58.825320Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 40, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# geocoder object can be used as map parameter to simply display a geometry\n", "plots = GGBunch()\n", "plots.add_plot(p + geom_map(map=cities, fill='gray') + ggtitle('geom_map()'), 0, 0)\n", "plots.add_plot(p + geom_rect(map=cities, fill='gray') + ggtitle('geom_rect()'), 300, 0)\n", "plots.add_plot(p + geom_point(map=cities) + ggtitle('geom_point()'), 600, 0)\n", "plots" ] }, { "cell_type": "code", "execution_count": 41, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:26:58.826679Z", "iopub.status.busy": "2024-04-17T07:26:58.826596Z", "iopub.status.idle": "2024-04-17T07:27:00.289016Z", "shell.execute_reply": "2024-04-17T07:27:00.288638Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 41, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# GeoDataFrame also can be also as map parameter to display a geometry - syntax is the same as with Geocoder.\n", "# It is usefull for optimisation - geocoder caches geocodes, but doesn't cache geometries.\n", "centroids = cities.get_centroids()\n", "bboxes = cities.get_limits()\n", "boundaries = cities.get_boundaries()\n", "p = ggplot() + ggsize(300, 200)\n", "plots = GGBunch()\n", "plots.add_plot(p + geom_map(map=cities.get_boundaries(), fill='gray') + ggtitle('geom_map()'), 0, 0)\n", "plots.add_plot(p + geom_rect(map=cities.get_limits(), fill='gray') + ggtitle('geom_rect()'), 300, 0)\n", "plots.add_plot(p + geom_point(map=cities.get_centroids()) + ggtitle('geom_point()'), 600, 0)\n", "plots" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### map and map_join" ] }, { "cell_type": "code", "execution_count": 42, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:00.290353Z", "iopub.status.busy": "2024-04-17T07:27:00.290235Z", "iopub.status.idle": "2024-04-17T07:27:00.539343Z", "shell.execute_reply": "2024-04-17T07:27:00.539021Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
idcityfound namestatecentroidpositionlimit
0158809705bostonBostonmassachusetts[-71.0884755326693, 42.3110405355692][-71.1912493407726, 42.2279115021229, -71.0096...[-71.1912493407726, 42.2279115021229, -70.9244...
161785451new yorkNew Yorknew york[-73.8673749469137, 40.6847005337477][-74.0417455136776, 40.5700233578682, -73.7001...[-74.2556785047054, 40.4960802197456, -73.7001...
28898137worcesterWorcestervermont[-72.5724501055639, 44.4132962822914][-72.6543393731117, 44.3454243242741, -72.4935...[-72.6543393731117, 44.3454243242741, -72.4935...
3158851900worcesterWorcestermassachusetts[-71.8154652712922, 42.2678737342358][-71.8840424716473, 42.2100399434566, -71.7312...[-71.8840424716473, 42.2100399434566, -71.7312...
\n", "
" ], "text/plain": [ " id city found name state \\\n", "0 158809705 boston Boston massachusetts \n", "1 61785451 new york New York new york \n", "2 8898137 worcester Worcester vermont \n", "3 158851900 worcester Worcester massachusetts \n", "\n", " centroid \\\n", "0 [-71.0884755326693, 42.3110405355692] \n", "1 [-73.8673749469137, 40.6847005337477] \n", "2 [-72.5724501055639, 44.4132962822914] \n", "3 [-71.8154652712922, 42.2678737342358] \n", "\n", " position \\\n", "0 [-71.1912493407726, 42.2279115021229, -71.0096... \n", "1 [-74.0417455136776, 40.5700233578682, -73.7001... \n", "2 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "3 [-71.8840424716473, 42.2100399434566, -71.7312... \n", "\n", " limit \n", "0 [-71.1912493407726, 42.2279115021229, -70.9244... \n", "1 [-74.2556785047054, 40.4960802197456, -73.7001... \n", "2 [-72.6543393731117, 44.3454243242741, -72.4935... \n", "3 [-71.8840424716473, 42.2100399434566, -71.7312... " ] }, "execution_count": 42, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# map_join allows to join data and geometry.\n", "# To make this exmaple more complex a demo data contains cities with same name (Worcester).\n", "# Also there is a city and state with same name (New York). \n", "# All names in DataFrame are in lower case to distinct user input from geocoding result.\n", "import pandas\n", "d = pandas.DataFrame({\n", " 'City_Name': ['boston', 'new york', 'worcester', 'worcester'],\n", " 'State_Name': ['massachusetts', 'new york', 'vermont', 'massachusetts'],\n", " 'mean': [523, 556, 600, 533]\n", "})\n", "\n", "geocoder = geocode_cities(d.City_Name).states(d.State_Name)\n", "geocoder.get_geocodes()" ] }, { "cell_type": "code", "execution_count": 43, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:00.540451Z", "iopub.status.busy": "2024-04-17T07:27:00.540366Z", "iopub.status.idle": "2024-04-17T07:27:01.048278Z", "shell.execute_reply": "2024-04-17T07:27:01.048066Z" } }, "outputs": [], "source": [ "# Cache boundaries\n", "background_states = geocode_states(['massachusetts', 'new york', 'vermont']).inc_res().get_boundaries()\n", "\n", "def draw_plot(map, map_join):\n", " return ggplot() + \\\n", " geom_map(map=background_states) + \\\n", " geom_point(aes(size='mean', color='City_Name'), data=d, map=map, map_join=map_join) + \\\n", " theme_void()" ] }, { "cell_type": "code", "execution_count": 44, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:01.049608Z", "iopub.status.busy": "2024-04-17T07:27:01.049500Z", "iopub.status.idle": "2024-04-17T07:27:01.286056Z", "shell.execute_reply": "2024-04-17T07:27:01.285750Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 44, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Draw a GeoDataFrame with a data. \n", "# Names in GeoDataFrame from Geocoder are predefined: 'city', 'county', 'state', 'country'\n", "# Order of levels in map_join should match:\n", "draw_plot(map=geocoder.get_centroids(), map_join=[['City_Name', 'State_Name'], ['city', 'state']])\n", "\n", "# Note that Worcesters have proper position and data, but color is the same color. \n", "# To make the color distinct a new column with combination of city and state names can be used." ] }, { "cell_type": "code", "execution_count": 45, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:01.287288Z", "iopub.status.busy": "2024-04-17T07:27:01.287189Z", "iopub.status.idle": "2024-04-17T07:27:01.526556Z", "shell.execute_reply": "2024-04-17T07:27:01.526349Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 45, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# With Geocoder or GeoDataFrame returned by Geocoder we can omit generated map names.\n", "# Only data columns have to be defined. Map columns will be generated with the following order: \n", "# - city, county, state, country. \n", "# Not requested levels will be ommited.\n", "# Data columns should exactly follow this order.\n", "draw_plot(map=geocoder, map_join=[['City_Name', 'State_Name']])" ] }, { "cell_type": "code", "execution_count": 46, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:01.527726Z", "iopub.status.busy": "2024-04-17T07:27:01.527620Z", "iopub.status.idle": "2024-04-17T07:27:01.771282Z", "shell.execute_reply": "2024-04-17T07:27:01.770936Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 46, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Not following the order leads to an unexpected result: \n", "draw_plot(map=geocoder, map_join=[['State_Name', 'City_Name']])" ] }, { "cell_type": "code", "execution_count": 47, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:01.772520Z", "iopub.status.busy": "2024-04-17T07:27:01.772419Z", "iopub.status.idle": "2024-04-17T07:27:01.774444Z", "shell.execute_reply": "2024-04-17T07:27:01.774260Z" } }, "outputs": [], "source": [ "us48 = geocode_states('us-48').inc_res()\n", "p = ggplot() + \\\n", " theme_void() + theme(legend_position='none') + \\\n", " ggsize(600, 300)" ] }, { "cell_type": "code", "execution_count": 48, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:01.775406Z", "iopub.status.busy": "2024-04-17T07:27:01.775329Z", "iopub.status.idle": "2024-04-17T07:27:02.378962Z", "shell.execute_reply": "2024-04-17T07:27:02.378623Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 48, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Geocoder can be passed to a data parameter. In this case column 'found name' can be used for join and styling:\n", "p + geom_map(aes(fill='found name'), \n", " data=us48, \n", " map=us48, map_join='found name', \n", " tooltips=layer_tooltips().line('@{found name}'))" ] }, { "cell_type": "code", "execution_count": 49, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:02.380207Z", "iopub.status.busy": "2024-04-17T07:27:02.380102Z", "iopub.status.idle": "2024-04-17T07:27:02.771956Z", "shell.execute_reply": "2024-04-17T07:27:02.771760Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 49, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# With GeoDataFrame as data a plot spec is even more compact\n", "p + geom_map(aes(fill='found name'), data=us48.get_boundaries(), tooltips=layer_tooltips().line('@{found name}'))" ] }, { "cell_type": "code", "execution_count": 50, "metadata": { "execution": { "iopub.execute_input": "2024-04-17T07:27:02.773212Z", "iopub.status.busy": "2024-04-17T07:27:02.773111Z", "iopub.status.idle": "2024-04-17T07:27:03.140722Z", "shell.execute_reply": "2024-04-17T07:27:03.140523Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " " ], "text/plain": [ "" ] }, "execution_count": 50, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# map_join works fine even when data and map rows doesn't match\n", "\n", "# For the simplicity I'll re-use states from us-48. Names can be provided by user.\n", "import random\n", "random.seed(1)\n", "area_of_interest = us48.get_geocodes().state.tolist()\n", "length = 30\n", "mean_by_state = {\n", " 'State_Name': random.sample(area_of_interest, length),\n", " 'Mean_Value': random.sample(range(0, 500), length)\n", "}\n", "\n", "p + geom_map(\n", " aes(fill='Mean_Value'), \n", " data=mean_by_state, map=us48, \n", " map_join='State_Name', \n", " tooltips=layer_tooltips()\n", " .line('@{found name}')\n", " .line('mean:|@Mean_Value')\n", ")\n", "\n", "# Note the variable 'found name' that is used in tooltip. \n", "# Thanks to map_join this variable is available for tooltip processor." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.13" } }, "nbformat": 4, "nbformat_minor": 4 }