How to use the ArcGISOnlineFindAddressCandidate Custom Transformer

Files

Addresses.gdb.zip
- 700 KB
- Download

As of FME 2024.0, support for Esri ArcGIS Online (AGOL), ArcGIS Enterprise Portal, and ArcGIS Server Feature Service formats has transitioned to a unified approach using the new Esri ArcGIS Feature Service (Format). This format replaces the legacy reader/writer formats for each of the three services.

Starting in FME 2026.1, the legacy formats will be hidden in the Quick Add menu. Instead, equivalent functionality is now provided by the downloadable Esri ArcGIS Connector package, available on FME Hub. The package also includes new web services and key transformers such as the ArcGISOnlineConnector, ArcGISAttachmentConnector, and ArcGISBranchVersionManager. The package can be installed directly through the Quick Add menu in FME Workbench. Once installed, the new Esri Feature Service format will appear in the Gallery as a unified method for interacting with all three types of Esri ArcGIS Feature Services.

For details on this transition, including guidance on updating existing workspaces, please refer to the article: Working with Esri ArcGIS Feature Services in FME.

Introduction

The ArcGISOnlineFindAddressCandidate transformer uses the ArcGIS Online (AGOL) REST API to geocode addresses one location per request; the input address can be combined into a single input field or divided among multiple parameters. Check out some of the other ArcGIS Online custom transformers here: Getting Started with ArcGIS Online Custom Transformers.

What is ArcGIS Online?

ArcGIS Online is Esri’s cloud-based mapping software. It lets you build interactive web maps and provides analysis tools, such as the Routing Service, to gain location intelligence. ArcGIS Online enables you to work effectively across your organization by collaboratively building and using maps that you can share within your organization or publicly.

Requirements

ArcGIS Online Account with available credits

Step-By-Step Instructions

1. Download the Data
Either prepare your own data or download the Addresses.gdb zip file located in the Files section of this article.

2. Create a Workspace
Open FME Workbench and select Blank workspace to begin building your workflow on an empty canvas.

3. Add the Data to the Canvas
After unzipping the Addresses.gdb.zip that you have downloaded, add the Addresses.gdb to the canvas. You can achieve this by either adding a File Geodatabase Open API reader and browsing for the file, or drag and drop the file onto the canvas itself. Select OK.

Select the PostalAddress Feature Class when adding. Select OK again.

4. Add a Sampler
Add a Sampler with quick add by typing freely on the canvas. Choose a large number for the Sampling Rate and connect it to the reader.

This is because the transformer can only take one input at a time, making an individual HTTP request for every input feature, which would potentially take up more time. If you would like to input all points to be geocoded, then we suggest using the ArcGISOnlineBatchGeocoder.

5. Add an ArcGISOnlineFindAddressCandidate transformer
Next, add the ArcGISOnlineFindAddressCandidate custom transformer to the canvas. Connect the ArcGISOnlineFindAddressCandidate to the Sampler.

6. Using the ArcGIS Online API
In the ArcGISOnlineFindAddressCandidate parameters, select “Add Web Connection” from the drop-down of the AGOL Web Connection highlighted in red. Then give the connection a name and select “Authenticate” at the bottom. This will bring you to the authentication web connection page and prompt you for your username and password. This is needed because this service requires credits to complete the process.

7. Input Parameters
Our address is split into components for this dataset instead of a single line. Input the parameters as follows after choosing the components:

Address Line 1 = PSTLADDRESS
City = PSTLCITY
Region = PSTLPROV
Postal/Zip Code = POSTALCODE
Select a Country (optional) = Canada

8. Run the Workspace and View the Output
Run the workspace with Feature Caching Enabled, then view the output in Visual Preview. You will have four outputs from the ArcGISOnlineFindAddressCandidate transformer:

Output: This provides the input address as a Single Line, the split of each attribute based on commas, the X and Y coordinates, and the spatial reference number.
<Rejected>: Input features are output via this port if the API calls fail. Any error message is stored in the fme_rejection_message attribute.

Final Workspace

Additional Resources

Data Attribution

The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.