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.
Gestion des entités rejetées : ce paramètre permet d'interrompre la traduction ou de la poursuivre lorsqu'elle rencontre une entité rejetée. Ce paramètre est disponible à la fois comme option par défaut de FME et comme paramètre de traitement.
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. |
Éditer les paramètres des Transformers
À l'aide d'un ensemble d'options de menu, les paramètres du Transformer peuvent être attribués en faisant référence à d'autres éléments du traitement. Des fonctions plus avancées, telles qu'un éditeur avancé et un éditeur arithmétique, sont également disponibles dans certains Transformers. Pour accéder à un menu de ces options, cliquez sur 
à côté du paramètre applicable. Pour plus d'informations, voir Options de menus et paramètres de Transformer.
Définir les valeurs
Il existe plusieurs façons de définir une valeur à utiliser dans un Transformer. La plus simple est de simplement taper une valeur ou une chaîne de caractères, qui peut inclure des fonctions de différents types comme des références d'attributs, des fonctions mathématiques et de chaînes de caractères, et des paramètres d'espace de travail. Il existe un certain nombre d'outils et de raccourcis qui peuvent aider à construire des valeurs, généralement disponibles dans le menu contextuel déroulant adjacent au champ de valeur.
Définir des valeurs de paramètres
Utilisation de l'éditeur de texte
L'éditeur de texte fournit un moyen efficace de construire des chaînes de textes (dont les expressions régulières) à partir de données source diverses, telles que des attributs, des paramètres et des constantes, et le résultat est directement utilisé dans le paramètre.
Utilisation de l'éditeur arithmétique
L'éditeur arithmétique fournit un moyen simple de construire des expressions mathématiques à partir de plusieurs données source, telles que des attributs et des fonctions, et le résultat est directement utilisé dans un paramètre.
Valeur conditionnelle
Définit des valeurs selon un ou plusieurs tests.
Fenêtre de définition de conditions
Contenu
Les expressions et chaînes de caractères peuvent inclure des fonctions, caractères, paramètres et plus.
Lors du paramétrage des valeurs - qu'elles soient entrées directement dans un paramètre ou construites en utilisant l'un des éditeurs - les chaînes de caractères et les expressions contenant des fonctions Chaîne de caractères, Math, Date et heure ou Entité FME auront ces fonctions évaluées. Par conséquent, les noms de ces fonctions (sous la forme @<nom_de_fonction>) ne doivent pas être utilisés comme valeurs littérales de chaîne de caractères.
Types de contenu
| Ces fonctions manipulent les chaînes de caractères. | |
|
Caractères spéciaux |
Un ensemble de caractères de contrôle est disponible dans l'éditeur de texte. |
| Plusieurs fonctions sont disponibles dans les deux éditeurs. | |
| Fonctions Date/heure | Les fonctions de dates et heures sont disponibles dans l'Editeur texte. |
| Ces opérateur sont disponibles dans l'éditeur arithmétique. | |
| Elles retournent des valeurs spécifiques aux entités. | |
| Les paramètres FME et spécifiques au projet peuvent être utilisés. | |
| Créer et modifier un paramètre publié | Créer ses propres paramètres éditables. |
Options - Tables
Les Transformers avec des paramètres de style table possèdent des outils additionnels pour remplir et manipuler des valeurs.
Outils de tableau
|
Réordonner
|
Activé une fois que vous avez cliqué sur un élément de ligne. Les choix comprennent :
|
|
Couper, Copier et Coller
|
Activé une fois que vous avez cliqué sur un élément de ligne. Les choix comprennent :
Copier, copier et coller peuvent être utilisés au sein d'un Transformer ou entre Transfromers. |
|
Filtre
|
Commencez à taper une chaîne de caractères, et la matrice n'affichera que les lignes correspondant à ces caractères. Recherche dans toutes les colonnes. Cela n'affecte que l'affichage des attributs dans le Transformer - cela ne change pas les attributs qui sont sortis. |
|
Importer
|
Le bouton d'import remplit la table avec un jeu de nouveaux attributs lus depuis un jeu de données. L'application spécifique varie selon les Transformers. |
|
Réinitialiser/Rafraîchir
|
Réinitialise la table à son état initial, et peut fournir des options additionnelles pour supprimer des entrées invalides. Le comportement varie d'un Transformer à l'autre. |
Note : Tous les outils ne sont pas disponibles dans tous les 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
FME Community iest l'endroit où trouver des démos, des tutoriaux, des articles, des FAQ et bien plus encore. Obtenez des réponses à vos questions, apprenez des autres utilisateurs et suggérez, votez et commentez de nouvelles entités.
Search for all results about the Geocoder on the FME Community.
Les exemples peuvent contenir des informations sous licence Open Government - Vancouver et/ou Open Government - Canada.