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.

Copy this code sample. 
<?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.

Copy this code sample. 
<?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.

Copy this code sample. 
<?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.

Copy this code sample. 
<?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