Localized input field names

Both batch geocoding and multifield geocoding utilize the same input address component fields: Address, Neighborhood, City, Subregion, Region, CountryCode, Postal, and PostalExt. These fields are described in the findAddressCandidates topic. They are used as a generic way to represent the components of a street address within any country. However, different terms may be used to refer to the same address components in different countries, and the terms may have various translations as well, depending on the locale. For instance, in Spain, the Address component is translated as Dirección; in Italy, it is Indirizzo.

Developers integrating the World Geocoding Service into their application need to know the appropriate input field names to use for the language and country of their users. This information can be obtained from the service info page: http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson. The info page contains the localized versions of the input field names for all of the countries and languages supported by the service.

The addressFields object in the info page contains descriptions for each of the input address fields for multifield addresses. Each address field is specified by its name, followed by a list of primary localized names for the field (the localizedNames object), and a list of valid alternate localized names for the field (the recognizedNames object). The localizedNames and recognizedNames are sorted by locale; each locale is represented by either a two-digit language code, or a two-digit language code and two-digit country code pair. For the language codes, the ISO 639-1 standard is followed. For country codes, the ISO 3166-1-alpha-2 standard is used.

NoteNote:

The localization information provided in the service info is only intended to be used for localization of field names in a user interface context. Localized input field names cannot be passed to the service in a request; only the input fields described in findAddressCandidates are valid when sending a batch geocoding request or multiple input field request to the service.

See the following abbreviated snippet from the service info, which shows the Address field with a portion of its localizedNames and recognizedNames.

"addressFields": [
  {
   "name": "Address",
   "localizedNames": {
    "de": "Adresse",
    "de-at": "Strasse"
    "de-de": "Adresse",
    "en": "Address",
    "en-ar": "Address",

   "recognizedNames": {
    "de": [
     "Adresse",
     "Anschrift",
     "Hausanschrift",
     "Strasse",
     "Straße"
    ],
    "de-at": [
     "Anschrift",
     "Hausanschrift",
     "Strasse",
     "Straße"
    ],
    "de-de": [
     "Adresse"
    ],
    "en": [
     "Address",
     "Street",
     "Street Address"
    ],
    "en-ar": [
     "Address",
     "Street",
     "Street Address"
    ],

localizedNames

Refer to the localizedNames object in the snippet above. The rows representing the localized field names are in the format <language - optional country>: <localized name>. See the row "de": "Adresse". In this row, "de" is the language code for German. Since there is no corresponding country code, in this case "Adresse" is the global, noncountry-specific German version of the Address field name. In the row "de-at": "Strasse", "de" is the language code for German and "at" is the country code for Austria, so "Strasse" is the German language version of the Address field name specific to Austria.

The localizedNames values represent the most appropriate translations for the address field names by language and country. They can be used to provide the address field name labels in an application which supports multifield geocoding in various locales. For example, the terms "Address", "City", "Region", and "Postal" will have no meaning for a user in Austria who speaks German. For such a scenario, a developer can query the service info for the Austrian German (de-at) versions of these fields and use them as the input field labels in the user interface (UI) for their application.

The localizedNames values can similarly be used in an application that supports batch geocoding. Typically, in batch geocoding applications, there is a UI for mapping the fields in the input address table to the standardized address fields expected by the application. For users in Austria, the expected name for the Address field in such a UI would be "Strasse". For example, imagine a user has a table of addresses in which the street address component is contained in a field named "Street Address". When the user specifies this table as the input for batch geocoding, they would need to map their "Street Address" field to the "Strasse" expected field in the UI. A developer can query the localizedNames object in the service info for the localized names in the appropriate locale and set them as the expected address field names in this type of application.

recognizedNames

Refer to the recognizedNames object in the snippet above. The rows representing the alternate localized field names are in the format <language - optional country>: <[alternate names]>. See the row beginning with "de-at" in the recognizedNames section.

"de-at": [
     "Anschrift",
     "Hausanschrift",
     "Strasse",
     "Straße"
    	]
Again, "de" is the language code for German and "at" is the country code for Austria, so the values in the array that follows are the German language alternate names for "Address" that are specific to residents of Austria.

The values in the recognizedNames object can be used by a developer of a batch geocoding application for automatic field mapping. As explained in the localizedNames section above, batch geocoding applications generally include a UI for mapping the fields in the input address table to the address fields expected by the application. To simplify the user experience, the developer may specify certain input table field names to automatically map to the corresponding expected address fields in the UI. Consider the "de-at" scenario. The developer has already determined that the German-Austria translation of "Address" is "Strasse" and has set this as the expected address field name in their batch geocoding UI. By querying the recognizedNames object in the Address field name section of the service info for "de-at", they can obtain all the valid German-Austria names for "Strasse". Now when the user specifies their address table for batch geocoding, the application can analyze the field names in the table; if either "Anschrift", "Hausanschrift", "Strasse", or "Straße" is detected as a field name, the application can automatically map it to the "Strasse" (Address) field in the UI.

Single-line batch geocoding input

Tables containing addresses in a single field can be batch geocoded as well. The service info contains localizedNames and recognizedNames values for the SingleLine input field within the singleLineAddressField object of the service info. A developer can query this object to obtain the valid translations for "SingleLine" in various languages and language or country locales.

Supported countries

The service info also provides a list of all the countries supported by the World Geocoding Service. The countries object in the service info contains an array of two-digit country codes representing the supported countries. A developer can query this object to verify whether a particular country is supported before querying the service info for the localized and recognized names of address fields in that country.

3/3/2017