lets_plot.geo_data.NamesGeocoder

class lets_plot.geo_data.NamesGeocoder(level: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]] = None, request: Optional[Union[str, List[str], pandas.core.series.Series]] = 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: Optional[Union[str, lets_plot.geo_data.gis.request.LevelKind]] = None, request: Optional[Union[str, List[str], pandas.core.series.Series]] = None)

Initialize self.

scope(scope) → lets_plot.geo_data.geocoder.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.50721 36.72540, -86.50738 ...
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 Region [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) → lets_plot.geo_data.geocoder.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: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, lets_plot.geo_data.geocoder.Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]]) → lets_plot.geo_data.geocoder.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() → lets_plot.geo_data.geocoder.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 Deutschland MULTIPOLYGON (((8.45947 47.59135, 8.48145 47.5...
1 Hungary Magyarország MULTIPOLYGON (((17.31445 45.98170, 17.29248 45...
ignore_all_errors() → lets_plot.geo_data.geocoder.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() → lets_plot.geo_data.geocoder.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: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, state: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, country: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, lets_plot.geo_data.gis.request.MapRegion, List]] = None, scope: Optional[Union[str, lets_plot.geo_data.geocodes.Geocodes, Geocoder, shapely.geometry.Polygon]] = None, closest_to: Optional[Union[lets_plot.geo_data.geocodes.Geocodes, shapely.geometry.Point]] = 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 Deutschland MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1 Poland Polska MULTIPOLYGON (((22.89551 49.03787, 22.89551 49...
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 Deutschland POINT (10.57925 51.16420)
1 Poland Polska 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 Deutschland [10.5792501010919, 51.1642031371593] [5.86631566286087, 47.2701117396355, 15.041808... [5.86631566286087, 47.2701117396355, 15.041808...
1 60189 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 Deutschland POLYGON ((15.04181 47.27011, 15.04181 55.05857...
1 Poland Polska 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 Deutschland MULTIPOLYGON (((7.47070 49.15297, 7.47070 49.1...
1 Poland Polska MULTIPOLYGON (((22.89551 49.03787, 22.89551 49...