Rawseo.com - Address Verification API

Address Verification Toolkit - Installation Guide

Jaslabs, LLC - http://www.rawseo.com
Support: support@rawseo.com

Introduction

Thank you for downloading the 15-day trial of the rawseo address verification toolkit. This toolkit can be used on any website to correct and verify addresses through the United States Postal Service. If you would like to use it past the 30 days, you need to purchase a site license Here. After the toolkit has expired, you will not be notified (IE: There will be no popups warning you that it has expired. It will just stop functioning/verifying addresses).

If you would like us to notify you when your 15-day trial is about to expire, please enter your email address below:

Pre-install

Step 1: Register for a USPS web tools account here
Step 2: After your account has been created in step one, you need to get special permission from USPS to use the address verification API. This is free, but you need to fill out the form here
Step 3: Upload all files included in the download to your site
Step 4: Open the following file: plugins/configure.php and change the following (it's near the top of the file):

define("USPS_USERNAME","*your username from usps goes here*");


Step 5: Click the test button below to make sure you have all of the proper settings and software installed.



Installing on your site

Step 1: Add the following between the <head> </head> tag on the page where your address form resides (rusps.formname should also be changed to the name of your form).

<script type="text/javascript" src="usps/js/jslibs.js.php"></script>
<script type="text/javascript">
rusps.formname = '** Your form name **';   //this is the name of the form that contain the fields we need to check
</script>

Note: The input type names on your page should match the ones in plugins/configure.php
//this defines your form fields on the page.  These should be the names of your fields on your page
define('ADDRESS1_FIELD','address1');
define('ADDRESS2_FIELD','address2');
define('CITY_FIELD','city');
define('STATE_FIELD','state');
define('ZIP_FIELD','zip');
//end defining form fields

By default, the state values returned are the capitalized abbreviations. If you need this changed, it can also be done in plugins/configure.php
$stateMap['AL'] = ""; 			//ALABAMA
$stateMap['AK'] = "";			//ALASKA
$stateMap['AS'] = ""; 			//AMERICAN SAMOA
$stateMap['AZ'] = "";			//ARIZONA
$stateMap['AR'] = ""; 			//ARKANSAS
$stateMap['CA'] = "";			//CALIFORNIA
$stateMap['CO'] = ""; 			//COLORADO
$stateMap['CT'] = "";			//CONNECTICUT
$stateMap['DE'] = ""; 			//DELAWARE
//end defining form fields
(The values added above will overwrite the value returned from the USPS servers)

Documentation

Variable Possible values Default Description
rusps.formname Name of a form the page This is the name of the form that contains the fields to be verified
rusps.ftimeout Timeout in milliseconds 5000
rusps.fconfirm true,false false After an address needs to be corrected, if this is set to true, a popup will be displayed to the user for confirmation
rusps.fconfmsg The message displayed to the user if an address needs to be corrected "Is this what you meant?" his is the messaged displayed on the confirmation popup after an address correction
rusps.fill ['address1','address2','city','zip'] All fields will be corrected by default You can specify fields that you only want filled in
rusps.fcallback A function name that will be called when an address needs to be corrected (see below) The function you specify will be called when an address needs to be corrected
rusps.ferror A function name that will be called when an error has occured (see below) The function you specify will be called when an error has occured
rusps.autocheck true/false true If this is disabled, fields on your form will not be checked and you need to call the check functions manually.
rusps.autocheckmode 1,2,3 3 If autocheck is set to true, this allows you to specify what is enabled (1=address verification only,2=zip code check only, 3=both (default))


Function Description
rusps.verifyAddress('address') This function should get called when you want to verify an address (city+state+address is required). It will fill in a corrected address and a zipcode.
rusps.verifyAddress('zipcode') This function should get called when you want to retrieve a city+state from a zipcode.
-------------------------------
- rusps.fcallback description -
-------------------------------

function callback(address1,address2,city,state,zip)
{
	alert('called from a callback: \n\n'+address1+address2+'\n'+city+'\n'+state+'\n'+zip);
	return true;
}


-------------------------------
- rusps.ferror description    -
-------------------------------

//error handling function
function errorHandler(code)
{	
	switch(code)
	{
		case 1:
			//The address you specified could not be found
		break;
		case 3:
		 	//Could not connect to the USPS api servers.
		break;
		case 4:
			//An unknown error has occured
		break;
	}
}

Examples

Example 1

This is a simple example of usage. Both address verification and zipcode checks are enabled automatically



Example 1 Source:
<head>
<script type="text/javascript" src="js/jslibs.js.php5"></script>
<script type="text/javascript">
rusps.formname = 'checkform';   //this is the name of the form that contain the fields we need to check
</script>
</head>

The main form that is validated.
<form name="checkform" id="checkform">
<table>
<tr>
<td>Address 1:</td><td><input type="text" name="address1" value="1600 Pennsylvania Avenue"></td>
</tr>
<tr>
<td>Address 2:</td><td><input type="text" id="address2" name="address2"></td>
</tr>
<tr>
<td>City:</td><td><input type="text" id="city" name="city" value="Washington"></td>
</tr>
<tr>
<td>State:</td>
<td>
<select name="state">
<option value="AL">Alabama</option>
<option value="AK">Alaska</option>
<option value="AS">American Samoa</option>
<option value="AZ">Arizona</option>
<option value="AR">Arkansas</option>
<option value="CA">California</option>
<option value="CO">Colorado</option>
<option value="CT">Connecticut</option>
<option value="DE">Delaware</option>
<option value="DC" selected>District of Columbia</option>
<option value="FM">Federated States Of Micronesia</option>
<option value="FL">Florida</option>
<option value="GA">Georgia</option>
<option value="GU">Guam</option>
<option value="HI">Hawaii</option>
<option value="ID">Idaho</option>
<option value="IL">Illinois</option>
<option value="IN">Indiana</option>
<option value="IA">Iowa</option>
<option value="KS">Kansas</option>
<option value="KY">Kentucky</option>
<option value="LA">Louisiana</option>
<option value="ME">Maine</option>
<option value="MH">Marshall Islands</option>
<option value="MD">Maryland</option>
<option value="MA">Massachusetts</option>
<option value="MI">Michigan</option>
<option value="MN">Minnesota</option>
<option value="MS">Mississippi</option>
<option value="MO">Missouri</option>
<option value="MT">Montana</option>
<option value="NE">Nebraska</option>
<option value="NV">Nevada</option>
<option value="NH">New Hampshire</option>
<option value="NJ">New Jersey</option>
<option value="NM">New Mexico</option>
<option value="NY">New York</option>
<option value="NC">North Carolina</option>
<option value="ND">North Dakota</option>
<option value="MP">Northern Mariana Islands</option>
<option value="OH">Ohio</option>
<option value="OK">Oklahoma</option>
<option value="OR">Oregon</option>
<option value="PW">Palau</option>
<option value="PA">Pennsylvania</option>
<option value="PR">Puerto Rico</option>
<option value="RI">Rhode Island</option>
<option value="SC">South Carolina</option>
<option value="SD">South Dakota</option>
<option value="TN">Tennessee</option>
<option value="TX">Texas</option>
<option value="UT">Utah</option>
<option value="VT">Vermont</option>
<option value="VI">Virgin Islands</option>
<option value="VA">Virginia</option>
<option value="WA">Washington</option>
<option value="WV">West Virginia</option>
<option value="WI">Wisconsin</option>
<option value="WY">Wyoming</option>
</select>
</tr>
<tr>
<td>Zip:</td><td><input type="text" name="zip" autocomplete="off"></td>
</tr>
</table>

Example 2

Auto-corrections have been disabled (zipcode and address) and the address is only verified when the ser clicks the "verify" button.


Example 2 Source:
<head>
<script type="text/javascript" src="js/jslibs.js.php"></script>
<script type="text/javascript">
rusps.formname = 'checkform';   //this is the name of the form that contain the fields we need to check
rusps.ftimeout = 5000;			//set timeout for getting results (in milliseconds)
rusps.fconfirm = true;			//upon verifying of the address, do we want to confirm?
rusps.fconfmsg = 'Is this the address you meant?'; //message displayed on the confirm box
rusps.autocheck = false;
</script>
</head>

The main form that is validated.
<form name="checkform" id="checkform">
<table>
<tr>
<td>Address 1:</td><td><input type="text" name="address1" value="1600 Pennsylvania Avenue"></td>
</tr>
<tr>
<td>Address 2:</td><td><input type="text" id="address2" name="address2"></td>
</tr>
<tr>
<td>City:</td><td><input type="text" id="city" name="city" value="Washington"></td>
</tr>
<tr>
<td>State:</td>
<td>

<select name="state">
<option value="AL">Alabama</option>
<option value="AK">Alaska</option>
<option value="AS">American Samoa</option>
<option value="AZ">Arizona</option>
<option value="AR">Arkansas</option>
<option value="CA">California</option>
<option value="CO">Colorado</option>
<option value="CT">Connecticut</option>
<option value="DE">Delaware</option>
<option value="DC" selected>District of Columbia</option>
<option value="FM">Federated States Of Micronesia</option>
<option value="FL">Florida</option>
<option value="GA">Georgia</option>
<option value="GU">Guam</option>
<option value="HI">Hawaii</option>
<option value="ID">Idaho</option>
<option value="IL">Illinois</option>
<option value="IN">Indiana</option>
<option value="IA">Iowa</option>
<option value="KS">Kansas</option>
<option value="KY">Kentucky</option>
<option value="LA">Louisiana</option>
<option value="ME">Maine</option>
<option value="MH">Marshall Islands</option>
<option value="MD">Maryland</option>
<option value="MA">Massachusetts</option>
<option value="MI">Michigan</option>
<option value="MN">Minnesota</option>
<option value="MS">Mississippi</option>
<option value="MO">Missouri</option>
<option value="MT">Montana</option>
<option value="NE">Nebraska</option>
<option value="NV">Nevada</option>
<option value="NH">New Hampshire</option>
<option value="NJ">New Jersey</option>
<option value="NM">New Mexico</option>
<option value="NY">New York</option>
<option value="NC">North Carolina</option>
<option value="ND">North Dakota</option>
<option value="MP">Northern Mariana Islands</option>
<option value="OH">Ohio</option>
<option value="OK">Oklahoma</option>
<option value="OR">Oregon</option>
<option value="PW">Palau</option>
<option value="PA">Pennsylvania</option>
<option value="PR">Puerto Rico</option>
<option value="RI">Rhode Island</option>
<option value="SC">South Carolina</option>
<option value="SD">South Dakota</option>
<option value="TN">Tennessee</option>
<option value="TX">Texas</option>
<option value="UT">Utah</option>
<option value="VT">Vermont</option>
<option value="VI">Virgin Islands</option>
<option value="VA">Virginia</option>
<option value="WA">Washington</option>
<option value="WV">West Virginia</option>
<option value="WI">Wisconsin</option>
<option value="WY">Wyoming</option>
</select>
</tr>
<tr>
<td>Zip:</td><td><input type="text" name="zip" autocomplete="off"></td>
</tr>
<tr>
<td> </td><td><input type="button" value="Verify" onclick="rusps.verifyAddress('address')"></td>
</tr>
</table>
</form>