FME Transformers: 2024.1
FME Transformers: 2024.1
Geocoder
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 Address Batch Geocoding |
Single free-form street address or discrete street address elements to latitude/longitude values, submitted as a batch request. Batch geocoding requests are not submitted concurrently. |
Forward IP Address Geocoding |
IP address string to latitude/longitude values |
Forward Address Geocoding to Service ID |
Single free-form street address or discrete street address elements to a service-specific identifier |
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 |
Reverse Street Address Geocoding from Service ID |
Service specific lookup key to a single street address string |
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.
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
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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. |
_key |
A service ID for the geocoded address |
_precision_code, _precision_level |
Precision information about a geocoded result. |
_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.
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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.
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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. |
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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. |
Connection |
Some services require a web connection, which can be created within the Geocoder or through Tools -> FME Options -> Web Connections. |
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. |
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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. |
Country |
The name of the country, for use in 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). |
Batch Size |
If batch geocoding is supported for a service and a batch geocoding mode is selected, this value is used to control the size of batch requests submitted. The geocoding service documentation should be consulted to determine the appropriate batch size for a service. Recommended batch size may vary based on factors such as data quality. If errors occur, consider reducing the batch size. |
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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. If a batch geocoding method mode was selected, the value of this parameter will be ignored. |
Include Full JSON Response |
If Yes, an attribute named json_response will be included on the output feature, containing the raw JSON response from the geocoding service. |
Verify HTTPS Certificates |
This controls whether HTTPS certificates should be verified when making web requests. The value of this parameter will override the Verify HTTPS Certificates parameter which may be defined by a web connection used when using the ArcGIS Server geocoding service. |
Geocoding Services
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
The following services are supported:
Service |
Modes |
---|---|
ArcGIS Online |
Forward, Forward (Batch), Reverse |
ArcGIS Server |
Forward, Forward (Batch), 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 |
Precisely |
Forward, Reverse, Forward to Key, Reverse From Key |
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.
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
ArcGIS Online |
This service type makes use of a published geocoding service or locator view hosted on ArcGIS Online or a local ArcGIS Server installation. The World Geocoding service provided by Esri is used by default. To access this geocoding service, you need to provide valid ArcGIS Online access credentials. Contact Esri to set up your own ArcGIS Online account: https://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. For more information on batch geocoding, please see |
ArcGIS Server |
This service type makes use of a published geocoding service or locator view 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. For more information on batch geocoding, please see |
Bing |
To access this geocoding service, you will 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 can use a Geocoder.ca web connection or provide valid Geocoder.ca access credentials. Contact Geocoder.ca to set up your own account: https://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: https://geocoder.ca/?terms=1. |
|
To access this geocoding service, you can use a Google web connection or 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 will 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 can use an ipstack web connection or 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 can use an OpenCage web connection or 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: https://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: https://operations.osmfoundation.org/policies/nominatim/. |
Precisely |
To access this geocoding service, you need to provide valid access credentials. Contact Precisely to set up your account: https://developer.precisely.com/ 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://developer.precisely.com/pricing. |
TAMU (Texas A&M University Geoservices) |
To access this geocoding service, you can use a TAMU web connection or provide valid access credentials. Contact Texas A&M Geoservices to set up your own account: https://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: https://geoservices.tamu.edu/About/Legal. |
Editing Transformer Parameters
Transformer parameters can be set by directly entering values, using expressions, or referencing other elements in the workspace such as attribute values or user parameters. Various editors and context menus are available to assist. To see what is available, click beside the applicable parameter.
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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.
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.
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
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. |
![Closed](../Skins/Default/Stylesheets/Images/transparent.gif)
Table Tools
Transformers with table-style parameters have additional tools for populating and manipulating values.
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.
For more information, see Transformer Parameter Menu Options.
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, Open Government Licence - British Columbia, and/or Open Government Licence – Canada.