World Geocoder (XWG)

This section defines the supported geocoding datasets, operations, and input and output field information for the World Geocoder.

Supported Data Sets

The following table lists the supported geocoding dataset(s) with the available geocoding levels for the World Geocoder.

Note: Custom User Dictionaries are not supported.
Data Set City Centroid Suburb/Village Centroid Postal Centroid Street Centroid Interpolated Street Address Point-level Address Point of Interest
TomTom, GeoNames, Pitney Bowes World data Yes Yes Yes No No No No

Supported Operations

The following operations are supported for the World Geocoder:
  • Geocoding—Takes one or more addresses as input and returns latitude/longitude coordinates and other information.

Postal Geocoding

The World Geocoder can geocode to a postal centroid if postcode information is available from the country. Postcode information can come from any of the data sources (TomTom, GeoNames, or Pitney Bowes). See Country Postal Data Coverage for a summary of postal data coverage. Depending on the country, postal geocoding may provide more accurate results that geographic geocoding. Postal level geocoding is possible if these conditions are met:
  • Your input address consists of a valid postcode.
  • The data source contains postcode information for the country. Not every country has postcode data.

Geographic Geocoding

The World Geocoder can geocode to the centroid of an administrative division (such as town or village). The World Geocoder can geocode to the geographic level if these conditions are met:
  • Your input addresses contains accurate geographic information without valid postcode address content in the input. If the address in question includes valid postcode input, then the World Geocoder will attempt postal geocoding.
  • The data source contains geographic level information for the country. Geographic information can come from any of the data sources (TomTom, GeoNames, or Pitney Bowes).

Country Coverage

The World Geocoder has coverage for almost every country in the world. The accuracy and scope of coverage varies depending on the quality of the available data source. Some countries include postcode data, while other countries have geographic coverage only. See the following table for a complete list of Geographic coverage by country. For a complete list of Geographic coverage by country, see Country Geographic Data Coverage. For Postal coverage by country, see Country Postal Data Coverage

Input Fields

The input address may contain some or all of the following address elements.

Parameter Type Description
placeName String Specifies the building name, place name, Point of Interest (POI), company or firm name associated with the input address. Optional.
Note: Information provided in this field will be ignored by the World Geocoder.
mainAddress String Single Line Input—If no other address field is populated, then the mainAddress entry will be treated as a single line input. Single line input can consist of multiple input address fields; these should be entered in the typical address order for the country. For more details, refer to the section "Single Line Input" below.

Street Address—If the post address components (city, postalCode, etc.) are provided separately or in the lastLine field, then the contents of mainAddress will be treated as the street address part and can include company name, house number, building names and street names. Optional.

Street Intersection Input—To enter an intersection, specify the two street names separated by a double ampersand (&&).

Note: Information provided in this field will be ignored by the World Geocoder.
lastLine String The last line of the address. Optional. For example:

2 Manchester Rd
Harare
areaName1 String

The name of one of the following depending on the country:

  • Not used—BEL, CHE, DNK, IRL, LIE, LUX, NLD, NOR, SGP
  • Bundesland—DEU
  • Province—CAN
  • Province (changwat)—THA
  • Province (voivodship)—POL
  • Region—AUT, ESP, FRA, GBR, NZL, PRT
  • Region (län)—FIN
  • Region (lan)—SWE
  • State—AUS, BRA
  • State (negeri)—MYS
areaName2 String

The name of one of the following depending on the country:

  • Not used—AUT, BRA, CAN, FIN, GBR, MYS, PRT, SGP.
  • Department—FRA
  • District (amphoe)—THA
  • District (fylke/counties)—NOR
  • District (poviat)—POL
  • Kommun—SWE
  • Kreis—DEU
  • Local Government Authority (LGA)—AUS
  • Province—BEL, CHE, DNK, ESP, IRL, ITA, LIE, LUX, NLD
  • Region—NZL
areaName3 String Specifies the city or town name. Your input address should use the official city name. This will produce the best geocoding results.

For Thailand, this field contains the subdistrict (tambon).
areaName4 String

The name of one of the following depending on the country:

  • Not used—AUS, AUT, BEL, CHE, DEU, DNK, FIN, FRA, IRL, LIE, LUX, MYS, NLD, NOR, POL, SGP, SWE, THA
  • Dissemination Area and Enumeration Area (DA and EA)—CAN
  • Locality—BRA, GBR, ITA, PRT
  • Suburb—NZL
postalCode String The postal code in the appropriate format for the country.
country String The three-letter ISO 3166-1 Alpha-3 country code. For the World Geocoder, the country code is XWG. Required for forward geocoding.

Address Guidelines for the World Geocoder

Follow these suggestions to ensure that your street input data is in the best format possible for optimum matching and geocoding.

  • Address Aliases — Some countries have alternative administrative names. For example, there may be an official name for a city or town, but there may also be common but unofficial alternative name for the same city or town. If alias information is available in the source data, World includes this alias in the database. This enables World to geocode successfully when alternative names are used in input addresses.
  • Language Aliases — Some countries have more than one official or prominent language. For example, the same town may be commonly known by both German and Italian names. If language alias information is available in the source data, World uses this in the database. This enables World to geocode successfully when alternative language names are used in input addresses.
  • State or Province Abbreviations — In some countries, the state or province is an important part of the address and often this address element is abbreviated. For selected countries, these state/province abbreviations are recognized by World. For example, in the United States each state has a two-letter abbreviation (such as CA for California). Similarly, Netherlands, state abbreviations (such as GLD for Gelderland) are recognized.

    The World Geocoder accepts state/province abbreviations for the following countries:

    • Australia (AUS)
    • Canada (CAN)
    • Italy (ITA)
    • Mexico (MEX)
    • Netherlands (NLD)
    • United States (USA)

Single Line Input

Instead of entering each address component in separate fields, you can enter the entire address in the mainAddress input field with the address elements ordered in the typical order for the country. Some examples of common address element ordering is as follows:

[address_number][street_info][postal_code][area]

[address_number][street_info][area][postal_code]

[street_info][address_number][area][postal_code]

[street_info][address_number][postal_code][area]

[street_info][address_number][area]

[address_number][street_info][area]

Where:
  • [street_info] consists of the street name, street type and any pre- or post-directional information (for example, East, West, etc.). Optional.
  • [address_number] is optional.
  • [area] is the city only, or city plus supporting information, such as state, province, locality.
  • [postal_code] is the postal code.
  • Either the [area] or [postal_code] is required.
For best results, put a comma between the street information and the last address line information.

Custom Options

There are no custom options for the XWG geocoder.

Output Fields

The following table lists the address fields returned for a candidate located by the World Geocoder.

Note: The placeName, addressNumber, unitType and unitValue field values are only returned when a geocoding dataset that supports street address interpolation is installed.
Field Name Description
mainAddressLine The street address which may include company name, house number, building names and street names.
addressLastLine The last line of the address.
placeName The building name, place name, Point of Interest (POI), company or firm name associated with the address.
areaName1

The meaning varies by country:

  • AUS—State
  • AUT—Region
  • BEL—Not used
  • BRA—State
  • CAN—Province
  • CHE—State
  • DEU—Bundesland
  • DNK—Not used
  • ESP—Region
  • FIN—Region (län)
  • FRA—Region
  • GBR—Region
  • IRL—Not used
  • ITA—Region
  • LIE—State
  • LUX—Not used
  • MYS—State (negeri)
  • NLD—Not used
  • NOR—Not used
  • NZL—Region
  • POL—Province (voivodship)
  • PRT—Region
  • SGP—Not used
  • SWE—Region (lan)
  • THA—Province (changwat)
areaName2

This field contains an area that is smaller than a state/province but larger than a city. The specific area varies by country:

  • AUS—Local Government Authority (LGA)
  • AUT—Province
  • BEL—Province
  • BHS—Not used
  • BRA—Not used
  • CAN—Not used
  • CHE—Province
  • DEU—Kreis
  • DNK—Province
  • FIN—Province (kommune)
  • FRA—Department
  • GBR—County
  • ITA—Province
  • LIE—Province
  • LUX—Province
  • MYS—District (daerah)
  • NLD—Province
  • NZL—Not used
  • POL—District (poviat)
  • PRT—Not used
  • SGP—District
  • SWE—Region (kommun)
  • THA—District (amphoe)
areaName3 The city or town.
areaName4 The meaning varies by country:
  • Not used—AUS, AUT, BEL, CHE, DEU, DNK, FIN, FRA, IRL, LIE, LUX, MYS, NLD, NOR, POL, SGP, SWE, THA
  • Dissemination Area and Enumeration Area (DA and EA)—CAN
  • Locality—BRA, GBR, ITA, PRT
  • Suburb—NZL
postCode1 The postal code for the address. The format of the postal code varies by country.
postCode2 The postal code extension, if applicable to the country.
country The three-letter ISO 3166-1 Alpha-3 country code. For the World Geocoder, the country code is XWG.
addressNumber The address number.
streetName The street or road name.
unitType The unit type such as APT, STE, etc.
unitValue The unit value/number, such as "3B".
customFields The World Geocoder custom output fields are listed in the following section.

Custom Output Fields

The following table lists the output fields that are unique for the XWG geocoder.

Name Description
CITYRANK This option returns the city ranking from 1 (highest) to 10 (lowest). Zero (0) means that a rank was not available.