Find Address Candidates
The find_address_candidates tool forward-geocodes an address, postal code, or point of interest into one or more candidate locations using the first geocode service in your organization's utility services or another geocode service you specify.
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, postal code, or point of interest—into a list of candidate matches with coordinates and match scores.
Usage guidance
find_address_candidates provides an interface for performing geocoding operations against an ArcGIS Geocoding service using the Find Address Candidates API. The tool accepts a singleLine parameter for a free-text address, postal code, or point of interest (POI), and an optional output spatial reference (outWkid, default 4326) that controls the spatial reference of the returned coordinates.
Output
The tool 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
xandycoordinates 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
singleLinesimple. Most requests work best when thesingleLinefield 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
singleLineto help disambiguate ambiguous location names.Prefer
searchExtentfor geographic anchors. When the conversation provides a geographic anchor—a current map extent, a city already on screen, a prior geocode result—pass it in thesearchExtentbounding box rather than stuffing it intosingleLine. Structured extent filtering is more reliable than free-text disambiguation.Be explicit about extent spatial reference. The tool passes
searchExtentto the geocode service as provided and does not assign a spatial reference to it. If the extent does not include its ownspatialReference, the geocode service applies its default behavior, which may not match the coordinates you supplied. When mixing coordinate systems, set the extent'sspatialReferenceexplicitly to avoid incorrect results.
Choosing a geocode service
By default, find_address_candidates uses the first geocode service listed in your organization's utility services. You can instead target a specific geocoder with one of two optional parameters:
geocodeServerName—The name of a geocode service available in your organization's utility services. The value must match one of the configured utility-service names.geocodeServerUrl—The URL of a geocode service, supplied without the protocol (for example,datahub.esriuk.com/arcgis/rest/services/gb_locators/os_open_names_locator/GeocodeServer).
If both are provided, geocodeServerUrl takes precedence over geocodeServerName. If neither is provided, the first geocode service in the organization's utility services is used. Generally, use the default unless the client clearly asks for a different geocoder.
When to use
- The client wants to forward-geocode an address, postal code, or POI—using either the organization's default geocode service or a specific geocode service selected by name (
geocodeServerName) or URL (geocodeServerUrl). If both are given, the URL takes precedence.
When not to use
- The client needs to reference a geocode service by item ID.
find_address_candidatesselects a geocode service by name or URL only—it does not accept an item ID.
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.
Note:
These prompts are for illustration only. Before you use them, modify them to match the data published in your ArcGIS Enterprise environment.
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 organization's locator service.
Use the USA_Locator in my organization's utility services to find 1600 Pennsylvania Avenue NW, Washington DC.
With output spatial reference
Use my organization's geocoding service to find 'Chicago, IL' and return coordinates in Web Mercator.
Geocode '90210' using the USA_Locator published in my organization's utility services and give me the WGS84 coordinates.
With search extent
Use my organization's geocoding service to find 'Springfield' within the state of Illinois bounding box.
Use the USA_Locator service in my organization's utility services to search for 'Main Street' limited to California's extent.
Ambiguity and scoring tests
Run 'Washington' through my organization's geocoding service and show me all the candidates with their scores.
Use my organization's 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 organization's utility services.
Use my organization's geocoding service to find 'xkzqp blorp 99999' and report the result.