_Cover_Address_Validation_Street_XML Address Validation Street Level XML Developer Guide

User Manual:

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

Address Validation - Street Level
XML Developer Guide
July 9 , 2018
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
2
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.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
3
Notice
In all communications with UPS concerning this document, please refer to the document date located on the
cover.
Copyright
© 2018 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.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
4
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
Element Constraints .............................................................................................................................. 11
AddressValidationRequest Top Level Containers ............................................................................. 12
AddressValidationRequest XPath Tables ........................................................................................... 12
AddressValidationResponse Top Level Containers .......................................................................... 15
AddressValidationResponse XPath Table .......................................................................................... 15
Chapter 5: Address Validation Street Level XML Examples ................................................... 20
AddressValidationRequest XML .......................................................................................................... 20
AddressValidationResponse XML ....................................................................................................... 20
Chapter 6: Address Validation Street Level FAQs .................................................................. 21
Appendices ......................................................................................................................... 23
Error Codes (XML) ................................................................................................................................. 24
Common Error Codes ........................................................................................................................ 24
Address Validation Street Level Error Codes (XML) ......................................................................... 25
Address Validation Street Level API Supported Countries/Territories ........................................... 26
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 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 XML API
into your application, service, or system.
In this guide, you will find:
New release features
Address Validation Street Level XML API functionality and business rules
XML API request and response schema
FAQs for the Address Validation Street Level API
Address Validation Street Level error response code descriptions
This guide applies to the following API:
Address Validation Street Level XML API
This guide does not apply to the following APIs:
Address Validation Street Level Web Service API
Address Validation City, State, Zip API
Intended Audience
This guide is intended for developers who will be integrating the Address Validation Street Level XML 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
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 Street
Level API, continue with Chapter 2: Understanding the Address Validation API. There you will find an overview of
the Rating 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 Street Level XML Examples.
Reference tables, services codes, and error codes are located in the Appendices.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
6
Release Features
July 2018
Expand address classification for the following countries (see Appendix)
Belarus(BY)
Jersey(JE)
Romania(RO)
Russia(RU)
Slovenia(SI)
Turkey(TR)
Ukraine(UA)
January 2018
Expand address classification for Greece(GR) and Luxembourg (LU) (see Appendix)
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 XML Developer Guide
July 9th, 2018
© 2018 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 an AddressValidationRequest to UPS API Services. UPS replies with an AddressValidationResponse.
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 or territories that support Residential/Commercial classification is available in the Appendix refer to the
topic: Address Validation Street Level API Supported Countries/Territories.
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 XML Developer Guide
July 9th, 2018
© 2018 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 or territories, refer to Address Validation Street Level API Supported
Countries/Territories 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 XML Developer Guide
July 9th, 2018
© 2018 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 XML Developer Guide
July 9th, 2018
© 2018 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, Address Validation Street Level 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 test Address Validation Street Level XML to:
https://wwwcie.ups.com/ups.app/xml/XAV
Production
All API URLs are case sensitive.
Once testing is complete, direct your Address Validation Street Level XML to the production URL:
https://onlinetools.ups.com/ups.app/xml/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/ups.app/xml/XAV
Service Name:
XAV
Remote User:
null
Server Port:
443
Server Name:
wwwcie.ups.com
Servlet Path:
/XAV
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
11
Chapter 4: Address Validation API Elements and Details
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 XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
12
AddressValidationRequest Top Level Containers
AddressValidationRequest XPath Tables
Note: Not all containers/elements are reflected separately in the table of contents.
Name
Constraint
Description
/AddressValidationRequest
AddressValidationRequest
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
AddressValidationRequest Container.
/AddressValidationRequest/Request
Request
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
Request Container.
/AddressValidationRequest/Request/TransactionReference
TransactionReference
Required: No
Type: Container
Max Allowed: 1
Length: N/A
TransactionReference identifies transactions
between client and server.
/AddressValidationRequest/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, that can contain any information
you want, as long as it is valid XML; it is echoed
back by the server.
/AddressValidationRequest/Request/RequestAction
RequestAction
Required: Yes
Type: String
Max Allowed: 1
Length: 3
Indicates the action to be taken by the XML
service. Must be 'XAV'.
/AddressValidationRequest/Request/RequestOption
RequestOption
Required: No
Type: String
Max Allowed: 1
Length: 1
Identifies the optional processing to be performed.
If not present or invalid value then the default will
be used.
1= Address Validation (Default)
2= Address Classification
3= Address Validation and Address Classification.
For a list of valid values, refer to the Address
Validation API Supported Countries/Territories in
the Appendix.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
13
Name
Constraint
Description
/AddressValidationRequest/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.
/AddressValidationRequest/MaximumListSize
MaximumListSize
Required: No
Type: String
Max Allowed: 1
Length: 1...3
The maximum number of Candidates to return for
this request. Valid values:
0-50
Default value: 15
/AddressValidationRequest/AddressKeyFormat
AddressKeyFormat
Required: Yes
Type: Container
Max Allowed: 1
Length:
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.
/AddressValidationRequest/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.
/AddressValidationRequest/AddressKeyFormat/BuildingName
BuildingName
Required: No
Type: String
Max Allowed: 1
Length: 1...40
Name of building. Ignored if user selects the
RegionalRequestIndicator.
/AddressValidationRequest/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.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
14
Name
Constraint
Description
/AddressValidationRequest/AddressKeyFormat/Region
Region
Required: No
Type: String
Max Allowed: 1
Length: 1...100
Single entry containing the following:
- Political Division 2
- Political Division 1
- Post Code Primary Low
- Post Code Extended Low
If the node is present the following tags will be
ignored Political Division 2, Political Division 1,
Post Code Primary Low, and Post Code Extended
Low.
Valid only for US or PR origins only.
Using this tag for non US/PR origins may cause
address format errors.
/AddressValidationRequest/AddressKeyFormat/PoliticalDivision2
PoliticalDivision2
Required: No
Type: String
Max Allowed: 1
Length: 1...30
City or town name.
/AddressValidationRequest/AddressKeyFormat/PoliticalDivision1
PoliticalDivision1
Required: No
Type: String
Max Allowed: 1
Length: 1...30
State or Province/Territory name.
/AddressValidationRequest/AddressKeyFormat/PostcodePrimaryLow
PostcodePrimaryLow
Required: No
Type: String
Max Allowed: 1
Length: 1...10
Postal Code.
/AddressValidationRequest/AddressKeyFormat/PostcodeExtendedLow
PostcodeExtendedLow
Required: No
Type: String
Max Allowed: 1
Length: 1...10
4 digit Postal Code extension. For U.S. use only.
/AddressValidationRequest/AddressKeyFormat/Urbanization
Urbanization
Required: No
Type: String
Max Allowed: 1
Length: 1...30
Political Division 3.Only valid for Puerto Rico.
/AddressValidationRequest/AddressKeyFormat/CountryCode
CountryCode
Required: Yes
Type: String
Max Allowed: 1
Length: 2
Country/Territory Code.
For a list of valid values, refer to the Address
Validation API Supported Countries/Territories
table in the Appendix.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
15
AddressValidationResponse Top Level Containers
AddressValidationResponse XPath Table
Note: Not all containers/elements are reflected separately in the table of contents.
Name
Constraint
Description
/AddressValidationResponse
AddressValidationResponse
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
Container for AddressValidationResponse.
/AddressValidationResponse/Response
Response
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
Response Container.
/AddressValidationResponse/Response/TransactionReference
TransactionReference
Required: No
Type: Container
Max Allowed: 1
Length: N/A
Transaction Reference container.
/AddressValidationResponse/Response/TransactionReference/CustomerContext
CustomerContext
Required: No
Type: String
Max Allowed: 1
Length: 1...512
Echoes back the Customer context from the
Request
/AddressValidationResponse/Response/ResponseStatusCode
ResponseStatusCode
Required: Yes
Type: String
Max Allowed: 1
Length: 1
Identifies the success or failure of the transaction.
1 = Success
0 = Failure
/AddressValidationResponse/Response/ResponseStatusDescription
ResponseStatusDescription
Required: No
Type: String
Max Allowed: 1
Length: 1...35
Describes Response Status Code. Returns text of
'Success' or 'Failure'.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
16
Name
Constraint
Description
/AddressValidationResponse/Response/Error
Error
Required: Yes
Type: Container
Max Allowed: 1
Length: N/A
Error Container. The error is described with a code
and description.
/AddressValidationResponse/Response/Error/ErrorSeverity
ErrorSeverity
Required: Yes
Type: String
Max Allowed: 1
Length: 1...10
Valid values:
'Hard' - The provided Request data will always fail
'Transient' - A UPS application is suffering an
intermittent failure. Try the transaction again later.
/AddressValidationResponse/Response/Error/ErrorCode
ErrorCode
Required: Yes
Type: String
Max Allowed: 1
Length: 1...2
Warning code returned by the system.
/AddressValidationResponse/Response/Error/ErrorDescription
ErrorDescription
Required: No
Type: String
Max Allowed: 1
Length: 1...150
Describes the error code.
/AddressValidationResponse/Response/Error/MinimumRetrySeconds
MinimumRetrySeconds
Required: No
Type: String
Max Allowed: 1
Length: 1...15
How long to wait before re-transmitting a
Transaction that failed with a 'Transitive' error
/AddressValidationResponse/Response/Error/ErrorLocation
ErrorLocation
Required: Yes
Type: Container
Max Allowed: 1
Length: 1...150
XPATH of the element causing the 'Hard' error
/AddressValidationResponse/Response/Error/ErrorLocation/ErrorLocationElementName
ErrorLocationElementName
Required: No
Type: String
Max Allowed: 1
Length: 1...30
Element whose value causes the 'Hard' error
/AddressValidationResponse/Response/Error/ErrorLocation/ErrorLocationAttributeName
ErrorLocationAttributeName
Required: No
Type: String
Max Allowed: 1
Length:
Unbounded
Error Location Attribute information.
/AddressValidationResponse/Response/Error/ErrorDigest
ErrorDigest
Required: No
Type: String
Max Allowed: 1
Length:
Unbounded
Details of the error
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
17
Name
Constraint
Description
/AddressValidationResponse/ValidAddressIndicator
ValidAddressIndicator
Required: Cond
Type: String
Max Allowed: 1
Length: 0
Indicates query found a valid match.
/AddressValidationResponse/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.
/AddressValidationResponse/NoCandidatesIndicator
NoCandidatesIndicator
Required: Cond
Type: String
Max Allowed: 1
Length: 0
No Candidate found.
/AddressValidationResponse/AddressClassification
AddressClassification
Required: No
Type: Container
Max Allowed: 1
Length: N/A
Container returning the classification of the input
address, if requested
/AddressValidationResponse/AddressClassification/Code
Code
Required: Yes*
Type: String
Max Allowed: 1
Length: 1
Contains the classification code of the input
address.
0 = Unknown
1= Commercial
2 = Residential
/AddressValidationResponse/AddressClassification/Description
Description
Required: Yes*
Type: String
Max Allowed: 1
Length: 1...15
Contains the text description of the address
classification code:
Unknown
Commercial
Residential
/AddressValidationResponse/AddressKeyFormat
AddressKeyFormat
Required: Cond
Type: Container
Max Allowed: 1
Length: N/A
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.
/AddressValidationResponse/AddressKeyFormat/AddressClassification
AddressClassification
Required: No
Type: Container
Max Allowed: 1
Length: N/A
Container returning the classification of the
address, if requested
/AddressValidationResponse/AddressKeyFormat/AddressClassification/Code
Code
Required: Yes*
Type: String
Max Allowed: 1
Length: 1
Contains the classification code of the address.
0 = Unknown
1 = Commercial
2 = Residential
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
18
Name
Constraint
Description
/AddressValidationResponse/AddressKeyFormat/AddressClassification/Description
Description
Required: Yes*
Type: String
Max Allowed: 1
Length: 1...15
Contains the text description of the address
classification code.
Unknown
Commercial
Residential
/AddressValidationResponse/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.
/AddressValidationResponse/AddressKeyFormat/BuildingName
BuildingName
Required: Cond
Type: String
Max Allowed: 1
Length: 1...40
Name of building. Not returned if user selects the
RegionalRequestIndicator.
/AddressValidationResponse/AddressKeyFormat/AddressLine
AddressLine
Required: Cond
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.
/AddressValidationResponse/AddressKeyFormat/Region
Region
Required: No
Type: String
Max Allowed: 1
Length: 1...30
Single entry containing in this order Political
Division 2, Political Division 1 and Post Code
Primary Low and/or PostcodeExtendedLow.
/AddressValidationResponse/AddressKeyFormat/PoliticalDivision2
PoliticalDivision2
Required: Cond
Type: String
Max Allowed: 1
Length: 1...30
City or Town.
/AddressValidationResponse/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/Territory 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.
/AddressValidationResponse/AddressKeyFormat/PostcodePrimaryLow
PostcodePrimaryLow
Required: Cond
Type: String
Max Allowed: 1
Length: 1...10
Low-end Postal Code. Returned for countries or
territories with Postal Codes. May be alphanumeric
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
19
Name
Constraint
Description
/AddressValidationResponse/AddressKeyFormat/PostcodeExtendedLow
PostcodeExtendedLow
Required: No
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
/AddressValidationResponse/AddressKeyFormat/Urbanization
Urbanization
Required: No
Type: String
Max Allowed: 1
Length: 1...10
Puerto Rico Political Division 3. Only valid for
Puerto Rico.
/AddressValidationResponse/AddressKeyFormat/CountryCode
CountryCode
Required: Yes
Type: String
Max Allowed: 1
Length: 1...2
A Country or Territory code. Required to be
returned.
For a list of valid values, refer to the Address
Validation API Supported Countries/Territories
table in the Appendix.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
20
Chapter 5: Address Validation Street Level XML Examples
AddressValidationRequest XML
<?xml version="1.0" ?>
<AccessRequest xml:lang='en-US'>
<AccessLicenseNumber>YOURACCESSLICENSENUMBER</AccessLicenseNumber>
<UserId>YOURUSERID</UserId>
<Password>YOURPASSWORD</Password>
</AccessRequest>
<?xml version="1.0" ?>
<AddressValidationRequest xml:lang='en-US'>
<Request>
<TransactionReference>
<CustomerContext>Your Customer Context</CustomerContext>
</TransactionReference>
<RequestAction>XAV</RequestAction>
<RequestOption>1</RequestOption>
</Request>
<AddressKeyFormat>
<AddressLine>12380 MORRIS RD</AddressLine>
<Region>ALPHARETTA GA 30005-4177</Region>
<PoliticalDivision2>ALPHARETTA</PoliticalDivision2>
<PoliticalDivision1>GA</PoliticalDivision1>
<PostcodePrimaryLow>30005</PostcodePrimaryLow>
<PostcodeExtendedLow>4177</PostcodeExtendedLow>
<CountryCode>US</CountryCode>
</AddressKeyFormat>
</AddressValidationRequest>
AddressValidationResponse XML
<?xml version="1.0" ?>
<AddressValidationResponse>
<Response>
<TransactionReference>
<CustomerContext>Your Customer Context</CustomerContext>
</TransactionReference>
<ResponseStatusCode>1</ResponseStatusCode>
<ResponseStatusDescription>Success</ResponseStatusDescription>
</Response>
<ValidAddressIndicator/>
<AddressKeyFormat>
<AddressLine>12380 MORRIS RD</AddressLine>
<Region>ALPHARETTA GA 30005-4177</Region>
<PoliticalDivision2>ALPHARETTA</PoliticalDivision2>
<PoliticalDivision1>GA</PoliticalDivision1>
<PostcodePrimaryLow>30005</PostcodePrimaryLow>
<PostcodeExtendedLow>4177</PostcodeExtendedLow>
<CountryCode>US</CountryCode>
</AddressKeyFormat>
</AddressValidationResponse>
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 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 or teritories' 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/Territories 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 XML Developer Guide
July 9th, 2018
© 2018 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 XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
23
Appendices
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
24
Error Codes (XML)
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.
To discover errors, check the ResponseStatusCode element. A “1” normally indicates a successful response,
whereas a “0” indicates a Transient or Hard error. The PrimaryErrorCode element contains the error code and
description.
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.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
25
Code
Severity
Description
250005
Hard
No Access and Authentication Credentials provided.
250006
Hard
The maximum number of user access attempts was exceeded.
250007
Hard
The UserId is currently locked out, please try again in 30 minutes.
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 Error Codes (XML)
Error Code
Severity
Description
Condition
260050
Hard
Invalid Request Action
The request action is invalid.
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/territory code is not US or PR.
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/territory code that is not supported for
classification.
264008
Hard
Country code and address format
combination is not allowed.
Country/Territory code and address format
combination is not allowed.
264027
Hard
Additional address fields are
needed to perform the requested
operation.
The Country/Territory Code is valid but the other
fields are blank. Additional fields need to be
provided in order to validate or classify the address.
264030
Hard
The state is not supported in the
Customer Integration
Environment.
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
26
Address Validation Street Level API Supported Countries/Territories
UPS Country/Territory code abbreviations generally follow the ISO Standard 3166.
NOTE: Not all UPS services are available in every country or territory. Refer to the UPS Rate and
Service Guide at UPS.com for more information on UPS services.
Country/Territory
Name
Country/Territory
Code
Residential / Commercial
Classification
Street Level
Validation
Aland Islands
AX
X
Austria
AT
X
Azores
A2
X
Belgium
BE
X
Belarus
BY
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
Greece
GR
X
Holland
HO
X
Hungary
HU
X
Ireland, Republic of
IE
X
Italy
IT
X
Jersey
JE
X
Luxembourg
LU
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
Address Validation Street Level XML Developer Guide
July 9th, 2018
© 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary
27
Country/Territory
Name
Country/Territory
Code
Residential / Commercial
Classification
Street Level
Validation
Puerto Rico
PR
X
X
Romania
RO
X
Russia
RU
X
Scotland
SF
X
Slovenia
SI
X
Spain
ES
X
Sweden
SE
X
Switzerland
CH
X
Turkey
TR
X
Ukraine
UA
X
United Kingdom
GB
X
United States
US
X
X
Wales
WL
X

Navigation menu