class_docstr: Nominatim geocoder for OpenStreetMap data.
  
  Documentation at:
      https://nominatim.org/release-docs/develop/api/Overview/
  
  .. attention::
     Using Nominatim with the default `user_agent` is strongly discouraged,
     as it violates Nominatim's Usage Policy
     https://operations.osmfoundation.org/policies/nominatim/
     and may possibly cause 403 and 429 HTTP errors. Please make sure
     to specify a custom `user_agent` with
     ``Nominatim(user_agent="my-application")`` or by
     overriding the default `user_agent`:
     ``geopy.geocoders.options.default_user_agent = "my-application"``.
     An exception will be thrown if a custom `user_agent` is not specified.
class_docstr_tok: ["Nominatim","geocoder","for","OpenStreetMap","data",".","Documentation","at",":","https",":","\/\/nominatim.org\/release-docs\/develop\/api\/Overview\/","..","attention",":",":","Using","Nominatim","with","the","default","`","user_agent","`","is","strongly","discouraged",",","as","it","violates","Nominatim","'s","Usage","Policy","https",":","\/\/operations.osmfoundation.org\/policies\/nominatim\/","and","may","possibly","cause","403","and","429","HTTP","errors",".","Please","make","sure","to","specify","a","custom","`","user_agent","`","with","``","Nominatim","(","user_agent=","''","my-application","''",")","``","or","by","overriding","the","default","`","user_agent","`",":","``","geopy.geocoders.options.default_user_agent","=","``","my-application","''","``",".","An","exception","will","be","thrown","if","a","custom","`","user_agent","`","is","not","specified","."]
docstr: Return a location point by address.
  
  :param query: The address, query or a structured query
      you wish to geocode.
  
      For a structured query, provide a dictionary whose keys
      are one of: `street`, `city`, `county`, `state`, `country`, or
      `postalcode`. For more information, see Nominatim's
      documentation for `structured requests`:
  
          https://nominatim.org/release-docs/develop/api/Search
  
  :type query: dict or str
  
  :param bool exactly_one: Return one result or a list of results, if
      available.
  
  :param int timeout: Time, in seconds, to wait for the geocoding service
      to respond before raising a :class:`geopy.exc.GeocoderTimedOut`
      exception. Set this only if you wish to override, on this call
      only, the value set during the geocoder's initialization.
  
  :param int limit: Maximum amount of results to return from Nominatim.
      Unless exactly_one is set to False, limit will always be 1.
  
  :param bool addressdetails: If you want in *Location.raw* to include
      address details such as house_number, city_district, postcode, etc
      (in a structured form) set it to True
  
  :param str language: Preferred language in which to return results.
      Either uses standard
      `RFC2616 <http://www.ietf.org/rfc/rfc2616.txt>`_
      accept-language string or a simple comma-separated
      list of language codes.
  
  :param str geometry: If present, specifies whether the geocoding
      service should return the result's geometry in `wkt`, `svg`,
      `kml`, or `geojson` formats. This is available via the
      `raw` attribute on the returned :class:`geopy.location.Location`
      object.
  
  :param bool extratags: Include additional information in the result if available,
      e.g. wikipedia link, opening hours.
  
  :param country_codes: Limit search results
      to a specific country (or a list of countries).
      A country_code should be the ISO 3166-1alpha2 code,
      e.g. ``gb`` for the United Kingdom, ``de`` for Germany, etc.
  
  :type country_codes: str or list
  
  :type viewbox: list or tuple of 2 items of :class:`geopy.point.Point` or
      ``(latitude, longitude)`` or ``"%(latitude)s, %(longitude)s"``.
  
  :param viewbox: Prefer this area to find search results. By default this is
      treated as a hint, if you want to restrict results to this area,
      specify ``bounded=True`` as well.
      Example: ``[Point(22, 180), Point(-22, -180)]``.
  
  :param bool bounded: Restrict the results to only items contained
      within the bounding ``viewbox``.
  
  :param str featuretype: If present, restrict results to certain type of features.
      Allowed values: `country`, `state`, `city`, `settlement`.
  
  :param bool namedetails: If you want in *Location.raw* to include
      namedetails, set it to True. This will be a list of alternative names,
      including language variants, etc.
  
  :rtype: ``None``, :class:`geopy.location.Location` or a list of them, if
      ``exactly_one=False``.
docstr_tok: ["Return","a","location","point","by","address",".",":","param","query",":","The","address",",","query","or","a","structured","query","you","wish","to","geocode",".","For","a","structured","query",",","provide","a","dictionary","whose","keys","are","one","of",":","`","street","`",",","`","city","`",",","`","county","`",",","`","state","`",",","`","country","`",",","or","`","postalcode","`",".","For","more","information",",","see","Nominatim's","documentation","for","`","structured","requests","`",":","https",":","\/\/nominatim.org\/release-docs\/develop\/api\/Search",":","type","query",":","dict","or","str",":","param","bool","exactly_one",":","Return","one","result","or","a","list","of","results",",","if","available",".",":","param","int","timeout",":","Time",",","in","seconds",",","to","wait","for","the","geocoding","service","to","respond","before","raising","a",":","class",":","`","geopy.exc.GeocoderTimedOut","`","exception",".","Set","this","only","if","you","wish","to","override",",","on","this","call","only",",","the","value","set","during","the","geocoder","'s","initialization",".",":","param","int","limit",":","Maximum","amount","of","results","to","return","from","Nominatim",".","Unless","exactly_one","is","set","to","False",",","limit","will","always","be","1.",":","param","bool","addressdetails",":","If","you","want","in","*","Location.raw","*","to","include","address","details","such","as","house_number",",","city_district",",","postcode",",","etc","(","in","a","structured","form",")","set","it","to","True",":","param","str","language",":","Preferred","language","in","which","to","return","results",".","Either","uses","standard","`","RFC2616","<","http",":","\/\/www.ietf.org\/rfc\/rfc2616.txt",">","`","_","accept-language","string","or","a","simple","comma-separated","list","of","language","codes",".",":","param","str","geometry",":","If","present",",","specifies","whether","the","geocoding","service","should","return","the","result","'s","geometry","in","`","wkt","`",",","`","svg","`",",","`","kml","`",",","or","`","geojson","`","formats",".","This","is","available","via","the","`","raw","`","attribute","on","the","returned",":","class",":","`","geopy.location.Location","`","object",".",":","param","bool","extratags",":","Include","additional","information","in","the","result","if","available",",","e.g",".","wikipedia","link",",","opening","hours",".",":","param","country_codes",":","Limit","search","results","to","a","specific","country","(","or","a","list","of","countries",")",".","A","country_code","should","be","the","ISO","3166-1alpha2","code",",","e.g",".","``","gb","``","for","the","United","Kingdom",",","``","de","``","for","Germany",",","etc",".",":","type","country_codes",":","str","or","list",":","type","viewbox",":","list","or","tuple","of","2","items","of",":","class",":","`","geopy.point.Point","`","or","``","(","latitude",",","longitude",")","``","or","``","``","%","(","latitude",")","s",",","%","(","longitude",")","s","''","``",".",":","param","viewbox",":","Prefer","this","area","to","find","search","results",".","By","default","this","is","treated","as","a","hint",",","if","you","want","to","restrict","results","to","this","area",",","specify","``","bounded=True","``","as","well",".","Example",":","``","[","Point","(","22",",","180",")",",","Point","(","-22",",","-180",")","]","``",".",":","param","bool","bounded",":","Restrict","the","results","to","only","items","contained","within","the","bounding","``","viewbox","``",".",":","param","str","featuretype",":","If","present",",","restrict","results","to","certain","type","of","features",".","Allowed","values",":","`","country","`",",","`","state","`",",","`","city","`",",","`","settlement","`",".",":","param","bool","namedetails",":","If","you","want","in","*","Location.raw","*","to","include","namedetails",",","set","it","to","True",".","This","will","be","a","list","of","alternative","names",",","including","language","variants",",","etc",".",":","rtype",":","``","None","``",",",":","class",":","`","geopy.location.Location","`","or","a","list","of","them",",","if","``","exactly_one=False","``","."]
code: def geocode(
      self,
      query,
      *,
      exactly_one=True,
      timeout=DEFAULT_SENTINEL,
      limit=None,
      addressdetails=False,
      language=False,
      geometry=None,
      extratags=False,
      country_codes=None,
      viewbox=None,
      bounded=False,
      featuretype=None,
      namedetails=False,
  ):
      """
      Return a location point by address.
  
      :param query: The address, query or a structured query
          you wish to geocode.
  
          For a structured query, provide a dictionary whose keys
          are one of: `street`, `city`, `county`, `state`, `country`, or
          `postalcode`. For more information, see Nominatim's
          documentation for `structured requests`:
  
              https://nominatim.org/release-docs/develop/api/Search
  
      :type query: dict or str
  
      :param bool exactly_one: Return one result or a list of results, if
          available.
  
      :param int timeout: Time, in seconds, to wait for the geocoding service
          to respond before raising a :class:`geopy.exc.GeocoderTimedOut`
          exception. Set this only if you wish to override, on this call
          only, the value set during the geocoder's initialization.
  
      :param int limit: Maximum amount of results to return from Nominatim.
          Unless exactly_one is set to False, limit will always be 1.
  
      :param bool addressdetails: If you want in *Location.raw* to include
          address details such as house_number, city_district, postcode, etc
          (in a structured form) set it to True
  
      :param str language: Preferred language in which to return results.
          Either uses standard
          `RFC2616 <http://www.ietf.org/rfc/rfc2616.txt>`_
          accept-language string or a simple comma-separated
          list of language codes.
  
      :param str geometry: If present, specifies whether the geocoding
          service should return the result's geometry in `wkt`, `svg`,
          `kml`, or `geojson` formats. This is available via the
          `raw` attribute on the returned :class:`geopy.location.Location`
          object.
  
      :param bool extratags: Include additional information in the result if available,
          e.g. wikipedia link, opening hours.
  
      :param country_codes: Limit search results
          to a specific country (or a list of countries).
          A country_code should be the ISO 3166-1alpha2 code,
          e.g. ``gb`` for the United Kingdom, ``de`` for Germany, etc.
  
      :type country_codes: str or list
  
      :type viewbox: list or tuple of 2 items of :class:`geopy.point.Point` or
          ``(latitude, longitude)`` or ``"%(latitude)s, %(longitude)s"``.
  
      :param viewbox: Prefer this area to find search results. By default this is
          treated as a hint, if you want to restrict results to this area,
          specify ``bounded=True`` as well.
          Example: ``[Point(22, 180), Point(-22, -180)]``.
  
      :param bool bounded: Restrict the results to only items contained
          within the bounding ``viewbox``.
  
      :param str featuretype: If present, restrict results to certain type of features.
          Allowed values: `country`, `state`, `city`, `settlement`.
  
      :param bool namedetails: If you want in *Location.raw* to include
          namedetails, set it to True. This will be a list of alternative names,
          including language variants, etc.
  
      :rtype: ``None``, :class:`geopy.location.Location` or a list of them, if
          ``exactly_one=False``.
  
      """
  
      if isinstance(query, collections.abc.Mapping):
          params = {
              key: val
              for key, val in query.items()
              if key in self.structured_query_params
          }
      else:
          params = {"q": query}
  
      params.update({"format": "json"})
  
      if exactly_one:
          params["limit"] = 1
      elif limit is not None:
          limit = int(limit)
          if limit < 1:
              raise ValueError("Limit cannot be less than 1")
          params["limit"] = limit
  
      if viewbox:
          params["viewbox"] = self._format_bounding_box(
              viewbox, "%(lon1)s,%(lat1)s,%(lon2)s,%(lat2)s"
          )
  
      if bounded:
          params["bounded"] = 1
  
      if not country_codes:
          country_codes = []
      if isinstance(country_codes, str):
          country_codes = [country_codes]
      if country_codes:
          params["countrycodes"] = ",".join(country_codes)
  
      if addressdetails:
          params["addressdetails"] = 1
  
      if namedetails:
          params["namedetails"] = 1
  
      if language:
          params["accept-language"] = language
  
      if extratags:
          params["extratags"] = True
  
      if geometry is not None:
          geometry = geometry.lower()
          if geometry == "wkt":
              params["polygon_text"] = 1
          elif geometry == "svg":
              params["polygon_svg"] = 1
          elif geometry == "kml":
              params["polygon_kml"] = 1
          elif geometry == "geojson":
              params["polygon_geojson"] = 1
          else:
              raise GeocoderQueryError(
                  "Invalid geometry format. Must be one of: "
                  "wkt, svg, kml, geojson."
              )
  
      if featuretype:
          params["featureType"] = featuretype
  
      url = self._construct_url(self.api, params)
      logger.debug("%s.geocode: %s", self.__class__.__name__, url)
      callback = partial(self._parse_json, exactly_one=exactly_one)
      return self._call_geocoder(url, callback, timeout=timeout)
  
file_path: geopy/geopy/geocoders/nominatim.py
imports: import collections.abc
  from functools import partial
  from urllib.parse import urlencode
  from geopy.exc import ConfigurationError, GeocoderQueryError
  from geopy.geocoders.base import _DEFAULT_USER_AGENT, DEFAULT_SENTINEL, Geocoder
  from geopy.location import Location
  from geopy.util import logger
label_desc: Use image node_id 3 for calling the Nominatim obj's underlying member method code with example usage: obj.geocode(query) and returns: self