Krengel Ship for UPS Street-Level Address Validation
From Wiki
|
| User Guide |
Contents |
Overview
The Krengel Ship for UPS Street Address Validation service allows you to enter in a complete address and validate to the street. This tool can save both time and money by preventing shipments sent to incorrect addresses.
Note that this API is only functional for the United States (US) and Puerto Rico (PR) due to UPS limitations.
Example 1
Pressing Enter will submit this request to the UPS Street-Level Address Validation API, and return a response as shown below:
Example 2
Pressing Enter will submit this request to the UPS Street-Level Address Validation API, and return a response as shown below:
Technical Information
This API section in UPSUI is making use of the following elements:
Request Tables
The request data is stored in UPSXVRQ.
Table Structure
| 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_sAdrVld. UIDs are generated using UPS_getUID. |
| USERID | 30 characters | UPS OnLine Tools ID | Required. Contains a user ID stored in UPSUSER. |
| ADDR1 | 35 characters | Address Line 1 | |
| ADDR2 | 35 characters | Address Line 2 | |
| ADDR3 | 35 characters | Address Line 3 | |
| CITY | 40 characters | City | |
| STATE | 5 characters | State | For US addresses, use the 2 character abbreviations used by the US Postal Service. For international addresses, follow the abbreviation standards of the country. |
| POSTCD | 16 characters | Postal Code | For US addresses, use the Zip Code with the +4 code if available. For international addresses, use the postal code system of the country. |
| CNTRY | 2 characters | Country Code | For all addresses, use the Alpha-2 abbreviation specified in ISO 3166-1. Note that currently, only US, PR, and CA are valid. |
Response Table
The response data is stored in UPSXVRS.
Table Structure
| 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_sAdrVld. 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. |
| NOCANDS | 1 character | No Candidates Indicator | Will be populated if UPS did not return any possible candidate addresses. If there were no candidates, this field will have a value of T - otherwise, it will be empty. |
| CLSCD | 1 character | Address Classification Code | Will be 0, 1, or 2 for Unknown, Commercial, or Residential, respectively. The text description for CLSCD is stored in field CLSDSC. |
| CLSDSC | 15 characters | Address Classification Description | Will be Unknown, Commercial, or Residential. Describes the code stored in field CLSDSC. |
| ADDR1 | 35 characters | Address Line 1 | |
| ADDR2 | 35 characters | Address Line 2 | |
| ADDR3 | 35 characters | Address Line 3 | |
| CITY | 40 characters | City | Possible matching city. |
| STATE | 5 characters | State | Possible matching state. This field will contain the 2 character abbreviations used by the US Postal Service. |
| POSTCD | 16 characters | Postal Code | This field will contain the Zip Code + 4 for US addresses. For PR and CA, it will follow local postal code conventions. |
| CNTRY | 2 characters | Country Code | This field will contain the Alpha-2 abbreviation specified in ISO 3166-1. This API can only be used for addresses in the United States, Puerto Rico, and Canada, so this will only be US, PR, or CA. |
API Function
The Krengel Ship for UPS API function used is UPS_sAdrVld.
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.
- Define the Krengel Ship for UPS Error Data Structure.
- Call UPS_getUID to get the UID that will be used to store and identify the record in UPSXVRQ.
- Insert a record into UPSXVRQ with a valid combination of data (explained above).
- Call UPS_sAdrVld, passing the UID and the Krengel Ship for UPS Error Data Structure.
- The UPS_sAdrVld API will send the request to the UPS web service, and will store the response in UPSXVRS.
- 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 UPSXVRS - field PID will be the UID used to call UPS_sAdrVld.
Note
This API will not return results for all states while using the development environment. Until then, you will receive the following error message if you attempt to use an address that is from a state other than California (CA) and New York (NY).
The state is not supported in the Customer Integration Environment.
To use this API in a production environment, you will need to Get Production Access to UPS APIs.