NamesGeocoder#

class NamesGeocoder(level: str | LevelKind | None = None, request: str | List[str] | Series | None = None)#

Do not use this class explicitly.

Instead you should construct its objects with special functions: geocode(), geocode_cities(), geocode_counties(), geocode_states(), geocode_countries(), reverse_geocode().

__init__(level: str | LevelKind | None = None, request: str | List[str] | Series | None = None)#

Initialize self.

scope(scope) → NamesGeocoder#

Limit area of interest to resolve an ambiguity.

Parameters:
scopestr or Geocoder

Area of interest. If it is of str type then it should be the geo-object name. If it is of Geocoder type then it must contain only one object.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5scope = geocode_states('Kentucky')
6city = geocode_cities('Franklin').scope(scope).get_boundaries()
7display(city)
8ggplot() + geom_map(data=city) + ggtitle('Franklin, Kentucky')

The geodata is provided by © OpenStreetMap contributors and is made available here under the Open Database License (ODbL).
city found name geometry
0 Franklin Franklin MULTIPOLYGON (((-86.60248 36.72056, -86.60131 ...
highlights(v: bool)#

Add matched string to geocodes DataFrame. Doesn’t affect GeoDataFrame.

Parameters:
vbool

If True geocodes DataFrame will contain column ‘highlights’ with string that matched the name.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from lets_plot.geo_data import *
2geocode(names='OH').allow_ambiguous().highlights(True).get_geocodes()
id state found name centroid position limit highlights
0 162061 OH Ohio [-82.7062932155643, 40.3632525354624] [-84.8203365504742, 38.4031417965889, -80.5189... [-84.8203365504742, 38.4031417965889, -80.5189... [OH, US-OH]
1 2279601 OH Omaheke [19.0250448143271, -22.0418351143599] [17.933823466301, -23.8670682907104, 20.999026... [17.933823466301, -23.8670682907104, 20.999026... [OH, NA-OH]
countries(countries)#

Set parents for ‘country’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters:
countriesstr or Geocoder or list

Parents for ‘country’ level. If it is of str type then it should be the country name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5cities = geocode_cities(['Boston', 'Boston']).countries(['US', 'UK']).get_centroids()
6display(cities)
7ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name country geometry
0 Boston Boston US POINT (-71.08848 42.31104)
1 Boston Boston UK POINT (-0.04838 52.97469)
states(states) → NamesGeocoder#

Set parents for ‘state’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters:
statesstr or Geocoder or list

Parents for ‘state’ level. If it is of str type then it should be the state name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5states = geocode_states(['Massachusetts', 'New York'])
6cities = geocode_cities(['Boston', 'Boston']).states(states).get_centroids()
7display(cities)
8ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name state geometry
0 Boston Boston Massachusetts POINT (-71.08848 42.31104)
1 Boston North Boston New York POINT (-78.77965 42.67952)
counties(counties: str | Geocodes | Geocoder | MapRegion | List | None) → NamesGeocoder#

Set parents for ‘county’ level to resolve an ambiguity or to join geometry with data via multi-key.

Parameters:
countiesstr or Geocoder or list

Parents for ‘county’ level. If it is of str type then it should be the county name. If it is of Geocoder type then it must contain the same number of values as the number of names of Geocoder. If it is of list type then it must be the same size as the number of names of Geocoder.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5counties = geocode_counties(['Suffolk County', 'Erie County'])\
6           .states(['Massachusetts', 'New York'])
7cities = geocode_cities(['Boston', 'Boston']).counties(counties).get_centroids()
8display(cities)
9ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name county geometry
0 Boston Boston Suffolk County POINT (-71.08848 42.31104)
1 Boston North Boston Erie County POINT (-78.77965 42.67952)
ignore_not_found() → NamesGeocoder#

Remove not found objects from the result.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5countries = geocode_countries(['Germany', 'Hungary', 'Czechoslovakia'])\
6            .ignore_not_found().get_boundaries(6)
7display(countries)
8ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Germany MULTIPOLYGON (((6.17408 50.55639, 6.24050 50.5...
1 Hungary Hungary MULTIPOLYGON (((16.11389 46.86906, 16.17924 46...
ignore_all_errors() → NamesGeocoder#

Remove objects that have multiple matches from the result.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5cities = geocode_cities(['Boston', 'Worcester', 'Barnstable'])\
6         .ignore_all_errors().get_centroids()
7display(cities)
8ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name geometry
0 Boston Boston POINT (-71.08848 42.31104)
1 Barnstable Barnstable POINT (-70.36277 41.66125)
allow_ambiguous() → NamesGeocoder#

For objects that have multiple matches add all of them to the result.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5cities = geocode_cities('Worcester').scope('US')\
6         .allow_ambiguous().get_centroids()
7display(cities)
8ggplot() + geom_livemap() + geom_point(data=cities, color='red', size=5)
city found name geometry
0 Worcester Worcester POINT (-72.57245 44.41330)
1 Worcester Worcester POINT (-71.81547 42.26787)
2 Worcester Worcester Township POINT (-75.34387 40.19262)
where(name: str, county: str | Geocodes | Geocoder | MapRegion | List | None = None, state: str | Geocodes | Geocoder | MapRegion | List | None = None, country: str | Geocodes | Geocoder | MapRegion | List | None = None, scope: str | Geocodes | Geocoder | shapely.geometry.Polygon | None = None, closest_to: Geocodes | shapely.geometry.Point | None = None) → NamesGeocoder#

Allows to resolve ambiguity by setting up extra parameters. Combination of name, county, state, country identifies a row with an ambiguity. If row with given names does not exist error will be generated.

Parameters:
namestr

Name in Geocoder that needs better qualification.

countystr

If Geocoder has parent counties this field must be present to identify a row for the name.

statestr

If Geocoder has parent states this field must be present to identify a row for the name.

countrystr

If Geocoder has parent countries this field must be present to identify a row for the name.

scopestr or Geocoder or shapely.geometry.Polygon

Limits area of geocoding. If parent country is set then error will be generated. If type is a str - geoobject should have geocoded scope in parents. If type is a Geocoder - geoobject should have geocoded scope in parents. Scope should contain only one entry. If type is a shapely.geometry.Polygon - geoobject centroid should fall into bbox of the polygon.

closest_toGeocoder or shapely.geometry.Point

Resolve ambiguity by taking closest geoobject.

Returns:
NamesGeocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5city = geocode_cities('Warwick').countries('US')\
6       .where(name='Warwick', country='US', scope='Massachusetts').get_centroids()
7display(city)
8ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
city found name country geometry
0 Warwick Warwick US POINT (-72.33655 42.66792) 

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5closest_city = geocode_cities('Birmingham').get_centroids().iloc[0].geometry
6city = geocode_cities('Warwick')\
7       .where(name='Warwick', closest_to=closest_city).get_centroids()
8display(city)
9ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
city found name geometry
0 Warwick Warwick POINT (-1.58228 52.30154)
get_boundaries(resolution=None) → GeoDataFrame#

Return boundaries for given regions in the form of GeoDataFrame.

Parameters:
resolutionint or str

Boundaries resolution.

Returns:
GeoDataFrame

Table of data.

Notes

If resolution has int type, it may take one of the following values:

  • 1-3 for world scale view,

  • 4-6 for country scale view,

  • 7-9 for state scale view,

  • 10-12 for county scale view,

  • 13-15 for city scale view.

Here value 1 corresponds to maximum performance and 15 - to maximum quality.

If resolution is of str type, it may take one of the following values:

  • ‘world’ corresponds to int value 2,

  • ‘country’ corresponds to int value 5,

  • ‘state’ corresponds to int value 8,

  • ‘county’ corresponds to int value 11,

  • ‘city’ corresponds to int value 14.

Here value ‘world’ corresponds to maximum performance and ‘city’ - to maximum quality.

The resolution choice depends on the type of displayed area. The number of objects also matters: one state looks good on a ‘state’ scale while 50 states is a ‘country’ view.

It is allowed to use any resolution for all regions. For example, ‘city’ scale can be used for a state to get a more detailed boundary when zooming in, or ‘world’ for a small preview.

If resolution is not specified (or equal to None), it will be auto-detected. Auto-detection by level_kind is used for geocoding and the number of objects. In this case performance is preferred over quality. The pixelated geometries can be obtained. Use explicit resolution or inc_res() function for better quality.

If the number of objects is equal to n, then resolution will be the following:

  • For countries: if n < 3 then resolution=3, else resolution=1.

  • For states: if n < 3 then resolution=7, if n < 10 then resolution=4, else resolution=2.

  • For counties: if n < 5 then resolution=10, if n < 20 then resolution=8, else resolution=3.

  • For cities: if n < 5 then resolution=13, if n < 50 then resolution=4, else resolution=3.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
6display(countries)
7ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Germany MULTIPOLYGON (((5.97574 50.80235, 6.02503 50.8...
1 Poland Poland MULTIPOLYGON (((14.24606 53.89950, 14.27857 53...
get_centroids() → GeoDataFrame#

Return centroids (Point geometry) for given regions in form of GeoDataFrame.

Returns:
GeoDataFrame

Table of data.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5countries = geocode_countries(['Germany', 'Poland']).get_centroids()
6display(countries)
7ggplot() + geom_point(aes(color='found name'), data=countries, size=10)
country found name geometry
0 Germany Germany POINT (10.57925 51.16420)
1 Poland Poland POINT (19.15683 51.91905)
get_geocodes() → DataFrame#

Return metadata for given regions.

Returns:
DataFrame

Table of data.

Examples

1from lets_plot.geo_data import *
2geocode_countries(['Germany', 'Russia']).get_geocodes()
id country found name centroid position limit
0 51477 Germany Germany [10.5792501010919, 51.1642031371593] [5.86631566286087, 47.2701117396355, 15.041808... [5.86631566286087, 47.2701117396355, 15.041808...
1 60189 Russia Russia [87.2574204719613, 59.4541937112808] [27.3174405097961, 41.1850968003273, 180, 77.7... [19.6384236216545, 41.1850968003273, -168.9977...
get_limits() → GeoDataFrame#

Return bboxes (Polygon geometry) for given regions in form of GeoDataFrame. For regions intersecting anti-meridian bbox will be divided into two parts and stored as two rows.

Returns:
GeoDataFrame

Table of data.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5countries = geocode_countries(['Germany', 'Poland']).get_limits()
6display(countries)
7ggplot() + geom_rect(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Germany POLYGON ((15.04181 47.27011, 15.04181 55.05857...
1 Poland Poland POLYGON ((24.14578 49.00205, 24.14578 54.83583...
inc_res(delta=2)#

Increase auto-detected resolution for boundaries.

Parameters:
deltaint, default=2

Value that will be added to auto-detected resolution.

Returns:
Geocoder

Geocoder object specification.

Examples

1from IPython.display import display
2from lets_plot import *
3from lets_plot.geo_data import *
4LetsPlot.setup_html()
5countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
6display(countries)
7ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
country found name geometry
0 Germany Germany MULTIPOLYGON (((5.97574 50.80235, 6.02503 50.8...
1 Poland Poland MULTIPOLYGON (((14.24606 53.89950, 14.27857 53...