• Personal tools
  • Log in
• • Main Page
• documentation
  • RPG-XML Suite
  • Krengel Ship for UPS
  • DB2 Web Service Enabler
  • All Products
• Toolbox
  • What links here
  • Related changes
  • Special pages

Krengel Ship for UPS Address Validation

From Wiki

User Guide

Contents 1 Overview 2 Example 1 3 Example 2 4 Example 3 5 Technical Information 5.1 Request Tables 5.2 Response Table 5.3 API Function 5.4 Technical Example

Overview

The Address Validation service included in Krengel Ship for UPS allows you to enter in parts of an address, and have matching address information returned. This tool is very useful to allow someone entering in an address to be able to enter in a Postal Code and State and return the City, saving on typing and eliminating errors. This service can also be used to ensure the information entered is valid.

The Address Validation request must contain one of the following combinations:

• City, State, and Postal Code
• City
• Postal Code
• City and State
• City and Postal Code
• State and Postal Code

This tool assesses the accuracy of an input city, state, postal code combination and returns a list of up to 10 valid city/state/postal code combinations that closely match the input. The tool returns each valid city/state/postal code combination with an assigned rank and quality value to indicate how closely it matches.

Example 1

In this example, we're going to perform a request only using the Postal Code.

Pressing Enter will submit this request to the UPS Address Validation API, and return a response as shown below:

Example 2

In this example, we're going to perform a request only using the City. Due to this being much less specific than a Postal Code, UPS will return multiple results that could match.

Pressing Enter will submit this request to the UPS Address Validation API, and return a response as shown below:

Notice that UPS returned multiple results - pressing Page Down and Page Up will scroll through the different results.

Example 3

In this example, we're going to perform a request after populating all fields. This will also demonstrate the Prompting capabilities of UPSUI.

After filling in some sample data for City and Postal Code, you can move your cursor to the State field, and press F4. This will open the Prompt window. You can select a value from the list with an X in the leftmost field, and press Enter. The state field will populate based upon your selection. Promptable fields appear in most UPSUI screens.

Press Enter again to submit the request.

Note that in this example, the Quality field has a value of 100% - this indicates an exact match between the data we provided UPS, and a correct City/State/Postal Code.

You can also see the PID and UID request identifiers on this screen. These are used to identify individual records in the result table.

Technical Information

This API section in UPSUI is making use of the following elements:

Request Tables

The request data is stored in UPSAVRQ.

Name	Data Type	Description	Notes
UID	15,0 packed	Record Unique ID	Key. This is used to uniquely identify a request. This UID corresponds to the UID passed as the first parameter to UPS_adrVld. UIDs are generated using UPS_getUID.
USERID	30 characters	UPS OnLine Tools ID	Required. Contains a user ID stored in UPSUSER.
CITY	40 characters	City
STATE	5 characters	State	Use the 2 character abbreviations used by the US Postal Service.
POSTCD	16 characters	Postal Code	Use the Zip Code with the +4 code if available.

Response Table

The response data is stored in UPSAVRS.

Name	Data Type	Description	Notes
PID	15,0 packed	Parent Unique ID	Key. This is used to uniquely identify a request. This UID corresponds to the UID passed as the first parameter to UPS_adrVld. UIDs are generated using UPS_getUID.
UID	15,0 packed	Child Unique ID	Key. This is used to uniquely identify a result from a response. UIDs are generated using UPS_getUID.
RANK	10,0 packed	Result Ranking	Numerical ranking of the results returned by UPS. Results are ranked due to relevance and likelihood of matching the request data.
QUALITY	3,2 packed	Result Quality	Quality of individual result. This is meant to be viewed as a percentage.
CITY	40 characters	City	Possible matching city.
STATE	5 characters	State	Possible matching state.
POSTCDL	16 characters	Postal Code Low	Low end of a range of possible postal codes.
POSTCDH	16 characters	Postal Code High	High end of a range of possible postal codes.

API Function

The Krengel Ship for UPS API function used is UPS_adrVld.

Technical Example

This is a brief explanation of how this API is implemented in the included Krengel Ship for UPS User Interface program. You can use the source code for the Krengel Ship for UPS User Interface combined with this example to implement the API in your existing business programs.

1. Define the Krengel Ship for UPS Error Data Structure.
2. Call UPS_getUID to get the UID that will be used to store and identify the record in UPSAVRQ.
3. Insert a record into UPSAVRQ with a valid combination of data (explained above).
4. Call UPS_adrVld, passing the UID and the Krengel Ship for UPS Error Data Structure.
5. The UPS_adrVld API will send the request to the UPS web service, and will store the response in UPSAVRS.
6. Check the Krengel Ship for UPS Error Data Structure to see if an error occurred. If an error did not occur, you may read the records out of UPSAVRS - field PID will be the UID used to call UPS_adrVld.