docs: def findAddressCandidates(self,
                                addressDict=None,
                                singleLine=None,
                                maxLocations=10,
                                outFields="*",
                                outSR=4326,
                                searchExtent=None,
                                location=None,
                                distance=2000,
                                magicKey=None,
                                category=None):
          """
          The findAddressCandidates operation is performed on a geocode
          service resource. The result of this operation is a resource
          representing the list of address candidates. This resource provides
          information about candidates, including the address, location, and
          match score. Locators published using ArcGIS Server 10 or later
          support the single line address field for the findAddressCandidates
          operation.
          You can provide arguments to the findAddressCandidates operation as
          query parameters defined in the following parameters table:
  
          Inputs:
              addressDict - The various address fields accepted by the
               corresponding geocode service. These fields are listed in the
               addressFields property of the JSON representation associated
               geocode service resource.
               Example: Suppose that addressFields of a geocode service
               resource includes fields with the following names: Street,
               City, State, and Zone. If you want to perform the
               findAddressCandidates operation by providing values for the
               Street and Zone fields, you'd set the query parameters as
               Street=380+New+York+St&Zone=92373
  
              singleLine - Specifies the location to be geocoded. The input
               address components are formatted as a single string. The
               singleLine parameter and <addressField> parameters should not
               be passed in the same request.
              maxLocations - The maximum number of locations to be returned
               by a search, up to the maximum number allowed by the geocode
               service. If not specified, the maximum number of candidates
               for which the service is configured will be returned.
              outFields - The list of fields to be included in the returned
               result set. This list is a comma-delimited list of field
               names. If you specify the shape field in the list of return
               fields, it is ignored. For non-intersection addresses, you can
               specify the candidate fields from the geocode service
               resource. For intersection addresses, you can specify the
               intersection candidate fields from the geocode service
               resource.
              outSR - The well-known ID (WKID) of the spatial reference or a
               spatial reference JSON object for the returned address
               candidates. For a list of valid WKID values, see Projected
               coordinate systems and Geographic coordinate systems.
              searchExtent - The spatial extent (bounding box) to be used in
               geocoding. The response will return only the candidates that
               are within this spatial extent. Unless the spatialReference is
               included in the searchExtent, the coordinates are assumed to
               be in the spatial reference of the locator.
               Simple syntax: <xmin>, <ymin>, <xmax>, <ymax>
              location - Defines an origin point location that is used with
               the distance parameter to sort geocoding candidates based on
               their proximity to the location. The distance parameter
               specifies the radial distance from the location in meters. The
               priority of candidates within this radius is boosted relative
               to those outside the radius. This is useful in mobile
               applications where a user searches for places in the vicinity
               of their current GPS location; the location and distance
               parameters can be used in this scenario. The location
               parameter can be specified without specifying a distance. If
               distance is not specified, it defaults to 2000 meters. The
               location can be represented with a simple comma-separated
               syntax (x,y), or as a JSON point object. If the spatial
               reference of the location coordinates is different than that
               of the geocode service, then it must be defined in the JSON
               object. If the comma-separated syntax is used, or if the
               spatial reference is not included in the JSON object, then the
               spatial reference of the location is assumed to be the same as
               that of the geocode service. This parameter was added at 10.3
               and is only supported by geocode services published with
               ArcGIS 10.3 for Server and later versions.
              distance - Specifies the radius of an area around a point
               location that is used to boost the rank of geocoding
               candidates so that candidates closest to the location are
               returned first. The distance value is in meters. If the
               distance parameter is specified, the location parameter must
               be specified as well. Unlike the searchExtent parameter, the
               location and distance parameters allow searches to extend
               beyond the specified search radius. They are not used to
               filter results, but rather to rank resulting candidates based
               on their distance from a location. You must pass a
               searchExtent value in addition to location and distance if you
               want to confine the search results to a specific area.
              magicKey - The findAddressCandidates operation retrieves
               results more quickly when you pass in valid singleLine and
               magicKey values than when you don't pass in magicKey. However,
               to get this advantage, you need to make a prior request to the
               suggest operation, which provides a magicKey. This may or may
               not be relevant to your workflow.
               The suggest operation is often called on to improve the user
               experience of search boxes by analyzing partial text and
               providing complete names of places, addresses, points of
               interest, and so on. For instance, typing Mbu into a search
               box offers Mbuji-Mayi, Democratic Republic of the Congo as a
               suggestion, so the user doesn't need to type the complete
               name.
               Looking at the suggestion process from another perspective, as
               the user types, the suggest operation performs a text search,
               which is a redundant part of the overall search that the
               findAddressCandidates operation can also perform. The user
               chooses a place name or type-narrowing the results to a
               specific record. The results from suggest include text and
               magicKey values that contain the information the user chose;
               passing these values from suggest into findAddressCandidates
               results in faster and more accurate find operations.
               In summary, using the magicKey parameter in
               findAddressCandidates is a two-step process:
                1. Make a request to suggest. The response includes text and
                   magicKey properties.
                2. Make a request to findAddressCandidates and pass in the
                   text and magicKey values returned from suggest as the
                   singleLine and magicKey input parameters respectively.
              category - The category parameter is only supported by geocode
               services published using StreetMap Premium locators.
          """
          url = self._url + "/findAddressCandidates"
          params = {
              "f" : "json",
              "distance" : distance
          }
          if addressDict is None and \
             singleLine is None:
              raise Exception("A singleline address or an address dictionary must be passed into this function")
          if not magicKey is None:
              params['magicKey'] = magicKey
          if not category is None:
              params['category'] = category
          if not addressDict is None:
              params = params.update(addressDict)
          if not singleLine is None:
              params['SingleLine'] = singleLine
          if not maxLocations is None:
              params['maxLocations'] = maxLocations
          if not outFields is None:
              params['outFields'] = outFields
          if not outSR is None:
              params['outSR'] = {"wkid": outSR}
          if not searchExtent is None:
              params['searchExtent'] = searchExtent
          if isinstance(location, Point):
              params['location'] = location.asDictionary
          elif isinstance(location, list):
              params['location'] = "%s,%s" % (location[0], location[1])
          return self._get(url=url,
                               param_dict=params,
                               securityHandler=self._securityHandler,
                               proxy_url=self._proxy_url,
                               proxy_port=self._proxy_port)