class_docstr: Geocoder using the IGN France GeoCoder OpenLS API.
  
  Documentation at:
      https://geoservices.ign.fr/services-web-essentiels
class_docstr_tok: ["Geocoder","using","the","IGN","France","GeoCoder","OpenLS","API",".","Documentation","at",":","https",":","\/\/geoservices.ign.fr\/services-web-essentiels"]
docstr: Return a location point by address.
  
  :param str query: The query string to be geocoded.
  
  :param str query_type: The type to provide for geocoding. It can be
      `PositionOfInterest`, `StreetAddress` or `CadastralParcel`.
      `StreetAddress` is the default choice if none provided.
  
  :param int maximum_responses: The maximum number of responses
      to ask to the API in the query body.
  
  :param str is_freeform: Set if return is structured with
      freeform structure or a more structured returned.
      By default, value is False.
  
  :param str filtering: Provide string that help setting geocoder
      filter. It contains an XML string. See examples in documentation
      and ignfrance.py file in directory tests.
  
  :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","query","string","to","be","geocoded",".",":","param","str","query_type",":","The","type","to","provide","for","geocoding",".","It","can","be","`","PositionOfInterest","`",",","`","StreetAddress","`","or","`","CadastralParcel","`",".","`","StreetAddress","`","is","the","default","choice","if","none","provided",".",":","param","int","maximum_responses",":","The","maximum","number","of","responses","to","ask","to","the","API","in","the","query","body",".",":","param","str","is_freeform",":","Set","if","return","is","structured","with","freeform","structure","or","a","more","structured","returned",".","By","default",",","value","is","False",".",":","param","str","filtering",":","Provide","string","that","help","setting","geocoder","filter",".","It","contains","an","XML","string",".","See","examples","in","documentation","and","ignfrance.py","file","in","directory","tests",".",":","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,
      *,
      query_type="StreetAddress",
      maximum_responses=25,
      is_freeform=False,
      filtering=None,
      exactly_one=True,
      timeout=DEFAULT_SENTINEL,
  ):
      """
      Return a location point by address.
  
      :param str query: The query string to be geocoded.
  
      :param str query_type: The type to provide for geocoding. It can be
          `PositionOfInterest`, `StreetAddress` or `CadastralParcel`.
          `StreetAddress` is the default choice if none provided.
  
      :param int maximum_responses: The maximum number of responses
          to ask to the API in the query body.
  
      :param str is_freeform: Set if return is structured with
          freeform structure or a more structured returned.
          By default, value is False.
  
      :param str filtering: Provide string that help setting geocoder
          filter. It contains an XML string. See examples in documentation
          and ignfrance.py file in directory tests.
  
      :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``.
  
      """
  
      # Check if acceptable query type
      if query_type not in [
          "PositionOfInterest",
          "StreetAddress",
          "CadastralParcel",
      ]:
          raise GeocoderQueryError(
              """You did not provided a query_type the
              webservice can consume. It should be PositionOfInterest,
              'StreetAddress or CadastralParcel"""
          )
  
      # Check query validity for CadastralParcel
      if query_type == "CadastralParcel" and len(query.strip()) != 14:
          raise GeocoderQueryError(
              """You must send a string of fourteen
                  characters long to match the cadastre required code"""
          )
  
      sub_request = """
                  <GeocodeRequest returnFreeForm="{is_freeform}">
                      <Address countryCode="{query_type}">
                          <freeFormAddress>{query}</freeFormAddress>
                          {filtering}
                      </Address>
                  </GeocodeRequest>
          """
  
      xml_request = self.xml_request.format(
          method_name="LocationUtilityService",
          sub_request=sub_request,
          maximum_responses=maximum_responses,
      )
  
      # Manage type change for xml case sensitive
      if is_freeform:
          is_freeform = "true"
      else:
          is_freeform = "false"
  
      # Manage filtering value
      if filtering is None:
          filtering = ""
  
      # Create query using parameters
      request_string = xml_request.format(
          is_freeform=is_freeform,
          query=query,
          query_type=query_type,
          filtering=filtering,
      )
  
      params = {"xls": request_string}
  
      url = "?".join((self.api, urlencode(params)))
  
      logger.debug("%s.geocode: %s", self.__class__.__name__, url)
      callback = partial(
          self._parse_xml,
          is_freeform=is_freeform,
          exactly_one=exactly_one,
      )
      return self._request_raw_content(url, callback, timeout=timeout)
  
file_path: geopy/geopy/geocoders/ignfrance.py
imports: import warnings
  import xml.etree.ElementTree
  from functools import partial
  from urllib.parse import urlencode
  from geopy.exc import GeocoderQueryError
  from geopy.geocoders.base import DEFAULT_SENTINEL, Geocoder
  from geopy.location import Location
  from geopy.util import logger
label_desc: Use image node_id 2 for calling the IGNFrance obj's underlying member method code with example usage: obj.geocode(query) and returns: self