class_docstr: 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()`.
class_docstr_tok: ["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","(",")","`","."]
docstr: 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
  ----------
  name : str
      Name in `Geocoder` that needs better qualification.
  county : str
      If `Geocoder` has parent counties this field must be present to identify a row for the name.
  state : str
      If `Geocoder` has parent states this field must be present to identify a row for the name.
  country : str
      If `Geocoder` has parent countries this field must be present to identify a row for the name.
  scope : str 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_to : `Geocoder` or `shapely.geometry.Point`
      Resolve ambiguity by taking closest geoobject.
  
  Returns
  -------
  `NamesGeocoder`
      Geocoder object specification.
  
  Examples
  --------
  .. jupyter-execute::
      :linenos:
      :emphasize-lines: 6
  
      from IPython.display import display
      from lets_plot import *
      from lets_plot.geo_data import *
      LetsPlot.setup_html()
      city = geocode_cities('Warwick').countries('US')\
             .where(name='Warwick', country='US', scope='Massachusetts').get_centroids()
      display(city)
      ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
  
  |
  
  .. jupyter-execute::
      :linenos:
      :emphasize-lines: 7
  
      from IPython.display import display
      from lets_plot import *
      from lets_plot.geo_data import *
      LetsPlot.setup_html()
      closest_city = geocode_cities('Birmingham').get_centroids().iloc[0].geometry
      city = geocode_cities('Warwick')\
             .where(name='Warwick', closest_to=closest_city).get_centroids()
      display(city)
      ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
docstr_tok: ["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","--","--","--","--","--","name",":","str","Name","in","`","Geocoder","`","that","needs","better","qualification",".","county",":","str","If","`","Geocoder","`","has","parent","counties","this","field","must","be","present","to","identify","a","row","for","the","name",".","state",":","str","If","`","Geocoder","`","has","parent","states","this","field","must","be","present","to","identify","a","row","for","the","name",".","country",":","str","If","`","Geocoder","`","has","parent","countries","this","field","must","be","present","to","identify","a","row","for","the","name",".","scope",":","str","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_to",":","`","Geocoder","`","or","`","shapely.geometry.Point","`","Resolve","ambiguity","by","taking","closest","geoobject",".","Returns","--","--","--","-","`","NamesGeocoder","`","Geocoder","object","specification",".","Examples","--","--","--","--","..","jupyter-execute",":",":",":","linenos",":",":","emphasize-lines",":","6","from","IPython.display","import","display","from","lets_plot","import","*","from","lets_plot.geo_data","import","*","LetsPlot.setup_html","(",")","city","=","geocode_cities","(","'Warwick","'",")",".countries","(","'US","'",")","\\",".where","(","name='Warwick","'",",","country='US","'",",","scope='Massachusetts","'",")",".get_centroids","(",")","display","(","city",")","ggplot","(",")","+","geom_livemap","(",")","+","geom_point","(","data=city",",","color='red","'",",","size=5",")","|","..","jupyter-execute",":",":",":","linenos",":",":","emphasize-lines",":","7","from","IPython.display","import","display","from","lets_plot","import","*","from","lets_plot.geo_data","import","*","LetsPlot.setup_html","(",")","closest_city","=","geocode_cities","(","'Birmingham","'",")",".get_centroids","(",")",".iloc","[","0","]",".geometry","city","=","geocode_cities","(","'Warwick","'",")","\\",".where","(","name='Warwick","'",",","closest_to=closest_city",")",".get_centroids","(",")","display","(","city",")","ggplot","(",")","+","geom_livemap","(",")","+","geom_point","(","data=city",",","color='red","'",",","size=5",")"]
code: def where(
      self,
      name: str,
      county: Optional[parent_types] = None,
      state: Optional[parent_types] = None,
      country: Optional[parent_types] = None,
      scope: scope_types = None,
      closest_to: Optional[Union[Geocodes, ShapelyPointType]] = 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
          ----------
          name : str
              Name in `Geocoder` that needs better qualification.
          county : str
              If `Geocoder` has parent counties this field must be present to identify a row for the name.
          state : str
              If `Geocoder` has parent states this field must be present to identify a row for the name.
          country : str
              If `Geocoder` has parent countries this field must be present to identify a row for the name.
          scope : str 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_to : `Geocoder` or `shapely.geometry.Point`
              Resolve ambiguity by taking closest geoobject.
  
          Returns
          -------
          `NamesGeocoder`
              Geocoder object specification.
  
          Examples
          --------
          .. jupyter-execute::
              :linenos:
              :emphasize-lines: 6
  
              from IPython.display import display
              from lets_plot import *
              from lets_plot.geo_data import *
              LetsPlot.setup_html()
              city = geocode_cities('Warwick').countries('US')\\
                     .where(name='Warwick', country='US', scope='Massachusetts').get_centroids()
              display(city)
              ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
  
          |
  
          .. jupyter-execute::
              :linenos:
              :emphasize-lines: 7
  
              from IPython.display import display
              from lets_plot import *
              from lets_plot.geo_data import *
              LetsPlot.setup_html()
              closest_city = geocode_cities('Birmingham').get_centroids().iloc[0].geometry
              city = geocode_cities('Warwick')\\
                     .where(name='Warwick', closest_to=closest_city).get_centroids()
              display(city)
              ggplot() + geom_livemap() + geom_point(data=city, color='red', size=5)
  
          """
      self._reset_geocodes()
      query_spec = QuerySpec(
          name,
          _make_parent_region(county),
          _make_parent_region(state),
          _make_parent_region(country),
      )
  
      def query_exist(query):
          for i in range(len(self._names)):
              if (
                  query.name == self._names[i]
                  and query.country == _get_or_none(self._countries, i)
                  and query.state == _get_or_none(self._states, i)
                  and query.county == _get_or_none(self._counties, i)
              ):
                  return True
          return False
  
      if not query_exist(query_spec):
          parents: List[str] = []
          if query_spec.county is not None:
              parents.append("county={}".format(str(query_spec.county)))
  
          if query_spec.state is not None:
              parents.append("state={}".format(str(query_spec.state)))
  
          if query_spec.country is not None:
              parents.append(
                  "country={}".format(str(query_spec.country))
              )
  
          parents_str = ", ".join(parents)
          if len(parents_str) == 0:
              raise ValueError("{} is not found in names".format(name))
          else:
              raise ValueError(
                  "{}({}) is not found in names".format(
                      name, parents_str
                  )
              )
  
      if scope is None:
          new_scope = None
          ambiguity_resolver = _make_ambiguity_resolver(
              scope=None, closest_object=closest_to
          )
      else:
          if LazyShapely.is_polygon(scope):
              new_scope = None
              ambiguity_resolver = _make_ambiguity_resolver(
                  scope=scope, closest_object=closest_to
              )
          else:
              new_scope = _prepare_new_scope(scope)[0]
              ambiguity_resolver = _make_ambiguity_resolver(
                  scope=None, closest_object=closest_to
              )
  
      self._overridings[query_spec] = WhereSpec(
          new_scope, ambiguity_resolver
      )
      return self
  
imports: from collections import namedtuple
  from collections.abc import Iterable
  from typing import Union, List, Optional, Dict
  from pandas import Series
  from .geocodes import _to_level_kind, request_types, Geocodes, _raise_exception, _ensure_is_list
  from .gis.geocoding_service import GeocodingService
  from .gis.geometry import GeoRect, GeoPoint
  from .gis.request import RequestBuilder, GeocodingRequest, RequestKind, MapRegion, AmbiguityResolver, RegionQuery, LevelKind, IgnoringStrategyKind, PayloadKind, ReverseGeocodingRequest
  from .gis.response import Response, SuccessResponse
  from .type_assertion import assert_list_type
label_desc: Use image node_id 10 for calling the NamesGeocoder obj's underlying member method code with example usage: obj.where(name, county, state, country, scope, closest_to) and returns: self, False, True