How To Use The Perfect Address Software Developer's Kit - An Overview

The Perfect Address SDK performs address verification, address correction and 
standardization, and supplementary address information retrieval under the 
control of your program. 

You can use the Perfect Address SDK in many different ways. The two most common
applications are (1) to update all addresses in a database in a "batch" mode, 
and (2) to verify individual addresses interactively in an "on-line" mode. An 
example of a batch application: you have a database of 10,000 customers whose 
addresses you want to correct and standardize in a single programming "batch" 
run. An example of an interactive application: you have operators taking orders 
over the telephone. You want to verify, correct, and standardize each customer's
address interactively while the customer is still on the phone. 

The SDK performs well in either application, but it does not provide a complete 
solution in either case. You must provide the primary computer program to 
connect the SDK to your operating environment, whatever that might be. That 
primary computer program could be a commercial program or it could be a custom 
program.

You can think of the SDK as a general purpose address matching toolkit, which 
provides tools to your program. These tools make it easy for your program to 
perform address verification and correction in the context of your operating 
environment, whatever that might be. The SDK alone cannot process all of the 
records in your database, because it has no knowledge of your particular 
database organization or structure. Likewise, it cannot capture an address 
from a user interface or display a corrected address to an operator because 
it has no knowledge of your particular data entry environment. We designed 
the SDK as a general purpose address matching toolkit which can be used in 
many different environments. Its uses are limited only by your imagination!

The SDK can be directly integrated with many commercial programs either for 
cleaning up an entire address database or to process addresses as they are 
collected. Most commercial database programs, including MS Access, Visual 
FoxPro, Visual Basic, Paradox, etc., provide the programming "hooks" 
necessary to call the Perfect Address SDK. This makes it relatively easy to
incorporate address matching into applications written for these commercial 
products.

The SDK processes only one address at any time. Your program must extract 
each address from your database or from a data entry form, pass the address 
to the SDK for address verification, retrieve the corrected address from the 
SDK, and then update the database or display the corrected address to an 
operator, as you wish.

The actual address verification and correction using the Perfect Address SDK 
is a two-step process. First, the address must be found in the 750 MB address 
database. This is a complex process called "address matching" using rules 
defined by the US Postal Service. If the address can be "matched" to a single 
entry in the address database then it is possible to continue with the address 
correction and information retrieval steps. If an address cannot be "matched" 
to a single address database entry then address correction and information 
retrieval are not possible for that particular address. In the latter case 
there are some alternate manual steps which can be taken to correct the address.


Step 1: The Address Search

Your program must first gather the components of an address (street address, 
city and state or ZIP code) and pass the address to the Perfect Address SDK 
address matching DLL module (unzdll32.dll) using the UNZ_CHECKADDRESS function 
call. The DLL module parses the address into its components and then searches 
the 650 MB address database for the best match it can find, using address 
matching rules defined by the US Postal Service. The DLL then reports the results 
of this search back to your program as a result code.

The results of an address check can be any one of these four possibilities:

a. The address was found with an exact match. No spelling or format changes are 
   needed.
b. The address was found, but spelling and/or format changes were necessary to 
   achieve a match.
c. The address was not found. No match was possible using USPS address matching 
   rules.
d. More than one matching address was found. The SDK cannot decide which one 
   is correct.


Step 2: Standardized Address Retrieval

Your program must examine the result code returned by function UNZ_CHECKADDRESS 
to decide what to do next. Here are some suggestions:

a. An exact match requires no further action. The address was already in 
   standardized format, complete with ZIP+4. Nothing can be gained by 
   retrieving the address from the SDK. You MAY wish to retrieve additional 
   information about the address, such as its county, area code, congressional 
   district, and so on. These steps are described below.

b. If the result code indicates that the address was corrected to achieve a 
   match or was reformatted to USPS standardized address format, you probably 
   will want to retrieve the corrected, standardized address from the SDK to 
   update your database or display to an operator. To retrieve the corrected 
   address your program must call the SDK again using one or more of the
   SDK's address retrieval functions, such as UNZ_GETSTDADDRESS, listed below. 
   It is not necessary to pass the address to the SDK again; the SDK remembers 
   the last address which you verified, and returns the corrected, standardized 
   form of that address. You can use the address information retrieved by these 
   functions to update your database record or display the corrected address to 
   an operator. If your program does not perform this update step, your database 
   will remain unchanged. NOTE: THE SDK ITSELF NEVER DIRECTLY UPDATES YOUR 
   DATABASE FILES. Only your program can do that.

   Your program can retrieve corrected and standardized address information as 
   full standardized address lines or as individual address components, 
   depending upon which functions your program calls:

   UNZ_GETSTDADDRESS   - Returns the standardized address as full address lines
   UNZ_GETSTREETPARTS  - Returns the standardized address as separate components
   UNZ_GETSTREETNUMBER - Returns the numeric address and predirection
   UNZ_GETSTREETNAME   - Returns the street name, suffix, and postdirection
   UNZ_GETCITYSTZIP    - Returns the city-state-ZIP+4

   The SDK also provides other functions which return standardized address 
   components in various useful ways. See the Perfect Address SDK Programmer's 
   Guide for more details.

   A reminder: your program should ONLY call these functions to retrieve a 
   standardized address AFTER calling UNZ_CHECKADDRESS and receiving a result 
   indicating an exact match or corrected address match. If an address match 
   WAS NOT FOUND, then these functions return ambiguous results.

c. If no matching address was found, even after applying all logical naming 
   and spelling corrections according to USPS address matching rules, then 
   there is nothing your program can retrieve from the SDK about this 
   particular address. The SDK cannot correctly "standardize" an address if no 
   match was found, because it cannot "guess" (according to USPS address 
   matching rules) the components of the address. 

   What can you do in this case? Perhaps the operator has severely misspelled 
   the street name or the city name. Or the customer left out some important 
   address information. It is also possible that the street or address simply 
   has not yet been added to the USPS's national address database. It often 
   takes months for new subdivisions to be added to the national database.

   The result code returned by UNZ_CHECKADDRESS can give your program important 
   clues about why address matching failed for an address. Addresses which 
   cannot be resolved by the SDK require human intervention to determine the 
   exact cause of the problem. In a database, you might mark the record with a 
   special code or place the record into a special file for further examination 
   by an operator at a later time. For an interactive application, you might 
   wish to display street information to the operator. 

   For example, the SDK includes functions which allow your program to retrieve 
   all valid street names for the target city. Using street name data returned 
   by functions UNZ_GETSTREETCOUNT and UNZ_GETSTREETITEM your program might 
   build an interactive display for your operators to assist them to manually 
   resolve a troublesome address. Your program can retrieve street information 
   from the SDK to incorporate into such displays, but your program must build 
   the displays itself. The SDK itself contains no display functions for 
   building such interactive displays.

   Another approach to resolving address matching problems is to use the 
   interactive Windows program Perfect Address (a separate product). This 
   program allows an operator to "see" into the national address database in 
   an interactive way, possibly resolving the address while discussing the 
   problem with the customer on the telephone. Note: the Perfect Address SDK 
   includes a single-user version of Perfect Address which you can use to 
   evaluate this approach. However, for network use on a company-wide basis, 
   you'll need an Enterprise License for Perfect Address. Contact CD Light for 
   more details. Both products use the exact same 650 MB national address
   database.

d. If the SDK finds multiple addresses which match the input address, there is 
   nothing your program can retrieve from the SDK about the input address 
   itself. However, your program can retrieve the list of matching standardized 
   addresses using functions UNZ_GETMATCHCOUNT and UNZ_GETMATCHADDR. This 
   makes it possible to display the list of matching addresses to the operator, 
   who may then be able to resolve the ambiguity. However, the SDK itself 
   contains no display functions for building such an interactive display.


Retrieving Additional Address Information

If the results of the address check indicate that an exact match or corrected 
match was found, then, in addition to the standardized address, your program 
MAY retrieve additional information about that address:

UNZ_GETAREACODE     - the area code (for the 5-digit ZIP code)
UNZ_GETCOUNTY       - the county name
UNZ_GETCNTYFIPS     - the county FIPS code
UNZ_GETDPBC         - delivery point bar code digits
UNZ_GETCONGDIST     - congressional district
UNZ_GETTIMEZONE     - time zone and daylight savings flag

Note that if an address match WAS NOT FOUND, then these functions return 
ambiguous results.


Summary

The Perfect Address SDK provides tools which your custom or commercial 
database program can use to verify and correct an address and find additional 
information about an address. Your program must pass the address to be 
verified to the SDK and then retrieve the corrected address from the SDK. All 
database scanning and update functions and user interface functions must
reside in your program.


