{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Geocoding Examples"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:53.435089Z",
"iopub.status.busy": "2026-01-27T17:08:53.434995Z",
"iopub.status.idle": "2026-01-27T17:08:53.437893Z",
"shell.execute_reply": "2026-01-27T17:08:53.437593Z"
}
},
"outputs": [],
"source": [
"from lets_plot import *"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:53.438869Z",
"iopub.status.busy": "2026-01-27T17:08:53.438791Z",
"iopub.status.idle": "2026-01-27T17:08:53.440613Z",
"shell.execute_reply": "2026-01-27T17:08:53.440379Z"
}
},
"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": "2026-01-27T17:08:53.453393Z",
"iopub.status.busy": "2026-01-27T17:08:53.453309Z",
"iopub.status.idle": "2026-01-27T17:08:53.493300Z",
"shell.execute_reply": "2026-01-27T17:08:53.492876Z"
}
},
"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": [
"from lets_plot.geo_data import *"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Sweden and Finland"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Create countries geocoder"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:53.494235Z",
"iopub.status.busy": "2026-01-27T17:08:53.494158Z",
"iopub.status.idle": "2026-01-27T17:08:53.707004Z",
"shell.execute_reply": "2026-01-27T17:08:53.706427Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" id | \n",
" country | \n",
" found name | \n",
" centroid | \n",
" position | \n",
" limit | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 54224 | \n",
" Finland | \n",
" Finland | \n",
" [27.5426266740774, 64.9500560760498] | \n",
" [20.5486419796944, 59.8079609870911, 31.586707... | \n",
" [19.3040004372597, 59.7582100331783, 31.586707... | \n",
"
\n",
" \n",
" | 1 | \n",
" 52822 | \n",
" Sweden | \n",
" Sweden | \n",
" [14.8960665316738, 62.1977656334639] | \n",
" [11.1130450665951, 55.3366836905479, 24.152978... | \n",
" [10.9653197228909, 55.3366836905479, 24.166640... | \n",
"
\n",
" \n",
"
\n",
"
"
],
"text/plain": [
" id country found name centroid \\\n",
"0 54224 Finland Finland [27.5426266740774, 64.9500560760498] \n",
"1 52822 Sweden Sweden [14.8960665316738, 62.1977656334639] \n",
"\n",
" position \\\n",
"0 [20.5486419796944, 59.8079609870911, 31.586707... \n",
"1 [11.1130450665951, 55.3366836905479, 24.152978... \n",
"\n",
" limit \n",
"0 [19.3040004372597, 59.7582100331783, 31.586707... \n",
"1 [10.9653197228909, 55.3366836905479, 24.166640... "
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"country_gcoder = geocode_countries(['Finland', 'Sweden'])\n",
"country_gcoder.get_geocodes()"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:53.708248Z",
"iopub.status.busy": "2026-01-27T17:08:53.708120Z",
"iopub.status.idle": "2026-01-27T17:08:53.710115Z",
"shell.execute_reply": "2026-01-27T17:08:53.709736Z"
}
},
"outputs": [],
"source": [
"map_options = theme_void() + coord_map()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Plot boundary polygons"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:53.711012Z",
"iopub.status.busy": "2026-01-27T17:08:53.710898Z",
"iopub.status.idle": "2026-01-27T17:08:53.965581Z",
"shell.execute_reply": "2026-01-27T17:08:53.965195Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"(ggplot() + \n",
" geom_polygon(aes(fill='found name'), \n",
" data=country_gcoder.get_boundaries(),\n",
" tooltips=layer_tooltips().line(\"^fill\"),\n",
" color=\"white\") +\n",
" map_options + \n",
" scale_fill_hue(name=\"Country\"))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Plot ploygons on interactive base-map\n",
"\n",
"Note: *nbviewer* won't load base-map tiles due to its CSP."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:53.966635Z",
"iopub.status.busy": "2026-01-27T17:08:53.966551Z",
"iopub.status.idle": "2026-01-27T17:08:54.186865Z",
"shell.execute_reply": "2026-01-27T17:08:54.186110Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"(ggplot() + geom_livemap() + \n",
" geom_polygon(aes(fill='found name'), \n",
" data=country_gcoder.get_boundaries(),\n",
" tooltips=layer_tooltips().line(\"^fill\"),\n",
" color=\"white\") +\n",
" scale_fill_hue(name=\"Country\"))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### The World"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Create countries geocoder"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:54.187860Z",
"iopub.status.busy": "2026-01-27T17:08:54.187776Z",
"iopub.status.idle": "2026-01-27T17:08:54.501510Z",
"shell.execute_reply": "2026-01-27T17:08:54.501127Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" id | \n",
" country | \n",
" found name | \n",
" centroid | \n",
" position | \n",
" limit | \n",
"
\n",
" \n",
" \n",
" \n",
" | 0 | \n",
" 9407 | \n",
" Andorra | \n",
" Andorra | \n",
" [1.58972340139334, 42.542395144701] | \n",
" [1.41357779502869, 42.4288237094879, 1.7866636... | \n",
" [1.41357779502869, 42.4288237094879, 1.7866636... | \n",
"
\n",
" \n",
" | 1 | \n",
" 14296 | \n",
" Slovakia | \n",
" Slovakia | \n",
" [19.6367939386235, 48.6726971715689] | \n",
" [16.8331897258759, 47.7314288914204, 22.565710... | \n",
" [16.8331897258759, 47.7314288914204, 22.565710... | \n",
"
\n",
" \n",
" | 2 | \n",
" 16239 | \n",
" Austria | \n",
" Austria | \n",
" [14.7548074169977, 47.6964113116264] | \n",
" [9.5307482779026, 46.3722757995129, 17.1607759... | \n",
" [9.5307482779026, 46.3722757995129, 17.1607759... | \n",
"
\n",
" \n",
"
\n",
"
"
],
"text/plain": [
" id country found name centroid \\\n",
"0 9407 Andorra Andorra [1.58972340139334, 42.542395144701] \n",
"1 14296 Slovakia Slovakia [19.6367939386235, 48.6726971715689] \n",
"2 16239 Austria Austria [14.7548074169977, 47.6964113116264] \n",
"\n",
" position \\\n",
"0 [1.41357779502869, 42.4288237094879, 1.7866636... \n",
"1 [16.8331897258759, 47.7314288914204, 22.565710... \n",
"2 [9.5307482779026, 46.3722757995129, 17.1607759... \n",
"\n",
" limit \n",
"0 [1.41357779502869, 42.4288237094879, 1.7866636... \n",
"1 [16.8331897258759, 47.7314288914204, 22.565710... \n",
"2 [9.5307482779026, 46.3722757995129, 17.1607759... "
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"world_gcoder = geocode_countries()\n",
"world_gcoder.get_geocodes().head(3)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### World choropleth"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:54.503005Z",
"iopub.status.busy": "2026-01-27T17:08:54.502920Z",
"iopub.status.idle": "2026-01-27T17:08:54.972090Z",
"shell.execute_reply": "2026-01-27T17:08:54.971605Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"(ggplot() + \n",
" geom_polygon(aes(fill='found name'), \n",
" data=world_gcoder.get_boundaries(), \n",
" color=\"white\", \n",
" tooltips=layer_tooltips().line(\"^fill\"),\n",
" show_legend=False) +\n",
" map_options +\n",
" scale_fill_brewer(name=\"Country\", palette=\"Dark2\") + \n",
" ggsize(900, 600))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### New York State and New York City"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:54.973491Z",
"iopub.status.busy": "2026-01-27T17:08:54.973415Z",
"iopub.status.idle": "2026-01-27T17:08:55.840375Z",
"shell.execute_reply": "2026-01-27T17:08:55.839785Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"(ggplot() + \n",
" geom_polygon(map=geocode_states(\"New York\"), fill=\"#01327A\") +\n",
" geom_polygon(map=geocode_cities(\"New York\"), fill=\"#F2C010\") +\n",
" map_options)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### The US states"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Create state geocoder for the US [48 contiguous states](https://en.wikipedia.org/wiki/Contiguous_United_States) (aka CONUS)"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:55.841788Z",
"iopub.status.busy": "2026-01-27T17:08:55.841711Z",
"iopub.status.idle": "2026-01-27T17:08:55.843124Z",
"shell.execute_reply": "2026-01-27T17:08:55.842923Z"
}
},
"outputs": [],
"source": [
"conus_gcoder = geocode_states('us-48').inc_res()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### The US choropleth"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:55.844299Z",
"iopub.status.busy": "2026-01-27T17:08:55.844215Z",
"iopub.status.idle": "2026-01-27T17:08:56.426453Z",
"shell.execute_reply": "2026-01-27T17:08:56.426094Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"conus_plot = (ggplot() +\n",
" geom_polygon(aes(fill='found name'), \n",
" data=conus_gcoder.get_boundaries(), \n",
" show_legend=False, \n",
" color=\"white\",\n",
" tooltips=layer_tooltips().line(\"^fill\")) +\n",
" map_options +\n",
" scale_fill_brewer(name=\"State\", palette=\"Dark2\") + \n",
" ggsize(900, 500))\n",
"conus_plot"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Add the states of Alaska and Hawaii"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:56.427739Z",
"iopub.status.busy": "2026-01-27T17:08:56.427663Z",
"iopub.status.idle": "2026-01-27T17:08:57.791640Z",
"shell.execute_reply": "2026-01-27T17:08:57.791073Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"alaska_plot = (ggplot() + geom_map(map=geocode_states('alaska'), \n",
" fill=\"light-blue\", \n",
" color=\"#172048\",\n",
" tooltips=layer_tooltips().line(\"Alaska\")) +\n",
" xlim(-180, -130) + map_options)\n",
"hawaii_plot = (ggplot() + geom_map(map=geocode_states('hawaii'), \n",
" fill=\"#00A954\", \n",
" color=\"#D91023\",\n",
" tooltips=layer_tooltips().line(\"Hawaii\")) +\n",
" xlim(-162, -154) + ylim(18, 23) +\n",
" map_options)\n",
"\n",
"ggbunch(\n",
" [conus_plot, alaska_plot, hawaii_plot],\n",
" [\n",
" (0, 0, 1, .8),\n",
" (0, .6, .25, .4),\n",
" (.25, .74, .25, .25)\n",
" ],\n",
") + ggsize(800, 500)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Resolving ambiguity"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### There are many cities named \"Warwick\""
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:57.796035Z",
"iopub.status.busy": "2026-01-27T17:08:57.795958Z",
"iopub.status.idle": "2026-01-27T17:08:59.015758Z",
"shell.execute_reply": "2026-01-27T17:08:59.015235Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Create a Warwick city geocoder.\n",
"world_warwicks = geocode_cities('warwick').allow_ambiguous()\n",
"\n",
"# Plot Warwicks.\n",
"(ggplot() + geom_map(map=geocode_countries())\n",
" + geom_point(map=world_warwicks, size=3, color=\"red\")\n",
" + coord_map(xlim=[-130, 20])\n",
" + theme_void())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Find one Warwick which is closest to Boston, US\n",
"\n",
"Note that the name \"Boston\" is not unique either. Therefore we will need two geocoders: one for Boston, US, and the other for the town of Warwick near Boston."
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:59.017294Z",
"iopub.status.busy": "2026-01-27T17:08:59.017213Z",
"iopub.status.idle": "2026-01-27T17:08:59.449131Z",
"shell.execute_reply": "2026-01-27T17:08:59.448537Z"
}
},
"outputs": [],
"source": [
"boston_us = geocode_cities('boston').countries('US')\n",
"warwick_near_boston = world_warwicks.where('warwick', closest_to=boston_us)\n",
"\n",
"# Let's also geocode Massachusetts counties. \n",
"counties_ma = geocode_counties().scope(\"Massachusetts\")"
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:08:59.450692Z",
"iopub.status.busy": "2026-01-27T17:08:59.450566Z",
"iopub.status.idle": "2026-01-27T17:09:00.609911Z",
"shell.execute_reply": "2026-01-27T17:09:00.609550Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"(ggplot() + geom_map(map=counties_ma)\n",
" + geom_point(map=warwick_near_boston, size=7, color=\"red\") \\\n",
" + geom_polygon(map=boston_us)\n",
" + theme_void())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Filter Warwicks using Shaply `box`"
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:09:00.611226Z",
"iopub.status.busy": "2026-01-27T17:09:00.611132Z",
"iopub.status.idle": "2026-01-27T17:09:00.612786Z",
"shell.execute_reply": "2026-01-27T17:09:00.612569Z"
}
},
"outputs": [],
"source": [
"from shapely.geometry import box\n",
"warwicks_in_box = (world_warwicks\n",
" .where('warwick', scope=box(-72, 41.5, -71, 42)))"
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:09:00.613943Z",
"iopub.status.busy": "2026-01-27T17:09:00.613830Z",
"iopub.status.idle": "2026-01-27T17:09:01.528334Z",
"shell.execute_reply": "2026-01-27T17:09:01.528044Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 18,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"(ggplot() + geom_map(map=counties_ma)\n",
" + geom_rect(xmin=-72, ymin=41.5, xmax=-71, ymax=42, alpha=0, color=\"magenta\", linetype=\"dashed\")\n",
" + geom_point(map=warwicks_in_box, size=7, color=\"red\")\n",
" + geom_polygon(map=boston_us)\n",
" + theme_void())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Explore the details on an interactive map\n",
"\n",
"Note: nbviewer won't load base-map tiles due to its CSP."
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {
"execution": {
"iopub.execute_input": "2026-01-27T17:09:01.529630Z",
"iopub.status.busy": "2026-01-27T17:09:01.529549Z",
"iopub.status.idle": "2026-01-27T17:09:01.963717Z",
"shell.execute_reply": "2026-01-27T17:09:01.963217Z"
}
},
"outputs": [
{
"data": {
"text/html": [
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 19,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"(ggplot() + geom_livemap()\n",
" + geom_rect(xmin=-72, ymin=41.5, xmax=-71, ymax=42, alpha=0, color=\"magenta\", linetype=\"dashed\")\n",
" + geom_point(map=warwicks_in_box, size=7, color=\"red\")\n",
" + geom_polygon(map=boston_us))"
]
}
],
"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
}