getCityState - Checkout API Method

Owned by Perry Tew
Last updated: May 16, 2011Version comment
9 min read

Method Definition

Method Signature

CityStateZip getCityState(String zip);

Description

Takes a zip and does a city and state lookup with the United States Postal Service.

Result

A CityStateZip object.

Discussion

  1. Make the remote call
  2. Check to make sure the result is not null. If it is, a system error occurred.
  3. Check CityStateZip .validZip flag. If false, the zip was invalid. Also, if false, examine the CityStateZip .error property. If it contains anything, a system error occurred.
  4. If zip was valid, city and state will be populated and may be used.

Examples



As with all Checkout API examples, remember to install the relay script on your local web server before attempting to run these examples. Browsers will not allow cross site scripting.
For more information, please see the discussion on XHR issues.



The following file is also an attachment to this page.

Checkout API v1.1 
<html>
<head>
  <script type='text/javascript' src='js/jquery-1.4.2.min.js'></script>
  <script type='text/javascript' src='js/jquery.json-2.2.min.js'></script>
  <script type='text/javascript' src='js/checkoutapi-1.1.js'></script>

  <script type='text/javascript'>

    window.onload = function(){
      log('initializing checkout');
      initializeCheckoutAPI("DEMO", 'secure.ultracart.com', 'http://www.mystore.com/proxy.php');
      log('getting cart instance');
      getCartInstance();
      log('attaching lookup function to zip element blur event');
      document.getElementById('zip').addEventListener('blur', lookup);

    };

    function lookup(){
      var zip = document.getElementById('zip');
      var city = document.getElementById('city');
      var state = document.getElementById('state');

      log('lookup(' + zip.value + '):');

      //Method 1: Asynchronously
      getCityState(zip.value, {async:true, onComplete:function(result){
        if(result == null){
          log('result of remote call was null. something went wrong on the server.');
        } else if(result.validZip){
          log('    SUCCESS! ' + result.city + ' ' + result.state);
          city.value = result.city;
          state.value = result.state;
        } else {
          log('    Invalid Zip Code');
          if(result.error){
            log('    System Error: ' + result.error); // handle this gracefully or just ignore...
          }
        }
      }});


      //Method 2: Synchronous
      /*
      var result = getCityState(zip.value);
      if(result == null){
        log('result of remote call was null. something went wrong on the server.');
      } else if(result.validZip){
        log('    SUCCESS! ' + result.city + ' ' + result.state);
        city.value = result.city;
        state.value = result.state;
      } else {
        log('    Invalid Zip Code');
        if(result.error){
          log('    System Error: ' + result.error); // handle this gracefully or just ignore...
        }
      }
      */

    }

    function log(msg){
      var div = document.getElementById('log');
      var txtNode = document.createTextNode(msg);
      var br = document.createElement('br');
      div.appendChild(txtNode);
      div.appendChild(br);
    }

  </script>
</head>
<body>

<table>
<tr><td>Zip Code:</td><td><input type='text' id='zip'/></td></tr>
<tr><td>City:</td><td><input type='text' id='city'/></td></tr>
<tr><td>State:</td><td><input type='text' id='state' /></td></tr>
</table>
<div id='log' style='margin-top:20px;'>
<div style='font-weight:bold'>Log Events Will Appear Below:</div>
</div>




</body>
</html>



The following file is also an attachment to this page.

Checkout API v1.2 
<html>
<head>
  <script type='text/javascript' src='js/jquery-1.4.2.min.js'></script>
  <script type='text/javascript' src='js/jquery.json-2.2.min.js'></script>
  <script type='text/javascript' src='js/checkoutapi-1.2.js'></script>

  <script type='text/javascript'>

    window.onload = function(){
      log('initializing checkout');
      initializeCheckoutAPI({merchantId: "DEMO", secureHostName:'secure.ultracart.com', callbackUrl:'http://www.mystore.com/proxy.php', debugMode:true, verboseAjax:true});
      log('getting cart instance');
      getCartInstance();
      log('attaching lookup function to zip element blur event');
      document.getElementById('zip').addEventListener('blur', lookup);

    };

    function lookup(){
      var zip = document.getElementById('zip');
      var city = document.getElementById('city');
      var state = document.getElementById('state');

      log('lookup(' + zip.value + '):');

      //Method 1: Asynchronously
      getCityState(zip.value, {async:true, onComplete:function(result){
        if(result == null){
          log('result of remote call was null. something went wrong on the server.');
        } else if(result.validZip){
          log('    SUCCESS! ' + result.city + ' ' + result.state);
          city.value = result.city;
          state.value = result.state;
        } else {
          log('    Invalid Zip Code');
          if(result.error){
            log('    System Error: ' + result.error); // handle this gracefully or just ignore...
          }
        }
      }});


      //Method 2: Synchronous
      /*
      var result = getCityState(zip.value);
      if(result == null){
        log('result of remote call was null. something went wrong on the server.');
      } else if(result.validZip){
        log('    SUCCESS! ' + result.city + ' ' + result.state);
        city.value = result.city;
        state.value = result.state;
      } else {
        log('    Invalid Zip Code');
        if(result.error){
          log('    System Error: ' + result.error); // handle this gracefully or just ignore...
        }
      }
      */

    }

    function log(msg){
      var div = document.getElementById('log');
      var txtNode = document.createTextNode(msg);
      var br = document.createElement('br');
      div.appendChild(txtNode);
      div.appendChild(br);
    }

  </script>
</head>
<body>

<table>
<tr><td>Zip Code:</td><td><input type='text' id='zip'/></td></tr>
<tr><td>City:</td><td><input type='text' id='city'/></td></tr>
<tr><td>State:</td><td><input type='text' id='state' /></td></tr>
</table>
<div id='log' style='margin-top:20px;'>
<div style='font-weight:bold'>Log Events Will Appear Below (debugMode is also ON, so open your browser's console for additional info):</div>
</div>




</body>
</html>



The following file is also an attachment to this page.

Checkout API v2.0 
<html>
<head>
  <script type='text/javascript' src='js/jquery-1.4.2.min.js'></script>
  <script type='text/javascript' src='js/jquery.json-2.2.min.js'></script>
  <script type='text/javascript' src='js/checkoutapi-2.0.js'></script>

  <script type='text/javascript'>

    var merchantCartConfig =
    {
      merchantId: "DEMO",
      screenBrandingThemeCode: 'DFLT', // doesn't affect these pages, but will determine how receipt and upsell pages appear.
      isCheckoutPage: false, // if true, additional code is run during init() to populate shipping methods and such.  This must
                            // be true if you are collecting address information, displaying shipping, or finalizing an order.
      checkoutSite: 'secure.ultracart.com', // this site is only used during checkout. You may omit this, and checkout will proceed to secure.ultracart.com
                                          // if you provide a value, it must be an SSL alias that points to secure.ultracart.com (Custom SSL Certificate)
                                          // if isCheckoutPage = false, this value doesn't matter.

      remoteApiUrl: 'http://www.mystore.com/proxy.php', // this url is used for all remote calls. It may point to secure.ultracart.com, a custom SSL site, or your own proxy script.
                                                             // you may omit this, and the default url is used (points to a path at secure.ultracart.com)
                                                             // see the top of the checkoutapi script for the path info if you have a custom ssl cert.
      debugMode: true,
      verboseAjax: true
    };

    jQuery('document').ready(function(){
      log('initializing checkout');
      ultraCart.init(merchantCartConfig);
      log('attaching lookup function to zip element blur event');
      document.getElementById('zip').addEventListener('blur', lookup);
    });


    function lookup(){
      var zip = document.getElementById('zip');
      var city = document.getElementById('city');
      var state = document.getElementById('state');

      log('lookup(' + zip.value + '):');

      //Method 1: Asynchronously
      ultraCart.getCityState(zip.value, {async:true, onComplete:function(result){
        if(result == null){
          log('result of remote call was null. something went wrong on the server.');
        } else if(result.validZip){
          log('    SUCCESS! ' + result.city + ' ' + result.state);
          city.value = result.city;
          state.value = result.state;
        } else {
          log('    Invalid Zip Code');
          if(result.error){
            log('    System Error: ' + result.error); // handle this gracefully or just ignore...
          }
        }
      }});


      //Method 2: Synchronous
      /*
      var result = ultraCart.getCityState(zip.value);
      if(result == null){
        log('result of remote call was null. something went wrong on the server.');
      } else if(result.validZip){
        log('    SUCCESS! ' + result.city + ' ' + result.state);
        city.value = result.city;
        state.value = result.state;
      } else {
        log('    Invalid Zip Code');
        if(result.error){
          log('    System Error: ' + result.error); // handle this gracefully or just ignore...
        }
      }
      */

    }

    function log(msg){
      var div = document.getElementById('log');
      var txtNode = document.createTextNode(msg);
      var br = document.createElement('br');
      div.appendChild(txtNode);
      div.appendChild(br);
    }

  </script>
</head>
<body>

<table>
<tr><td>Zip Code:</td><td><input type='text' id='zip'/></td></tr>
<tr><td>City:</td><td><input type='text' id='city'/></td></tr>
<tr><td>State:</td><td><input type='text' id='state' /></td></tr>
</table>
<div id='log' style='margin-top:20px;'>
<div style='font-weight:bold'>Log Events Will Appear Below (debugMode is also ON, so open your browser's console for additional info):</div>
</div>




</body>
</html>