Geocoding Addresses

Introduction

In this tutorial, you will learn how to geocode addresses using the Forward and Reverse Geocoding Modes in the Geocoder transformer. In Exercise 1, you will use the Forward Mode by reading a spreadsheet that contains a list of schools with the address attributes in a single column. Similarly, in Exercise 2, you will use the Reverse Mode by reading a spreadsheet that contains a list of schools with the corresponding latitude and longitude coordinates to derive the address information.

Geocoding services return the address as a single formatted string, which may not be the shape you need. In Exercise 3, you will break the full JSON response from a geocoding service into a consistent set of address components: address number, street, city, state, and postal code. This is especially important when your geocoded results need to adhere to a specific schema.

Data Source

The source dataset for part 1 is a Microsoft Excel file containing school addresses for the City of Vancouver.

The source dataset for part 2 is a JSON file containing latitude and longitude locations for schools in Vancouver.

Step-by-step Instructions

Exercise 1: Forward Geocoding

In this scenario, you will be geocoding using the address attribute from an Excel file to derive X and Y coordinates in the LL84 coordinate system. This tutorial uses the OpenStreetMap geocoding service to obtain latitude and longitude coordinates for schools in Vancouver.

1. Create a New Workspace

Open FME Workbench and create a blank workspace.

2. Add a Microsoft Excel Reader

Add a Microsoft Excel reader to the canvas by clicking on the Reader button on the top menu bar or by going to Readers > Add Reader. In the Add Reader dialog, select Microsoft Excel as the Format, then for Dataset, browse to the SchoolAddresses.xlsx dataset, which is available for download from the Files section of this article.

The Excel Workbook contains three attribute columns: School Name, School Category, and Address. Use the Address column to geocode the schools and obtain their coordinates in the LL84 coordinate system.

3. Forward Geocode

Click on the SchoolAddress reader feature type to select it. Then add a Geocoder transformer to the canvas by typing “Geocoder” to bring up the list of FME Transformers in the Quick Add Search. Select the Geocoder from the list of Transformers by double-clicking it, or use the arrow keys and Enter to add it.

Double-click on the Geocoder to open the parameters. In the parameters, change the Geocoding Service to OpenStreetMap. Then set the Mode to Forward and select the ADDRESS attribute for Street Address.

For more information on the geocoding services available in the Geocoder package, see the Geocoder Documentation. Additionally, many services restrict how you may use or display their results and may produce different address formats. Check the terms and conditions with your chosen service.

4. Run Workspace

Add an Inspector to the canvas and connect it to the Geocoder Output port. Additionally, connect a Logger to the Geocoder <Rejected> output port. If the geocoding service can’t find any addresses, log them via the Logger and continue the translation.

Run the workspace by clicking the Run button on the top toolbar, or by selecting Run > Run Workspace from the top menu bar.

After running the workspace, the Visual Preview will show point features for all the schools, including their addresses and Lat/Long.

34 addresses were rejected. These may have been rejected due to spelling or address format.

Exercise 2: Reverse Geocoding

In this scenario, you will be geocoding using the latitude and longitude attributes from a JSON file to derive postal address information. This tutorial will utilize the OpenStreetMap geocoding service to obtain school addresses in the Vancouver area.

1. Create a New Workspace

Open FME Workbench and create a blank workspace.

2. Add a JSON (JavaScript Object Notation) Reader

Add a JSON (JavaScript Object Notation) reader to the canvas by clicking on the Reader button on the top menu bar or by going to Readers > Add Reader. In the Add Reader dialog, select JSON (JavaScript Object Notation) as the Format, then for Dataset, browse to the SchoolCoords.json dataset, which is available for download from the Files section of this article.

As of FME 2025.2, the Coordinate System parameter is now configured within the Parameters dialog of each reader/writer format. For more information, including details about the change and affected transformers, please see Coordinate System Parameter Location Change.

3. Reverse Geocode

Click on the SchoolCoords reader feature type to select it. Then add a Geocoder transformer to the canvas by typing “Geocoder” to bring up the list of FME Transformers in the Quick Add Search. Select the Geocoder from the list of Transformers by double-clicking it, or use the arrow keys and Enter to add it.

Double-click on the Geocoder to open the parameters. In the parameters, change the Geocoding Service to OpenStreetMap. Then change the Mode to Reverse and set the Latitude and Longitude parameters to their corresponding values.

4. Run Workspace

Add an Inspector to the canvas and connect it to the Geocoder Output port. Additionally, connect a Logger to the Geocoder <Rejected> output port. If the geocoding service can’t find any coordinates, log them via the Logger and continue the translation.

Run the workspace by clicking the Run button on the top toolbar, or by selecting Run > Run Workspace from the top menu bar.

After running the workspace, the Visual Preview will show point features for all the schools, including their addresses and Lat/Long.

Exercise 3: Normalize Geocoding Results

Exercise 2 produced an _address attribute that holds the full address as one comma-separated string. If you choose to, you could parse the string and assign the pieces to their respective attributes. However, when the number and order of pieces aren't stable, this becomes much harder to normalize. 

From OpenStreetMap, here are a few examples of how an address could appear:

• Anchor Point 3, 1333, Hornby Street, Granville, Downtown, Vancouver, Metro Vancouver Regional District, British Columbia, V6Z 1W7, Canada
• Keefer Street, Strathcona, Vancouver, Metro Vancouver Regional District, British Columbia, V6A 1Z3, Canada
• 3505, West 7th Avenue, Kitsilano, Vancouver, Metro Vancouver Regional District, British Columbia, V6R 2B1, Canada

The fix is to stop parsing the formatted string and work with the full structured response instead. The service already knows which piece is the street and which is the postal code in the full JSON response.

In this exercise, you will extend the Exercise 2 workspace to produce five consistent attributes: AddressNumber, Street, City, Province, and PostalCode. Use these to freely manipulate the output address structure, especially if you need a format different from the default.

1. Open the Reverse Geocoding Workspace

Continue with the workspace from Exercise 2, or open Exercise3_Complete.fmwt. This exercise uses OpenStreetMap; the same method works for any service, but the JSON queries will differ. See Adapting to Other Services below.

Turn on feature caching (Run > Enable Feature Caching) so you can inspect the response repeatedly without re-calling the service.

2. Enable the Full JSON Response

Open the Geocoder parameters and expand the Advanced section. Set the following parameter:

• Include Full JSON Response: Yes

3. Run the Workspace and Inspect the Response

Geocoding services meter requests, so limit your input while testing queries. You can do this through a Sampler, or by setting Max Features to Read on the reader.

Run the workspace with caching enabled, then click the green eye icon on the Geocoder Output port to view the cached data. Alongside the usual output attributes, an attribute called _json_response now holds the complete response from the service.

Select a feature and preview the _json_response. The address components are nested inside an address object:

Compared to the flat _address string for the same feature, there is much more detail.

4. Add a JSONExtractor

Add a JSONExtractor and connect it to the Geocoder Output port. In the parameter dialog, set the following:

• JSON Document: _json_response
• Extract Queries:
  • Query 1:
    • Target Attribute: addressnumber
    • JSON Query: json["address"]["house_number"]
  • Query 2:
    • Target Attribute: street
    • JSON Query: json["address"]["road"]
  • Query 3: 
    • Target Attribute: city
    • JSON Query: json["address"]["city"]
  • Query 4:
    • Target Attribute: province
    • JSON Query: json["address"]["state"]
  • Query 5:
    • Target Attribute: postalcode
    • JSON Query: json["address"]["postcode"]

For more resources on JSON Queries in FME, see the Additional Resources section.

5. Add an AttributeManager

Add an AttributeManager and connect its Input port to the JSONExtractor Evaluated output port. Create a new attribute:

• Input Attribute: normalized_address
• Output Attribute: normalized_address
• Value: @Value(addressnumber), @Value(street), @Value(city), @Value(province), @Value(postalcode)
• Action: Set Value

Finally, remove any attributes you don’t need in a second AttributeManager. This leaves each feature with only the attributes you need.

6. Run the Workspace

Move the Inspector from the Geocoder Output port to the AttributeManager Output Port. Run the workspace and inspect the output.

Additional Resources

JSONExtractor Transformer [Documentation]

Tutorial: Getting Started with JSON [Article]

Transforming JSON using the JSONExtractor, JSONFlattener, and JSONFragmenter [Article]

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.