How to Build an Address Validation Request
This page covers how to build a ROM address validation API request message and how to interpret the response message.
The address validation API supports:
-
Mailing address with up to four lines
-
Mailing addresses in a large number of countries (see the following link)
For more details please see the Address Validation API page.
Address Validation API Request Message
Building the address validations request message from your address form is simple. The diagram below illustrates an request message with a valid address.
<?xml version="1.0" encoding="UTF-8"?>
<AddressValidationRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Header>
<MaxAddressSuggestions>3</MaxAddressSuggestions> <!-- see NOTE6 -->
</Header>
<Address>
<Line1>935 1st Ave</Line1> <!-- see NOTE1 -->
<City>King of Prussia</City> <!-- see NOTE2 -->
<MainDivision>PA</MainDivision> <!-- see NOTE3 -->
<CountryCode>US</CountryCode> <!-- see NOTE4 -->
<PostalCode>19406-1342</PostalCode> <!-- see NOTE5 -->
</Address>
</AddressValidationRequest>| NOTE1 | Copy the address lines from your address form. The API supports up to four |
| NOTE2 | Copy the city name from your address form |
| NOTE3 | Use the state or province (depending on country) from your address form as the MainDivision value. For the most accurate results send the ISO-3166-2 code for the state, province or territory in question. |
| NOTE4 | Use the the country from your address form here. For the most accurate results send the ISO-3166 alpha-2 code for the country in question. |
| NOTE5 | Copy the zip or postal code from your address form here. |
| NOTE6 | You can tell the API how many address correction suggestions you’d like returned |
|
Postal code standards for countries, states, provinces and territories
Using standard accepted postal codes for the
countries (ISO-3166 alpha-2 codes)
and main divisions (ISO-3166-2 codes)
in the addresses sent to ROM API maximizes the chance
of successful fulfillment of the order.
|
|
Always send country code with an address
To ensure accurate deliveries always send an ISO-3166 alpha-2
country code with an address even if your e-commerce application
only does business in a single country and your address form does
not support country selection
|
Interpreting the Address Validation Response Message
The request is made via HTTPS POST to
/v1.0/stores/<your store ID>/address/validate.xml and must include
the following HTTP headers:
ApiKey: <your API key>Content-Type: text/xml
The ROM address validation API supports the following HTTP response status codes:
| Status | Description | Action |
|---|---|---|
|
200 |
Success |
Interrogate the response payload for additional information. |
|
400 |
Bad request. The API could not process the request due to either a syntax error or bad data in the provided request payload. |
This is a programming time error. Interrogate the fault message in the response payload for more information. Fix the syntax or data issue in the requesting application. |
|
500 |
API processing error. The API could not process the request due to a temporary internal error. |
Requesting application should proceed as if the API responded with a 200 status and the response payload reported no problems with the address. |
|
Timeouts
e-commerce application should set a reasonable timeout on all
ROM API calls. If an API call does not respond within the
configured timeout the application should proceed as if the call returned
a 500 http status.
|
The sample request above should produce a 200 HTTP response and a response payload XML which says all is good. The figure below illustrates such a response payload.
<?xml version="1.0" encoding="UTF-8"?>
<AddressValidationResponse xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Header>
<MaxAddressSuggestions>3</MaxAddressSuggestions>
</Header>
<RequestAddress>
<Line1>935 1st Ave</Line1>
<City>King of Prussia</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19406-1342</PostalCode>
</RequestAddress>
<Result> <!-- see NOTE1 -->
<ResultCode>V</ResultCode>
<ResultSuggestionCount>0</ResultSuggestionCount>
</Result>
</AddressValidationResponse>| NOTE1 | The //Result section reports back that the input adress is valid:
//ResultCode == "V";
and that no suggestions were returned: //SuggestionCount == 0. |
Interpreting Address Correction Suggestions in the Response
The address validation request message in the figure below represents a less well formed version of the address above.
<?xml version="1.0" encoding="UTF-8"?>
<AddressValidationRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Header>
<MaxAddressSuggestions>3</MaxAddressSuggestions>
</Header>
<Address>
<Line1>935 First Avenue</Line1>
<City>Klang of Prooshah</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19407</PostalCode>
</Address></AddressValidationRequest>The ROM address validation API responds to this request message with a status indicating that there were problems with the input address. The response also contains a suggested correction and details indicating which input fields were problematic.
<?xml version="1.0" encoding="UTF-8"?>
<AddressValidationResponse xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Header>
<MaxAddressSuggestions>3</MaxAddressSuggestions>
</Header>
<RequestAddress> <!-- see NOTE1 -->
<Line1>935 First Avenue</Line1>
<City>Klang of Prooshah</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19407</PostalCode>
</RequestAddress>
<Result>
<ResultCode>C</ResultCode> <!-- see NOTE2 -->
<ErrorLocations> <!-- see NOTE3 -->
<ErrorLocation>PostalCode</ErrorLocation>
<ErrorLocation>AddressLine1</ErrorLocation>
<ErrorLocation>City</ErrorLocation>
</ErrorLocations>
<ResultSuggestionCount>1</ResultSuggestionCount> <!-- see NOTE4 -->
<SuggestedAddresses> <!-- see NOTE5 -->
<SuggestedAddress>
<Line1>935 1st Ave</Line1>
<City>King of Prussia</City>
<MainDivision>PA</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>19406-1342</PostalCode>
<FormattedAddress>935 1st Ave, King of Prussia PA
19406-1342, US</FormattedAddress>
<ErrorLocations> <!-- see NOTE3 -->
<ErrorLocation>AddressLine1</ErrorLocation>
<ErrorLocation>City</ErrorLocation>
<ErrorLocation>PostalCode</ErrorLocation>
</ErrorLocations>
</SuggestedAddress>
</SuggestedAddresses>
</Result>
</AddressValidationResponse>| NOTE1 | The address supplied on the request |
| NOTE2 | The result code "C" meaning that the address was corrected |
| NOTE3 | A list of fields that were problematic |
| NOTE4 | The number of corrected address suggestions returned |
| NOTE5 | A list of corrected address suggestions, in this case only one |