Advanced Geocoding

Overview

Geocoding is the process of converting names of places into geographic coordinates.

Lets-Plot now offers geocoding API covering the following administrative levels:

  • country

  • state

  • county

  • city

Lets-Plot geocoding API allows a user to execute a single and batch geocoding queries, and handle possible names ambiguity.

The core class is Geocoder. There is a function’s family for constructing the Geocoder object - geocode_cities(), geocode_counties(), geocode_states(), geocode_countries() and geocode(). For example:

1from lets_plot.geo_data import *
2countries = geocode_countries(['usa', 'canada'])
The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).
Note that actual geocoding process is not executing here, it starts when any get_xxx() function is called. We will use in examples function get_geocodes() which returns DataFrame with metadata.

Let us geocode countries. This code returns the DataFrame object containing internal IDs for Canada and the US:

1countries.get_geocodes()
id country found name centroid position limit
0 148838 usa United States [-99.7426055742426, 37.2502586245537] [-124.733375608921, 25.1162923872471, -66.9498... [144.618412256241, -14.3740922212601, -64.5648...
1 1428125 canada Canada [-110.450525298983, 56.8387750536203] [-141.002660393715, 41.6765552759171, -55.6205... [-141.002660393715, 41.6765552759171, -52.6194...
More complex queries can be created in order to specify how to handle geocoding ambiguities.

For example, this sample returns the DataFrame object containing IDs of all cities matching “warwick”:

1geocode_cities('warwick')  \
2    .allow_ambiguous()  \
3    .get_geocodes()
id city found name centroid position limit
0 119776 warwick Warwick [-83.9205776783726, 31.8303624540567] [-83.9291015267372, 31.8222776055336, -83.9120... [-83.9291015267372, 31.8222776055336, -83.9120...
1 176086 warwick Warwick [-74.3590787617065, 41.2538411468267] [-74.374563395977, 41.2334154546261, -74.33202... [-74.374563395977, 41.2334154546261, -74.33202...
2 176448 warwick Warwick [-1.58227695103754, 52.3015402257442] [-1.78017809987068, 52.2137045860291, -1.40608... [-1.78017809987068, 52.2137045860291, -1.40608...
3 181594 warwick Warwick [-98.7057320814883, 47.8541030734777] [-98.7164886295795, 47.8475135564804, -98.6948... [-98.7164886295795, 47.8475135564804, -98.6948...
4 184249 warwick Warwick [-96.9995924696813, 35.6883452832699] [-97.0261216163635, 35.6740544736385, -96.9776... [-97.0261216163635, 35.6740544736385, -96.9776...
5 4072420 warwick Warwick [-81.8960721893947, 43.0157359689474] [-82.0060113072395, 42.9303230345249, -81.7887... [-82.0060113072395, 42.9303230345249, -81.7887...
6 158818247 warwick Warwick [-72.3365538645007, 42.667919844389] [-72.4120393395424, 42.6094262301922, -72.2719... [-72.4120393395424, 42.6094262301922, -72.2719...
7 158863860 warwick Warwick [-71.4332938210472, 41.715542525053] [-71.5189133584499, 41.6628210246563, -71.3564... [-71.5189133584499, 41.6293966770172, -71.3564...
8 159726256 warwick Warwick [-72.0051031618881, 45.952380001545] [-72.0792764425278, 45.8764761686325, -71.9089... [-72.0792764425278, 45.8764761686325, -71.9089...
9 1817489924 warwick Warwick [152.032703831792, -28.2163204997778] [152.023720443249, -28.224236369133, 152.04168... [152.023720443249, -28.224236369133, 152.04168...
10 3049373 warwick Warwick Township [-75.757813608352, 40.1801763474941] [-75.8212745189667, 40.1465494930744, -75.6930... [-75.8212745189667, 40.1465494930744, -75.6930...
11 3521480 warwick Warwick Township [-75.0764330968138, 40.2491855621338] [-75.1225188374519, 40.2152167260647, -75.0345... [-75.1225188374519, 40.2152167260647, -75.0345...
12 9244563 warwick Warwick Mountain [-63.3714760496144, 45.5978938937187] [-63.4091444313526, 45.5644172430038, -63.3474... [-63.4091444313526, 45.5644172430038, -63.3474...
13 158903676 warwick West Warwick [-71.5257788638961, 41.6969098895788] [-71.5342850983143, 41.6620793938637, -71.4839... [-71.5342850983143, 41.6620793938637, -71.4839...
14 7997266 warwick Sainte-Élizabeth-de-Warwick [-72.1010115992802, 45.9195195883512] [-72.1493585407734, 45.8681344985962, -72.0435... [-72.1493585407734, 45.8681344985962, -72.0435...
This example returns the DataFrame object containing the ID of one particular “warwick” closest to Boston (US):
1boston_us = geocode_cities('boston').scope('us')
2geocode_cities('warwick') \
3    .where('warwick', closest_to=boston_us) \
4    .get_geocodes()
id city found name centroid position limit
0 158863860 warwick Warwick [-71.4332938210472, 41.715542525053] [-71.5189133584499, 41.6628210246563, -71.3564... [-71.5189133584499, 41.6293966770172, -71.3564...
Once the Geocoder object is available, it can be passed to any Lets-Plot geom supporting the map parameter. map parameter can be used to simply draw a GeoDataFrame or to draw a Geocoder. For more complex plots parameter map_join can be used to map data to geometries.

If necessary, the Geocoder object can be transformed to a geopandas GeoDataFrame using one of get_centroids(), get_boundaries(), or get_limits() methods.

All coordinates are in the EPSG:4326 coordinate reference system (CRS).

Note that an internet connection is required to execute geocoding queries.

Examples

  • Various geocoding cases with maps: https://nbviewer.jupyter.org/github/JetBrains/lets-plot-docs/blob/master/source/examples/cookbook/geocoding_examples.ipynb

  • Mapping US Household Income: https://www.kaggle.com/alshan/mapping-us-household-income

  • Geocoding the US counties: https://datalore.jetbrains.com/view/notebook/18vW14MKvPqWBIedhsrrSQ

  • Visualization of the Titanic’s voyage: https://datalore.jetbrains.com/view/notebook/c9z45DyqjHuYikaD2ikcVt https://www.kaggle.com/alshan/visualization-of-the-titanic-s-voyage https://colab.research.google.com/drive/1PerUfSCyStcbnlXnxBj-JVI25-cXB_N5?usp=sharing

Couldn't load map_titanic.png
  • Visualization of Airport Data on Map: https://www.kaggle.com/alshan/visualization-of-airport-data-on-map

Couldn't load map_airports.png

Reference

The geocoding_reference.ipynb notebook contains a demonstration code covering use-cases presented in this section.

Levels

Geocoding supports 4 administrative levels:

  • city

  • county

  • state

  • country

Function geocode() with level=None can try to detect level automatically - it enumerates all levels from country to city and selects best matching level (result without ambiguity and unknown names). For example:

1geocode(names=['florida', 'tx']).get_geocodes()
id state found name centroid position limit
0 162050 florida Florida [-81.664617414276, 28.0571937561035] [-87.6348964869976, 25.1162923872471, -80.0309... [-87.6348964869976, 24.5230695605278, -80.0309...
1 114690 tx Texas [-99.6829525269137, 31.1685702949762] [-106.645845472813, 25.8370596170425, -93.5078... [-106.645845472813, 25.8370596170425, -93.5078...
Level auto-detection can be useful, but it is slower and not recommended for large data sets.

Functions geocode_cities(), geocode_counties(), geocode_states(), geocode_countries() or geocode(level=xxx) search names only at a given level or return an error.

1geocode_states(['florida', 'tx']).get_geocodes()
id state found name centroid position limit
0 162050 florida Florida [-81.664617414276, 28.0571937561035] [-87.6348964869976, 25.1162923872471, -80.0309... [-87.6348964869976, 24.5230695605278, -80.0309...
1 114690 tx Texas [-99.6829525269137, 31.1685702949762] [-106.645845472813, 25.8370596170425, -93.5078... [-106.645845472813, 25.8370596170425, -93.5078...

Parents

Geocoder class provides functions to define parents with administrative level - counties(), states(), countries(). These functions can handle single or multiple values of type string or Geocoder. The number of values must match the number of names in Geocoder so that they form a table.

Parents will be present in the result DataFrame to make it possible to join data and geometry via map_join.

1geocode_cities(['warwick', 'worcester'])\
2    .counties(['Worth County', 'worcester county'])\
3    .states(['georgia', 'massachusetts'])\
4    .get_geocodes()
id city found name county state centroid position limit
0 119776 warwick Warwick Worth County georgia [-83.9205776783726, 31.8303624540567] [-83.9291015267372, 31.8222776055336, -83.9120... [-83.9291015267372, 31.8222776055336, -83.9120...
1 158851900 worcester Worcester worcester county massachusetts [-71.8154652712922, 42.2678737342358] [-71.8840424716473, 42.2100399434566, -71.7312... [-71.8840424716473, 42.2100399434566, -71.7312...
Parents can contain None value for countries with different administrative division:
1geocode_cities(['warwick', 'worcester'])\
2    .states(['Georgia', None])\
3    .countries(['USA', 'United Kingdom'])\
4    .get_geocodes()
id city found name state country centroid position limit
0 119776 warwick Warwick Georgia USA [-83.9205776783726, 31.8303624540567] [-83.9291015267372, 31.8222776055336, -83.9120... [-83.9291015267372, 31.8222776055336, -83.9120...
1 20971097 worcester Worcester None United Kingdom [-2.2095610731112, 52.1965283900499] [-2.2632023692131, 52.1616362035275, -2.157303... [-2.2632023692131, 52.1616362035275, -2.157303...
Parent can be Geocoder object. This allows resolving parent’s ambiguity:
1s = geocode_states(['vermont', 'georgia']).scope('usa')
2geocode_cities(['worcester', 'warwick']).states(s).get_geocodes()
id city found name state centroid position limit
0 8898137 worcester Worcester vermont [-72.5724501055639, 44.4132962822914] [-72.6543393731117, 44.3454243242741, -72.4935... [-72.6543393731117, 44.3454243242741, -72.4935...
1 119776 warwick Warwick georgia [-83.9205776783726, 31.8303624540567] [-83.9291015267372, 31.8222776055336, -83.9120... [-83.9291015267372, 31.8222776055336, -83.9120...

Scope

scope() is a special kind of parent. scope() can handle a string or a single entry Geocoder object. scope() is not associated with any administrative level, it acts as parent for any other parents and names. scope() can not be used with countries() parents. Typical use-case: all of names belong to the same parent.

1geocode_counties(['Dakota County', 'Nevada County']).states(['NE', 'AR']).scope('USA').get_geocodes()
id county found name state centroid position limit
0 1425447 Dakota County Dakota County NE [-96.5715826334556, 42.4019493162632] [-96.7274482548237, 42.2765184938908, -96.3566... [-96.7274482548237, 42.2765184938908, -96.3566...
1 1826825 Nevada County Nevada County AR [-93.2913903139467, 33.6979349702597] [-93.4838207066059, 33.4403765201569, -93.1042... [-93.4838207066059, 33.4403765201569, -93.1042...
Parents can be modified between searches:
1florida = geocode_states('florida')
2
3display(florida.countries('usa').get_geocodes())
4display(florida.countries('uruguay').get_geocodes())
5display(florida.countries(None).get_geocodes())
id state found name country centroid position limit
0 162050 florida Florida usa [-81.664617414276, 28.0571937561035] [-87.6348964869976, 25.1162923872471, -80.0309... [-87.6348964869976, 24.5230695605278, -80.0309...
id state found name country centroid position limit
0 1635164 florida Florida uruguay [-55.8642029687055, -33.7640165537596] [-56.5363445878029, -34.4264329969883, -55.098... [-56.5363445878029, -34.4264329969883, -55.098...
id state found name centroid position limit
0 162050 florida Florida [-81.664617414276, 28.0571937561035] [-87.6348964869976, 25.1162923872471, -80.0309... [-87.6348964869976, 24.5230695605278, -80.0309...

Fetch All

It is possible to fetch all objects within parent - just do not set the names parameter.

1geocode_counties().states('massachusetts').get_geocodes()
id county found name state centroid position limit
0 61321 Berkshire County Berkshire County massachusetts [-73.1970960029264, 42.4073023349047] [-73.5082098841667, 42.0398162305355, -72.9488... [-73.5082098841667, 42.0398162305355, -72.9488...
1 90434 Essex County Essex County massachusetts [-70.9657019377445, 42.6519144326448] [-71.2561883032322, 42.4163138866425, -70.6729... [-71.2561883032322, 42.4163138866425, -70.5907...
2 1181619 Hampden County Hampden County massachusetts [-72.6295139278191, 42.1725875884295] [-73.0750867724419, 41.9976854324341, -72.1350... [-73.0750867724419, 41.9976854324341, -72.1350...
3 1838804 Hampshire County Hampshire County massachusetts [-72.7141542430634, 42.369756102562] [-73.0685086548328, 42.1833908557892, -72.2032... [-73.0685086548328, 42.1833908557892, -72.2032...
4 1838805 Worcester County Worcester County massachusetts [-71.9577156176713, 42.3648966103792] [-72.3158794641495, 42.0080535113811, -71.4780... [-72.3158794641495, 42.0080535113811, -71.4780...
5 1839610 Franklin County Franklin County massachusetts [-72.5619375937952, 42.5192946195602] [-73.0237090587616, 42.3032829165459, -72.2249... [-73.0237090587616, 42.3032829165459, -72.2249...
6 1840537 Bristol County Bristol County massachusetts [-71.1762539847584, 41.7951115965843] [-71.3814635574818, 41.4945808053017, -70.8417... [-71.3814635574818, 41.4809954166412, -70.8158...
7 1840538 Middlesex County Middlesex County massachusetts [-71.2881300332954, 42.4460086226463] [-71.8987718224525, 42.1567820012569, -71.0203... [-71.8987718224525, 42.1567820012569, -71.0203...
8 1840539 Norfolk County Norfolk County massachusetts [-71.2060019640526, 42.1540769934654] [-71.503077596426, 41.9850830733776, -70.91473... [-71.503077596426, 41.9850830733776, -70.78201...
9 1840540 Plymouth County Plymouth County massachusetts [-70.8627991612476, 41.9707231968641] [-71.0804834961891, 41.6237345337868, -70.5256... [-71.0804834961891, 41.6237345337868, -70.5256...
10 2294308 Barnstable County Barnstable County massachusetts [-69.9965259842594, 41.7987298965454] [-70.686851888895, 41.5150675177574, -69.92929... [-70.686851888895, 41.5150675177574, -69.92929...
11 2298154 Suffolk County Suffolk County massachusetts [-71.0606561674246, 42.3390870541334] [-71.1912493407726, 42.2279115021229, -70.9532... [-71.1912493407726, 42.2279115021229, -70.9244...
12 2387087 Nantucket County Nantucket County massachusetts [-70.0092203651615, 41.3159892708063] [-70.2361777424812, 41.2393619120121, -69.9608... [-70.3080931305885, 41.2393619120121, -69.9608...
13 2387198 Dukes County Dukes County massachusetts [-70.6198368970106, 41.3932851701975] [-70.838218331337, 41.3013222813606, -70.44638... [-70.9499511122704, 41.2496776878834, -70.4463...

US-48

Geocoding supports a special name us-48 for CONUS. The us-48 can be used as name or parent.

1geocode_states('us-48').get_geocodes()
id state found name centroid position limit
0 63512 Maine Maine [-69.1608471741827, 45.2623642981052] [-71.0841688513756, 43.0649779736996, -66.9498... [-71.0841688513756, 42.9808665812016, -66.9498...
1 67213 New Hampshire New Hampshire [-71.5517876605831, 44.0015134960413] [-72.5572353601456, 42.6972283422947, -70.7018... [-72.5572353601456, 42.6972283422947, -70.7018...
2 60759 Vermont Vermont [-72.772353529363, 43.8718488067389] [-73.4377402067184, 42.7269606292248, -71.4653... [-73.4377402067184, 42.7269606292248, -71.4653...
3 61315 Massachusetts Massachusetts [-72.0964509339039, 42.1913791447878] [-73.5082098841667, 41.4945808053017, -69.9292... [-73.5082098841667, 41.2393619120121, -69.9292...
4 61320 New York New York [-76.0912327538441, 42.8993669897318] [-79.7619438171387, 40.7823456823826, -73.2414... [-79.7619438171387, 40.4960802197456, -71.8561...
5 114690 Texas Texas [-99.6829525269137, 31.1685702949762] [-106.645845472813, 25.8370596170425, -93.5078... [-106.645845472813, 25.8370596170425, -93.5078...
6 122586 Illinois Illinois [-89.451321863232, 39.7387826442719] [-91.5130515396595, 36.9701313972473, -87.0199... [-91.5130515396595, 36.9701313972473, -87.0199...
7 161638 Missouri Missouri [-92.4924265655452, 38.3039845526218] [-95.7741442322731, 35.9956835210323, -89.0988... [-95.7741442322731, 35.9956835210323, -89.0988...
8 161644 Kansas Kansas [-98.328692575607, 38.5217376798391] [-102.051756531, 36.9931246340275, -94.5882055... [-102.051756531, 36.9931246340275, -94.5882055...
9 161645 Oklahoma Oklahoma [-97.21699429948, 35.3174138814211] [-103.002461493015, 33.6191953718662, -94.4312... [-103.002461493015, 33.6191953718662, -94.4312...
10 161646 Arkansas Arkansas [-92.4984827479225, 34.7509514540434] [-94.6178559958935, 33.004105836153, -89.64224... [-94.6178559958935, 33.004105836153, -89.64224...
11 161648 Nebraska Nebraska [-100.027538024238, 41.501209884882] [-104.0535145998, 39.9999774992466, -95.308054... [-104.0535145998, 39.9999774992466, -95.308054...
12 161650 Iowa Iowa [-93.1514127397129, 41.9395130127668] [-96.6397158801556, 40.3756007552147, -90.1400... [-96.6397158801556, 40.3756007552147, -90.1400...
13 161652 South Dakota South Dakota [-100.253885285003, 44.2193739116192] [-104.057756513357, 42.4798929691315, -96.4363... [-104.057756513357, 42.4798929691315, -96.4363...
14 161653 North Dakota North Dakota [-100.452325244499, 47.4677764624357] [-104.049264639616, 45.9350354969501, -96.5543... [-104.049264639616, 45.9350354969501, -96.5543...
15 161655 Kentucky Kentucky [-84.729118063289, 37.823773920536] [-89.4172927737236, 36.497118473053, -81.96454... [-89.5715090632439, 36.497118473053, -81.96454...
16 161816 Indiana Indiana [-86.1734508970078, 39.7625309228897] [-88.0997018516064, 37.7717417478561, -84.7846... [-88.0997018516064, 37.7717417478561, -84.7846...
17 161838 Tennessee Tennessee [-86.3173561038854, 35.8305955678225] [-90.3102980554104, 34.982981979847, -81.64689... [-90.3102980554104, 34.982981979847, -81.64689...
18 161943 Mississippi Mississippi [-89.7084286073575, 32.5858394801617] [-91.6550087928772, 30.1744651794434, -88.0977... [-91.6550087928772, 30.1744651794434, -88.0977...
19 161950 Alabama Alabama [-86.7421099329499, 32.6446247845888] [-88.4731015563011, 30.2791893482208, -84.8882... [-88.4731015563011, 30.2249671518803, -84.8882...
20 161957 Georgia Georgia [-83.2514879869572, 32.6792977005243] [-85.6052421033382, 30.3557570278645, -80.8400... [-85.6052421033382, 30.3557570278645, -80.8400...
21 161961 Colorado Colorado [-105.549469314711, 38.9999721944332] [-109.060187637806, 36.9924259185791, -102.041... [-109.060187637806, 36.9924259185791, -102.041...
22 161991 Wyoming Wyoming [-107.548611778195, 43.0007712543011] [-111.055267006159, 40.9948222339153, -104.052... [-111.055267006159, 40.9948222339153, -104.052...
23 161993 Utah Utah [-111.54915785543, 39.4988744705915] [-114.052882343531, 36.9979673624039, -109.041... [-114.052882343531, 36.9979673624039, -109.041...
24 162014 New Mexico New Mexico [-106.045169724866, 34.2040651291609] [-109.050223231316, 31.3322111964226, -103.002... [-109.050223231316, 31.3322111964226, -103.002...
25 162018 Arizona Arizona [-111.665190827228, 34.1682100296021] [-114.818357974291, 31.3322138786316, -109.045... [-114.818357974291, 31.3322138786316, -109.045...
26 162050 Florida Florida [-81.664617414276, 28.0571937561035] [-87.6348964869976, 25.1162923872471, -80.0309... [-87.6348964869976, 24.5230695605278, -80.0309...
27 162061 Ohio Ohio [-82.7062932155643, 40.3632525354624] [-84.8203365504742, 38.4031417965889, -80.5189... [-84.8203365504742, 38.4031417965889, -80.5189...
28 162068 West Virginia West Virginia [-80.2961093874269, 38.9198365062475] [-82.644739151001, 37.2014826536179, -77.71902... [-82.644739151001, 37.2014826536179, -77.71902...
29 162069 District of Columbia District of Columbia [-76.9879975677786, 38.8937935978174] [-77.1197667717934, 38.7916302680969, -76.9093... [-77.1197667717934, 38.7916302680969, -76.9093...
30 162109 Pennsylvania Pennsylvania [-77.7395653681049, 41.1167051643133] [-80.5210827291012, 39.7197657823563, -74.6895... [-80.5210827291012, 39.7197657823563, -74.6895...
31 162110 Delaware Delaware [-75.5803336262906, 39.1468942165375] [-75.7890397310257, 38.4511278569698, -75.0505... [-75.7890397310257, 38.4511278569698, -75.0505...
32 162112 Maryland Maryland [-75.9553945026409, 38.8234928995371] [-79.4873057305813, 37.92381092906, -75.049993... [-79.4873057305813, 37.9135474562645, -75.0499...
33 162115 Montana Montana [-109.343314037162, 46.6796220839024] [-116.049231737852, 44.3579153716564, -104.039... [-116.049231737852, 44.3579153716564, -104.039...
34 162116 Idaho Idaho [-115.464817458905, 45.4943814128637] [-117.24303200841, 41.9880764186382, -111.0435... [-117.24303200841, 41.9880764186382, -111.0435...
35 165466 Wisconsin Wisconsin [-89.7229295951697, 44.8979325592518] [-92.889314442873, 42.4919508397579, -86.24954... [-92.889314442873, 42.4919508397579, -86.24954...
36 165471 Minnesota Minnesota [-94.5024903450148, 46.4419361203909] [-97.2392620146275, 43.4994287788868, -89.4833... [-97.2392620146275, 43.4994287788868, -89.4833...
37 165473 Nevada Nevada [-116.666956541192, 38.5030842572451] [-120.005727410316, 35.0018888711929, -114.039... [-120.005727410316, 35.0018888711929, -114.039...
38 165475 California California [-119.994112927034, 37.277335524559] [-124.409690648317, 32.5343263149261, -114.130... [-124.409690648317, 32.5343263149261, -114.130...
39 165476 Oregon Oregon [-120.525597872899, 44.1131933033466] [-124.56648722291, 41.9917939603329, -116.4635... [-124.56648722291, 41.9917939603329, -116.4635...
40 165479 Washington Washington [-119.70860442837, 47.2730628401041] [-124.733375608921, 45.5437226593494, -116.917... [-124.755572229624, 45.5437226593494, -116.917...
41 165789 Michigan Michigan [-84.5068071817736, 45.0034050643444] [-90.4186204075813, 41.6961273550987, -82.1228... [-90.4186204075813, 41.6961273550987, -82.1228...
42 165794 Connecticut Connecticut [-72.6619366808976, 41.5181306004524] [-73.7277755141258, 40.9867581725121, -71.7871... [-73.7277755141258, 40.9867581725121, -71.7871...
43 224040 South Carolina South Carolina [-80.570954325977, 33.6225119233131] [-83.353998363018, 32.0341077446938, -78.54161... [-83.353998363018, 32.0341077446938, -78.54161...
44 224042 Virginia Virginia [-78.2939080535943, 38.0035275220871] [-83.6753672361374, 36.5407902002335, -75.8670... [-83.6753672361374, 36.5407902002335, -75.2452...
45 224045 North Carolina North Carolina [-79.0290157899437, 35.214960873127] [-84.3218292295933, 33.8419796526432, -75.4610... [-84.3218292295933, 33.8419796526432, -75.4610...
46 224922 Louisiana Louisiana [-92.5706733638148, 31.0122518241405] [-94.0431873500347, 29.0049590170383, -88.9928... [-94.0431873500347, 28.9292603731155, -88.8210...
47 224951 New Jersey New Jersey [-74.3697877915224, 40.1556817442179] [-75.5598650872707, 38.9532735943794, -73.8940... [-75.5598650872707, 38.9296942949295, -73.8940...
48 392915 Rhode Island Rhode Island [-71.6161388376275, 41.660745665431] [-71.8864738941193, 41.3034854829311, -71.2255... [-71.8864738941193, 41.1466526985168, -71.1203...

Ambiguity

Often geocoding can find multiple objects for a name or do not find anything. In this case error will be generated:

1geocode_cities(['warwick', 'worcester']).get_geocodes()
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
C:\Temp/ipykernel_7064/2109755754.py in <module>
----> 1 geocode_cities(['warwick', 'worcester']).get_geocodes()

D:\anaconda3\envs\lets-plot-docs\lib\site-packages\lets_plot\geo_data\geocoder.py in get_geocodes(self)
    331 
    332         """
--> 333         return self._geocode().to_data_frame()
    334 
    335     def inc_res(self, delta=2):

D:\anaconda3\envs\lets-plot-docs\lib\site-packages\lets_plot\geo_data\geocoder.py in _geocode(self)
    932             response: Response = GeocodingService().do_request(request)
    933             if not isinstance(response, SuccessResponse):
--> 934                 _raise_exception(response)
    935             self._geocodes = Geocodes(response.level, response.answers, request.region_queries, self._highlights)
    936 

D:\anaconda3\envs\lets-plot-docs\lib\site-packages\lets_plot\geo_data\geocodes.py in _raise_exception(response)
    342 def _raise_exception(response: Response):
    343     msg = _format_error_message(response)
--> 344     raise ValueError(msg)
    345 
    346 

ValueError: Multiple objects (15) were found for warwick:
- Warwick (United States, Georgia, Worth County)
- Warwick (United States, New York, Orange County)
- Warwick (United Kingdom, England, West Midlands, Warwickshire)
- Warwick (United States, North Dakota, Benson County)
- Warwick (United States, Oklahoma, Lincoln County)
- Warwick (Canada, Ontario, Southwestern Ontario, Lambton County)
- Warwick (United States, Massachusetts, Franklin County)
- Warwick (United States, Rhode Island, Kent County)
- Warwick (Canada, Arthabaska, Québec, Centre-du-Québec)
- Warwick (Australia, Queensland)
Multiple objects (5) were found for worcester:
- Worcester (United States, Vermont, Washington County)
- Worcester (United Kingdom, England, West Midlands, Worcestershire)
- Worcester (South Africa, Western Cape, Cape Winelands District Municipality)
- Worcester (United States, Massachusetts, Worcester County)
- Worcester Township (United States, Pennsylvania, Montgomery County)
The ambiguity can be resolved in different ways.

allow_ambiguous()

The best way is to find an object that we search and use its parents. The function converts error result into success result that can be rendered on a map or verified manually in other way. Can be combined with ignore_not_found() to suppress the “not found” error, which has higher priority.

1geocode_cities(['warwick', 'worcester']).allow_ambiguous().get_geocodes()
id city found name centroid position limit
0 119776 warwick Warwick [-83.9205776783726, 31.8303624540567] [-83.9291015267372, 31.8222776055336, -83.9120... [-83.9291015267372, 31.8222776055336, -83.9120...
1 176086 warwick Warwick [-74.3590787617065, 41.2538411468267] [-74.374563395977, 41.2334154546261, -74.33202... [-74.374563395977, 41.2334154546261, -74.33202...
2 176448 warwick Warwick [-1.58227695103754, 52.3015402257442] [-1.78017809987068, 52.2137045860291, -1.40608... [-1.78017809987068, 52.2137045860291, -1.40608...
3 181594 warwick Warwick [-98.7057320814883, 47.8541030734777] [-98.7164886295795, 47.8475135564804, -98.6948... [-98.7164886295795, 47.8475135564804, -98.6948...
4 184249 warwick Warwick [-96.9995924696813, 35.6883452832699] [-97.0261216163635, 35.6740544736385, -96.9776... [-97.0261216163635, 35.6740544736385, -96.9776...
5 4072420 warwick Warwick [-81.8960721893947, 43.0157359689474] [-82.0060113072395, 42.9303230345249, -81.7887... [-82.0060113072395, 42.9303230345249, -81.7887...
6 158818247 warwick Warwick [-72.3365538645007, 42.667919844389] [-72.4120393395424, 42.6094262301922, -72.2719... [-72.4120393395424, 42.6094262301922, -72.2719...
7 158863860 warwick Warwick [-71.4332938210472, 41.715542525053] [-71.5189133584499, 41.6628210246563, -71.3564... [-71.5189133584499, 41.6293966770172, -71.3564...
8 159726256 warwick Warwick [-72.0051031618881, 45.952380001545] [-72.0792764425278, 45.8764761686325, -71.9089... [-72.0792764425278, 45.8764761686325, -71.9089...
9 1817489924 warwick Warwick [152.032703831792, -28.2163204997778] [152.023720443249, -28.224236369133, 152.04168... [152.023720443249, -28.224236369133, 152.04168...
10 3049373 warwick Warwick Township [-75.757813608352, 40.1801763474941] [-75.8212745189667, 40.1465494930744, -75.6930... [-75.8212745189667, 40.1465494930744, -75.6930...
11 3521480 warwick Warwick Township [-75.0764330968138, 40.2491855621338] [-75.1225188374519, 40.2152167260647, -75.0345... [-75.1225188374519, 40.2152167260647, -75.0345...
12 9244563 warwick Warwick Mountain [-63.3714760496144, 45.5978938937187] [-63.4091444313526, 45.5644172430038, -63.3474... [-63.4091444313526, 45.5644172430038, -63.3474...
13 158903676 warwick West Warwick [-71.5257788638961, 41.6969098895788] [-71.5342850983143, 41.6620793938637, -71.4839... [-71.5342850983143, 41.6620793938637, -71.4839...
14 7997266 warwick Sainte-Élizabeth-de-Warwick [-72.1010115992802, 45.9195195883512] [-72.1493585407734, 45.8681344985962, -72.0435... [-72.1493585407734, 45.8681344985962, -72.0435...
15 8898137 worcester Worcester [-72.5724501055639, 44.4132962822914] [-72.6543393731117, 44.3454243242741, -72.4935... [-72.6543393731117, 44.3454243242741, -72.4935...
16 20971097 worcester Worcester [-2.2095610731112, 52.1965283900499] [-2.2632023692131, 52.1616362035275, -2.157303... [-2.2632023692131, 52.1616362035275, -2.157303...
17 30670038 worcester Worcester [19.4459268450737, -33.6462374031544] [19.4369441270828, -33.6537154018879, 19.45490... [19.4369441270828, -33.6537154018879, 19.45490...
18 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] [-71.8840424716473, 42.2100399434566, -71.7312... [-71.8840424716473, 42.2100399434566, -71.7312...
19 3076291 worcester Worcester Township [-75.3438698875367, 40.1926231384277] [-75.4107637703419, 40.1558580994606, -75.2932... [-75.4107637703419, 40.1558580994606, -75.2932...

ignore_not_found()

Removes unknown names from the result.

1geocode_cities(['paris', 'foo']).ignore_not_found().get_geocodes()
id city found name centroid position limit
0 17807753 paris Paris [2.32002815231681, 48.8587861508131] [2.22412258386612, 48.8155750930309, 2.4697606... [2.22412258386612, 48.8155750930309, 2.4697606...

ignore_all_errors()

Remove not found names or names with multiple matches.

1geocode_cities(['paris', 'worcester', 'foo']).ignore_all_errors().get_geocodes()
id city found name centroid position limit
0 17807753 paris Paris [2.32002815231681, 48.8587861508131] [2.22412258386612, 48.8155750930309, 2.4697606... [2.22412258386612, 48.8155750930309, 2.4697606...

where()

For resolving an ambiguity geocoding provides a function that can configure names individually.

To configure a name the function where(...) should be called with the place name and all used parent names. Parents cannot be changed via where() function call. If name and parents do not match with ones from the where() function an error will be generated. It is important for cases like this:

1geocode_counties(['Washington', 'Washington']).states(['oregon', 'utah']).get_geocodes()
id county found name state centroid position limit
0 1837133 Washington Washington County oregon [-123.09834180777, 45.5489509552717] [-123.486059904099, 45.3171966969967, -122.743... [-123.486059904099, 45.3171966969967, -122.743...
1 1744372 Washington Washington County utah [-113.476485065118, 37.3094066977501] [-114.052882343531, 37.0000769197941, -112.899... [-114.052882343531, 37.0000769197941, -112.899...
closest_to

With parameter closest_to geocoding will take only the object closest to given place. Parameter closest_to can be a single value Geocoder.

1boston = geocode_cities('boston')
2geocode_cities('worcester').where('worcester', closest_to=boston).get_geocodes()
id city found name centroid position limit
0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] [-71.8840424716473, 42.2100399434566, -71.7312... [-71.8840424716473, 42.2100399434566, -71.7312...
Or it can be a shapely.geometry.Point.
1import shapely
2
3geocode_cities('worcester').where('worcester', closest_to=shapely.geometry.Point(-71.088, 42.311)).get_geocodes()
id city found name centroid position limit
0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] [-71.8840424716473, 42.2100399434566, -71.7312... [-71.8840424716473, 42.2100399434566, -71.7312...
scope

With parameter scope a shapely.geometry.Polygon can be used for limiting an area of the search (coordinates should be in WGS84 coordinate system). Note that bbox of the polygon will be used:

1geocode_cities('worcester')\
2    .where('worcester', scope=shapely.geometry.box(-71.00, 42.00, -72.00, 43.00))\
3    .get_geocodes()
id city found name centroid position limit
0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] [-71.8840424716473, 42.2100399434566, -71.7312... [-71.8840424716473, 42.2100399434566, -71.7312...
Also, scope can be a single value Geocoder object or a string:
1massachusetts = geocode_states('massachusetts')
2geocode_cities('worcester').where('worcester', scope=massachusetts).get_geocodes()
id city found name centroid position limit
0 158851900 worcester Worcester [-71.8154652712922, 42.2678737342358] [-71.8840424716473, 42.2100399434566, -71.7312... [-71.8840424716473, 42.2100399434566, -71.7312...
scope does not change parents in the result DataFrame:
1worcester_county=geocode_counties('Worcester County').states('massachusetts').countries('usa')
2
3geocode_cities(['worcester', 'worcester'])\
4    .countries(['USA', 'United Kingdom'])\
5    .where('worcester', country='USA', scope=worcester_county)\
6    .get_geocodes()
id city found name country centroid position limit
0 158851900 worcester Worcester USA [-71.8154652712922, 42.2678737342358] [-71.8840424716473, 42.2100399434566, -71.7312... [-71.8840424716473, 42.2100399434566, -71.7312...
1 20971097 worcester Worcester United Kingdom [-2.2095610731112, 52.1965283900499] [-2.2632023692131, 52.1616362035275, -2.157303... [-2.2632023692131, 52.1616362035275, -2.157303...

Working with Plots

Plotting a GeoDataFrame

get_xxx() functions return GeoDataFrame which can be used as data or map parameter (see this or this).

1from lets_plot import *
2LetsPlot.setup_html()
3
4ggplot() + geom_point(map=geocode_states('us-48').get_centroids())