Access an existing locator connection from a script

Last Published: April 25, 2020


Online locators can be accessed through an ArcCatalog GIS server connection. When a connection is created in ArcCatalog, an .ags file is created in the user's Windows login profile. The instructions provided describe how to access an existing locator connection from a Python script.


When a script is run outside of the ArcGIS environment, such as from a command line, batch file, or application, it references a folder in the user profile.

The following list gives the locations of this folder by operating system, where %USERPROFILE% corresponds to a folder such as
'c:\users\<username>' or 'c:\documents and settings\<username>.'
Windows XP: %USERPROFILE%\Application Data\ESRI\Desktop10.0\ArcCatalog
Windows Server: %USERPROFILE%\AppData\Roaming\ESRI\ArcCatalog
Windows 7: %USERPROFILE%\AppData\Roaming\ESRI\Desktop10.0\ArcCatalog

The user profile contains an .ags file, such as 'premiumlocators.ags,' with the connection path and credentials for the service.

Examples of the connection string format in a script are provided below.
For premium locators: GIS Servers\\premiumtasks\\Locators\\TA_BatchAddress_NA.GeocodeServer
For standard locators: GIS Servers\\arcgisonline\\Locators\\TA_Streets_US.GeocodeServer

The steps below describe how to use the server connection information in a script.

Run a task from a different user profile

To use the connection credentials located in one user profile while running a task in a different user profile, copy the .ags file to the corresponding location in the second user profile.

Run applications outside of a user profile with no credentials

To run an application outside of a user profile without credentials, add syntax, such as the following, within the script.

pathToAGS = r"C:\Users\<username>\AppData\Roaming\ESRI\Desktop10.0\ArcCatalog”
agsName = “premiumtasks” # for an AGS file called premiumtasks.ags
locatorName = “Locators\TA_Address_NA.GeocodeServer"
Locator = os.path.join(pathToAGS, agsName, locatorName)

In this case, the full path would appear as follows.


Obtain the full string for a specific locator

1. In the Geocode Addresses tool, click the Browse button for the Input Address Locator field.
2. Browse to the .ags file on disk. It is displayed as a server connection name in the dialog (for instance, 'arcgis on' if the task has not been renamed or 'premiumtasks' if it has been renamed).
3. Double-click the connection name to view the contents.
4. Browse to the exact locator desired within that connection.

The .ags file can be accessed from anywhere on disk using the syntax given above.

Article ID:000011322

  • ArcMap

Get help from ArcGIS experts

Contact technical support

Download the Esri Support App

Go to download options

Related Information

Discover more on this topic