class_docstr: Geocoder using the OpenCageData API.
  
  Documentation at:
      https://opencagedata.com/api
  
  .. versionchanged:: 2.2
      Improved error handling by using the default errors map
      (e.g. to raise :class:`.exc.GeocoderQuotaExceeded` instead of
      :class:`.exc.GeocoderQueryError` for HTTP 402 error)
class_docstr_tok: ["Geocoder","using","the","OpenCageData","API",".","Documentation","at",":","https",":","\/\/opencagedata.com\/api","..","versionchanged",":",":","2.2","Improved","error","handling","by","using","the","default","errors","map","(","e.g",".","to","raise",":","class",":","`",".exc.GeocoderQuotaExceeded","`","instead","of",":","class",":","`",".exc.GeocoderQueryError","`","for","HTTP","402","error",")"]
docstr: Return a location point by address.
  
  :param str query: The address or query you wish to geocode.
  
  :type bounds: list or tuple of 2 items of :class:`geopy.point.Point` or
      ``(latitude, longitude)`` or ``"%(latitude)s, %(longitude)s"``.
  :param bounds: Provides the geocoder with a hint to the region
      that the query resides in. This value will help the geocoder
      but will not restrict the possible results to the supplied
      region. The bounds parameter should be specified as 2
      coordinate points -- corners of a bounding box.
      Example: ``[Point(22, 180), Point(-22, -180)]``.
  
  :param country: Restricts the results to the specified
      country or countries. The country code is a 2 character code as
      defined by the ISO 3166-1 Alpha 2 standard (e.g. ``fr``).
      Might be a Python list of strings.
  :type country: str or list
  
  :param str language: an IETF format language code (such as `es`
      for Spanish or pt-BR for Brazilian Portuguese); if this is
      omitted a code of `en` (English) will be assumed by the remote
      service.
  
  :param bool annotations: Enable
      `annotations <https://opencagedata.com/api#annotations>`_
      data, which can be accessed via :attr:`.Location.raw`.
      Set to False if you don't need it to gain a little performance
      win.
  
      .. versionadded:: 2.2
  
  :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.
  
  :rtype: ``None``, :class:`geopy.location.Location` or a list of them, if
      ``exactly_one=False``.
docstr_tok: ["Return","a","location","point","by","address",".",":","param","str","query",":","The","address","or","query","you","wish","to","geocode",".",":","type","bounds",":","list","or","tuple","of","2","items","of",":","class",":","`","geopy.point.Point","`","or","``","(","latitude",",","longitude",")","``","or","``","``","%","(","latitude",")","s",",","%","(","longitude",")","s","''","``",".",":","param","bounds",":","Provides","the","geocoder","with","a","hint","to","the","region","that","the","query","resides","in",".","This","value","will","help","the","geocoder","but","will","not","restrict","the","possible","results","to","the","supplied","region",".","The","bounds","parameter","should","be","specified","as","2","coordinate","points","--","corners","of","a","bounding","box",".","Example",":","``","[","Point","(","22",",","180",")",",","Point","(","-22",",","-180",")","]","``",".",":","param","country",":","Restricts","the","results","to","the","specified","country","or","countries",".","The","country","code","is","a","2","character","code","as","defined","by","the","ISO","3166-1","Alpha","2","standard","(","e.g",".","``","fr","``",")",".","Might","be","a","Python","list","of","strings",".",":","type","country",":","str","or","list",":","param","str","language",":","an","IETF","format","language","code","(","such","as","`","es","`","for","Spanish","or","pt-BR","for","Brazilian","Portuguese",")",";","if","this","is","omitted","a","code","of","`","en","`","(","English",")","will","be","assumed","by","the","remote","service",".",":","param","bool","annotations",":","Enable","`","annotations","<","https",":","\/\/opencagedata.com\/api","#","annotations",">","`","_","data",",","which","can","be","accessed","via",":","attr",":","`",".Location.raw","`",".","Set","to","False","if","you","do","n't","need","it","to","gain","a","little","performance","win",".","..","versionadded",":",":","2.2",":","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",".",":","rtype",":","``","None","``",",",":","class",":","`","geopy.location.Location","`","or","a","list","of","them",",","if","``","exactly_one=False","``","."]
code: def geocode(
      self,
      query,
      *,
      bounds=None,
      country=None,
      language=None,
      annotations=True,
      exactly_one=True,
      timeout=DEFAULT_SENTINEL,
  ):
      """
      Return a location point by address.
  
      :param str query: The address or query you wish to geocode.
  
      :type bounds: list or tuple of 2 items of :class:`geopy.point.Point` or
          ``(latitude, longitude)`` or ``"%(latitude)s, %(longitude)s"``.
      :param bounds: Provides the geocoder with a hint to the region
          that the query resides in. This value will help the geocoder
          but will not restrict the possible results to the supplied
          region. The bounds parameter should be specified as 2
          coordinate points -- corners of a bounding box.
          Example: ``[Point(22, 180), Point(-22, -180)]``.
  
      :param country: Restricts the results to the specified
          country or countries. The country code is a 2 character code as
          defined by the ISO 3166-1 Alpha 2 standard (e.g. ``fr``).
          Might be a Python list of strings.
      :type country: str or list
  
      :param str language: an IETF format language code (such as `es`
          for Spanish or pt-BR for Brazilian Portuguese); if this is
          omitted a code of `en` (English) will be assumed by the remote
          service.
  
      :param bool annotations: Enable
          `annotations <https://opencagedata.com/api#annotations>`_
          data, which can be accessed via :attr:`.Location.raw`.
          Set to False if you don't need it to gain a little performance
          win.
  
          .. versionadded:: 2.2
  
      :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.
  
      :rtype: ``None``, :class:`geopy.location.Location` or a list of them, if
          ``exactly_one=False``.
  
      """
      params = {
          "key": self.api_key,
          "q": query,
      }
      if not annotations:
          params["no_annotations"] = 1
      if bounds:
          params["bounds"] = self._format_bounding_box(
              bounds, "%(lon1)s,%(lat1)s,%(lon2)s,%(lat2)s"
          )
      if language:
          params["language"] = language
  
      if not country:
          country = []
      if isinstance(country, str):
          country = [country]
      if country:
          params["countrycode"] = ",".join(country)
  
      url = "?".join((self.api, urlencode(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/opencage.py
imports: from functools import partial
  from urllib.parse import urlencode
  from geopy.exc import GeocoderServiceError
  from geopy.geocoders.base import DEFAULT_SENTINEL, ERROR_CODE_MAP, Geocoder
  from geopy.location import Location
  from geopy.util import logger
label_desc: Use image node_id 2 for calling the OpenCage obj's underlying member method code with example usage: obj.geocode(query) and returns: self