Typical Uses
- Find coordinates and create geometry for a list of street addresses
- Find addresses that match coordinates
How does it work?
The Geocoder provides a single interface to numerous geocoding web services. Once a service is selected, the appropriate parameters are presented, including connection credentials and the expected attributes the service needs to perform geocoding.
As features pass through the transformer, these attributes are passed to the service, and the results retrieved.
If the feature is successfully matched by the service, the results (attributes and/or geometry) are added to the feature and it is output through the Output port.
If the feature geocoding fails for any reason (including addresses not found, invalid coordinates, or failed credential authentication), it is output through the <Rejected> port.
Modes
The Geocoder can perform a variety of tasks, dependent upon which service you choose to use. Each service will provide one or more of these modes of geocoding:
|
Forward Street Address Geocoding |
Single free form street address to latitude/longitude values, for example: "7445, 132nd Street, Surrey, BC, V3W 1J8" Discrete street address elements to latitude/longitude values, for example: "7445" "132nd" "Street" "Surrey" "BC" "V3W 1J8" |
|
Forward IP Address Geocoding |
IP address string to latitude/longitude values |
|
Reverse Street Address Geocoding |
Latitude/longitude values to a single street address string |
|
Reverse Elevation Geocoding |
Latitude/longitude values to elevation in meters |
|
Reverse Timezone Geocoding |
Latitude/longitude values to timezone code, name and offset |
The geocoding service result is stored in output feature attributes, feature geometry, or both. For example, latitude/longitude output is represented on the feature as a point geometry, and also as ‘_latitude’ and ‘_longitude’ attributes.
Examples
Example: Creating point geometry and finding coordinates for a list of addresses
In this example, a spreadsheet containing a list of businesses, with address components spread over a series of columns, is geocoded and output to KML.
The geocoding will be done using the Google service, which expects to see addresses in a free-form single attribute, so a new attribute - “Address” - is created using the AttributeManager. This new attribute contains the complete address, with components separated by commas:
In the Geocoder, selecting Google as the Service brings up their required parameters. The API key provides authentication, the default geocoding mode of “Forward” is selected, and the Street Address is set to the newly constructed “Address” attribute.
Expanding the Output on the Geocoder now shows the additional attributes available from the service - some of which have been included in the KML writer, as indicated in green. And though we have chosen to include latitude and longitude as attributes, point geometry is also being created for the features (regardless of whether or not the information is retained as an attribute, as done here.)
The results are output to a KML file.
Usage Notes
- Many services have restrictions on how their results may be used or displayed. Check with your chosen service for terms and conditions. See available services.
- The expected input address format varies between services. See documentation provided by your chosen service for details.
- If you need to create address strings for your chosen service, you can build them right in the Geocoder using the Text Editor, or consider using the AttributeManager to construct them as persistent attributes.
Configuration
Input Ports
Input
This transformer accepts any feature. Attribute data will be used as specified to produce a geocoding result. Different services will require different sets of attributes.
- Street address geocoding requires either a single line freeform address string or discrete address elements (such as street address, city etc.)
- IP address geocoding accepts IPv4 or IPv6 addresses, such as 199.7.157.0, or 2001:0db8:0a0b:12f0:0000:0000:0000:0001.
- Reverse Geocoding accepts a pair of latitude/longitude attributes.
Input feature geometry is not used as input. If input from the geometry is desired the CoordinateExtractor can be used to extract the x and y coordinates from a point geometry to attributes on the feature.
Output Ports
Output
When the geocoding lookup is successful, the transformer will output the feature with added attributes and replaced geometry. Possible added attributes:
|
_address |
A single-line address |
|
_address_json |
A multipart address in JSON format (if geocoder result fields are not predictable). |
|
_latitude, _longitude |
Latitude, Longitude |
|
_elevation_meters, _elevation_feet, _elevation_resolution |
Elevation in meters and feet, as well as margin of error in elevation value. |
|
_timezone |
Timezone short code. Example: America/Vancouver |
|
_timezone_name |
Timezone description. Example: Pacific Daylight Time |
|
_timezone_offset |
Offset from UTC in seconds. May be negative or positive. |
|
_timezone_current_dst |
Current offset in seconds from standard time during daylight saving time. Typically 0 or 3600, but other values are possible. |
Note that attributes may be output in a corrected form from how they were entered.
For example, supplying “7445 132 street, surrey, bc” for forward geocoding might result in an output ‘_address’ attribute value of “7445 132 St, Surrey, BC V3W, Canada”. This can be a useful result for standardization of address data.
<Rejected>
Features that cause the operation to fail are output through this port. This could be caused by an invalid address, latitude/longitude coordinates that are not on the Earth, or a missing or invalid API key, among other reasons. Additionally, the attributes ‘fme_rejection_code’ and ‘fme_rejection_message’ will contain details about the failure. The original geometry is preserved.
Rejected Feature Handling: can be set to either terminate the translation or continue running when it encounters a rejected feature. This setting is available both as a default FME option and as a workspace parameter.
Parameters
This is a complete list of possible parameters for all services accessed by the Geocoder. Only the service-specific required parameters will be shown in the transformer once a service has been chosen.
Service
| Geocoding Service |
Select which service to use for geocoding requests. The service also determines which geocoding modes are available in the transformer interface. Some services support only IP addresses, while others support house addresses, or latitude/longitude pairs. For details on the available services, see Geocoding Services below. |
Connection
Certain providers require the user to specify additional credentials, for example an API key, or a username and password, before performing the geocoding. Custom URLs are also required or allowed for some services.
|
URL |
The URL field points to an alternative server location. This will usually be a self-hosted version of the online product, often using the customer’s own data instead of the generic, worldwide dataset available to the public. |
|
Authentication Type |
If a service supports more than one way of connecting, the choice will be available here. |
|
API Key |
Some services require the use of an API key, which is typically obtained by registering on the service website. Services that require a key cannot be used without one, typically because it is a paid service or enforces limits. Services where a key is optional generally provide improved performance or higher limits with a key than for unregistered users. |
|
Username/Password Client/Secret App ID/App Code |
Some services require or allow authentication with a username and password, App ID and App Code, or client key and secret. |
Geocoding Parameters
This is the full list of possible parameters from all services. Note that every service will not support every parameter listed below.
|
Mode |
If the chosen service supports multiple geocoding modes, they will be available for selection here; for example, the Google service supports Forward, Reverse, Elevation, and Timezone modes. If not, forward geocoding is always assumed. This choice also determines which input mode becomes active. Forward geocoding accepts input in the form of a street or IP address, while elevation, reverse, and timezone geocoding take in latitude and longitude for input. |
|
Street Address |
For a single line address, a comma-separated list of the address elements. For example, 123 Main Street, Surrey, BC, Canada. This string may be easily constructed from separate attributes, if required, by using the text editor to combine them right in the transformer, or using the AttributeManager earlier in the workspace. Note that some services are more lenient than others when it comes to the format of the address string. For discrete address elements, the street address will typically contain only the house number and street name. For example, 123 Main Street. This is used in conjunction with other fields to specify a full address. |
|
City |
The name of the city, for use in discrete address specification. |
|
Province/State |
The full name or abbreviation for the province or state component of a discrete address specification. |
|
Postal/ZIP Code |
The postal code or zip code component of a discrete address specification. |
|
Latitude/Longitude |
Distinct values for a latitude longitude pair. Example: Latitude: 49.1044 Longitude: -122.8011 |
|
Radius |
Search radius around a given coordinate. |
|
Out Fields |
Select additional attributes to include on the output feature. The values of these attributes will be taken directly from the geocoding server response. |
|
IP Address |
An IPv4 or IPv6 address. Example: 199.7.157.0, or 2001:0db8:0a0b:12f0:0000:0000:0000:0001 |
|
Return Language |
For some services, a language for geocoding results can be specified. This will usually apply to corrected addresses for forward geocoding as well as reverse geocoding result addresses. Example: Reverse geocoding 52.07, 4.28 will return “The Hague” in English (en), but “Den Haag” in Dutch (nl). |
Advanced
|
Timeout |
The user may optionally provide a value in this field to set the maximum amount of time, in seconds, to spend waiting on a single request. After the specified amount of time, if a request has not completed, the request will be retried, to a maximum of 3 attempts. If it does not succeed, the feature will be output with an error code. |
|
Maximum Concurrent Requests |
This specifies the number of geocoding requests to make in parallel. Please note that this may incur rate limiting from the geocoding service. The Geocoder will automatically wait and retry the request to a maximum of 3 attempts after a failure due to rate limiting. |
|
Include Full JSON Response |
If Yes, an attribute named |
|
Verify HTTPS Certificates |
This controls whether HTTPS certificates should be verified when making web requests. The value of this parameter will override the Verify SSL Certificates parameter which may be defined by a web connection used when using the ArcGIS Server geocoding service. |
Geocoding Services
Geocoding Services and Available Modes
The following services are supported:
|
Service |
Modes |
|---|---|
| ArcGIS Online | Forward, Reverse |
| ArcGIS Server | Forward, Reverse |
| Bing | Forward, Reverse |
| Geocode.Farm | Forward, Reverse |
| Geocoder.ca | Forward, Reverse |
| Forward, Reverse, Elevation, Timezone | |
| HERE | Forward, Reverse |
| IPInfo.io | IP Address |
| ipstack | IP Address |
| OpenCage | Forward, Reverse |
| OpenStreetMap | Forward, Reverse |
| TAMU | Forward, with census region information |
Note that many services have additional requirements for use. A common requirement is that the resulting data be displayed on a map from the same service. Storage of result data in a database may also require additional fees. Please consult the terms of service of the geocoding providers (listed below) to ensure that your use is in compliance.
Geocoding Service Provider Information
| ArcGIS Online |
To access this geocoding service, you need to provide valid ArcGIS Online access credentials. Contact Esri to set up your own ArcGIS Online account: http://www.arcgis.com/features/plans/pricing.html. Note that use of this Geocoder transformer may use up credits and you may be subject to transaction limits. For more information, please see https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm. Please review the terms of service before use: https://developers.arcgis.com/terms. |
| ArcGIS Server |
This service type makes use of a published geocoder service on a local ArcGIS Server installation. It is recommended to use an Esri ArcGIS Portal web connection when attempting to access an authenticated server. You will be required to provide the URL to the specific Geocoding Server hosted on the Portal. For more information, please see https://enterprise.arcgis.com/en/server/latest/publish-services/windows/geocode-services.htm. |
| Bing |
To access this geocoding service, you need to provide valid Bing Maps access credentials. Contact Microsoft to set up your own Bing Maps account: https://www.microsoft.com/maps/Licensing/licensing.aspx. Note that use of this Geocoder transformer may use up credits and you may be subject to transaction limits. Please review the terms of service before use: https://www.microsoft.com/maps/product/terms.html. |
| Geocode.Farm |
To access this geocoding service, you need to provide valid Geocode.Farm access credentials. Contact Geocode.Farm to set up your own account: https://geocode.farm/register. Note that use of the Geocoder transformer with this service may use up credits and you may be subject to transaction limits. Please review the terms of service before use: https://geocode.farm/policies/terms-of-service. |
| Geocoder.ca |
To access this geocoding service, you need to provide valid Geocoder.ca access credentials. Contact Geocoder.ca to set up your own account: http://geocoder.ca/?register=1. Note that use of the Geocoder transformer with this service may use up credits and you may be subject to transaction limits. Please review the terms of service before use: http://geocoder.ca/?terms=1. |
|
|
To access this geocoding service, you need to provide a valid Google Maps Geocoding API key. Contact Google to set up your own account: https://developers.google.com/maps/documentation/geocoding/get-api-key. Note that use of the Geocoder transformer with this service may use up credits and you may be subject to transaction limits. For more information, please see https://developers.google.com/maps/documentation/geocoding/usage-limits. Please review the terms of service before use: https://developers.google.com/maps/terms. Important: The Google Maps Geocoding API may only be used in conjunction with displaying results on a Google map. It is prohibited to use Google Maps Geocoding API data without displaying a Google map. For more info, please see: https://developers.google.com/maps/documentation/geocoding/policies. |
|
HERE |
To access this geocoding service, you need to provide valid HERE access credentials. Contact HERE to set up your own account: https://developer.here.com/plans/api/geocoder. Note that use of this Geocoder transformer may use up credits and you may be subject to transaction limits. You are not allowed to display or visualize results on any third party content (such as map, views from streets, or satellite imagery) not owned by HERE. Please review the terms of service for important information on usage restrictions: https://developer.here.com/terms-and-conditions. |
|
IPInfo.io |
This geocoding service has limited transaction volumes based on your subscription level. Contact IPInfo.io to set up your own account: https://ipinfo.io/pricing. Please review the terms of service before use: https://ipinfo.io/developers. |
| ipstack |
To access this geocoding service, you need to provide a valid ipstack API key. To get an API key, create an account at https://ipstack.com/. ipstack is the successor to FreeGeoIP.net, which shut down on 2018-07-01. FreeGeoIP.net was removed from the Geocoder in FME 2018.1. Note that use of this Geocoder transformer with this service may use up credits and you may be subject to transaction limits. Please review the terms of service before use: https://ipstack.com/terms. |
|
OpenCage |
To access this geocoding service, you need to provide valid OpenCage Geocoder access credentials. Contact OpenCage Data to set up your own account: https://geocoder.opencagedata.com/pricing. Note that use of this Geocoder transformer may use up credits and you may be subject to transaction limits. Please review the terms of service before use: https://geocoder.opencagedata.com/terms. |
|
OpenStreetMap (Nominatim) |
This service is intended for use with a self-hosted Nominatim server. More information on installing a Nominatim server is available at: http://wiki.openstreetmap.org/wiki/Nominatim/Installation. To use your own server with the Geocoder, supply the full URL. This will typically end in “search” - for example, http://nominatim.example.com/search. OpenStreetMaps’s Nominatim server, while publicly available, is not intended for heavy use and has several usage restrictions which make it inappropriate for use with FME in almost all cases: http://wiki.openstreetmap.org/wiki/Nominatim_usage_policy. |
|
TAMU (Texas A&M University Geoservices) |
To access this geocoding service, you need to provide valid access credentials. Contact Texas A&M Geoservices to set up your own account: http://geoservices.tamu.edu/Pricing. Note that use of the Geocoder transformer with this service may use up credits and you may be subject to transaction limits. Please review the terms of service before use: http://geoservices.tamu.edu/About/Legal. |
Editing Transformer Parameters
Using a set of menu options, transformer parameters can be assigned by referencing other elements in the workspace. More advanced functions, such as an advanced editor and an arithmetic editor, are also available in some transformers. To access a menu of these options, click 
beside the applicable parameter. For more information, see Transformer Parameter Menu Options.
Defining Values
There are several ways to define a value for use in a Transformer. The simplest is to simply type in a value or string, which can include functions of various types such as attribute references, math and string functions, and workspace parameters. There are a number of tools and shortcuts that can assist in constructing values, generally available from the drop-down context menu adjacent to the value field.
How to Set Parameter Values
Using the Text Editor
The Text Editor provides a convenient way to construct text strings (including regular expressions) from various data sources, such as attributes, parameters, and constants, where the result is used directly inside a parameter.
Using the Arithmetic Editor
The Arithmetic Editor provides a convenient way to construct math expressions from various data sources, such as attributes, parameters, and feature functions, where the result is used directly inside a parameter.
Conditional Values
Set values depending on one or more test conditions that either pass or fail.
Parameter Condition Definition Dialog
Content
Expressions and strings can include a number of functions, characters, parameters, and more.
When setting values - whether entered directly in a parameter or constructed using one of the editors - strings and expressions containing String, Math, Date/Time or FME Feature Functions will have those functions evaluated. Therefore, the names of these functions (in the form @<function_name>) should not be used as literal string values.
Content Types
| These functions manipulate and format strings. | |
|
Special Characters |
A set of control characters is available in the Text Editor. |
| Math functions are available in both editors. | |
| Date/Time Functions | Date and time functions are available in the Text Editor. |
| These operators are available in the Arithmetic Editor. | |
| These return primarily feature-specific values. | |
| FME and workspace-specific parameters may be used. | |
| Creating and Modifying User Parameters | Create your own editable parameters. |
Dialog Options - Tables
Transformers with table-style parameters have additional tools for populating and manipulating values.
Table Tools
|
Row Reordering
|
Enabled once you have clicked on a row item. Choices include:
|
|
Cut, Copy, and Paste
|
Enabled once you have clicked on a row item. Choices include:
Cut, copy, and paste may be used within a transformer, or between transformers. |
|
Filter
|
Start typing a string, and the matrix will only display rows matching those characters. Searches all columns. This only affects the display of attributes within the transformer - it does not alter which attributes are output. |
|
Import
|
Import populates the table with a set of new attributes read from a dataset. Specific application varies between transformers. |
|
Reset/Refresh
|
Generally resets the table to its initial state, and may provide additional options to remove invalid entries. Behavior varies between transformers. |
Note: Not all tools are available in all transformers.
Reference
|
Processing Behavior |
|
|
Feature Holding |
No |
| Dependencies | External geocoding web service(s) |
| Aliases | |
| History | This FME Package transformer replaces the Geocoder originally shipped with FME 2021.1 and older versions. |
FME Community
The FME Community is the place for demos, how-tos, articles, FAQs, and more. Get answers to your questions, learn from other users, and suggest, vote, and comment on new features.
Search for all results about the Geocoder on the FME Community.
Examples may contain information licensed under the Open Government Licence – Vancouver and/or the Open Government Licence – Canada.