find_address_candidates

The find_address_candidates tool forward-geocodes an address, place name, postal code, or point of interest into one or more candidate locations using the ArcGIS World Geocoding Service or a portal-configured geocoder.

Tool Name

find_address_candidates

Tool Alias

Find Address Candidates

Objective

Perform a forward-geocoding operation that converts a free-text location string—such as an address, place name, postal code, or point of interest—into a list of candidate matches with coordinates and match scores.

Description

find_address_candidates provides an interface for performing geocoding operations against an ArcGIS Geocode Server using the Find Address Candidates API. The input schema exposes a singleLine field that accepts a free-text address, place name, postal code, or POI, plus an optional output spatial reference (outWkid, default 4326) that controls the spatial reference of the returned coordinates.

Output

The output schema returns:

  • The spatial reference of the returned coordinates.
  • A list of candidate results—up to 5 candidates—each containing:
  • An address string.
  • A location with x and y coordinates in the requested spatial reference.
  • A set of attributes that further describe the candidate (GeocodeServer-defined fields).
  • A score from 0 to 100, where higher means a better match.

When ambiguity matters, prefer the highest-scoring candidate. Consider warning the user if even the top score is low.

Building good geocode requests

  • Keep singleLine simple. Most requests work best when the singleLine field contains just the location string. Adding too many qualifiers can confuse the geocoder.
  • Use prior context to disambiguate. If the user's intended location is already clear from the conversation, you can include extra context in singleLine to help disambiguate ambiguous place names.
  • Prefer searchExtent for geographic anchors. When the conversation provides a geographic anchor—a current map extent, a city already on screen, a prior geocode result—pass it via the searchExtent bounding box rather than stuffing it into singleLine. Structured extent filtering is more reliable than free-text disambiguation.
  • Be explicit about extent spatial reference. If searchExtent is provided without its own spatialReference, it is assumed to be in the same SR as outWkid (default 4326). When mixing coordinate systems, set the extent's spatialReference explicitly to avoid silent reprojection bugs.

When to use

  • The client wants to perform a geocoding operation without specifying a custom Geocode Server.

When not to use

  • The client wants to specify a particular GeocodeServer by URL, item ID, or name. find_address_candidates is intended for use with the ArcGIS World Geocoding Service or a portal-configured geocoder, and does not expose inputs for selecting a custom geocoder.

Schema

The full JSON Schema definitions for the input parameters accepted by find_address_candidates and the output payload it returns are provided as separate files alongside this document.

Input schema

The input schema describes the singleLine query, the optional output spatial reference (outWkid, default 4326), and the optional searchExtent bounding box used to disambiguate ambiguous place names.

Download or view FindAddressCandidatesToolInputSchema.json

Output schema

The output schema describes the response object: the spatial reference of the returned coordinates and an array of up to five candidate results, each including an address, a location, attribute fields, and a 0–100 match score.

Download or view FindAddressCandidatesToolOutputSchema.json

Sample prompts to test the tool

Send any of the prompts below to your MCP-compatible AI client to verify that find_address_candidates is working correctly. The prompts are grouped to exercise different inputs and behaviors—from a basic geocode against a named service to spatial-reference output, search-extent disambiguation, candidate scoring, and graceful handling of out-of-coverage or nonsense input.

Explicit service reference

  • Find Yellowstone National Park using the geocoding service published in my ArcGIS Enterprise.
  • Geocode '350 Fifth Avenue, New York, NY' using my Enterprise locator service.
  • Use the USA_Locator in my ArcGIS Enterprise to find 1600 Pennsylvania Avenue NW, Washington DC.

With output spatial reference

  • Use my Enterprise geocoding service to find 'Chicago, IL' and return coordinates in Web Mercator.
  • Geocode '90210' using the USA_Locator published in my ArcGIS Enterprise and give me the WGS84 coordinates.

With search extent

  • Use my ArcGIS Enterprise geocoder to find 'Springfield' within the state of Illinois bounding box.
  • Use the USA_Locator service in my Enterprise to search for 'Main Street' limited to California's extent.

Ambiguity and scoring tests

  • Run 'Washington' through my ArcGIS Enterprise geocoding service and show me all the candidates with their scores.
  • Use my Enterprise locator to geocode 'Main Street' and tell me how many candidates were returned.

Expected failure cases

  • Try to geocode '10 Downing Street, London' using the USA_Locator in my ArcGIS Enterprise.
  • Use my Enterprise geocoding service to find 'xkzqp blorp 99999' and report the result.