FAQs#

General#

What is the Perfect Address Software Developer’s Kit?#

The Perfect Address Software Developer’s Kit (SDK) consists of a mailing address database for the entire USA plus a search engine module which searches the 750-MB national address database quickly and efficiently in a standard Windows environment. The search engine is a Windows Dynamic Link Library (DLL) module which makes it easy for you to search the address database from your own custom programs or from commercial Windows applications such as MS Access or Visual Basic.

The Perfect Address SDK does all the dirty work of address matching, correcting spelling and naming mistakes for cities and streets, and adding the correct street name suffix. It even finds the proper city name from only the ZIP code, and corrects “alias” city names to the preferred city name. It also can provide additional information about an address, such as the proper county name and FIPS code, area code, time zone, and daylight saving time status.

Which commercial programs does the Perfect Address SDK work with?#

The Perfect Address SDK works with any commercial or custom program which can call a standard Windows DLL. This includes many commercial Windows database applications, such as:

  • MS Access

  • Visual FoxPro

  • dBase

  • Visual Basic

  • Delphi

  • Power Builder

  • Paradox

  • Oracle

It can also be used with spreadsheet programs such as Excel and Quattro Pro.

What does Perfect Address SDK do?#

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

Can I use the Perfect Address SDK with custom programs written in C or other languages?#

Yes. You can use the Perfect Address SDK with custom programs written in any language which can pass pointer parameters (passing by reference) in the standard Pascal calling convention. The search engine module is actually written in C++. The SDK includes sample programs written in C++ which show how to call the search engine to check an address. The SDK includes the necessary C/C++ header file.

Is the Perfect Address SDK compatible with Windows XP/Vista/7/8?#

Yes. It runs under all 32-bit and 64-bit Windows operating systems. It does not run under DOS.

Does the Perfect Address SDK run on UNIX? Mac? AS400?#

The Perfect Address SDK is available only for Windows platforms.

How can I use Perfect Address SDK?#

You can use the Perfect Address SDK in many different ways.

The two most common applications are:

1. Batch Mode

  • Update all addresses in a database in a “batch” 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.

2. Interactive Online Mode

  • Verify individual addresses interactively in an “on-line” mode.

  • 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.

Can I use the Perfect Address SDK to process my mailing list?#

The Perfect Address SDK can be called from your custom Windows program or many commercial Windows database programs to process each individual record in your address database, under the control of the calling program. Depending upon the exact features available in your database program, you should be able to process your entire address database in this “batch” mode.

Although the Perfect Address SDK was designed to be called from virtually any commercial database program, it has no knowledge of any particular database structure.

Does the Perfect Address SDK provide a complete solution?#

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.

Can Perfect Address SDK process all records in my database?#

No.

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!

What can Perfect Address SDK be integrated with?#

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.

How many addresses can Perfect Address SDK process at one time?#

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.

What is the address verification process for Perfect Address SDK?#

Can I use the Perfect Address SDK to get postal discounts?#

The Perfect Address SDK is not CASS-certified by the US Postal Service (USPS), and therefore cannot be used to obtain postal discounts. As a result, there is no USPS-mandated 60-day usage restriction on your access to the Perfect Address national address database, as with CASS-certified products. For more information on getting postal discounts, see How do I get postal discounts for my mailings?. See also What does “CASS” mean?.

If I can’t use the Perfect Address SDK to get postal discounts, why would I use it at all?#

Our customers use the Perfect Address SDK to verify and correct addresses at the point of address capture in interactive order processing or customer support applications. It is also used to standardize addresses in existing databases, so that duplicate records can be found and removed. Some customers use the SDK to add county, area code, or time zone information to their internal address databases.

If you use a mailing service bureau to prepare your mailing, your service bureau must process your address database to qualify for postal discounts, but normally does not return the updated address database to you. For that reason, you may wish to use the Perfect Address SDK to correct your address database in-house.

Can I use the Perfect Address SDK in an interactive application?#

Yes. The Perfect Address SDK can be used with either batch or interactive applications, but it includes special functions designed just for interactive applications. These interactive functions are not permitted under the USPS’s CASS rules, and therefore are not available in other products. If the search engine finds no exact match, it applies the “one component failure rule” in an attempt to find an address match. Using this rule, the search engine often finds multiple addresses which satisfy the address matching criteria. However, the USPS address matching rules prohibit the search engine from making a “guess” as to which address is correct.

For example, given this address:

250 FOREST

and applying the “one component failure rule”, the search engine might find these potential matches:

250 FOREST AVE

and

250 FOREST DR

Either address could be correct, and the search engine has no way to resolve the conflict. USPS rules specify that a “no match” error message must be returned to the calling program in this case. However, instead of returning a “no match” error code, the Perfect Address SDK (which lives under no USPS restrictions) returns a special error code which indicates to the calling program that multiple matching addresses have been found. The calling program can then utilize the special “multiple match” functions provided by the SDK to analyze and further process the individual matching addresses in an attempt to further resolve the conflict.

To help the calling program resolve multiple matching address conflicts such as the example above, the search engine provides two functions which permit your program to examine the multiple matching records one at a time, and take some appropriate action. For example, you might wish to display a list of possible matching addresses to an operator who could resolve the issue by discussing the addresses with the customer who may still be on the phone.

Who can use the Perfect Address SDK? Do I need to be a programmer to make it work?#

You don’t need to be a programmer in the formal sense to use the Perfect Address SDK. Users with only a little experience with the BASIC language have successfully interfaced Visual Basic and MS Access to the Perfect Address SDK. We provide a working sample program in Visual Basic to get you going. You need no knowledge of computer languages such as C or C#.

How does the Perfect Address SDK interact with the calling program?#

The calling program must first capture a street address from an operator or access an address record in a database file. It then must pass the address to the search engine for verification. The search engine searches the national address database, looking for the best match. Upon completing its search, the search engine returns an error code to the calling program, reporting one of the following results:

  • a single, exact address match

  • a single matching address, corrected as necessary

  • multiple matching addresses

  • address not found

The exact error code returned by the search engine provides details to the calling program about exactly what type of address correction was required, or why the address could not be matched. At this point the original address remains unchanged.

In the case of an address correction, the calling program must make a second call to the search engine to retrieve the corrected address. Then it is up to the calling program to decide what to do with the corrected address. The corrected address might be displayed to an operator for verification, or it might be copied back into the original database by the calling program. Note that the Perfect Address search engine module has no control over the disposition of the address information retrieved by the calling program.

What data does the Perfect Address national address database include for each address?#

The SDK provides some or all of the following information about each address which it successfully matches:

  • street number

  • predirection (N, E, W, S, NE, NW, SE, SW)

  • street name

  • street suffix (ST, AVE, RD, LN, etc.)

  • postdirection (N, E, W, S, NE, NW, SE, SW)

  • secondary type (APT, LOBBY, BLDG, STE, etc.)

  • secondary number

  • city

  • state

  • ZIP+4 (9-digit ZIP code)

  • congressional district (accurate to the ZIP+4 level)

  • delivery point bar code digits (calculated according to USPS rules)

  • county name (accurate to ZIP+4 level)

  • county FIPS code (accurate to ZIP+4 level)

  • area code (accurate to 5-digit ZIP code level)

  • time zone (accurate to 5-digit ZIP code level)

  • daylight saving time flag (accurate to 5-digit ZIP code level)

Can the Perfect Address SDK find the city associated with a 5-digit ZIP code?#

Yes. Using what we call the “reverse search” function, the SDK can find the preferred city name associated with any of the approximately 42,000 5-digit ZIP codes assigned by the US Postal Service.

Can the Perfect Address SDK find the address associated with a particular 9-digit ZIP code?#

Yes. Using what we call the “reverse search” function, the SDK can find the specific address or address range associated with a 9-digit (ZIP+4) ZIP code. Note that in many residential areas, a unique 9-digit ZIP code is often assigned by the US Postal Service to a range of addresses on a particular block. In those cases, the SDK returns the address range assigned to that particular 9-digit ZIP code. If a particular address or business is assigned a unique 9-digit ZIP code, the SDK will return the exact address associated with that 9-digit ZIP code.

Does the Perfect Address SDK standardize addresses?#

Yes. As part of its address matching logic, the Perfect Address SDK converts all addresses to the standard address format specified by the US Postal Service. This includes reformatting the address using standard street names, abbreviations, and suffixes, elimination of extraneous punctuation, and conversion of unapproved city names to the USPS-preferred city name.

Standardization of addresses greatly improves the detection and removal of duplicate records from an address database.

Where do you get the address data?#

We license the address database directly from the US Postal Service. Area code and time zone information comes from other sources. Our data is the most accurate and up-to-date address data currently available.

Does Perfect Address SDK automatically update my database files?#

The SDK itself never directly updates your database files. Only your program can do that.

How often do you update the Perfect Address national address database?#

We currently update the address database every month. You can subscribe to monthly, quarterly, or semiannual updates.

Does the Perfect Address database contain the names and telephone numbers of individuals?#

No. The address database covers about 125 million mailing addresses in the USA, but it has only addresses. The primary use of this database is to verify and correct addresses. If you want the names and telephone numbers of individuals, you need a different product. The Perfect Address national address database does include the names and addresses of nearly 750 thousand businesses (those which receive a large quantity of mail).

What database is used for Perfect Address SDK and Perfect Address Software?#

Both products use the exact same 650 MB national address database.

Does your address database include every street address in the country?#

The US Postal Service delivers mail to about 125 million addresses in the USA and its territories. The Perfect Address national address database provides address verification and correction for all 125 million addresses. However, like all other databases based on the USPS database, our database does not actually contain every exact street address to which mail can be delivered. Instead, the database contains about 45 million records, many of which define address ranges, especially in residential areas.

An address range record defines the lowest and highest street numbers which can exist for a given “block face” as well as the ZIP+4, congressional district number, and county name which apply to all addresses which may actually exist on that block face. So in most cases the exact street numbers are not actually available in the database. This, by the way, is exactly the case for all commercial products based on the USPS database, whether CASS-certified or not.

Why doesn’t your database include every street address in the country?#

We license our address database from the US Postal Service, and we include in the Perfect Address national address database every address and address range available in the USPS database. The USPS claims that privacy laws passed by Congress prohibit it from making available an exact street address database. Our address database is the most accurate and complete address database available in this price range, because it is based solely on US Postal Service data.

Some telephone database products include the names, addresses, and telephone numbers of people with listed telephone numbers. But these databases obviously are incomplete, since they omit people with unlisted telephone numbers. What’s more, since these products are based on published telephone books, the data is usually 12 to 24 months old by the time the database is published. Such data is often horribly inaccurate, making it less than useful.

Can I incorporate the Perfect Address SDK into my commercial application?#

Yes. The Perfect Address SDK search engine module is freely redistributable. In other words, we charge no royalty for your reproduction and distribution of the Perfect Address SDK search engine module. However, you are not permitted to reproduce the address database files. We encourage you to incorporate the SDK into your commercial applications and to sell the national address database to your customers. We offer substantial quantity discounts for the address databases.

Can the Perfect Address SDK be installed on a network?#

Yes. The Perfect Address SDK is fully network aware.

Are there any usage restrictions on the Perfect Address SDK?#

No. We place no time limit on your access to the Perfect Address national address database. There are currently also no usage counts nor network usage restrictions in the Perfect Address SDK License. However, CD Light reserves the right to change the terms of the Perfect Address SDK License at any time.

Is a site license available for the Perfect Address SDK?#

A site license isn’t currently required under the terms of the Perfect Address SDK License. We currently put no usage limit on a network installation of the Perfect Address search engine module. If you need multiple copies of the national address database, a quantity discount price schedule is available. However, CD Light reserves the right to change the terms of the Perfect Address SDK License at any time.

How do I handle addresses in my address database which the Perfect Address SDK cannot verify or correct?#

We suggest you mark such records with a special status flag or place them in an “unverified records” file. Then you can examine them later, using other software tools to help you resolve the bad addresses. One such tool is our interactive address lookup program, Perfect Address, sold separately.

Is the Perfect Address SDK CASS-certified?#

No, for some very valid reasons. CASS (Coding Accuracy Support System) certification by the US Postal Service would force us (and users of our products) to update the SDK address database every 60 days. In addition, USPS CASS rules prohibit accessing the address data in certain interactive ways, and enforce certain address matching rules which most users find inconvenient and illogical. So we have chosen not to CASS-certify the Perfect Address SDK.

Under current USPS bulk mail discount rules, a mailing list must be processed by CASS-certified software every six months and meet other sorting and address-correction requirements in order to qualify for even the smallest postal discount. Such recent “postal reform” requirements have significantly raised the break-even threshold, effectively pushing bulk mail discounts beyond the reach of the small mailer. As the USPS further automates, we suspect that most postal discounts will eventually disappear altogether. Could this be the ultimate goal of “postal reform”?

When we originally brought out the SDK in 1995, we submitted it to the USPS for CASS certification, and it passed on the first try! But customer surveys showed us that postal discounts were not the primary goal of our user base, most of whom were not happy at being forced to purchase a new address database every 90 days (every 60 days under current rules). As a result, we began to sell a “non-CASS” version of the SDK with no address database time limit and more logical and user-friendly address matching logic.

Eventually we dropped the CASS-certified version altogether, concentrating our development efforts on the non-CASS version. However, to ensure the accuracy of our address matching, we periodically retest the Perfect Address SDK against the USPS CASS test database to verify that the product still meets or exceeds USPS address matching standards. As a result, the Perfect Address SDK provides the best of both worlds: a low-cost, accurate, and logical address matching system with no onerous database lifetime limits, yet perfect for interactive address capture applications, or correction and standardization of address lists.

CASS-certified products similar to the Perfect Address SDK are available from Group 1 Software, PostalSoft, and other software vendors. These CASS-certified products are much more expensive than the Perfect Address SDK. Worse, all CASS-certified address databases currently have a USPS-mandated 60-day usage lifetime. But before you decide which product you need, see How do I get postal discounts for my mailings?.

What does “CASS” mean?#

CASS is a US Postal Service acronym for Coding Accuracy Support System. It refers to a USPS program for testing and certifying software used to prepare mailings which qualify for bulk mail discounts. Only software which has been “CASS-certified” by the USPS can be used to prepare mailings which qualify for postal discounts.

If the Perfect Address SDK isn’t CASS-certified, how can I be sure I’m getting the best address matching?#

From the beginning, we designed the SDK’s address matching logic to meet USPS CASS address matching requirements. To ensure the accuracy of our address matching, we retest the Perfect Address SDK periodically against the USPS CASS test database to verify that the product still meets or exceeds USPS address matching standards.

The search engine follows US Postal Service address matching rules to find a correct address match. The fundamental rule is called the “one component failure rule”. In simple terms, this rule permits an address match if and only if no more than a single delivery address component mismatch exists, where a “component” is defined as a pre-directional, street name, street suffix, or a post-directional.

This address:

250 E CENTER ST N

has all four address components. If one component can be added, changed, or deleted to achieve a unique match, the search engine is allowed to correct the address and return the ZIP+4. Under current USPS address matching rules, if more than one component is incorrect no match is allowed. If adding, changing or deleting a single component results in multiple matches, no match can be returned. The algorithm calls for adding a suffix first, before adding a directional. If there is no match, change or delete the suffix. Finally, change or delete a directional. Swapped directionals are NOT considered to be a component failure.

If there is no exact address match within the normal city, the search engine applies the “one component failure rule” within the input ZIP code. If there is still no match, the search engine applies the “one component failure rule” to all addresses within the postal finance number. If there is still no match, the address is rejected.

The search engine uses an advanced phonetic matching algorithm to match city and street names.

How do I get postal discounts for my mailings?#

Under current US Postal Service bulk mail rules, your mailing must be “processed” by software tested and certified by the US Postal Service (CASS-certified). Your mailing must meet many stringent USPS requirements to qualify for even the smallest discount:

  • Address verification via CASS-certified software every six months

  • Address correction via either NCOA or ACR every year

  • Sorting via PAVE-certified software

  • Use of tray and/or bag labels with bar codes

  • 100% of a mailing must have the Delivery Point Bar Code applied

There are two primary methods of preparing your mailing to meet these requirements: prepare the mailing yourself or have your mailing prepared by a mailing service bureau.

If you do the mailing preparation yourself, you must acquire the necessary USPS-certified software ($$$) with database updates every 60 days (more $$$) from one of the USPS-certified vendors. Next you must learn how to use the new software - not a trivial undertaking. Just getting up to speed on the pertinent USPS bulk mail rules can itself be a daunting task, generally requiring that you purchase and understand the USPS Domestic Mail Manual, a masterpiece of bureaucratic gobbledygook which comes in a four-inch 3-ring binder. Finally, you prepare your mailing and cross your fingers. Unfortunately, if you make even a simple mistake somewhere along the way, your friendly USPS “bulk mail acceptance unit” clerk will simply reject your mailing. What does that mean? No discount. All that work for nothing. Worse than that, your mailing is delayed while you try to straighten out the mess. Does this sound like fun?

Realistically, you have to mail thousands of pieces per month to even approach the financial break-even point where the postal discounts you get pay for the cost of the software and the time (your time) necessary to prepare the mailing. Below the break-even point it makes no sense to prepare your mailing in-house.

The alternative to this “do-it-yourself” nightmare is to “outsource” the preparation of your mailing to a mailing service bureau. These companies specialize in dealing with the USPS and its arcane bulk mail rules. They also can better afford to invest in the specialized USPS-certified software required and the frequent address database updates dictated by the USPS. They deal with the USPS bulk mail acceptance clerks on a daily basis, and they know what is needed to get your mailing through the system at the best possible discount. They are not cheap, but you may actually save money in the long run.

So what is the downside of using a mailing service bureau? Your address database doesn’t get corrected. It is true that the service bureau must process your address database with USPS-certified software to qualify for the discount. But they normally won’t update your database and return it to you corrected. So although you get the postal discount, your in-house database still contains old, incomplete, and non-standardized addresses. Addresses which would have been corrected by the mailing software, had you prepared the mailing in-house.

But does that really matter? After all, any incorrect addresses in your database will be corrected by the service bureau each time you send another mailing to the service bureau, so who cares? That may be true, but it also means that you cannot depend on the accuracy of addresses in your database, and you probably cannot detect duplicate records that surely exist there. Duplicate records creep into your database because of spelling mistakes, ZIP code errors, laziness of your employees and customers, etc.

Enter Perfect Address SDK! This inexpensive product helps you keep your address database up-to-date, helps find and remove duplicate records, and provides the following additional information about your address records, which you may find useful in other ways:

  • county name

  • county FIPS (Federal Information Processing Standard) code

  • telephone area code

  • time zone

  • daylight saving time flag

This is information about an address which you certainly will not get from your mailing service bureau.

How many addresses can the Perfect Address SDK process per hour?#

Under realistic office conditions, we have measured the performance of our search engine to be more than 200,000 addresses per hour.

Other vendors claim their products can process “millions” of addresses per hour. Can the Perfect Address SDK do that?#

Address processing speed is affected by a great many hardware factors, such as the speed of the CPU, the amount of RAM available, the speed of the hard drive where the address database is stored, etc. Address processing speed is also affected by how the addresses are sorted, the quality of the addresses (correct or incorrect), whether they are from the same general city/street, etc. We believe that in order to achieve such unbelievable speeds, these vendors repeatedly check the exact same correct address, over and over. Such a test is hardly a realistic measure of the performance you can expect with a “real world” address list. But if you are tempted to purchase a product based on such ridiculous performance claims, be sure you get a performance guarantee in writing! Your results will certainly vary!

Under realistic office conditions on normal office computers, we have measured the performance of our search engine to be more than 200,000 addresses per hour.

I need raw address data for one ZIP code, one city, one county, or one entire state. Can I use the Perfect Address SDK to extract the raw address data I need from the Perfect Address national address database?#

No. You can order raw address data for the entire USA directly from CD Light, the developer of the Perfect Address SDK. For more information, contact sales@zipinfo.com.

Other vendors’ products are much more expensive then the Perfect Address SDK. How can the Perfect Address SDK be any good if it costs so little?#

We find that dealing with postal discount issues makes CASS-certified products much more complicated, requiring significant levels of customer support, which must be reflected in the price. Our product is very simple to use and requires little support. Thus we can afford to price it below the CASS-certified products.

All of our products are backed by a 30-day, money-back guarantee. If you find that the Perfect Address SDK doesn’t live up to our claims or to your expectations, you have invested only a little of your time.