C_Cover_Address_Street_WS Address Validation Street Level Web Service Developer Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 27

Address Validation - Street Level
Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
ii
Important Information
UPS Developer Kit APIs
Your development of an application using UPS Developer Kit APIs is governed by the UPS Technology
Agreement you entered into with UPS. The following are key legal requirements from these agreements for the
UPS Developer Kit APIs. For more information on all requirements for the UPS Developer Kit APIs, please refer
to the UPS Technology Agreement.
Defined terms used but not defined in this document have the meaning set forth in the UPS Technology
Agreement.
Key Legal Requirements for UPS Developer APIs
Permitted Territories
This document can only be used in the countries of the Permitted Territory as defined in the UPS Technology
Agreement, as applicable.
Use
The application must not be designed to allow distribution of information received through the UPS Developer
Kit APIs to third parties, other than to persons having a bona fide interest in such information (e.g., the shipper,
receiver, or the third party payer, or to your service providers authorized by UPS).
Consent to Use of UPS Mark
All screens or forms generated by your application including information received through the UPS
Developer Kit APIs must include (1) the UPS Mark positioned in reasonable proximity to the Information
and of an appropriate size to readily identify the source of the Information as UPS and (2) the following
language at the bottom of every screen that displays the UPS Mark: "UPS, the UPS brand mark, and the
Color Brown are trademarks of United Parcel Service of America, Inc. All Rights Reserved." Except as
set forth in the preceding sentence, you have no right to use the UPS Mark without the prior written
approval of UPS.
You shall not use the UPS Mark in association with any third party trademarks in a manner that might
suggest co-branding or otherwise create potential confusion as to source or sponsorship of the
application, or ownership of the UPS Mark.
The UPS Mark shall be used only as provided by UPS electronically or in hard copy form. The UPS Mark
may not be altered in any manner, including proportions, colors, elements, etc., or animated, morphed or
otherwise distorted in perspective or dimensional appearance.
The UPS Mark may not be combined with any other symbols, including words, logos, icons, graphics,
photos, slogans, numbers, or other design elements. A minimum amount of empty space must surround
the UPS Mark separating it from any other object, such as type, photography, borders, edges, etc. The
required area of empty space around the UPS Mark must be 1/3x, where x equals the height of the UPS
Mark.
Copyright and Proprietary Notice
In your application and any POD Letters you prepare, you must include a prominent reproduction of UPS’s
copyright and proprietary notices in a form and format specified by UPS (See the Copyright section of this
document).
Display of Information
The application must not display information concerning any other provider of shipping services or such other
shipping services on any page, whether comprising one or more frames, displaying information your application
receives from the UPS Developer Kit APIs. Your application must present all data within each field received
through the UPS Developer Kit APIs without amendment, deletion, or modification of any type.
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
iii
Notice
In all communications with UPS concerning this document, please refer to the document date located on the
cover.
Copyright
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
The use, disclosure, reproduction, modification, transfer, or transmittal of this work for any purpose in any form
or by any means without the written permission of United Parcel Service is strictly prohibited.
Trademarks
Some of the UPS corporate applications use United States city, state, and postal code information obtained by
United Parcel Service of America, Inc. under a non-exclusive license from the United States Postal Service.
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
iv
Table of Contents
Chapter 1: Introduction ......................................................................................................... 5
Release Features ..................................................................................................................................... 6
Chapter 2: Understanding the Address Validation API ............................................................ 7
Business Processes and Rules ............................................................................................................. 7
UPS Address Validation Notice ............................................................................................................. 8
Residential / Commercial Address Classification ................................................................................ 8
Address Validation Examples ................................................................................................................ 8
Chapter 3: Customer Integration Environment (CIE) ............................................................. 10
Integration Testing ................................................................................................................................ 10
Production .............................................................................................................................................. 10
Server Availability Check...................................................................................................................... 10
Chapter 4: Address Validation API Elements and Details ...................................................... 11
Accessing the Address Validation Street Level Web Service API ................................................... 11
Element Constraints .............................................................................................................................. 11
XAVRequest Top Level Containers ..................................................................................................... 12
XAVRequest XPath Tables ................................................................................................................... 12
XAVResponse Top Level Containers .................................................................................................. 15
XAVResponse XPath Tables ................................................................................................................ 15
Chapter 5: Address Validation Web Service API Examples .................................................... 19
XAVRequest Example ........................................................................................................................... 19
XAVResponse Example ........................................................................................................................ 20
Chapter 6: Address Validation Street Level FAQs .................................................................. 21
Appendices ......................................................................................................................... 23
Error Codes (WS) ................................................................................................................................... 24
Common Error Codes ........................................................................................................................ 24
Address Validation Street Level Web Service Error Codes ............................................................... 25
Address Validation Street Level API Supported Countries .............................................................. 26
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
5
Chapter 1: Introduction
In this document, you will find guidance and instructions for integrating the Address Validation Street Level Web
Service into your application, service, or system.
In this guide, you will find:
New release features
Address Validation Web Service API functionality and business rules
Web service API request and response schema
FAQs for the Address Validation API
Address Validation Street Level error response code descriptions
This guide applies to the following API:
SOAP API for the Address Validation Street Level Web Service
This guide does not apply to the following APIs:
Address Validation Street Level XML API
Address Validation City, State, Zip API
Intended Audience
This guide is intended for developers who will be integrating the Address Validation Street Level Web Service API
into their application, service, or system.
Required Knowledge & Skills
This guide assumes you have a basic understanding of the following:
Concepts and instructions in the Introduction to the UPS Developer Kit guide
XML syntax and structure
Web services
Software development
How to Use this Guide
If this is your first time working with the UPS Developer Kit, begin with the Introduction to the UPS Developer Kit
guide. This guide serves as the foundation for all API-specific developer guides.
If you are experienced with the UPS Developer Kit but have not yet worked with the Address Validation API,
continue with Chapter 2: Understanding the Address Validation API. There you will find an overview of the Address
Validation functionality and business rules.
Chapter 3: Customer Integration Environment (CIE) contains information on UPS integration environments.
Chapter 4: Address Validation API Elements and Details contains an overview of the top-level containers and
elements that comprise the Rating request and response.
Request and response examples are located in Chapter 5: Address Validation Web Service API Examples.
Reference tables, services codes, and error codes are located in the Appendices.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
6
Release Features
July 2017
No change.
January 2017
No change.
July 2016
Residential Surcharge Expansion
Expand functionality to additional countries (see Appendix)
January 2016
No change.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
7
Chapter 2: Understanding the Address Validation API
The Address Validation Street Level API can be used to check addresses against the United States Postal Service
database of valid addresses in the U.S. and Puerto Rico. If an address is not valid according to this database, the API
can optionally provide a list of valid addresses that correspond to the intended address. The API can also determine if
an address is a commercial or residential address.
The figure below shows how client applications use address validation services. The process begins when the client
sends a XAVRequest to UPS API Services. UPS replies to this request with a XAVResponse.
Client applications can request either a general validation of a city, state, and zip code, or a validation of specific,
street-level address. The RegionalRequestIndicator in the request determines which type of validation the application
desires.
Client applications also indicate the maximum number of candidate addresses they wish to receive in the response.
UPS returns candidate addresses only if the address that the client provides is not valid. Candidate addresses are
valid addresses that might correspond to the requested address. If a client does not wish to receive candidate
addresses, it can specify zero (0) for this value.
Business Processes and Rules
UPS expects schema elements/tags as defined in the XPath and presented in the schema structure without
spelling or structural deviations. Elements/tags that are not defined in the schema or do not conform to the schema
structure will be ignored by UPS.
Only users that plan to ship packages manifested, tendered, and delivered by UPS can use the API.
Any customers/developers abusing or data mining the API will have their access revoked.
To access API documentation the user must have or create a My UPS profile.
To access testing and production sites the user must have an Access Key. To get an Access Key you must have a
My UPS profile and an associated shipping account. For additional information, refer to the UPS Developer Kit
User Guide.
Address Validation
The Address Verification Street Level (AVSL) API does not perform Apt/Suite validation.
The AVSL API Response never returns the address provided in the Request. It is the responsibility of the customer
to compare address provided in Request to addresses returned in Response.
Countries that support Residential/Commercial classification is available in the Appendix refer to the topic: Address
Validation Street Level API Supported Countries.
Street Level verification is only available for the United States and the U.S. territory of Puerto Rico.
The UPS address validation database is updated monthly with USPS information.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
8
UPS Address Validation Notice
You must display the following notice, or such other language provided by UPS from time to time, in reasonable
proximity to the Address Validation input and output information screens:
NOTICE: UPS assumes no liability for the information provided by the address validation functionality. The
address validation functionality does not support the identification or verification of occupants at an address.
Residential / Commercial Address Classification
The Address Validation Street Level API can determine whether a given address is a residential or commercial
address. Address classification uses the same request/response exchange as address validation. In fact,
classification and validation can be combined in a single request.
To view supported countries, refer to Address Validation Street Level API Supported Countries in the Appendix.
For address classification, UPS determines whether an address is a residence or a commercial location. For address
classification requests, it is important that the user include as much information as possible or available about the
address, for example, a contact name or "attention to" value. Such information is important for accurate results, as
many locations include both commercial and residential entities (such as a deli on the ground floor of an apartment
building).
NOTE: Consignee name is heavily weighted when determining resi / comm classification. Contrary to popular
assumptions, an “address” in and of itself is not residential or commercial, but rather the aggregate of all address
elements, including and especially consignee name, are used to determine the classification.
Address Validation Examples
If this address was sent in a request and included the Apt/Suite#
Company or Name:
LAKESIDE PAIN CENTER
AddressLine:
6010 LAKESIDE COMMONS DR.
AddressLine:
STE B
City:
Macon
State:
GA
Zip:
31210
Country:
US
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
9
The AVSL API does not perform Apt/Suite validation. In cases where there is a valid match (ValidAddressIndicator in
Response) the API will return
Company or Name:
LAKESIDE PAIN CENTER
AddressLine:
6010 LAKESIDE COMMONS DR.
AddressLine:
City:
Macon
State:
GA
Zip:
31210
Country:
US
If the following address is sent in a request, the system will check if it exists. In this case, this address does not exist.
LAKESIDE PAIN CENTER
6010 LAKESIDE
Macon
312
US
But the API will be able to return an address that maybe similar to the one that was provided as a candidate.
LAKESIDE PAIN CENTER
6010 LAKESIDE
Macon
GA
31210
US
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
10
Chapter 3: Customer Integration Environment (CIE)
The Customer Integration Environment allows customers to test their application prior to launch. This environment is
intended for integration testing of customer applications with the UPS servers.
Once your application has been thoroughly tested, you should redirect the application to the UPS Production
Environment.
No stress testing should ever be performed by customers against any UPS systems.
To access testing and production sites the user must have an Access Key. You can request an Access Key after
establishing a UPS profile and associating your shipping account.
System Availability
The Customer Integration Environment is available 24 hours a day, 7 days a week. Note, the system is occasionally
down for server maintenance.
Integration Testing
Test your Address Validation Street Level application with valid and invalid address elements.
NOTE: In the Customer Integration Environment, Street Level Address Validation will only produce results for
addresses in New York (NY) and California (CA).
It is recommended that you use addresses that are familiar to you, for example, your home or business address. This
will ensure that your application has the ability to process success and error responses correctly.
All API URLs are case sensitive.
For integration testing, direct your Address Validation Street Level Web Service to:
https://wwwcie.ups.com/webservices/XAV
Production
All API URLs are case sensitive.
Once testing is complete, direct your Address Validation Street Level Web Service API to the production URL:
https://onlinetools.ups.com/webservices/XAV
Server Availability Check
All of the UPS services work using HTTPS POST. If the server is available, it will reply with the service name, remote
user, server port, server name, and servlet path.
To see this in action, type the following URL in your web browser: https://wwwcie.ups.com/webservices/XAV
Service Name:
XAV
Remote User:
null
Server Port:
443
Server Name:
wwwcie.ups.com
Servlet Path:
/XAV
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
11
Chapter 4: Address Validation API Elements and Details
Accessing the Address Validation Street Level Web Service API
Access the Service at:
https://onlinetools.ups.com/webservices/XAV
Service Operation:
ValidateAddress
ValidateAddress
Operation:
Type: Request-Response (client sends a request to UPS and the UPS server
replies with a response)
SOAPAction Header: http://onlinetools.ups.com/webservices/XAVBinding
Element Constraints
The Request and Response XPath tables contain the full hierarchy of the API elements.
UPS expects schema elements/tags as defined in the XPath and presented in the schema structure i.e., no
spelling or structural deviations. Elements/tags that are not defined in the schema or do not conform to the
schema structure will be ignored by UPS.
Element constraints are defined as follows:
Required
Yes - indicates the element must be present in the request or response.
Yes* - indicates the element must be present in the request if the parent container is present in the request.
No - indicates the element is optional and may be used if it applies to the request.
Cond indicates the element is required under certain conditions.
Type
Container - holds a group of related elements.
String - consists of alphanumeric characters, spaces, and decimals.
Length
The maximum number of characters that can be present in a String. Length is not applicable (N/A) to Containers.
Max Allowed
The maximum number of elements or containers that can be present in the parent container.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
12
XAVRequest Top Level Containers
XAVRequest XPath Tables
Name
Constraint
Description
/XAVRequest
XAVRequest
Required: Yes
Type: Container
Max Allowed: 1
Length:
/XAVRequest/Request
Request
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
XAV Request Container.
/XAVRequest/Request/RequestOption
RequestOption
Required: Yes
Type: String
Max Allowed: 1
Length: 1
Identifies the optional processing to be performed.
If not present or invalid value then an error will be sent
back.
Valid values:
1 - Address Validation
2 - Address Classification
3 - Address Validation and Address Classification.
For a list of valid values, refer to Address Validation
API Supported Countries in the Appendix.
/XAVRequest/Request/TransactionReference
TransactionReference
Required: No
Type: Container
Max Allowed: 1
Length: N/A
TransactionReference identifies transactions between
client and server.
/XAVRequest/Request/TransactionReference/CustomerContext
CustomerContext
Required: No
Type: String
Max Allowed: 1
Length: 1...512
The client uses CustomerContext to synchronize
request/response pairs.
The client establishes CustomerContext, which can
contain any information you want, as long as it is valid
XML; it is echoed back by the server.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
13
Name
Constraint
Description
/XAVRequest/RegionalRequestIndicator
RegionalRequestIndicator
Required: No
Type: String
Max Allowed: 1
Length: 0
If this indicator is present then either the region
element or any combination of Political Division 1,
Political Division 2, PostcodePrimaryLow and the
PostcodeExtendedLow fields will be recognized for
validation in addition to the urbanization element.
If this tag is present, US and PR street level address
validation will not occur.
The default is to provide street level address
validation.
Not valid with the address classification request
option.
/XAVRequest/MaximumCandidateListSize
MaximumCandidateListSize
Required: No
Type: String
Max Allowed: 1
Length: 1..2
The maximum number of Candidates to return for this
request.
Valid values:
0 - 50
Default: 15
/XAVRequest/AddressKeyFormat
AddressKeyFormat
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
AddressKeyFormat container.
The Key format is based on addressing standards
jointly developed by the Postal Service and mailing
industry. The information provided in the Address Key
container will be returned in the same format.
/XAVRequest/AddressKeyFormat/ConsigneeName
ConsigneeName
Required: No
Type: String
Max Allowed: 1
Length: 1..40
Name of business, company or person. Ignored if user
selects the RegionalRequestIndicator.
/XAVRequest/AddressKeyFormat/AttentionName
AttentionName
Required: No
Type: String
Max Allowed: 1
Length: 1..40
Name of the building. Ignored if user selects the
RegionalRequestIndicator.
/XAVRequest/AddressKeyFormat/AddressLine
AddressLine
Required: No
Type: String
Max Allowed: 3
Length: 1..100
Address line (street number, street name and street
type) used for street level information.
Additional secondary information (apartment, suite,
floor, etc.)
Applicable to US and PR only. Ignored if user selects
the RegionalRequestIndicator.
/XAVRequest/AddressKeyFormat/Region
Region
Required: Cond
Type: String
Max Allowed: 1
Length: 1..100
If this node is present the following tags will be
ignored:
- Political Division 2
- Political Division 1
- PostcodePrimaryLow
- PostcodeExtendedLow
Valid only for US or PR origins only. Using this tag for
non US/PR origins may cause address format errors.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
14
Name
Constraint
Description
/XAVRequest/AddressKeyFormat/PoliticalDivision2
PoliticalDivision2
Required: Cond
Type: String
Max Allowed: 1
Length: 1..30
City or Town name.
/XAVRequest/AddressKeyFormat/PoliticalDivision1
PoliticalDivision1
Required: Cond
Type: String
Max Allowed: 1
Length: 1..30
State or Province/Territory name.
/XAVRequest/AddressKeyFormat/PostcodePrimaryLow
PostcodePrimaryLow
Required: Cond
Type: String
Max Allowed: 1
Length: 1..10
Postal Code.
/XAVRequest/AddressKeyFormat/PostcodeExtendedLow
PostcodeExtendedLow
Required: Cond
Type: String
Max Allowed: 1
Length: 1..10
4 digit Postal Code extension. For US use only.
/XAVRequest/AddressKeyFormat/Urbanization
Urbanization
Required: No
Type: String
Max Allowed: 1
Length: 1...30
Puerto Rico Political Division 3. Only valid for Puerto
Rico.
/XAVRequest/AddressKeyFormat/CountryCode
CountryCode
Required: Yes
Type: String
Max Allowed: 1
Length: 2
Country Code.
For a list of valid values, refer to the Address
Validation API Supported Countries table in the
Appendix.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
15
XAVResponse Top Level Containers
XAVResponse XPath Tables
Note: Not all containers/elements are reflected separately in the table of contents.
Name
Constraint
Description
/XAVResponse
XAVResponse
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
XAV Response Container.
/XAVResponse/Response
Response
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
Response Container.
/XAVResponse/Response/ResponseStatus
ResponseStatus
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
Response Status Container.
/XAVResponse/Response/ResponseStatus/Code
Code
Required: Yes
Type: String
Max Allowed: 1
Length: 1
Identifies the success or failure of the transaction.
Valid values:
1 = Success
0 = Failure
/XAVResponse/Response/ResponseStatus/Description
Description
Required: Yes
Type: String
Max Allowed: 1
Length: 1...35
Describes Response Status Code. Returns text of
'Success' or 'Failure'.
/XAVResponse/Response/Alert
Alert
Required: No
Type: Container
Max Allowed: 1
Length: N/A
Alert Container.
There can be zero to many alert containers with code
and description.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
16
Name
Constraint
Description
/XAVResponse/Response/Alert/Code
Code
Required: Yes*
Type: String
Max Allowed: 1
Length: 1...10
Warning code returned by the system.
/XAVResponse/Response/Alert/Description
Description
Required: Yes*
Type: String
Max Allowed: 1
Length: 1...150
Warning messages returned by the system.
/XAVResponse/Response/TransactionReference
TransactionReference
Required: No
Type: Container
Max Allowed: 1
Length: N/A
Transaction Reference Container.
/XAVResponse/Response/TransactionReference/CustomerContext
CustomerContext
Required: No
Type: String
Max Allowed: 1
Length: 1...512
The CustomerContext Information which will be
echoed during response.
/XAVResponse/ValidAddressIndicator
ValidAddressIndicator
Required: Cond
Type: String
Max Allowed: 1
Length: 0
Indicates query found a valid match.
/XAVResponse/AmbiguousAddressIndicator
AmbiguousAddressIndicator
Required: Cond
Type: String
Max Allowed: 1
Length: 0
Indicates query could not find a match based on the
information provided. Candidate list follows
/XAVResponse/NoCandidatesIndicator
NoCandidatesIndicator
Required: Cond
Type: String
Max Allowed: 1
Length: 0
No Candidate found.
/XAVResponse/AddressClassification
AddressClassification
Required: No
Type: Container
Max Allowed: 1
Length: N/a
AddressClassification Container.
/XAVResponse/AddressClassification/Code
Code
Required: Yes*
Type: String
Max Allowed: 1
Length: 1
Contains the classification code of the input address.
Valid values:
0 - UnClassified
1 - Commercial
2 - Residential
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
17
Name
Constraint
Description
/XAVResponse/AddressClassification/Description
Description
Required: Yes*
Type: String
Max Allowed: 1
Length: 1..15
Contains the text description of the address
classification code:
UnClassified
Commercial
Residential
/XAVResponse/Candidate
Candidate
Required: No
Type: Container
Max Allowed: 1
Length: N/A
Candidate Container.
/XAVResponse/Candidate/AddressClassification
AddressClassification
Required: No
Type: Container
Max Allowed: 1
Length: N/A
AddressClassification Container.
/XAVResponse/Candidate/AddressClassification/Code
Code
Required: Yes*
Type: String
Max Allowed: 1
Length: 1
Contains the classification code of the address:
0 - UnClassified
1 - Commercial
2 - Residential
/XAVResponse/Candidate/AddressClassification/Description
Description
Required: Yes*
Type: String
Max Allowed: 1
Length: 1..15
Contains the text description of the address
classification code (see Code above).
/XAVResponse/Candidate/AddressKeyFormat
AddressKeyFormat
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
AddressKeyFormat Container.
/XAVResponse/Candidate/AddressKeyFormat/ConsigneeName
ConsigneeName
Required: No
Type: String
Max Allowed: 1
Length: 1..40
Name of business, company or person. Not returned if
user selects the RegionalRequestIndicator.
/XAVResponse/Candidate/AddressKeyFormat/AttentionName
AttentionName
Required: No
Type: String
Max Allowed: 1
Length: 1..40
Name of building. Not returned if user selects the
RegionalRequestIndicator.
/XAVResponse/Candidate/AddressKeyFormat/AddressLine
AddressLine
Required: No
Type: String
Max Allowed: 3
Length: 1..100
Address line (street number, street name and street
type, and political division 1, political division 2 and
postal code) used for street level information.
Additional secondary information (apartment, suite,
floor, etc.)
Applicable to US and PR only.
Not returned if user selects the
RegionalRequestIndicator.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
18
Name
Constraint
Description
/XAVResponse/Candidate/AddressKeyFormat/Region
Region
Required: Cond
Type: String
Max Allowed: 1
Length: 1..100
Single entry containing in this order Political Division
2, Political Division 1 and Post Code Primary Low
and/or PostcodeExtendedLow.
/XAVResponse/Candidate/AddressKeyFormat/PoliticalDivision2
PoliticalDivision2
Required: Cond
Type: String
Max Allowed: 1
Length: 1..30
City or Town name.
/XAVResponse/Candidate/AddressKeyFormat/PoliticalDivision1
PoliticalDivision1
Required: Cond
Type: String
Max Allowed: 1
Length: 1..30
State/Province.
Returned if the location is within a
State/Province/Territory.
For International: returned if user enters valid Country
Code, and City/postal code and it has a match.
For Domestic addresses, the value must be a valid 2-
character value (per US Mail standards).
For International the full State or Province name will
be returned.
/XAVResponse/Candidate/AddressKeyFormat/PostcodePrimaryLow
PostcodePrimaryLow
Required: Cond
Type: String
Max Allowed: 1
Length: 1..10
Low-end Postal Code. Returned for countries with
Postal Codes. May be alphanumeric.
/XAVResponse/Candidate/AddressKeyFormat/PostcodeExtendedLow
PostcodeExtendedLow
Required: Cond
Type: String
Max Allowed: 1
Length: 1..10
Low-end extended postal code in a range. Example in
quotes: Postal Code 30076-'1234'.
Only returned in candidate list. May be alphanumeric
/XAVResponse/Candidate/AddressKeyFormat/Urbanization
Urbanization
Required: No
Type: String
Max Allowed: 1
Length: 1...30
Puerto Rico Political Division 3. Only Valid for Puerto
Rico.
/XAVResponse/Candidate/AddressKeyFormat/CountryCode
CountryCode
Required: Yes
Type: String
Max Allowed: 1
Length: 2
A country code. Required to be returned.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
19
Chapter 5: Address Validation Web Service API Examples
XAVRequest Example
<envr:Envelope xmlns:auth="http://www.ups.com/schema/xpci/1.0/auth"
xmlns:envr="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:upss="http://www.ups.com/XMLSchema/XOLTWS/UPSS/v1.0"
xmlns:common="http://www.ups.com/XMLSchema/XOLTWS/Common/v1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<envr:Header>
<upss:UPSSecurity>
<upss:UsernameToken>
<upss:Username>Your Username</upss:Username>
<upss:Password>Your Password</upss:Password>
</upss:UsernameToken>
<upss:ServiceAccessToken>
<upss:AccessLicenseNumber>Your Access License Number</upss:AccessLicenseNumber>
</upss:ServiceAccessToken>
</upss:UPSSecurity>
</envr:Header>
<envr:Body>
<XAV:XAVRequest xsi:schemaLocation="http://www.ups.com/XMLSchema/XOLTWS/xav/v1.0"
xmlns:XAV="http://www.ups.com/XMLSchema/XOLTWS/xav/v1.0">
<common:Request>
<common:RequestOption>1</common:RequestOption>
<common:TransactionReference>
<common:CustomerContext>Your Customer Context</common:CustomerContext>
</common:TransactionReference>
</common:Request>
<XAV:MaximumListSize>10</XAV:MaximumListSize>
<XAV:AddressKeyFormat>
<XAV:ConsigneeName>Consignee Name</XAV:ConsigneeName>
<XAV:BuildingName>Building Name</XAV:BuildingName>
<XAV:AddressLine>12380 Morris Road</XAV:AddressLine>
<XAV:PoliticalDivision2>Alpharetta</XAV:PoliticalDivision2>
<XAV:PoliticalDivision1>GA</XAV:PoliticalDivision1>
<XAV:PostcodePrimaryLow>30009</XAV:PostcodePrimaryLow>
<XAV:CountryCode>US</XAV:CountryCode>
</XAV:AddressKeyFormat>
</XAV:XAVRequest>
</envr:Body>
</envr:Envelope>
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
20
XAVResponse Example
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header/>
<soapenv:Body>
<xav:XAVResponse xmlns:xav="http://www.ups.com/XMLSchema/XOLTWS/xav/v1.0">
<common:Response xmlns:common="http://www.ups.com/XMLSchema/XOLTWS/Common/v1.0">
<common:ResponseStatus>
<common:Code>1</common:Code>
<common:Description>Success</common:Description>
</common:ResponseStatus>
<common:TransactionReference>
<common:CustomerContext>Your Customer Context</common:CustomerContext>
</common:TransactionReference>
</common:Response>
<xav:ValidAddressIndicator/>
<xav:Candidate>
<xav:AddressKeyFormat>
<xav:AddressLine>12380 MORRIS RD</xav:AddressLine>
<xav:PoliticalDivision1>GA</xav:PoliticalDivision1>
<xav:PostcodePrimaryLow>30005</xav:PostcodePrimaryLow>
<xav:PostcodeExtendedLow>4177</xav:PostcodeExtendedLow>
<xav:Region>ALPHARETTA GA 30005-4177</xav:Region>
<xav:CountryCode>US</xav:CountryCode>
</xav:AddressKeyFormat>
</xav:Candidate>
</xav:XAVResponse>
</soapenv:Body>
</soapenv:Envelope>
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
21
Chapter 6: Address Validation Street Level FAQs
Category
Question
Answer
General
What countries' addresses can be
validated by the Address Validation -
Street Level API?
Street Level Address Validation (SLAV) allows
the validation of street level address in the US
and Puerto Rico only.
General
Does the Address Validation - Street
Level API validate addresses?
The Address Validation - Street Level API
validates addresses in the US and Puerto Rico
only.
The API classifies addresses as Residential or
Commercial in keeping with UPS standards.
General
Why do we get back a candidate list of
addresses even when the response has
a Valid Address Indicator?
The API returns a candidate list even when there
is a Valid Address Indicator because the
parameters entered have more than one valid
match.
If the address that was entered as part of the
request is returned as part of the candidate list
then the address is valid and should be used.
General
How is street level AV completed? Does
it use the USPS to validate an address?
The UPS database is updated monthly with
USPS information.
General
How much time will it take to
program/implement the Address
Validation - Street Level API?
The programming/implementation of the Address
Validation - Street Level APIs may vary and is
strictly dependent on the skill level of the
developer.
An implementation of Address Validation Street
Level may take as little as a week for a very
skilled developer to as long as months for a less
skilled developer.
Address Validation
frequency of
updates
How frequently are the databases
updated for Address Validation Street
Level?
Address Validation Street Level API
1. Classification = weekly
2. Validation = monthly
Batch Upload
Does either the Address Validation or
Address Validation Street Level APIs
offer the ability to batch upload?
No.
Resi/Comm
Indicator
Which APIs provide address
classification?
Refer to Address Validation Street Level
API Supported Countries in the Appendix.
Resi/Comm
Database
What process does UPS use to apply
residential/commercial designations?
UPS business logic is used to determine the
results.
Suite/Apt #
Does Address Validation Street Level
API provide a candidate list for
addresses that have suite/apt
information?
The API does not return candidate lists for suite
or apartment number ranges.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
22
Category
Question
Answer
Valid/Invalid
Address
How do I know whether the address I
submitted is correct?
If the address is entered incorrectly, the API will
return an AmbiguousAddressIndicator and a list
of candidate addresses.
If the address is entered correctly, the API will
return a ValidAddressIndicator and the correct
address.
Note: The API will not return the address sent in
the XML Request. It is the responsibility of the
customer to compare the address sent in the
request to the address(es) returned in the
response.
CASS Certified
Is the Address Validation Street Level
API CASS certified or the data we
receive CASS certified?
UPS does not provide any API or application with
customer-facing CASS-certified address
validation. CASS certification is required for
discounts on USPS services, but not required for
any UPS services or discounts.
UPS address validation is not CASS-certified. It is
also free, as we are not competing with vendors
that provide CASS-certified Address Validation
software. The Address Validation API is provided
to allow customers who do not already use
CASS-certified Address Validation software, our
Address Validation Street Level API can be used
to help clean-up addresses for UPS shipments.
UPS delivers to addresses that are not in the
USPS database (some examples are addresses
that are warehouses that do not accept mail and
areas where the USPS only provides PO Box
delivery) - so an invalid address may still be
deliverable.
In addition, a valid address may be the wrong
address, and still require an address correction.
NOTE: The source of our data for address
validation is the USPS that we subscribe to and
refresh monthly.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
23
Appendices
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
24
Error Codes (WS)
When the UPS system is unable to respond to a request, be it from a malformed request, an illegal or invalid value, or
other issues, the API generates an error response. For examples and additional information on error responses, refer
to Chapter 3: Error Responses, in the Introduction to the UPS Developer Kit guide.
Successful responses may or may not include warnings.
o Without warnings - Indicates the request has been processed as anticipated.
o With warnings - Indicates the request has been processed with potentially unanticipated results. The warning
contains information in the response that should be passed to the end user.
The severity of an error may be transient or hard.
o Transient error - Indicates an error that is temporary in nature. Such errors may be caused by response
timeouts due to high server loads or scheduled maintenance in progress. The request may be issued
successfully at a later time.
o Hard error - Indicates the request has a problem that the system is not able to resolve. These errors are
critical and prevent requests from processing.
Do not resubmit requests with Hard Errors until the problems causing the error have been
resolved.
Common Error Codes
The following error codes can apply to all Webservice and other APIs.
Code
Severity
Description
10001
Hard
The XML document is not well formed.
10002
Hard
The XML document is well formed but the document is not valid.
10003
Hard
The XML document is either empty or null.
10006
Hard
Although the document is well formed and valid, the element content contains values
which do not conform to the rules and constraints contained in this specification.
10013
Hard
The message is too large to be processed by the Application.
20001
Transient
General process failure.
20002
Hard
The specified service name, {0}, and version number, {1}, combination is invalid.
20003
Hard
Please check the server environment for the proper J2EE ws apis.
20006
Hard
Invalid request action.
20007
Hard
Missing Required field, {0}.
20008
Hard
The field, {0}, contains invalid data, {1}.
20012
Hard
The Client Information exceeds its Maximum Limit of {0}.
250000
Hard
No XML declaration in the XML document.
250001
Hard
Invalid Access License for the tool. Please re-license.
250002
Hard
Invalid UserId/Password.
250003
Hard
Invalid Access License number.
250004
Hard
Incorrect UserId or Password.
250005
Hard
No Access and Authentication Credentials provided.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
25
Code
Severity
Description
250006
Hard
The maximum number of user access attempts was exceeded.
250007
Hard
The UserId is currently locked out; please try again in 24 hours.
250009
Hard
License Number not found in the UPS database.
250019
Hard
Invalid Field value.
250050
Transient
License system not available.
Address Validation Street Level Web Service Error Codes
Error Code
Severity
Description
Condition
250065
Hard
Invalid or missing request
element.
Occurs when Request Container is missing or
invalid in a request.
260000
Hard
XAV Web Service currently
unavailable.
XAV Web service is not exposed or service is down
for some reason.
264001
Transient
AV Service is not available.
Adapter parsing error, business process calling
error, backend service is unavailable, etc.
264002
Hard
Country Code is invalid or
missing.
The country code is not US or PR. (or) CountryCode
element is missing.
264003
Hard
The Maximum allowable
Candidate List size has been
exceeded within the User
Request.
The maximum candidate list size requested from the
user has been exceeded.
264004
Hard
The maximum validation query
time has been exceeded due to
poor address data.
Request has timed out. Usually due to insufficient
or poor address data from client.
264005
Hard
Address classification is not valid
for a regional request.
The customer submits a request for address
classification with a regional address format.
264006
Hard
Invalid candidate list size.
The maximum candidate list size given by the
customer is not a numeric value between 0 and
2147483647.
264007
Hard
Address classification is not
allowed for the country requested.
The request contains address classification with a
country code that is not supported for classification.
264008
Hard
Country code and address format
combination is not allowed.
Country code and address format combination is not
allowed.
264027
Hard
Additional address fields are
needed to perform the requested
operation.
The Country Code is valid but the other fields are
blank. Additional fields need to be provided in order
to validate or classify the address.
9261000
Hard
Invalid XAV Request Document
XAV SOAP request in invalid.
9264028
Hard
Invalid or missing request option.
RequestOption value is empty or outside the range
1 to 3 or element not present in request.
9264029
Hard
Missing address key format.
AddressKeyFormat container is missing.
9264030
Hard
The state is not supported in the
Customer Integration
Environment.
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
26
Address Validation Street Level API Supported Countries
UPS country code abbreviations generally follow the ISO Standard 3166.
NOTE: Not all UPS services are available in every country. Refer to the UPS Rate and Service Guide at
UPS.com for more information on UPS services.
Country Name
Country Code
Residential / Commercial
Classification
Street Level
Validation
Aland Islands
AX
X
Austria
AT
X
Azores
A2
X
Belgium
BE
X
Canada
CA
X
Canary Islands
IC
X
Ceuta
XC
X
Czech Republic
CZ
X
Denmark
DK
X
England
EN
X
Finland
FI
X
France
FR
X
Germany
DE
X
Holland
HO
X
Hungary
HU
X
Ireland, Republic of
IE
X
Italy
IT
X
Madeira
M3
X
Melila
XL
X
Mexico
MX
X
Netherlands
NL
X
Northern Ireland
NB
X
Norway
NO
X
Poland
PL
X
Portugal
PT
X
Puerto Rico
PR
X
X
Scotland
SF
X
Spain
ES
X
Sweden
SE
X
Address Validation Street Level Web Service Developer Guide
July 10, 2017
© 2017 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
27
Country Name
Country Code
Residential / Commercial
Classification
Street Level
Validation
Switzerland
CH
X
United Kingdom
GB
X
United States
US
X
X
Wales
WL
X

Navigation menu