I nostri servizi di normalizzazione indirizzi via WEB Services

The functions available for each country depend on the products licensed.

The webservice supports the validation of delivery addresses, PO box addresses and large user addresses, provided appropriate data is available for the selected country.

Webservice methods and parameters

The web service provides a method that allows an address to be postally checked (and corrected where necessary), structured and standardised, as well as enriched with information based on geographical coordinates.

EnhancedAddress[]	enhanceAddress (Authentication authentication, Parameter parameter, InputAddress address)
	throws java.rmi.RemoteException

Input

Address
The "address" to be validated can be a delivery address, a PO box address or a large-user address.

A delivery address can be provided in fields or lines. If entered in fields, the following address elements can be specified:

• Country
• Region
• Postcode
• Town
• Town district
• Street with house number and supplements

For a PO box address, the following elements can be specified for validation:

• Country
• PO box postcode
• PO box town
• PO box number

A large-user address consists of the following address elements:

• Country
• Large-user postcode
• Large-user town

Parameters
The web service allows to set validation parameters. The following input parameters are supported by the web service and can be passed in parameter:

• parCase
  Set the case of the output.
  • 0 = Output in upper and lower case.
  • 1 = Output in lower case.
  • 2 = Output in upper case
  • 3 = Output matches case of input.
  Default value: 0
  
• parSpecialChars
  Configure how special characters appear in the output.
  • 0 = Output special characters.
  • 1 = Special characters expanded in the output.
  • 2 = Only special characters in the input remain in the output.
  • 3 = Expand special characters if no country non-specific characters are in the input.
  Default value: 0
  
• parLanguage
  Select language. The setting of this parameter affects a number of output arguments and the language in which messages are expressed that are sent by the server.
  • 1 = German
  • 2 = English
  • 3 = French
  Default value: 2
  
• parSelListMax
  Maximum number of elements per selection list. Determines the size of a selection list.
  Possible values: 0 to 65535
  Default value: 1000
  
• parServerCodePage
  Select codepage for output.
  Possible values:
  • 0 = ISO8859-1
  • 1 = ISO8859-2
  • 2 = ISO8859-3
  • 3 = ISO8859-4
  • 4 = ISO8859-5
  • 5 = ISO8859-6
  • 6 = ISO8859-7
  • 7 = ISO8859-8
  • 8 = ISO8859-9
  • 9 = ISO8859-10
  • 10 = ISO8859-13
  • 11 = ISO8859-14
  • 12 = ISO8859-15
  • 13 = ISO8859-16
  Default value: 0
  
• parHnoConfirmed
  Enable/disable House No. validation. The system checks whether or not the house number entered exists. Currently, this feature is available for the Netherlands, Germany and Austria only. The German version requires an additional table (subject to fee).
  • 1 = House No. validation enabled.
  • 0 = House No. validation disabled.
  Default value: 1
  

Authentication

The authentication "authentication" is mandatory. This authorizes the client to execute the request. Only requests of registered clients are processed. The authentication includes the registrationNumber and password, which are set via the methods setRegistrationNumber() and setPassword().

Validation Result
The result of a postal validation includes at least one EnhancedAddress-object. This object may or may not contain an address. A distinction is made between three different cases:

• Address found unambiguously
• Address list created
• No address determined

• Address found unambiguously
  Whenever an unambiguous address is found, one EnahncedAddress-Object is available with following information;
  • Result class
  • PO box result class
  • Large-user result class
  • Coordinates result class
  • Warning, if generated by server
  
  Depending on the type of address, different address elements will be filled. The address type returned is shown by the result class.

  The following address elements are returned for a delivery address:
  

  • Country
  • Region
  • Postcode
  • Town
  • Town district
  • Street with house number and supplements
  • Result label for house number validation
  • Result labels for Region, Postcode, Town, Town district, Street and house number
  • Similarity measure for Town and Street
  • If the input address was passed in lines, the structured and normed address is additionally returned in the lines 1-6.
  • X-Coordinate
  • Y-Coordinate
  • Coordinates validity level

  PO Box address:

  • Country
  • PO Box-postcode
  • PO Box-Town
  • PO Box number
  • Result labels for PO Box postcode, PO Box town and PO Box number

  Large-user address:

  • Country
  • Large-user postcode
  • Large-user town
  • Result labels for Large-user postcode and Large-user town
  
  
• Address List Created
  For an ambiguous address, the number of EnhancedAddress-objects returned corresponds to either:
  • the number of objects found by the post server, or
  • the value set with the parSelListMax parameter.
  
  An address list can only be created for a delivery address. Each EnhancedAddress-object includes the following elements:
  • Result class
  • Country
  • Region
  • Postcode
  • Town
  • Town district
  • Street with house number and supplements
  • Result labels for Region, Postcode, Town, Town district, Street and house number
  • Similarity measure for Town and Street
  
  
• No Address Determined
  If the input address is unknown or if an error occurs during the validation, no address can be returned.
  In this case, the result only includes one EnhancedAddress-object with the following information:
  • Warning or error message
  
  All result classes are set to "0".
  All other elements contain their initial value.

Result Classes
Whenever an address was found, the result classes indicate the address type. All three result classes have one the following values:

• 0 - No address of this type checked
• 1 - Address found without ambiguity
• 2 - Address found with certainty
• 3 - Address found with uncertainty
• 5 - Insufficient information or address not found

Thus, for an address found without ambiguity, this means that only one result class will have a value > 0. The corresponding address elements can be queried next.

Result Labels
Result labels describe the quality of individual address elements, i.e. to what extent such an element was changed. Possible values:

• OK - Input correct
• NI - No input
• PI - Partial input
• C  - Changed
• SC - Severely changed
• NF - Not found
• DF - Default value
• NC - Not checked
• NP - Not checked due to PO box in Street field
• NR - Poste restante not checked

Coordinates Assignment
The geographical coordinates are automatically assigned to each delivery address found with certainty - provided this functionality has been licensed.

X- and Y-Coordinates are provided in WGS84 format.

Meaning of the 9 characters:
+ GGGNNNNNN or
- GGGNNNNNN
where GGG represents degrees and NNNNNN the fractional digits. If the last 'N' is not available in the raw data of a country, it is set to '0'.

Example:
48°43'30''
corresponds to (in decimal notation):
48,725
and is coded as:
'+04872500'

The coordinates validity level specifies the level for which the coordinates are valid. Possible values:

• 5 = Town
• 4 = Entire street
• 3 = Street section
• 2 = Single house number

The coordinates result class provides information on the quality with which coordinates are assigned.
Possible values:

• 0 - Coordinates assignment not performed
• 1 - Coordinates assigned with certainty, address found with certainty
• 2 - Coordinates assigned with certainty, address changed with certainty
• 3 - Default coordinates assigned for the corresponding level
• 5 - No coordinates could be assigned

Complete List of Fields and Methods
For the complete description of the InputAddress, Authentication, Parameter and EnhancedAddress classes, please refer to Javadoc.

WSDL-Description
The WSDL-file of the webservice PostalValidation can be found here.