_Cover_Address_Validation_Street_XML Address Validation Street Level XML Developer Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 27
| Download | |
| Open PDF In Browser | View PDF |
Address Validation - Street Level XML Developer Guide July 9 , 2018 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 2 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 3 Address Validation Street Level XML Developer Guide July 9th, 2018 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 © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 4 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 5 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 6 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 7 Address Validation Street Level XML Developer Guide July 9th, 2018 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 © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 8 Address Validation Street Level XML Developer Guide July 9th, 2018 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. Company or Name: LAKESIDE PAIN CENTER AddressLine: 6010 LAKESIDE AddressLine: City: Macon State: Zip: 312 Country: US But the API will be able to return an address that maybe similar to the one that was provided as a candidate. Company or Name: LAKESIDE PAIN CENTER AddressLine: 6010 LAKESIDE AddressLine: City: Macon State: GA Zip: 31210 Country: US © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 9 Address Validation Street Level XML Developer Guide July 9th, 2018 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 © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 10 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 11 Address Validation Street Level XML Developer Guide July 9th, 2018 AddressValidationRequest Top Level Containers AddressValidationRequest XPath Tables Note: Not all containers/elements are reflected separately in the table of contents. Name Constraint Description Required: Yes Type: Container Max Allowed: 1 Length: N/A AddressValidationRequest Container. Required: Yes Type: Container Max Allowed: 1 Length: N/A Request Container. /AddressValidationRequest AddressValidationRequest /AddressValidationRequest/Request Request /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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 12 Address Validation Street Level XML Developer Guide Name Constraint July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 13 Address Validation Street Level XML Developer Guide Name Constraint July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 14 Address Validation Street Level XML Developer Guide July 9th, 2018 AddressValidationResponse Top Level Containers AddressValidationResponse XPath Table Note: Not all containers/elements are reflected separately in the table of contents. Name Constraint Description Required: Yes Type: Container Max Allowed: 1 Length: N/A Container for AddressValidationResponse. /AddressValidationResponse 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'. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 15 Address Validation Street Level XML Developer Guide Name Constraint July 9th, 2018 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 © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 16 Address Validation Street Level XML Developer Guide Name Constraint July 9th, 2018 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 © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 17 Address Validation Street Level XML Developer Guide Name Constraint July 9th, 2018 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 © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 18 Address Validation Street Level XML Developer Guide Name Constraint July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 19 Address Validation Street Level XML Developer Guide July 9th, 2018 Chapter 5: Address Validation Street Level XML Examples AddressValidationRequest XMLYOURACCESSLICENSENUMBER YOURUSERID YOURPASSWORD AddressValidationResponse XML Your Customer Context XAV 1 12380 MORRIS RD ALPHARETTA GA 30005-4177 ALPHARETTA GA 30005 4177 US © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 20 Address Validation Street Level XML Developer Guide July 9th, 2018 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 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. 2. Validation = monthly © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 21 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 22 Address Validation Street Level XML Developer Guide July 9th, 2018 Appendices © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 23 Address Validation Street Level XML Developer Guide July 9th, 2018 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. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 24 Address Validation Street Level XML Developer Guide July 9th, 2018 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 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. Adapter parsing error, business process calling error, backend service is unavailable, etc. © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 25 Address Validation Street Level XML Developer Guide July 9th, 2018 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 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 Street Level Validation © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 26 Address Validation Street Level XML Developer Guide Country/Territory Name Country/Territory Code July 9th, 2018 Residential / Commercial Classification Puerto Rico PR 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 Wales WL X Street Level Validation X X © 2018 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary 27 Your Customer Context 1 Success 12380 MORRIS RD ALPHARETTA GA 30005-4177 ALPHARETTA GA 30005 4177 US
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : Yes Encryption : Standard V2.3 (128-bit) User Access : Print, Modify, Copy, Annotate, Fill forms, Extract, Print high-res Page Count : 27 Language : en-US Tagged PDF : Yes XMP Toolkit : 3.1-701 Producer : Microsoft® Word 2013 Creator Tool : Microsoft® Word 2013 Create Date : 2018:06:07 10:33:50-04:00 Modify Date : 2018:06:07 10:39:03-04:00 Title : _Cover_Address_Validation_Street_XML Creator : MadCap Software Author : MadCap SoftwareEXIF Metadata provided by EXIF.tools