Skip to main content

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 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 location 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 in 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. The tool passes searchExtent to the geocode service as provided and does not assign a spatial reference to it. If the extent does not include its own spatialReference, the geocode service applies its default behavior, which may not match the coordinates you supplied. When mixing coordinate systems, set the extent's spatialReference explicitly 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_candidates selects 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.