Reference Guide#

Introduction #

Perfect Address SDK can easily add transparent address matching and ZIP+4 lookup to your own programs. It can find the exact county name, county FIPS code and congressional district (117th Congress) for every address

The Perfect Address Software Developer’s Kit makes it easy to add transparent address matching and ZIP+4 lookup to your web site, custom or commercial data entry programs, point of sale programs, customer support applications, or database programs.

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

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 provides additional detailed information about each address, including the exact county name and FIPS code, congressional district, area code, time zone, and daylight saving time status.

And best of all, you can incorporate the Perfect Address SDK into your web site or commercial product. You can even distribute the SDK’s DLL modules free of all royalties!

The Perfect Address national address database covers 125 million mailing addresses
Access the Perfect Address database from your custom Windows programs
Access the Perfect Address database from commercial Windows applications
Verify and correct addresses in an interactive mode or in a batch mode
Includes one current national address database with no usage or time limits

Setup and List of Files #

Included Files #

The Perfect Address SDK includes:

One Windows DLL search engine, UNZDLL32.DLL, UNZDLL64.DLL
One national address database for the entire USA
Programmer documentation in Adobe Acrobat format
A header file for use with C/C++ compilers
Sample programs written in Microsoft C, Visual Basic, and MS Access (with source code)
Perfect Address Interactive (single-user license, for development use only)

Address Verification Process #

The actual address verification and correction using the Perfect Address SDK is a two-step process:

1- Find the Address

First, the address must be found in the 650 MB address database.
This is a complex process called “address matching” using rules defined by the US Postal Service.

2- Match the Address

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:

The address was found with an exact match. No spelling or format changes are needed.
The address was found, but spelling and/or format changes were necessary to achieve a match.
The address was not found. No match was possible using USPS address matching rules.
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.

Exact Match #

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.

Result Codes indicate Address changes.#

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.

How to retrieve the corrected address #

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.

Function	Description
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

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:

Passing the address through the SDK again #

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.

No Match Found #

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.

Reasons for No Match Found #

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.

Check the Result Codes #

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.

Interactive Application - Street Information #

For an interactive application, you might wish to display street information to the operator.

Retrieve all valid street names for a target city #

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.

Use Perfect Address Software #

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.

Multiple Addresses #

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:

Methods #

UNZ_INIT_EX #

Syntax:: UNZ_INIT_EX();
Returns:: HUNZ

This function replaces the obsolete function UNZ_INIT and should be used for all new applications. The only difference between the two initialization functions is the error code numbering scheme returned by UNZ_CHECKADDRESS and UNZ_CHECKZIP.

This function initializes the DLL for address and ZIP code verification requests. It returns a unique handle which must be used by the calling task on subsequent function calls to identify itself to the DLL.

Return Value

This function returns a handle of type HUNZ (a 16-bit or 32-bit integer value, depending upon which DLL you are using) which must be passed with all other handle function calls. If the value of the handle returned by UNZ_INIT_EX is 0, the initialization function has detected a fatal error during the initialization process. In this case you should call UNZ_ERROR to learn the exact cause of the failure. Your program should NOT call any other DLL functions after such an error. It is not necessary (in fact, not safe) to call UNZ_TERM after an initialization failure.

The most common cause of this problem is failure of the DLL to find the eight address database files it needs. The paths to these files are stored in file UNZDLL.INI, which is normally found in the Windows folder of your system. See the Installation chapter for a discussion of database file placement and editing of UNZDLL.INI to match your environment.

UNZ_INIT #

Syntax:: UNZ_INIT();
Returns:: HUNZ

This function is obsolete; it has been replaced by UNZ_INIT_EX This initialization function is retained only for backwards compatibility with existing applications. All new applications should use UNZ_INIT_EX. The only difference between the two initialization functions is the error code numbering scheme returned by UNZ_CHECKADDRESS and UNZ_CHECKZIP.

Return Value

This function returns a handle of type HUNZ (a 16-bit or 32-bit integer value, depending upon which DLL you are using) which must be passed with all other handle function calls. If the value of the handle returned by UNZ_INIT is 0, the initialization function has detected a fatal error during the initialization process. In this case you should call UNZ_ERROR to learn the exact cause of the failure. Your program should NOT call any other DLL functions after such an error. It is not necessary (in fact, not safe) to call UNZ_TERM after an initialization failure.

UNZ_TERM #

Syntax:: UNZ_TERM(HUNZ hUNZ);
Returns:: This function returns TRUE (1) for success or FALSE (0) on any error
Return Type:: int

This function terminates address verification requests for the calling task, and frees resources allocated by the DLL.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX

UNZ_CHECKADDRESS #

Syntax:: UNZ_CHECKADDRESS(hUNZ, szLine1, szLine2, szLine3, szLine4);
Returns:: An integer value indicating the result of the verification effort
Return Type:: int

This function performs verification and standardization of the address whose components are passed as parameters. The address strings passed to this function are not modified by this function; the resulting standardized address must be obtained by calling other functions, as defined below.

Address matching first attempts to identify the city and state, then the street from the list of valid streets for that city, and finally the street number from the range of valid addresses for that street.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szLine1 - Firm or high-rise name (optional)
szLine2 - Puerto Rican urbanization name (optional)
szLine3 - Street address (e.g. 100 N MAIN ST APT 6)
szLine4 - - City-state-ZIP code

Optional parameters must be included in the function call, but can be empty (containing a single NULL character or nothing but spaces). All address strings must also be NULL-terminated. This is accomplished by storing a binary zero character (NULL character) after the last text character in the string buffer. Note: this is performed automatically by Visual Basic or VBA when used with MS Access.

Return Value

This function returns an integer value indicating the result of the verification effort. The original input address strings are not modified by this function. The result of an address check can be any one of these four possibilities:

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

A result of 0 indicates that the address was fully validated with no changes. A non-zero result indicates that the address was corrected, that the address was uncorrectable, or that an error occurred during the verification process. See Chapter 6 for a full list of possible return codes. Function UNZ_GETADDRESSFLAGS provides a detailed breakdown of changes applied to a corrected address. If the result indicates that the original address was corrected to achieve a match, you must use other functions to retrieve the corrected address components from the DLL. A reminder: the original input address strings are not modified by this function.

To obtain the entire corrected address in a single call, use function UNZ_GETSTDADDRESS. You can retrieve corrected address components by calling functions UNZ_GETSTREETPARTS, UNZ_GETCITYSTZIP, UNZ_GETSTREETNUMBER, UNZ_GETSTREETNAME, or UNZ_GETSECONDARY. To retrieve the delivery point barcode digits call function UNZ_GETDPBC. Call function UNZ_GETCONGDIST to retrieve the congressional district for the address. If an address verification error occurred, the exact error text can be retrieved by calling function UNZ_GETERRORTEXT.

Remarks

Passing in an Address

For a simple address check, set szLine1 and szLine2 to NULL. Copy the street address line to szLine3, and the city-state-zip line to szLine4. Then call function UNZ_CHECKADDRESS. Note that if you provide the city and state, the ZIP code is optional. If you provide the 5-digit ZIP code, the city and state are optional. Extraneous blanks and embedded commas are ignored by the function. If you provide a ZIP+4, the function ignores the “+4”, returning the correct ZIP+4 for the address.

Each of these parameters should be stored as a NULL-terminated string in its own buffer. Leading and trailing spaces, if present, are ignored by the function. Multiple embedded spaces are also ignored by the function. However, individual data elements of the address and city-state-ZIP parameters should be separated by one space. Strings can be passed in upper, lower, or mixed case. Note: the DLL returns the standardized address as upper case or mixed case, depending upon the MixedCase flag in UNZDLL.INI. See Chapter 6 for more details.

The firm name parameter is optional. If present, it helps the function match the address, and can make a difference in the returned ZIP+4 and Delivery Point Bar Code. However, you should NOT place extraneous data in this parameter. If this parameter is unused, you should place a NULL character in the first position of the string buffer. Note: you MUST pass this string parameter to the function, even if the content is null.

The Puerto Rican urbanization parameter is also optional. This parameter is normally used for Puerto Rican addresses. If the address is in a state other than Puerto Rico, it is permissible to place additional data, such as mail stop or private mailbox number, in this field. This address data will be returned intact after a successful address verification. If this parameter is unused, you should place a NULL character in the first p

The street address parameter is required. Here you should place the data elements of the street address in this order, separated by spaces:

number pre-direction street suffix post-direction secondary number

Example:

425 S MEDICAL DR E STE 18

Multiple embedded spaces are ignored by the function. If these data elements are stored as separate data elements
in your database, you must combine them as shown before passing them to the function.
The city-state-ZIP parameter is required. Here you should place the data elements of the “last line” of the address
in this order, separated by spaces:

city state zipcode

Example:

BOUNTIFUL UT 84010

If your program maintains these data elements as separate data fields in your database, you must combine them as shown above before passing them to the function. The function ignores multiple embedded spaces and superfluous punctuation characters.

The function attempts to identify the correct city based on city and state, or ZIP code, or all three. If the city and state are present, the ZIP code can be omitted. The ZIP code can be either 5-digit, 9-digit (ZIP+4) or missing. If the ZIP code is present, the city and state can be omitted. The matching algorithm attempts to establish agreement between any two of the three possible data elements of the city-state-ZIP parameter. As long as two of the three elements match, the function will proceed with address matching. If the function can find no match between city, state and ZIP code, address matching fails. The function returns error code 50 (total city-state-zip mismatch) in this case.

You MUST pass all four address strings to the function in the order shown. The optional parameters must be passed, even if the parameter string is empty. The function does NOT currently scan the parameters “from the bottom”, although that is a possible future enhancement.

UNZ_CHECKLASTLINE #

Syntax:: UNZ_CHECKLASTLINE(hUNZ, szLine1);
Returns:: An integer value indicating the result of the verification effort
Return Type:: int

This function requests verification and standardization of only the last line (city-state-ZIP) of an address. The primary purpose of this function is to determine the 5-digit ZIP code for a particular city-state when a full address check fails.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
City-state-ZIP code string

szLine1 must be NULL-terminated (initialized to a binary zero character)

If you provide the city and state, the ZIP code is optional. If you provide the 5-digit ZIP code, the city and state are optional. Extraneous blanks and embedded commas are ignored by the function. If you provide a ZIP+4, the function ignores the “+4”.

Return Value

This function returns an integer value indicating the result of the verification effort. A result of 0 indicates that the city-state-ZIP was fully validated with no changes. A non-zero result indicates that the city-state-ZIP was corrected, that the city-state-ZIP was uncorrectable, or that an error occurred during the verification process. See Chapter 6 for a full list of possible return codes. Function UNZ_GETADDRESSFLAGS provides a detailed breakdown of changes applied to the corrected city-state-ZIP.

If the result indicates successful verification or correction, you must use other functions, such as UNZ_GETCITYSTZIP, to retrieve the standardized city-state-ZIP components from the DLL. The original input address strings are not modified by this function.

UNZ_CHECKZIP #

Syntax:: UNZ_CHECKZIP(hUNZ, szZIP, szZIP4);
Returns:: An integer value indicating the result of the verification effort
Return Type:: int

This function requests a search of the database based on ZIP code. If the provided ZIP code is a valid 5-digit ZIP code, this request finds the proper state and the city name preferred by the US Postal Service for use on mail associated with that ZIP code. If the provided ZIP code is a valid 9-digit ZIP code, this request finds the proper street address or address range associated with that ZIP code.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szZIP - A 5-digit or 9-digit ZIP code (xxxxx or xxxxx-xxxx) (string)
szZIP4 - The 4-digit add-on value of a 9-digit ZIP code (optional, string)

A 9-digit ZIP code can be passed as one string in the form 84093-1679, or can be provided as separate strings, 84093 in szZIP and 1679 in szZIP4. If the string passed in szZIP is a valid 9-digit ZIP code, the parameter szZIP4 is ignored. However, if szZIP is a 5-digit ZIP code and szZIP4 is not used, it must be initialized to 0 (NULL).

Return Value

This function returns an integer value indicating the result of the ZIP code search. A result of 0 indicates that the ZIP code and a matching address were found in the database. A non-zero result indicates that the ZIP code was not found, that the ZIP code applies to an address range, or that an error occurred during the verification process. See Chapter 6 for a full list of possible return codes.

If the result indicates successful search for the ZIP code, the city and state and (optionally) the matching address components can be returned to the calling task by calling functions UNZ_GETCITYSTZIP or UNZ_GETSTDADDRESS, as defined below. If a ZIP code lookup error occurred, the exact error text can be obtained by calling function UNZ_GETERRORTEXT.

Remarks

ZIP+4 ZIP codes are often assigned by the USPS to a range of addresses which belong to the same block of a street or to a range of apartments or suites in a high-rise apartment or office building. In this case, the DLL cannot identify a particular “correct” address for that ZIP code. Instead, the DLL returns the lowest address of the range as the “correct” address, and copies the address range to the AddrRange field of the parameter block. It also sets a return code to indicate the address range condition. 5 - 10 Address Lookup Functions

Sometimes the same ZIP+4 code is assigned by the USPS to more than one specific mail delivery point. The DLL always returns the first matching address it finds, ignoring the remaining matching addresses, if any.

UNZ_GETSTDADDRESS #

Syntax:: UNZ_GETSTDADDRESS(hUNZ, szFirmHigh, szPRUrb, szDelLine, szLastLine);
Returns:: No direct result; standard address lines copied into string buffers.
Return Type:: void

This function returns the four lines of a standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate fields of a parameter block reserved by the DLL for the calling task into the empty strings pointed to by the parameters.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szFirmHigh - Pointer to empty string for the firm or high-rise building name
szPRUrb - Pointer to empty string for the Puerto Rican urbanization name
szDelLine - Pointer to empty string for the delivery line (street address)
szLastLine - Pointer to empty string for the last line (city-state-ZIP)

The existing contents of these strings are overwritten with the results of the most recent address search. Each string buffer should ALWAYS have a minimum allocated size of 51 bytes. If the standard address contains no data for a particular field (such as a street address with no firm name) the corresponding string is returned as 0 (NULL).

UNZ_GETSTREETPARTS #

Syntax:: UNZ_GETSTREETPARTS(hUNZ, szNumber, szStreet, szUnit);
Returns:: No direct result; delivery line address components copied into string buffers
Return Type:: void

This function returns the individual components of the delivery line (street address line) of the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate fields of a parameter block reserved by the DLL for the calling task into the empty strings pointed to by the parameters.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szNumber - Pointer to empty string into which street number is copied, including predirection, if any
szStreet - Pointer to empty string into which street name, street suffix, and postdirection, if any, are copied
szUnit - Pointer to empty string into which secondary address type and number are copied

The existing contents of these strings are overwritten with the results of the most recent address search. The string buffers should have a minimum allocated size of 51 bytes. If the standard address contains no data for a particular field (such as a street address with no apartment number) the corresponding string is returned as 0 (NULL).

UNZ_GETSTREETNUMBER #

Syntax:: UNZ_GETSTREETNUMBER(hUNZ, zNumber);
Returns:: No direct result; the street number components copied into the string buffer.
Return Type:: void

This function returns the street number and predirection code, if any, of the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the szNumber parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szNumber - Pointer to empty string into which street number is copied, including predirection, if any

The existing contents of this string are overwritten with the street number components

UNZ_GETSTREETNAME #

Syntax:: UNZ_GETSTREETNAME(hUNZ, szName);
Returns:: No direct result; the street name components copied into the string buffer
Return Type:: void

This function returns the street name, suffix (DR, ST, AVE) and postdirection code, if any, of the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the szName parameter.

Input Parameters

szName - Pointer to empty string into which street name is copied, including predirection, if any
hUNZ - Handle returned by the call to UNZ_INIT_EX

The existing contents of this string are overwritten with the street name components of the most recent address search. The string buffer should have a minimum allocated size of 35 bytes.

UNZ_GETSECONDARY #

Syntax:: UNZ_GETSECONDARY(hUNZ, szUnit);
Returns:: No direct result; secondary address components copied into the string buffer.
Return Type:: void

This function returns the secondary (apartment/suite) address components of the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the szUnit parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szUnit - Pointer to empty string into which the secondary address is copied

The existing contents of this string are overwritten with the secondary address components of the most recent address search. The string buffer should have a minimum allocated size of 25 bytes. If the standard address contains no secondary address data, the szUnit string is returned as 0 (NULL).

UNZ_GETCITYSTZIP #

Syntax:: UNZ_GETCITYSTZIP(hUNZ, szCity, szState, szZIP);
Returns:: No direct result; last line address components copied into string buffers.
Return Type:: void

This function returns the individual components of the last line (city-state-ZIP line) of the standardized address.
This function should be called only after successfully calling UNZ_CHECKADDRESS
or UNZ_CHECKZIP.
This function copies the requested information from the appropriate fields of a parameter block reserved by the
DLL for the calling task into the empty strings pointed to by the parameters.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCity - Pointer to empty string for the city name
szState - Pointer to empty string the 2-letter state abbreviation
szZIP - Pointer to empty string for the 9-digit ZIP code

The existing contents of these strings are overwritten with the results of the most recent address search. Each string buffer should have a minimum allocated size of 51 bytes.

UNZ_GETCITY #

Syntax:: UNZ_GETCITY(hUNZ, szCity);
Returns:: No direct result; the city name copied into the string buffer
Return Type:: void

This function returns the city name of the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the szCity parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCity - Pointer to empty string into which the city name is copied

The existing contents of this string are overwritten with the city name of the most recent address search. The string buffer should have a minimum allocated size of 29 bytes.

UNZ_GETSTATE #

Syntax:: UNZ_GETSTATE(hUNZ, szState);
Returns:: No direct result; the state code copied into the string buffer.
Return Type:: void

This function returns the 2-character state code of the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the szState parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szState - Pointer to empty string into which the state code is copied

The existing contents of this string are overwritten with the state code of the most recent address search. The string buffer should have a minimum allocated size of 3 bytes.

UNZ_GETZIP #

Syntax:: UNZ_GETZIP((hUNZ, szZip);
Returns:: No direct result; the ZIP+4 copied into the string buffer
Return Type:: void

This function returns the ZIP+4 code of the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the szZip parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szZip - Pointer to empty string into which the ZIP+4 code is copied

The existing contents of this string are overwritten with the ZIP+4 code of the most recent address search. The string buffer should have a minimum allocated size of 11 bytes.

UNZ_GETDPBC #

Syntax:: UNZ_GETDPBC((hUNZ, szDPBC);
Returns:: No direct result; three DPBC digits copied into the string buffer.
Return Type:: void

This function returns a string containing the three digits which must be appended to the ZIP+4 to create a valid Delivery Point Bar Code (DPBC). The first two digits are derived from the address, while the last digit is a check digit calculated over the other 11 DPBC digits. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter.

Note: to obtain the full 12-digit DPBC, you must append the three digits returned by this function to the nine digits of the ZIP+4.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szDPBC - Pointer to empty string for the delivery point barcode characters

The existing contents of the string are overwritten with three ASCII digits representing the last three digits of the DPBC for the most recent address search. The string buffer should have a minimum allocated size of 4 bytes.

UNZ_GETCONGDIST #

Syntax:: UNZ_GETCONGDIST(hUNZ, szCongDist);
Returns:: No direct result; two congressional district characters copied into the string buffer.
Return Type:: void

This function returns a string containing the two character congressional district code for the standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter.

For states with only a single representative, the congressional district is returned as 00.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCongDist - Pointer to empty string for the congressional district

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 5 bytes.

UNZ_GETCOUNTY #

Syntax:: UNZ_GETCOUNTY(hUNZ, szCounty);
Returns:: No direct result; county name characters copied into the string buffer.
Return Type:: void

This function returns a string containing the name of the county in which the standardized address resides. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCounty - Pointer to empty string for the county name

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 26 bytes.

UNZ_GETCNTYFIPS #

Syntax:: UNZ_GETCNTYFIPS(hUNZ, szCntyFIPS);
Returns:: No direct result; county FIPS code characters copied into the string buffer
Return Type:: void

This function returns a three-digit numeric ASCII string containing the Federal Information Processing Standard (FIPS) number for the county in which the standardized address resides. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCntyFIPS - Pointer to empty string for the county FIPS code

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 4 bytes.

UNZ_GETAREACODE #

Syntax:: UNZ_GETAREACODE(hUNZ, szAreacode);
Returns:: UNZ_GETAREACODE
Return Type:: void

This function returns a three-digit numeric ASCII string containing the most prevalent area code for the 5-digit ZIP code in which the standardized address resides. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter.

Please note that in areas where multiple area codes apply to a single ZIP code, only the most prevalent area code is returned by this function.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szAreacode - Pointer to empty string for the Area code

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 4 bytes.

Return Value

Please note that because area code and ZIP code boundaries rarely coincide and because of “overlay” area codes in use in some parts of the country, we cannot guarantee that the area code returned by this function is accurate in all cases.

UNZ_GETTIMEZONE #

Syntax:: UNZ_GETTIMEZONE(hUNZ, szTimezone);
Returns:: An integer having a value of 0 (false) or 1 (true). Time zone is copied into the string buffer
Return Type:: void

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szTimezone - Pointer to empty string for the Time zone

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 7 bytes.

Return Value

The following ASCII Time zone strings may be returned by this function:

EST - Eastern standard time
CST - Central standard time
MST - Mountain standard time
PST - Pacific standard time
AST - Alaska standard time
HST - Hawaii standard time
EST+1 - Puerto Rico, Virgin Islands, and APO/FPO (Central America)
GMT+1 - APO/FPO (Central Europe)
PST-5 - Micronesia
PST-6 - Guam
PST-7 - APO/FPO (Pacific)

Note that all time zones are defined relative to standard time, even in those areas where daylight savings time may be in effect. The DST flag only indicates that a particular address participates in DST at some time during the year, not that DST in actually in effect at the moment.

UNZ_GETADDRRANGE #

Syntax:: UNZ_GETADDRRANGE(hUNZ, szRange);
Returns:: No direct result; address range characters copied into the string buffer
Return Type:: void

This function returns a string containing an address range which applies to a particular ZIP+4 ZIP code. This function should be called only after UNZ_CHECKZIP returns a code indicating an address range (XC_ARNG or XC_URNG). This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szRange - Pointer to empty string for the unit range

The existing contents of the string are overwritten with the results of the most recent ZIP+4 search. The string buffer should have a minimum allocated size of 51 bytes.

Return Value

An integer having a value of 0 (false) or 1 (true), indicating whether that particular address participates in daylight savings time at some time during the year, plus the Time zone code characters copied into the string buffer.

UNZ_GETADDRESSFLAGS #

Syntax:: UNZ_GETADDRESSFLAGS(hUNZ, szErrTxt);
Returns:: No direct result; address correction flag characters copied into the string buffer
Return Type:: void

This function returns a text string containing one or more flag characters detailing the corrections and warnings from the last address check. This function should be called only after successfully calling UNZ_CHECKADDRESS. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter. If the last address check validated the address with no errors or corrections (return code of 0), this function returns a null (empty) string.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szErrTxt - Pointer to empty string for the error text

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 31 bytes.

Return Value

Here are the flag characters and their meaning:

Z	ZIP code corrected
4	ZIP+4 added or corrected
S	state corrected
C	city corrected
A	street number and/or predirection corrected
N	street name, suffix, and/or postdirection corrected
P	PO Box address corrected
#	Secondary address (apt/ste) corrected or ignored
F	Firm name not found, ignored
U	PR Urb name corrected
C,S	missing city-state corrected to match ZIP
D	Address verified, but USPS doesn’t deliver (no +4)
X	Extraneous characters (ignored)

These flags appear in no particular order, and with no spacing. However, a particular flag character will appear only once.

UNZ_GETSTATS #

Syntax:: UNZ_GETSTATS(hUNZ, szTotal, szZIP4, sz5Digit, szCRRT);
Returns:: No direct result; address processing statistics copied into string buffers.
Return Type:: void

This function interrogates the DLL concerning the count of address records processed and the count of records successfully verified. These counts are returned as four strings of ASCII characters, which the function copies into the empty strings pointed to by the parameters. This function should be called only after a group of address records has been processed by the DLL, but before terminating access to the DLL.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szTotal - Pointer to empty string into which the total count of address records processed is copied.
szZIP4 - Pointer to empty string into which the count of address records successfully ZIP+4 encoded
is copied. Unverified addresses and non-delivery addresses are NOT counted.
sz5Digit - Pointer to empty string into which the count of address records successfully encoded with a
5-digit ZIP code is copied. Non-delivery addresses ARE counted.
szCongDist - Pointer to empty string into which the count of address records for which a congressional district was found is copied. Normally this number is identical to szZIP4.

Note: A non-delivery address is one to which the USPS does not deliver mail, but the address is known to be valid. A non-delivery address is assigned the proper 5-digit ZIP code, but no ZIP+4. An unverified address is one which the DLL cannot find in the database, even using advanced address matching logic. No address is returned.

UNZ_GETMATCHCOUNT #

Syntax:: UNZ_GETMATCHCOUNT(hUNZ);
Returns:: An integer count of the number of addresses which matched the address last checked using UNZ_CHECKADDRESS
Return Type:: int

This function returns an integer count of the number of matching addresses found by the DLL on the previous UNZ_CHECKADDRESS call. This function can be used onlywhen the return code from UNZ_CHECKADDRESS is XC_MULT (multiple matching records).

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX

UNZ_GETMATCHADDR #

Syntax:: UNZ_GETMATCHADDR(hUNZ, item, szFirmHigh, szPRUrb, szDelLine, szLastLine);
Returns:: An integer value indicating the result of method
Return Type:: int

Desc

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
item - number of matching address to be returned
szFirmHigh - Pointer to empty string for the firm or high-rise building name
szPRUrb - Pointer to empty string for the Puerto Rican urbanization name
szDelLine - Pointer to empty string for delivery line (street address)
szLastLine - Pointer to empty string for the last line (city-state-ZIP)

The existing contents of these strings are overwritten with the selected address information. Each string buffer should have a minimum allocated size of 51 bytes. If the selected address contains no data for a particular field (such as a street address with no firm name) the corresponding string is returned with a binary 0 in the first position of the string buffer.

Return Value

If there is no error, the function copies the address information for the selected address into the string buffers, and returns TRUE (integer 1). It returns FALSE (integer 0) on any error.

UNZ_GETADDRCOMP #

Syntax:: UNZ_GETADDRCOMP(hUNZ, szNumber, szPredir, szStreet, szSuffix, szPostdir, szSecyType, szSecyNbr, szPOB, szRR, szHC, szCity, szState, szZIP5, szZIP4);
Returns:: No function value returned; standard address components copied into string buffers
Return Type:: void

This function returns the individual components of a standardized address. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP. This function copies the requested information from the appropriate fields of a parameter block reserved by the DLL for the calling task into the empty strings pointed to by the parameters.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szNumber - Pointer to empty string for the street number
szPredir - Pointer to empty string for the street pre direction
szStreet - Pointer to empty string for the street name
szSuffix - Pointer to empty string for the street suffix
szPostdir - Pointer to empty string for the street post direction
szSecyType - Pointer to empty string for the secondary address type
szSecyNbr - Pointer to empty string for the secondary address number
szPOB - Pointer to empty string for the PO Box number
szRR - Pointer to empty string for the rural route number
szHC - Pointer to empty string for the highway contract number
szCity - Pointer to empty string for the city name
szState - Pointer to empty string for the 2-character state code
szZIP5 - Pointer to empty string for the 5-digit ZIP code
szZIP4 - Pointer to empty string for the 4-digit ZIP code add on

The existing contents of these strings are overwritten with the results of the most recent address search. Each string buffer should ALWAYS have a minimum allocated size of 31 bytes. If the standard address contains no data for a particular add

UNZ_GETSTREETCOUNT #

Syntax:: UNZ_GETSTREETCOUNT(hUNZ, szCityName);
Returns:: An integer value indicating the result of method
Return Type:: int

This function returns the count of individual street names (including special names) in the street list for the city specified by szCityName. This function should be called prior to calling UNZ_GETSTREETITEM to determine the maximum number of streets in the street list for a given city.

The city name can be anything which is valid as the “last line” of an address. This includes city and state, valid 5- digit ZIP code, or both. If the city name is specified by a ZIP code, the street list includes all streets defined for that city, even if some of the streets in the list do not exist within the boundaries of the specified ZIP code.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCityName - Pointer to string containing name of city and state, or ZIP code

Return Value

If successful, returns the integer count (1 origin) of street names in the street list for the specified city. If unsuccessful, returns an integer 0 value. An error return indicates that the city name could not be found or that the specified city has no street list (no street names defined for that city). Successfully calling this function establishes the city named as the “current” city for subsequent calls to UNZ_GETSTREETITEM.

UNZ_GETSTREETITEM #

Syntax:: UNZ_GETSTREETITEM(hUNZ, item_number, szStreetName);
Returns:: An integer value indicating the result of method
Return Type:: int

This function returns the actual street name specified by item_number from the list of streets for the city specified by the last UNZ_GETSTREETCOUNT function call. This function can be called repeatedly following a successful call to UNZ_GETSTREETCOUNT to build a list of streets for a particular city. The integer value “item_number” ranges in value from 1 to n, where n is the value returned by the last call to UNZ_GETSTREETCOUNT.

If you want to build only a partial list of streets starting with a particular name or letter of the alphabet, you can use a binary search technique to position to a particular section of the street list, then call UNZ_GETSTREETITEM with sequential item numbers to build the desired list of streets.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
item_number - number of street name to be returned from street list of current city
szStreetName - Pointer to empty string buffer for the street name string

Return Value

Returns the selected street name as a string in the buffer defined by the szStreetName parameter, and TRUE (integer 1) on no error. If no street name can be returned, returns FALSE (integer 0). An error might be caused by failure to call UNZ_GETSTREETCOUNT prior to calling UNZ_GETSTREETITEM or if the item_number parameter exceeds the number of streets contained in the street list of the current city. The name string returned by this function contains the name of the street, the street suffix, if any, and the street postdirection, if any. Note that the predirection, if any, is NOT considered to be part of the street name. Note also that special “street” names such as PO Box, General Delivery, Rural Routes (RR), and Highway Contracts (HC), ARE part of the street list, and may appear as the returned street name.

UNZ_GETERRORTEXT #

Syntax:: UNZ_GETERRORTEXT(hUNZ, szErrTxt);
Returns:: No direct result; error text characters copied into the string buffer.
Return Type:: void

This function returns a text string which explains the results of the last address check or ZIP code check. This function copies the requested information from the appropriate field of a parameter block reserved by the DLL for the calling task into the empty string pointed to by the second parameter. If the last address check or ZIP code check produced no error this function returns an empty string.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szErrTxt - Pointer to empty string for the error text

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 81 bytes.

UNZ_GETADDRESSTYPE #

Syntax:: UNZ_GETADDRESSTYPE(hUNZ, szAddrType);
Returns:: No direct result; address type character copied into the string buffer
Return Type:: void

This function returns a single-character text string which indicates the type of address record which was matched during the last successful UNZ_CHECKADDRESS or UNZ_CHECKZIP function call. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szAddrType - Pointer to empty string for the address type character

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 2 bytes.

Return Value

The single ASCII character which is returned by this function is one of the following:

S	Street address
P	Post Office Box
R	Rural route or Highway Contract
H	Highrise apartment/office building
F	Firm (business)
G	General Delivery

UNZ_GETZIPTYPE #

Syntax:: UNZ_GETZIPTYPE(hUNZ, szZipType);
Returns:: No direct result; address type character copied into the string buffer
Return Type:: void

This function returns a single-character text string which indicates the type of ZIP code which was matched during the last successful UNZ_CHECKADDRESS or UNZ_CHECKZIP function call. This function should be called only after successfully calling UNZ_CHECKADDRESS or UNZ_CHECKZIP.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szZipType - Pointer to empty string for the ZIP code type character

The existing contents of the string are overwritten with the results of the most recent address search. The string buffer should have a minimum allocated size of 2 bytes.

Return Value

The single ASCII character which is returned by this function is one of the following:

P	Post Office Box ZIP code only (no street addresses)
M	Military ZIP code (state codes AA, AE, or AP)
U	Unique ZIP code (assigned to a single business or organization)

This function can also return an empty (NULL) string, which indicates that the ZIP code type is “normal”, meaning the ZIP code is not one of the types defined above. ZIP codes which apply to street addresses or to a combination of street addresses and PO Boxes have no special type and return an empty string.

UNZ_GETFIRSTCITYNAME #

Syntax:: UNZ_GETFIRSTCITYNAME(hUNZ, szZip, szCityName, szApproved);
Returns:: An integer value indicating the result of method
Return Type:: int

This function is the first of the “first-next” pair of functions which return the city name(s) with approval flag associated with a 5-digit ZIP code. You should call this function once to initiate retrieval of city name(s) by ZIP code and to retrieve the first city name associated with the ZIP code. Thereafter you should call UNZ_GETNEXTCITYNAME to retrieve additional city names until you reach the last city name associated with the ZIP code. You may stop retrieving city names at any time. The city names are returned in alphabetical order.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szZip - Null-terminated 5-digit ASCII ZIP code string
szCityName - pointer to empty 30-character string for first city name result
szApproved - pointer to empty 10-character string for approval code result

Return Value

Returns 0 along with a valid city name and approval code if the ZIP code is verified. Returns a numerical error code for the following cases:

1	No more cities associated with that ZIP code
2	Unable to verify ZIP code
3	invalid handle or other error

The city name is a null-terminated string containing a city name associated with the ZIP code.

The approval flag is a null-terminated string containing a single ASCII character. The allowed characters are:

P	This city name is the “preferred” (default) city name, as defined by the USPS.
A	This city name is approved for mail delivery to the ZIP code.
N	This city name is not approved for mail delivery to the ZIP code.

UNZ_GETNEXTCITYNAME #

Syntax:: UNZ_GETNEXTCITYNAME(hUNZ, szCityName, szApproved);
Returns:: An integer value indicating the result of method
Return Type:: int

This function is the second of the “first-next” pair of functions which return the city name(s) with approval flag associated with a 5-digit ZIP code. The city names are returned in alphabetical order. You should call the UNZ_GETFIRSTCITYNAME function first to initiate the SDK to the first city name for that ZIP code. Thereafter you should call this function to retrieve additional city names, if any, associated with that particular ZIP code until you reach the last city name of the group. You may stop retrieving city names at any time.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCityName - pointer to empty 30-character string for city name result
szApproved - pointer to empty 10-character string for approval code result

Return Value

Returns 0 with a valid city name.. Returns a numerical error code for the following cases:

1	No more cities associated with that ZIP code
3	invalid handle or other error

The city name is a null-terminated string containing a city name associated with the ZIP code.

The approval flag is a null-terminated string containing a single ASCII character. The allowed characters are:

P	This city name is the “preferred” (default) city name, as defined by the USPS.
A	This city name is approved for mail delivery to the ZIP code.
N	This city name is not approved for mail delivery to the ZIP code.

UNZ_GETFIRSTADDR #

Syntax:: UNZ_GETFIRSTADDR(hUNZ, szCityStZip, szStreet, szAddr1, szAddr2, szAddr3, szAddr4);
Returns:: An integer value indicating the result of method
Return Type:: int

This function is the first of the “first-next” pair of functions which retrieve street address records for a given city. These functions retrieve address records based on street name or ZIP code or both. If you enter a city-state and no street name, you will retrieve all street address records for that city-state. If you enter a city-state and also a valid street name you will retrieve all records for that one street (all ZIP codes). If you enter a city-state and a 5-digit ZIP code as well, you will retrieve address records for that ZIP code only, the same as if you had entered the ZIP code alone. If you enter a 5-digit ZIP code (no city-state) and no street name you will retrieve all records for all streets in that ZIP code. If you enter a ZIP code and a valid street name you will retrieve only those records for that one street with that ZIP code. The street name parameter is optional, but must be present and initialized to contain a NULL character in the first byte position if there is no street name in the parameter. You should call this function once to initiate the SDK to the first address record of the group you wish to retrieve. Thereafter you should call UNZ_GETNEXTADDR to retrieve additional address records until you reach the last record of the group. You may stop retrieving records at any time.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCityStZip - pointer to string containing city and state, or 5-digit ZIP code
szStreet - pointer to empty 52-byte string for the street name (optional)
szAddr1 - pointer to empty 52-byte string for the firm name result, if any
szAddr2 - pointer to empty 52-byte string for the Puerto Rican urb name result, if any
szAddr3 - pointer to empty 52-byte string for the street address range result
szAddr4 - pointer to empty 52-byte string for the city-state-zip result

Return Value

Returns 0 on a good street address record, or a numeric error code. The numeric error codes are:

1	No more addresses
2	Unable to verify city-state or ZIP code
4	Unable to verify street name

UNZ_GETNEXTADDR #

Syntax:: UNZ_GETNEXTADDR(hUNZ, szAddr1, szAddr2, szAddr3, szAddr4);
Returns:: Returns 0 with a valid street address record, or 1 if there are no more records.
Return Type:: int

This function is the second of the “first-next” pair of functions which return address records for a given city. These functions return address records based on street name or ZIP code or both. You should call the UNZ_GETFIRSTADDR function once to initiate the SDK to the first address record of the group you wish to retrieve. Thereafter you should call this function to retrieve additional records until you reach the last record of the group. You may stop retrieving records at any time.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szAddr1 - pointer to empty 52-byte string for the street name (optional)
szAddr2 - pointer to empty 52-byte string Puerto Rican urb name result, if any
szAddr3 - pointer to empty 52-byte string street address range result
szAddr4 - pointer to empty 52-byte string city-state-zip result

UNZ_GETZIPCOUNT #

Syntax:: UNZ_GETZIPCOUNT(hUNZ);
Returns:: Returns the count of active ZIP codes.
Return Type:: int

This function returns the integer count (1 origin) of all ZIP codes in the ZIP code list. The purpose of this function is to find the maximum number of ZIP codes to be retrieved using the UNZ_GETZIPITEM function.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX

UNZ_GETZIPITEM #

Syntax:: UNZ_GETZIPITEM(hUNZ, item_number, szZIP);
Returns:: An integer value indicating the result of method
Return Type:: int

Desc

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
item_number - Number of ZIP code to be returned from ZIP code list
szZIP - Pointer to empty string buffer for the 5-character ZIP code strin

Return Value

Returns the selected ZIP code in the szZIP buffer and TRUE (integer 1) on no error. Returns 0 if the item_number parameter is out of range.

UNZ_GETZIPCITYCOUNT #

Syntax:: UNZ_GETZIPCITYCOUNT(hUNZ, szCity);
Returns:: An integer value indicating the result of method
Return Type:: int

This function returns the integer count (1 origin) of all ZIP codes for the specified city. The purpose of this function is to find the maximum number of ZIP codes to be retrieved using the UNZ_GETZIPCITYITEM function.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szCity - Pointer to string containing city and state

Return Value

Returns the integer count (1 origin) of all ZIP codes in the specified city, or 0 if the city and state cannot be found.

UNZ_GETZIPCITYITEM #

Syntax:: UNZ_GETZIPCITYITEM(hUNZ, item_number, szZIP);
Returns:: An integer value indicating the result of method
Return Type:: int

This function retrieves one ZIP code from the list of ZIP codes for a specific city.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
item_number - Number of ZIP code to be returned from selected city
szZIP - Pointer to empty string buffer for the 5-character ZIP code string

Return Value

Returns the selected ZIP code in the szZIP buffer and TRUE (integer 1) on no error. Returns 0 if the item_number parameter is out of range.

UNZ_GETCITYSTATECOUNT #

Syntax:: UNZ_GETCITYSTATECOUNT(hUNZ, szState);
Returns:: An integer value indicating the result of method
Return Type:: int

This function returns the count of all cities for the specified state. The purpose of this function is to find the maximum number of city names to be retrieved using the UNZ_GETCITYSTATEITEM function.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
szState - Pointer to string containing state name or abbreviation

UNZ_GETCITYSTATEITEM #

Syntax:: UNZ_GETCITYSTATEITEM(hUNZ, item_number, szCity);
Returns:: An integer value indicating the result of method
Return Type:: int

This function retrieves one city name from the list of cities for a specific state.

Input Parameters

hUNZ - Handle returned by the call to UNZ_INIT_EX
item_number - Number of city to be returned from selected state
szCity - Pointer to empty string buffer for the city name

Return Value

Returns the selected city name in the szCity buffer and TRUE (integer 1) on no error. Returns 0 if the item_number parameter is out of range.

UNZ_ERROR #

Syntax:: UNZ_ERROR();
Returns:: DLL Return Code
Return Type:: int

This function returns the most recent internal error registered by the DLL. Normally this function is used after a failure of the DLL to initialize properly (UNZ_INIT or UNZ_INIT_EX). However, it can also be used after any internal error to discover the nature of the problem (memory allocation error, read error, file corrupted, etc.).

Return Value: An integer indicating the most recent internal error registered by the DLL. These values are defined Return Codes.

Return Codes #

The Perfect Address SDK provides two primary search functions, UNZ_CHECKADDRESS for checking an address and UNZ_CHECKZIP for checking a ZIP code. These two functions return an integer error code which indicates the success or failure of the search.

The return code is a single integer value which provides limited information about the search results. Correcting an address may require trying various changes to the address according to the rules of the address matching algorithm to find a match in the address database. Of necessity, the normal integer return code identifies only one such change to the address. However, it is possible to query the search engine for a more detailed analysis of the search results. 6 - 4 Development Environment

The integer value of 0 is returned by UNZ_INIT or UNZ_INIT_EX if the initialization function detects a fatal error during the initialization process:

ECFATAL

Fatal initialization or memory allocation error

The most common cause of this problem is failure of the DLL to find the data files it needs. The paths to these files are stored in file UNZDLL.INI, which is normally found in the Windows folder of your system. See the Installation Chapter for a discussion of file placement and editing of UNZDLL.INI.

When the calling program receives a return value of 0 in response to UNZ_INIT or UNZ_INIT_EX, the DLL initialization has failed. This means that the DLL cannot be used for address verification or ZIP verification. You should call function UNZ_ERROR to determine the exact cause of the initialization failure. Your program should NOT call any other DLL functions after such an error until the cause of the error has been resolved.

The fatal error codes returned by UNZ_ERROR are:

Error Name	Return Value	Error Definition
FE00	100	CASS CD-ROM database has expired (obsolete)
FE01	101	Memory (internal buffers) allocation error
FE02	102	Unable to open data file z1.dat
FE03	103	Error reading data file z1.dat
FE04	104	Unable to open data file z2.dat
FE05	105	Error reading data file z2.dat
FE06	106	Unable to open data file z3.dat
FE07	107	Error reading data file z3.dat
FE08	108	Unable to open data file z4.dat
FE09	109	Error reading data file z4.dat
FE10	110	Unable to open data file z5.dat
FE11	111	Error reading data file z5.dat
FE12	112	Unable to open data file z6.dat
FE13	113	Error reading data file z6.dat
FE14	114	Unable to open data file z7.dat
FE15	115	Error reading data file z7.dat
FE16	116	Unable to open data file z8.dat
FE17	117	Data file z8.dat version mismatch with DLL (wrong version)
FE18	118	Unable to find DLL params (UNZDLL.INI or Registry params)
FE19	119	Unable to allocate handle memory

Return codes produced when using UNZ_INIT_EX #

The following is a list of codes returned by UNZ_CHECKADDRESS and UNZ_CHECKZIP when the DLL has been initialized using UNZ_INIT_EX. These return codes are arranged into numeric groups, making it easy for the calling program to perform basic tests to distinguish between a valid address (0), a corrected address (<50), an uncorrectable address (50-79), and internal runtime errors (80-99).

Group	Range	Meaning
no error	0	The address was verified with no changes
warnings	1 - 49	The address was corrected as indicated
critical	50 - 79	The address could not be verified or corrected
runtime	80 - 99	A non-fatal error occurred
fatal	>= 100	DLL initialization failed (returned by UNZ_ERROR only)

The following code is returned by UNZ_CHECKADDRESS if the address was verified with no corrections.

XC_GOODADDR

Address was verified with no corrections

The following codes may be returned by UNZ_CHECKADDRESS indicating that the address was corrected. If multiple corrections are necessary to achieve an address match, only the final correction is reported as a return code by UNZ_CHECKADDRESS. For a detailed indication of multiple address corrections, you should use function UNZ_GETADDRESSFLAGS to retrieve a correction vector containing a single character for each correction which was applied.

Error Code	Return Value	Vector Char	Error Meaning
XC_ZIP	1	Z, 4	ZIP code or ZIP+4 added/corrected
XC_STATE	2	S	state name added/corrected
XC_CITY	3	C	city name added/corrected
XC_ADDR	4	A	street number and/or predirection corrected
XC_STREET	5	N	street name, suffix, and/or postdirection corrected
XC_POB	6	P	PO Box address corrected
XC_UNIT	7	#	Secondary address (apt/ste) corrected or ignored
XC_FIRM	8	F	Firm name not found, ignored
XC_URB	9	U	PR Urb name corrected
XC_CS	10	C, S	Missing city-state corrected to match ZIP
XC_NONDEL	20	D	Address verified, but USPS doesn’t deliver (no +4)
XC_EXTRA	21	X	Extraneous characters (ignored)
XC_GENDEL	22	G	General delivery default match (town has no street delivery)
XC_5DIG	30	Z	Verified only 5-digit ZIP code (UNZ_CHECKZIP)

The following codes may be returned by UNZ_CHECKADDRESS indicating that the address could not be verified or corrected.

XC_BADCSZ	50	Total city-state-zip mismatch
XC_NODATA	51	Insufficient address data
XC_BADSTR	52	Street name not found
XC_BADNBR	53	Street number or box number out of range
XC_NOSTR	54	City has no streets (Unable to load street list)
XC_MULT	55	Multiple matching records
XC_BADURB	56	PR Urb not found in city street list
XC_FHERR	57	Firm/Highrise name conflict

The following codes may be returned by UNZ_CHECKADDRESS or UNZ_CHECKZIP, They indicate that a runtime error was detected bythe DLL during the verification of an address or ZIP code. These errors are not fatal, and do not prevent further calls to the DLL. These codes may indicate errors in passing parameters by the calling program, hardware I/O errors, or database internal content errors.

RTE00	80	Invalid or missing parameter block
RTE01	81	Invalid handle parameter
RTE02	82	Missing function parameter
RTE03	83	z8.dat file seek error
RTE04	84	z8.dat file read error
RTE05	85	z8.dat record type error
RTE06	86	z8.dat record length error
RTE07	87	z8.dat record format error
RTE08	88	Corrupted Z1.DAT - Z7.DAT
RTE09	89	Z8.DAT file read error
RTE10	90	Z8.DAT file corrupted
RTE11	91	Z8.DAT file corrupted
RTE12	92	Z8.DAT file corrupted

This group of codes is returned only by UNZ_CHECKZIP.

XC_GOODZIP	0	Valid ZIP+4, single address found
XC_ARNG	40	Valid ZIP+4 applies to primary address range
XC_URNG	41	Valid ZIP+4 applies to secondary address range
XC_BADZIP	60	ZIP code format error (xxxxx or xxxxx-xxxx)
XC_ZNF	61	ZIP code not found

Error codes produced when using UNZ_INIT #

The following is a list of codes returned by UNZ_CHECKADDRESS and UNZ_CHECKZIP when the DLL has been initialized using UNZ_INIT.

Warning - These codes are not arranged into numeric groups. NOTE: A return code of non-zero DOES NOT NECESSARILY IMPLY THAT THE ADDRESS COULD NOT BE CORRECTED! Some return codes simply indicate what correction was applied to the address. Column ADDR OKAY contains “Y” if the address check successfully corrected the address, or “N” if the function could neither validate nor correct the address.

Error Name	Return Value	Addr Okay	Error Definition
EC01	1	Y	ZIP code added/corrected (corrected)
EC02	2	Y	State code added/corrected (corrected)
EC03	3	Y	City name added/corrected (corrected)
EC04	4	N	Total city-state-zip mismatch (uncorrectable)
EC05	5	N	Insufficient address data (uncorrectable)
EC06	6	Y	city name corrected to preferred city (corrected)
EC07	7	Y	Street name corrected (corrected)
EC08	8	N	Street not found (uncorrectable)
EC09	9	N	Street or box number not found (uncorrectable)
EC10	10	Y	Apt/ste not found (address accepted)
EC15	15	Y	Address corrected (corrected)
EC16	16	N	City-state missing (corrected)
EC17	17	Y	No streets, matched to General Delivery ZIP+4
EC30	30	N	Firm/Highrise name conflict
EC31	31	Y	Non-delivery address (corrected, but no ZIP+4)
EC32	32	N	Multiple matching records (uncorrectable)
EC33	33	Y	Street name changed to preferred (corrected)
EC98	98	N	PR Urb not found in city street list (uncorrectable)
EC99	99	N	City has no streets (uncorrectable)

The following integer values are returned only by UNZ_CHECKZIP:

Error Name	Return Value	Addr Okay	Error Definition
EC20	20	N	ZIP code format error
EC21	21	N	ZIP code not found
EC22	22	N	ZIP code applies to address range
EC23	23	N	ZIP code applies to unit range
EC24	24	Y	Verified 5-digit ZIP code

Errors detected by the DLL:: The DLL has been programmed to return an error code to the calling program instead of displaying a Windows Message Box. Your calling program should always watch for fatal return error codes, which indicate that some serious failure has occurred. Continuing to call the DLL after a serious error could lead to a General Protection Fault by the DLL.

Reference Guide

Contents

Reference Guide#