How to Build an Address Validation API 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> (6)
    </Header>
    <Address>
        <Line1>935 1st Ave</Line1> (1)
        <City>King of Prussia</City> (2)
        <MainDivision>PA</MainDivision> (3)
        <CountryCode>US</CountryCode> (4)
        <PostalCode>19406-1342</PostalCode> (5)
    </Address>
</AddressValidationRequest>

1	Copy the address lines from your address form. The API supports up to four
2	Copy the city name from your address form
3	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.
4	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.
5	Copy the zip or postal code from your address form here.
6	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> (1)
      <ResultCode>V</ResultCode>
      <ResultSuggestionCount>0</ResultSuggestionCount>
   </Result>
</AddressValidationResponse>

1	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> (1)
      <Line1>935 First Avenue</Line1>
      <City>Klang of Prooshah</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19407</PostalCode>
   </RequestAddress>
   <Result>
      <ResultCode>C</ResultCode> (2)
      <ErrorLocations>           (3)
         <ErrorLocation>PostalCode</ErrorLocation>
         <ErrorLocation>AddressLine1</ErrorLocation>
         <ErrorLocation>City</ErrorLocation>
      </ErrorLocations>
      <ResultSuggestionCount>1</ResultSuggestionCount> (4)
      <SuggestedAddresses> (5)
         <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> (3)
               <ErrorLocation>AddressLine1</ErrorLocation>
               <ErrorLocation>City</ErrorLocation>
               <ErrorLocation>PostalCode</ErrorLocation>
            </ErrorLocations>
         </SuggestedAddress>
      </SuggestedAddresses>
   </Result>
</AddressValidationResponse>

1	The address supplied on the request
2	The result code "C" meaning that the address was corrected
3	A list of fields that were problematic
4	The number of corrected address suggestions returned
5	A list of corrected address suggestions, in this case only one