Rawseo.com - Address Verification API
Address Verification Toolkit - Installation Guide
|
|
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>