Reference Guide

Address Object

Melissa's Address Object cleans up bad and incomplete contact data. This can help you reduce undeliverables, increase communication, and save money on direct marketing and CRM campaigns.

To do this, the Address Object is broken into four different interfaces:

For far more information, continue reading deeper into this document!

Minimum System Requirements

The Address Object has the following system requirements:

Hardware Detail
HDD 20GB Hard Disk Space
Operating System Details
Windows Windows 7 or later personal computer OS version. Windows Server 2008 R2 or later Windows Server version.
Linux Linux distribution supporting GCC 3.3 or GCC 4.1.
Solaris Solaris 8.0 and newer supporting Workshop6 compiler or Workshop 12.
AIX AIX 5.2 supporting XLC6
HP-UX Version 11 or later supporting ACC3 or GCC 3.4

Installation

  1. To install Address Object you need to close all open applications, including any anti-virus and e-mail software.
  2. Download the zip file from the link you received in your email.
  3. Unzip the file and run the setup file for your operating system.
  4. Operating System Install File Name
    Windows setup.exe
    Unix setup.sh
  5. Read the license agreement, and then click Yes if you agree to the terms. (To proceed with the installation, you must accept this agreement.)
  6. Select the component(s) that you want to install.
  7. Verify the install location and selected options.
  8. Click Install the component(s).
  9. Verify the installation and clean up the download file if you need hard disk space.

Authentication

Melissa requires a License Key to access the full features of Address Object. Your License Key will be sent to you from your Melissa representative. Without the License Key, Address Object will only run in DEMO mode.

Your license key will determine what functionality you have access to and your valid subscription dates are. Once a license key expires, your application using Address Object will no longer work. This is why it is important to make sure you keep your license up to date. Your Melissa representative will work with you closely to make sure you have time to renew your subscription and update your license.

AddressCheck Interface

The AddressCheck Interface verifies and standardizes your address data using the most current USPS® and CanadaPost data. We also use and make available additional data that is proprietary to Melissa:

  • Over 5 million Non-USPS addresses that are not serviced by the US Postal Service
  • Data to append residential suites based on the last name
  • Aggregated and combined delivery indicator data from multiple sources
  • Melissa unique persistent global identifier

Use the AddressCheck Interface of Address Object to verify addresses in real time, either as part of your in-house data entry system or when gathering customer data via your website. Standardizing street names and abbreviations will also help eliminate duplicate entries.

Address Object is both CASS™ certified and SERP™ certified. We are official postal solution providers for the United States Post Office and CanadaPost. You have the ability to generate a CASS™ 3553 Form or SOA™ Form to facilitate your mailing campaign and quality for postal discounts.

Using the Interface

Make sure to first set up the Address Object before you continue below and use the AddressCheck interface.

To use the AddressCheck Interface, we've grouped the functions in order of use. Follow the steps below to use the interface:

  1. Initialization: Prepare the instance for processing
  2. Options: Setting configuration for your use case
  3. Set Inputs: Pass in the address data for verification
  4. Verify: Tell the object to process the input address
  5. Results: Review the status of the verification
  6. Output: Grab and use the verification output values
  7. Generate Mailing Forms (CASS™ Form 3553 or SOA™) (Optional)

The rest of this document will walk you through these different steps and expand on their implementation and use.

Initialization

After you've set your License Key in an Environment Variable, you need to initialize the AddressCheck Interface and set up the data files. These data files are how Address Object knows if an address is valid. If you don't set these right Address Object is going to "New phone, who dis" you. Be sure to set these up and that they work.

Instantiate

You have to first instantiate the AddressCheck Interface.

Set Your License

You can set your license in two ways:

  1. Set your MD_LICENSE enivornment variable with your license.
  2. Set your license via the SetLicenseString method.

Set Data Paths

Once you've realized setting an environment variable is the smart thing to do, set the data file paths. There are multiple data files for Address Object. We recommend you set the paths for all the files.

These are the basic data file paths that you should set and use.

  • SetPathToUSFiles
  • SetPathToDPVDataFiles
  • SetPathToLACSLinkDataFiles
  • SetPathToSuiteLinkDataFiles
  • SetPathToRBDIFiles
  • SetPathToSuiteFinderDataFiles

If you have Canadian addresses, you will need to set the path for the Canada files.

  • SetPathToCanadaFiles

To use the Meilssa proprietary persistent unique identifier, enable this data path:

  • SetPathToAddrKeyDataFiles

Initialize

Once you set the data file paths you need to initialize them to load them and ensure everything is working. Call InitializeDataFiles. If it returns anything other than 0 the initialization has failed and you need to check the return value of GetInitializeErrorString to find out why it failed. It's important to do this step since the data files are integral to the functionality of Address Object.

  • InitializeDataFiles
  • GetInitializeErrorString

Database Expiration Methods

Have you ever went to take a sip of some nice cold milk but instead you had to chew it? That's what it's like for Address Object when you try to use old data. Use these methods to check the dates of the databases and the build number of the object.

  • GetBuildNumber
  • GetCanadianDatabaseDate
  • GetCanadianExpirationDate
  • GetExpirationDate
  • GetUSDatabaseDate
  • GetUSExpirationDate
  • GetLicenseExpirationDate
_ AddressCheck Initialization
//Initialize AddressCheck Interface
SET addPtr = NEW instance of AddressCheck

//Set Data File paths
CALL SetPathToUSFiles WITH PathToUSDataFiles
CALL SetPathToDPVDataFiles WITH PathToDPVFiles
CALL SetPathToLACSLinkDataFiles WITH PathToLACSLinkFiles
CALL SetPathToSuiteLinkDataFiles WITH PathToSuiteLinkFiles
CALL SetPathToCanadaFiles WITH PathToCanadaDataFiles
CALL SetPathToRBDIFiles WITH PathToRBDIFiles
CALL SetPathToSuiteFinderDataFiles WITH PathToSuiteFinderFiles
CALL SetPathToRBDIFiles WITH PathToRBDIFiles
CALL SetPathToAddrKeyDataFiles WITH PathToAddrKeyDataFiles


//Initialize Data Files and check for errors
CALL InitializeDataFiles RETURNING result
IF result <> 0 THEN
CALL GetInitializeErrorString RETURN ErrorMessage
DISPLAY ErrorMessage
ELSE
Process Addresses
END IF
!> Environment Variable Alternative

The environment variable method of setting the license will override the value entered into SetLicenseString() via code. The environment variable method is the recommended method as it can be easily changed without re-compiling. When your current subscription expires and you renew, you will be issued a new license string.

!> Data Paths and Updates

Most of these are updated monthly and you'll need at least 20GB of Hard Disk space for these files. The main exception is the EWS file which is updated weekly.

!> CASS™ is Needy

Originally, CASS™ processing only used the USFiles. However, over the years, the USPS® has added additional files like DPV™, LACSLink®, and SuiteLink®. They are required now for CASS™ processing but were not required when first added.

!> LACSLink®

Some rural addresses are confusing, so they were updated to be easier to find for emergency services. LACSLink® checks the old rural addresses with the updated version and corrects it.

!> RBDI and Saving Money

Residential Business Delivery Indicator (RBDI) can save you money! Most shipping carriers charge a higher price for residential deliveries. RBDI helps you select the most cost-effective shipping by identifying residential addresses.

!> Database Dates

Make sure you call the GET database date methods AFTER you initialize the data files. Otherwise you'll get crazy dates, like 1969 or 1899.

Options

Now that you have the object initialized and the data files set up and working, you get to decide what options to use with the AddressCheck Interface. You're the captain now.

DisableAddressSwapping

If set to True this will disable address swapping. With address swapping, AddressCheck will swap SetAddress and SetAddress2 when SetAddress cannot be coded but SetAddress2 can.

EnableEarlyWarningSystem

If set to True this enables checking for new addresses using the Early Warning System (EWS) data. EWS data is composed of new addresses (e.g. New Housing Developments) that are scheduled for inclusion in the USPS® National Database.

UseUSPSPreferredCityNames

U.S. Only - If set to True then VerifyAddress will always return the preferred city name for the submitted address, regardless of whether or not an approved vanity name was sent.

SetDiacritics

Canada Only - This takes an enumerated value to determine how AddressCheck will handle diacritic characters in French words for addresses located in Quebec.

  • Auto - If the input value contains diacritic characters, AddressCheck will use diacritics in the output. If it does not, it will not use diacritics.
  • On - The return values will always have diacritics and all addresses will be returned in the French format.
  • Off - The return values will never have diacritics and all addresses will be returned in the English format.
SetStandardizationType

This takes an enumerated value to determine how AddressCheck handles the abbreviations of suffixes and directionals when standardizing a street address.

  • ShortFormat - The street address is returned with directionals and suffixes shortened according to postal standards. This is the default setting.
  • LongFormat - The street address is returned with directionals and suffixes spelled out rather than abbreviated.
  • AutoFormat - The street address is returned with the abbreviation or non-abbreviation of the directionals and suffixes preserved. If any of these components need to be corrected and replaced, the replacement will preserve the original standardization.
SetSuiteParseMode

This takes an enumerated value to determine how AddressCheck handles the parsing of a suite into its own field or appended to Address1.

  • ParseSuite - The suite is parsed into the suite field. This is the default setting.
  • CombineSuite - The suite is appended to Address1.
SetAliasMode

This takes an enumerated value to determine how AddressCheck handles if a street address alias (nickname or former name) will be converted or preserved.

  • ConvertAlias - The street address alias is converted to the USPS preferred street name. This is the default setting.
  • PreserveAlias - The street address alias is preserved and returned as sent.
_ Set Options
//Set Options
CALL UseUSPSPreferredCityNames WITH TRUE
CALL SetStandardizationType WITH LongFormat
!> EnableEarlyWarningSystem

EWS files are updated every week. Grab them here: ftp://ftp.melissadata.com/updates/ews.txt. They should go in the same directory as all of your other data files.

!> SetDiacritics Example

Off:

"Musée du Louvre"
...is returned as:
"Musee du Louvre"
!> SetStandardizationType Examples

ShortFormat:

"100 West Main Street East"
...is returned as:
"100 W Main ST E"

LongFormat:

"100 W Main ST E"
...is returned as:
"100 West Main Street East"

AutoFormat:

"100 W Main Ave East"
...is returned as:
"100 W Main ST East"

Set Inputs

These functions supply the address data to be verified by calling VerifyAddress. Start with clearing all properties, then add your address data fields using their respective function.

Once you've verified the address, the Get Output functions will have the verified and standardized address data.

ClearProperties

This clears all of the stored address information values of the AddressCheck Interface. Always call this before the address setting functions to ensure the data for each verified address belongs only to that address.

Set Address Data Methods

These methods set the address information to be verified. They are quite self-explanatory.

  • SetAddress
  • SetAddress2
  • SetSuite
  • SetCity
  • SetState
  • SetZip
  • SetCountryCode

SetAddress and SetAddress2... Say what now?

Address Object can take in two lines of street address data with SetAddress and SetAddress2.

SetAddress will typically contain the primary street address (Street number, street name, plus any directionals and street suffixes). It can contain a secondary address (suite number, address number, unit number, or a private mailbox located at a CMRA).

SetAddress2 will often contain the secondary address information if it is not submitted with SetAddress or SetSuite. However, SetAddress2 can also be used if there is another primary address that is part of the same record. This could be a Post Office Box or a separate street address.

If secondary address information is submitted with SetAddress2, Address Object will append this information to SetAddress before processing the record.

For Example:

Address Line 1: 1234 Main Street
Address Line 2: Suite #101

Would actually be verified as:

Address Line 1: 1234 Main Street Suite #101
Address Line 2: <empty>
SetCompany

If a company name is supplied for a company that has been assigned a specific Plus4 by the USPS® the address checking logic will return a more accurate Plus4 code.

VerifyAddress will not change the company name you set.

SetLastName

This sets the last name associated with the address. If you have the last name, Melissa’s proprietary AddressPlus database can append missing residential suites to an address.

SetLastLine

If your City, State, and ZIP™ do not have their own separate fields you can use this method to set them all at once.

This can be used as an alternative to SetCity, SetState, and SetZip.

SetUrbanization

Puerto Rico Only - This sets an urbanization name associated with the input address. When more than one address is found for a ZIP Code™, the urbanization is used to know which neighborhood to look in and provide more accurate results.

SetCountry

Address Object handles US and CA addresses. Setting the country is not necessary as we can detect the country based on the postal code. However, if you have the country, you should pass it in.

Set Parsed Data Methods

You'll use these when your address data is already parsed, which we have found is rare. Otherwise you probably won't really care about these methods.

  • SetParsedAddressRange
  • SetParsedPreDirection
  • SetParsedStreetName
  • SetParsedSuffix
  • SetParsedPostDirection
  • SetParsedSuiteName
  • SetParsedSuiteRange
  • SetParsedRouteService - Canada Only
  • SetParsedDeliveryInstallation - Canada Only
  • SetPlus4
SetParsedLockBox - Canada Only

A lock box is the Canadian equivalent of a Post Office Box in the U.S. (The two terms are often used interchangeably in Canada)

_ Set Inputs
//First clear properties!
//This ensures no left over data from a previous call will contaminate the current call
CALL ClearProperties

//Set the address data
CALL SetCompany WITH CompanyName
CALL SetAddress WITH AddressLine1
CALL SetAddress2 WITH AddressLine2
CALL SetSuite WITH SuiteNumber
CALL SetCity WITH City
CALL SetState WITH State
CALL SetZip WITH Zip5
CALL SetUrbanization WITH Urbanization
CALL SetCountryCode WITH CountryCode
!> SetAddress

Address Object needs the city/state/zip to be parsed out in their own fields or in last line format. If you do not have that, we have several options. Rightfielder is a tool to parse out the individual fields needed. You can also use our Global Address product which can handle addresses with only address lines.

!> SetAddress2

US addresses actually only officially has 1 address line. Address2 is typically used to hold additional information but will not be used for verification. The exception is if we see that this data is part of the address like a suite or a private mailbox.

!> SuiteLink®

SuiteLink® enables Address Object to assign the suite information tied to the Company Name. If the company name has an assigned suite GetSuite will have the suite information.

!> SetLastLine

For Example you can send:

Rancho Santa Margarita, CA 92688-2212

instead of:

Rancho Santa Margarita //to SetCity
CA //to SetState
92688 //to SetZip
!> SetUrbanization

For Example:

Mr John Smith
URB Fair Oaks ←The Urbanization
Ave Wilson Churchill 123
Rio Piedras PR 00926-0123
!> SetCountry

If we see a country that is not US or CA, we will return a result code of AS09. If you have records outside of US and CA, you should use our Global Address product.

Verify the Address

VerifyAddress

Calling VerifyAddress will verify, standardize, and enhance a U.S. or Canadian address based on the input data. After calling VerifyAddress, check the Result codes with GetResults to see the level of matching and verification on the input address. This will also let you know if there were any problems with the call.

_ Verify Address
//Verify the address data
CALL VerifyAddress
!> Integer Artificer

VerifyAddress returns an integer. This is an artifact of an older version of the product and left for compatibility reasons. However, you should not use the return value for any purpose.

Get Results

Retrieve Status and Return Codes

GetResults

This returns a comma-delimited string of four-character codes that detail the level of matching found for the current address, any errors that occurred, and any changes that were made while standardizing the information. For a general primer on Result Codes, please visit: Quickstart Result Codes.

For a list of all possible codes, visit: Melissa Address Object Wiki - Result Code Details

Validity's Main Indicators

Address Handling

To determine validity of an address, you should look at our 3 main indicators:

Code Description Validity
AS01 USPS Address Fully Verified Good Data
AS02 Address partially verified to building level. Error with suite. Partially Good Data
AS03 Non-USPS address fully verified. Good Data

AS02 is a judgement call. The street address is good but the suite was either missing or invalid. However, often times if you have the name or company name, the mail can still be delivered or the address is still good enough to use for deduplication.

Non-Rental Addresses

Let’s look at some other possible scenarios. Let’s say you want to also filter out any addresses that are rental addresses like a PO Box or a private mailbox. The thing to keep in mind here is that you can use more than Result codes for your decision handling. You want to use these result codes:

Code Description Type
AS10 CMRA Address Rental Address
AS11 PBSA Address Rental Address

But you also want to look at the AddressType.

Mailable Addresses

Now, let’s say we want “Mailable only” addresses where we think it only be addresses that is actively lived in or used. This is different than AS01/AS03, which really just means that this address exists. We will consider AS03 as non-mailable as almost all main active residences would be registered with the USPS.

Code Description Mailable
AS16 Vacant Address Not Mailable
AS17 No USPS Mail Delivery Not Mailable

USPS Vs. Third Party Delivery

Lastly, let’s say we want to differentiate between using USPS and a third part Delivery Company like Fedex or UPS. There are a couple of considerations.

USPS or Third Party Delivery?

Code Description Type
AS01 USPS Address Fully Verified Mostly Both. More Info Needed
AS03 Non-USPS address fully verified. Third Party
AS16 Vacant Address Both. USPS may hold mail.
AS17 No USPS Mail Delivery Third Party
AS20 Deliverable only by USPS USPS

AS16 and AS17 are the judgement calls. Vacant means the USPS lists the address as having been vacant for 90 days. They may not even attempt delivery. However, a third part delivery may fail if a signature is required.

AS17 means the USPS marks the address as not being deliverable. Our experience is that these addresses are often deliverable with a third party. That is not a guareentee though.

!> GetResults

For Example:

AS01, AS14, AC01
_ Address Handling
If(Results.Contains(“AS01”) or Results.Contains(“AS03”))
{
//Handle good address
}
else if (Results.Contains(“AS02”))
{
//Handle partially good address
{
else
{
//Handle bad address
}
_ Non-Rental Addresses
//Non-Rental Address Decision Tree
If((Results.Contains(“AS01”) or Results.Contains(“AS03”)) and not Results.Contains(AS10) and not Results.Contains(AS11) and AddressObject.AddressType <> “P”)
{
//Handle good non-rental address
}
else if((Results.Contains(“AS01”) or Results.Contains(“AS03”))
{
//Handle good rental address
}
else if (Results.Contains(“AS02”))
{
//Handle partially good address
{
else
{
//Handle bad address
}
_ Mailable Addresses
//Mailable Address Decision Tree
If((Results.Contains(“AS01”)  and not Results.Contains(AS16) and not Results.Contains(AS17))
{
//Handle good Mailable address
}
else if((Results.Contains(“AS01”) or Results.Contains(“AS03”))
{
//Handle good non-mailable address
}
else if (Results.Contains(“AS02”))
{
//Handle partially good address
{
else
{
//Handle bad address
}
_ USPS Vs. Third Party Delivery
//USPS vs Third Party Delivery
If((Results.Contains(“AS01”) or  Results.Contains(“AS03”))
{
if(Results.Contains(“AS20”)
{
  //Use USPS Only
}
else if(Results.Contains(“AS03”) or (Results.Contains(“AS17”))
{
  //Third party delivery only. AS17 is a judgement call.
}
else
{
  //Delivery by USPS or Third party
}
}
else if (Results.Contains(“AS02”))
{
//Handle partially good address
{
else
{
//Handle bad address
}

Get Outputs

Retrieve the Standardized and Verified Address Data

These return the address information that has been verified and standardized.

  • GetCompany
  • GetAddress
  • GetAddress2
  • GetSuite
  • GetPrivateMailbox
  • GetCity
  • GetState
  • GetZip
  • GetPlus4
  • GetCountyName
  • GetCountryCode
  • GetUrbanization

Retrieve Parsed Street Address

These return the parsed street address parts.

  • GetParsedAddressRange
  • GetParsedPreDirection
  • GetParsedStreetName
  • GetParsedPostDirection
  • GetParsedSuffix
  • GetParsedSuiteName
  • GetParsedSuiteRange
  • GetParsedPrivateMailboxName
  • GetParsedPrivateMailboxNumber
  • GetParsedRouteService - Canada Only
  • GetParsedLockBox - Canada Only
  • GetParsedDeliveryInstallation - Canada Only
GetParsedGarbage

This returns any unused characters left over from the street address after it has processed, up to 50 characters.

Other Outputs

These return additional information linked to the input address.

GetAddressTypeCode and GetAddressTypeString

These are the code and string definition combos detailing the type of address returned.

U.S. Address Type Codes

Code Description
A Alias
F Firm or Company address
G General Delivery address
H High Rise or Business complex
P PO Box address
R Rural Route address
S Street or Residential address

Canadian Address Type Codes

Code Description
1 Street
2 Street Served By Route and GD
3 Lock Box
4 Route Service
5 General Delivery
B LVR Street
C Government Street
D LVR Lock Box
E Government Lock Box
L LVR General Delivery
K Building
GetCityAbbreviation

City abbreviation. Any city with a name longer than 28 characters must have an official abbreviation. If the city name is more than 28 characters long, this will contain the official USPS abbreviation for the city.

GetCongressionalDistrict

An electoral division in a US State where a member of the U.S. House of Representatives is elected. You can use this information to target particular congressional districts or to refer people to their Representative in Congress.

GetCountyFips

The Federal Information Processing Standard (FIPS) is a 5-digit code assigned to each county in the U.S. by the Bureau of the Census. The first two digits are the state code and the last three digits are the county number.

GetTimeZone and GetTimeZoneCode

The time zone is a 2-digit number representing the hours past Greenwich Mean Time. The time zone code is a code returned corresponding to a time zone. See the table below for a list of the time zones.

Time Zone Codes

Code Time Zone
4 Atlantic Time
5 Eastern Time
6 Central Time
7 Mountain Time
8 Pacific Time
9 Alaska Time
10 Hawaii-Aleutian Time
11 Samoa Time
GetZipType

Returns a code indicating the type of address belonging to the ZIP Code™.

ZIP™ Type Codes

Code ZIP™ Type
M Military/APO
P PO Box
U Unique (assigned to specific organizations)
Blank Standard
GetCarrierRoute

The Carrier Route (CRRT) code applies to pieces grouped by individual mail carrier routes. CRRT-coded mail can receive presort discounts if enough pieces qualify per Carrier Route.

Carrier Route First Letter Codes

Code Description
B PO Box
C City Delivery
G General Delivery
H Highway Contract
R Rural Route
GetDeliveryPointCode

This field contains a 3-digit number composed of a “check digit” (which is the last digit of this 3-digit number), plus two additional numbers (usually the first 2 digits of the address number).

GetDeliveryPointCheckDigit

This field contains the last digit in the Delivery Point Barcode. The DPB Check Digit enables bar code scanners to verify that they have scanned the first 11 digits of the Delivery Point Barcode correctly. If the Delivery Point field and the DPB Check Digit field are both formatted, AddressCheck will return a 2-digit number for the Delivery Point and a 1-digit number for the DPB Check Digit.

GetRBDI

This returns a code indicating if the address is a residence, business, or unknown. This is useful to filter out addresses based on their types, or sort them to determine the best carrier for delivery.

RBDI Address Type Codes

Code Description
R Residential
B Business
U Unknown
GetAddressKey

This returns a 11 digit code representing the combination of the ZIP Code™, the plus4, and the delivery point. This is a fairly good representation of a unique US address and often used as the core of postal barcode. However, this code is not guaranteed to be unique to an individual address, please use the GetMelissaAddressKey instead for that purpose. It is possible that this field is empty or not 11 digits if the address is a Non-USPS® address.

GetMelissaAddressKey

This is a globally unique and persistent key for the location, even if parts of the address change. When an address is fully validated this field returns a 10-digit proprietary key for the address.

With AddressKey (US and Canada only), if an address ZIP Code™ changes, the AddressKey would also change. Melissa Address Key (MAK) is independent and will not change. This makes MAK a good way to permanently identify and locate addresses. Once you have a MAK it can be used as an input in most Melissa services and thus is a good tool for deduping.

GetMelissaAddressKeyBase

Every full address has its own Melissa Address Key (MAK). If that address is a suites or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. This provides a link between all the individual MAK addresses that belong to the same building. This field also returns a 10-digit proprietary key. Note, if we can validate the address to the building but not the suite, we can return just the BaseMAK.

!> GetPrivateMailbox - Don't Forget!

IMPORTANT! Make sure to look at and keep this data. The Suite and PrivateMailbox data is not included in the Adddres or Address2 fields.

!> GetParsedGarbage

Common items found returned by this method are community center names, names of individuals, additional delivery instructions, and so on.

Find Suggestions

If VerifyAddress was unable to correct the input address, you can still get possible correct addresses by using the Find Suggestions functions.

FindSuggestion

This can be called after VerifyAddress if the original address could not be verified by Address Object.

FindSuggestion will only work if SetCASSEnable is set to false. You cannot combine suggestions with CASS™ verification. You must also have DPV™ enabled and a valid directory path to the DPV™ data files set.

If the method returns a 1, a suggestion was found and you can retrieve the suggested address using the regular output fields.

If you get a 0 then no suggestion was found.

FindSuggestionNext

This returns the next suggestion, if any, based on the originally submitted address.

You can call this after a successful call to FindSuggestion and can be repeated until you get a 0, indicating that no further suggestions are available.

If you get a 1, that means a new suggestion is available and can be retrieved using the same regular output fields.

_ Call FindSuggestion
//If the address could not be verified, find the most likely alternative
IF FindSuggestion <> 0 THEN
{
CALL GetAddress RETURNING AddressLine1
//get remaining address outputs

WHILE(FindSuggestionNext <> 0)
{
  CALL GetAddress RETURNING AddressLine1
  //get remaining address outputs
}
}
!> Time!

FindSuggestion will take a long time! Be sure to plan for this if you want to use it.

CASS™ Form

CASS™ (Coding Accuracy Support System) certification is used by the USPS® to ensure accuracy in address data software. For you it means we check and correct your address data to USPS® specifications, giving you the best mailable address you can get. Many clients use Address Object to improve their data quality and are very happy with it. However, if you want to actually get the CASS™ 3553 form for discount bulk mailings, here are some additional steps to take.

To see what the CASS™ form 3553 looks like, click here: CASS Form 3553

SetCASSEnable

This enables full CASS Certified™ address verification. It's disabled by default so you're first step in using CASS™ will be to set this to True. You can set it before or after calling InitializeDataFiles() but make sure to call it before passing in any address data.

CASS™ Form 3553 - Item D3 Methods

These set the information on CASS™ Form 3553 item D3 for the company that owns the list or for whom the mailing is being prepared.

  • SetPS3553_D3_Name
  • SetPS3553_D3_Company
  • SetPS3553_D3_Address
  • SetPS3553_D3_City
  • SetPS3553_D3_State
  • SetPS3553_D3_ZIP
SetPS3553_B4_ListName

This sets the name or identification number of the address list. If you use more than one list, this will be left blank. If you use an identification number, you have to precede it with ID#.

SetPS3553_B1_ProcessorName

This sets the name of the company that coded the address list(s) and/or used the Address Object to perform ZIP+4® matching.

GetFormPS3553

After you are done processing, call this method to get the HTML string for the CASS 3553 form. You can then save that string to a file of your choosing or store it in a database.

SaveFormPS3553

This will save the CASS™ Form 3553 as either an HTML or PDF file. Pass in the full directory path and filename with an [extension].

ResetFormPS3553

Use this to reset the running totals for a CASS™ processing.

You must call this method if you need to produce several CASS™ forms in sequence for multiple jobs.

_ Enable CASS™
//Enable CASS™ functionality
//Required BEFORE InitializeDataFiles
CALL SetCASSEnable WITH TRUE
_ Set CASS™ Info
//Provide CASS™ owner name/address
CALL SetPS3553_B1_ProcessorName WITH ProcessorName
CALL SetPS3553_B4_ListName WITH ListName
CALL SetPS3553_D3_Name WITH ListOwnerName
CALL SetPS3553_D3_Address WITH strListOwnerAddr
CALL SetPS3553_D3_City WITH ListOwnerCity
CALL SetPS3553_D3_State WITH ListOwnerState
CALL SetPS3553_D3_ZIP WITH ListOwnerZip
_ Save CASS™ Form
//After verification, and if using USPS® CASS™
CALL SaveFormPS3553 WITH CASSFormPath
!> CASS™ Data Files

If you want to use CASS™ Processing you must ensure you're using the required data files. They are the DPV™, LACSLink™, and SuiteLink® data files.

!> SaveFormPS3553

You must include the extension you want in your CASS™ Form 3553 filename, either .HTML or .PDF!

For Example:

SaveFormPS3553(“C:\Program Files\Melissa Data\Data Files\CASSForm.pdf”)
!> ResetFormPS3553

Each instance is only able to keep track and maintain a single CASS™ form. You will not be able to split a job into multiple threads and combine back into a single cass form. You will need to maintain the values yourself to do that.

SOA™ Form

Usage

If you want to use SOA™ Processing you need to have it enabled on your account. If you don't have this service, call your Melissa sales representative to subscribe. Then you need use the required Canada data files.

You then have to set the SOA™ Customer info and contract number.

Finally set a path for the SOA™ form to be saved. This form will be required by the Canada Post for your mailing.

SOA™ Set Methods

SetSOACustomerInfo

This sets the Company name and mailing address for use on the Statement of Accuracy (SOA™) report. This takes two string values as parameters:

  • CustName - The Company name on your Canada Post contract.
  • CustAddress - The mailing address on your Canada Post contract.
SetSOACPCNumber

The CPC Number is an eight-digit number that appears on your Canada Post contract.

GetFormSOA

This returns the current Statement of Accuracy in HTML format as a string.

For more methods on retrieving individual parts of the SOA™ Form, see the Appendix.

SOA™ Methods

ResetFormSOA

Use this to reset the running totals for Canadian addresses.

You must call this method if you want to process multiple databases with the same instance of Address Object.

SaveFormSOA

This saves an HTML file of the Statement of Accuracy (SOA™).

_ Set SOA™ Info
//Provide SOA™ customer info/number
CALL SetSOACustomerInfo WITH CustomerInfo
CALL SetSOACPCNumber WITH CPCNumber
_ Save SOA™ Form
//After verification, and if using Canada Post SOA™
CALL SaveFormSOA WITH SOAFormPath
!> ResetFormSOA

It's a good practice to always call ResetFormSOA before processing Canadian addresses.

!> SOA™ Expiration

Good news everybody! The SOA™ is good for one year after it's generated. You don't need to generate another one unless your address data changes.

!> SaveFormSOA

You must include the .HTML extension in the filename you pass to this method!

FAQ

Address Object Database Schema

I bet you want to know the maximum and minimum lengths of properties for Address Object. Well you're in luck, that's exactly what's here!

Maximum Field lengths are a bit of a tricky topic. Address Object does not have any built in maximum length. The effective maximum length depends on two factors:

  • The length of the data available from the USPS® and CanadaPost
  • The length of the input data

For addresses that we do not code, we will return the input (sometimes with a few standardizations, if possible) back to you. This effectively makes the output length the same as the input length. We do not truncate the input data to fit a pre-determined field length.

For addresses that we do code, we are essentially returning the official postal data. The maximum length is effectively the same as the longest data string in the source data. Since addresses change and are added frequently, this is not a number that is guaranteed to be stable, so it is important to put a buffer to account for future cases. Our recommended maximum lengths below of coded records are based on this information.

Recommendations

  • Set the maximum field length to at least match the input maximum data length
  • Set the maximum field length to far beyond (100+ characters) the numbers of the source data above. In this day and age, storage space is much less a limiting factor than before. We suggest setting a length that guarantees nothing gets truncated.
USPS®
Field Name Max Length Recommended
Company 75 characters (The company name is usually returned as is based on the input)
Address1 65 characters
Address2 Address2 is not part of the official address. Extra data like care of information will be returned here based on the input.
Suite 20 characters (This is one where we can code the address to the house number put pass through a suite from the input that is only any length)
PrivateMailbox 20 characters (This is one where there is no official source data for so the input is passed though as long as it is in the expected format)
City 35 characters
Urbanization 35 characters
State 2 characters
Zip 5 characters
CanadaPost
Field Name Max Length Recommended
Company 75 characters (The company name is usually returned as is based on the input)
Address1 65 characters
Address2 Address2 is not part of the official address. Extra data like care of information will be returned here based on the input.
Suite 20 characters (This is one where we can code the address to the house number put pass through a suite from the input that is only any length)
City 35 characters
State 2 characters
Zip 7 characters

StreetData Interface

The StreetData Interface is provided to access U.S. street address data directly rather than through the AddressCheck Interface.

You might want this data to show customers alternate addresses if the address checking logic is unable to code their address. All records that match their range can be displayed, allowing for the correction of misspellings. Other uses can include filtering our data, since you may only need the street names in a particular carrier route, congressional district, or county FIPS code.

The records returned this interface contain address ranges, but that does not mean that each address in that range is a deliverable address. For example you may see a range of 1 to 10 Main Street. The deliverable addresses may be 1, 2, 3, 5, 6, 9, and 10. That means 4, 7, and 8 will not be deliverable. These records are effective for checking existing addresses, but not for creating addresses, which is prohibited by the USPS®.

Using the Interface

Make sure to first set up the Address Object before you continue below and use the StreetData interface.

Follow the steps below to use the interface:

  1. Initialize StreetData Interface, Set Data File Paths, Initialize Data Files
  2. Call FindStreet with the Street Name to Match
  3. Continue Calling FindStreetNext until you get False
  4. Loop through Street list and Compare with a Parsed Address

Initialization

After you've set your Licence Key in an Environment Variable, you need to initialize the StreetData Interface and set up the data files. These data files are key to StreetData working. As in, no key, you're not getting anywhere.

Instantiate

You have to first instantiate the StreetData Interface.

Set License String

Then you have the choice of setting the license string. But it's not recommended. We really want you to do the right thing and set the license string via Environment Variables.

  • SetLicenseString

Initialize

Unlike the other interfaces, with StreetData initialization also opens the required data files.

Initialize

Initialize takes two parameters, one for each required data file. It then, quite unsurprisingly, initializes StreetData - readying it for that data you're about to sling at it.

  • DataPath - The path to the mdAddr.dat file.
  • NationalPath - The path to the mdAddr.nat file.

Initialize returns one of the following codes: (and GetInitalizeErrorString returns the corresponding description.)

Initialize Return Codes

Code Description
0 No error - initialization was successful.
1 Could not open the mdAddr.dat file.
2 Could not open the mdAddr.nat or mdAddr.str file.
4 The internal database date of the mdAddr.dat and mdAddr.nat files do not match.
5 Not all the memory buffers could be initialized.
6 Unknown error
GetInitializeErrorString

This returns the definition of the code returned by Initialize.

Database Expiration Methods

Wondering why something isn't working? Have you checked your expiration dates? That's what these methods are for - to check the dates of the databases and the build number of the object.

  • GetBuildNumber
  • GetDatabaseDate
  • GetLicenseExpirationDate
_ Instantiate StreetData
//Instantiate StreetData Interface
Set streetPtr in New Instance of StreetData
_ Initialize Data Files
//Initialize Data Files and check for errors
CALL Initialize WITH DataPaths RETURNING Result
IF Result <> 0 THEN
Call GetInitializeErrorString RETURN ErrorMessage
Display ErrorMessage
End If
!> Initialize, Data Files, and You

If the data files are in the same directory as the Component, you do not need to call Initialize. However, if there is an error, an exception will be reported instead of an error code.

FindStreet

Your next big step is to search for those street addresses! FindStreet locates the range of street addresses that matches the pattern and ZIP Code™ you send it.

FindStreet

This method requires three parameters to do it's magic:

  • StreetName - Obviously the street name. You can use wildcards at the end of this value. e.g. MA* would match any streets beginning with MA.
  • ZIP - The five digit ZIP Code™.
  • CodeOnly - A Boolean. By default set to 0 and will match any records within the city of the ZIP Code™. If you set this to 1, FindStreet will only return records in the set ZIP Code™.

Getting the Next Record

FindStreetNext

This method gets the next StreetData record. It will return either True or False.

Use this to cycle through multiple results.

  • True - The next street record will be called.
  • False - There are no more matching street records.
_ Call FindStreet
CALL FindStreet WITH StreetName, Code RETURNING Result
IF Result is TRUE THEN
CALL GetAddressType RETURNING AddressType
CALL GetPrimaryRangeLow RETURNING RangeLow
CALL GetPrimaryRangeHigh RETURNING RangeHigh
CALL GetPrimaryRangeOddEven RETURNING RangeOddEven
CALL GetPreDirection RETURNING PreDirection
CALL GetStreetName RETURNING StreetName
CALL GetSuffix RETURNING Suffix
CALL GetPostDirection RETURNING PostDirection
CALL GetSuiteName RETURNING SuiteName
CALL GetSuiteRangeHigh RETURNING SuiteHigh
CALL GetSuiteRangeLow RETURNING SuiteLow
CALL GetSuiteRangeOddEven RETURNING SuiteOddEven
CALL GetZip RETURNING Zip
CALL GetPlus4Low RETURNING Plus4Low
CALL GetPlus4High RETURNING Plus4High
WRITE VALUES TO LIST OR SPREADSHEET
End If
!> Life After FindStreet

Once you have the range of street addresses you can then cycle through multiple results using the FindStreetNext method.

_ Call FindStreetNext
CALL FindStreetNext RETURNING Result
WHILE Result Is TRUE
CALL GetAddressType RETURNING AddressType
CALL GetPrimaryRangeLow RETURNING RangeLow
CALL GetPrimaryRangeHigh RETURNING RangeHigh
CALL GetPrimaryRangeOddEven RETURNING RangeOddEven
CALL GetPreDirection RETURNING PreDirection
CALL GetStreetName RETURNING StreetName
CALL GetSuffix RETURNING Suffix
CALL GetPostDirection RETURNING PostDirection
CALL GetSuiteName RETURNING SuiteName
CALL GetSuiteRangeHigh RETURNING SuiteHigh
CALL GetSuiteRangeLow RETURNING SuiteLow
CALL GetSuiteRangeOddEven RETURNING SuiteOddEven
CALL GetZip RETURNING Zip
CALL GetPlus4Low RETURNING Plus4Low
CALL GetPlus4High RETURNING Plus4High

WRITE Values TO Range Lost

CALL FindStreetNext RETURNING Result
ENDWHILE

Get Street Range

Once you call FindStreet you're going to need to get the Street Range.

Parsed Street Data

These methods return the parsed street data.

GetAddressType

This method returns a 1-character code indicating what type of address was returned. For a list of the codes, see U.S. Address Type Codes

GetBaseAlternateIndicator

This method returns a 1-character code indicating if the record is a base (preferred) B or alternate A.

GetCarrierRoute

This returns a 4-character code indicating the type of delivery for that address. For a list of the codes, see Carrier Route Codes

  • GetPreDirection
  • GetStreetName
  • GetSuffix
  • GetPostDirection
  • GetSuiteName
  • GetZip
  • GetCompany
  • GetCongressionalDistrict
  • GetCountyFips
  • GetLACSIndicator
  • GetLastLineNumber
  • GetUrbanizationCode
  • GetUrbanizationName
  • GetDeliveryInstallation

Get Primary Range Methods

These methods return the lowest or highest street number in a 10-character string padded on the left with zeroes.

For example, for GetPrimaryRangeLow, if the street range is 100 to 200 Main Street, you'll get 0000000100. Don't forget those padded zeroes.

  • GetPrimaryRangeLow - Returns the lowest street number.
  • GetPrimaryRangeHigh - Returns the highest street number.

Get Suite Range Methods

These methods return the lowest or highest suite number in an 8-character maximum string.

For example, for GetSuiteRangeHigh, if the suite range is 1001 to 2001, you'll get 2001. This time there are no padded zeroes... don't get confused.

  • GetSuiteRangeLow - Returns the lowest street number.
  • GetSuiteRangeHigh - Returns the highest street number.

Get Range Odd/Even Methods

These methods return a single character telling you the parity of the range, in a mathematical sense. (It tells you if it's odd, even, or both).

  • GetPrimaryRangeOddEven - Returns the parity of the street range.
  • GetSuiteRangeOddEven - Returns the parity of the suite range.

Get Range Odd/Even Codes

Code Description
O Only Odd street numbers are in the range.
E Only Even street numbers are in the range.
B Both odd and even street numbers are in the range.

Get Plus4 Methods

These methods return the lowest or highest Plus4 number in a 4-character maximum string. Both of these methods usually contain the same value, except when dealing with PO Boxes. (Every PO Box has its own Plus4 code).

  • GetPlus4Low - Returns the lowest Plus4 number. If the value is xxxx, the USPS® considers the street record undeliverable.
  • GetPlus4High - Returns the highest Plus4 number.
!> Base or Alternate?

GetBaseAlternateIndicator will tell you which type a record is, but what does it mean to have a base or alternate record?

A Base record can represent a range of addresses or an individual address, such as a firm record. They are generally preferred over alternate records.

Alternate records are individual delivery points.

!> Got Hyphens?
(In your Primary Ranges)

A hyphen in front of the range field indicates a significant leading zero. This means the leading zero is part of the range and is required. For example, -7 means the range is 07 and cannot be just 7. Got it?

Check Against Results

IsAddressInRange2

This method tells you if an address falls within the address range of a compared USPS® address record and matches at an Odd/Even level. It will return either 1 or 0.

When you have multiple matches from VerifyAddress, use this method with FindStreet and FindStreetNext to match the address with a valid address record.

  • 1 - The address is in range and matches the Odd/Even range.
  • 0 - The address is out of range or does not match the Odd/Even range.

Auto-Complete

GetAutoCompletion

This returns possible street address matches based off of a ZIP Code™ and at least one character of a street address. You get one possible street address per call.

It's also a really good idea to wait until you have at least four characters or an alphabet letter before you call GetAutoCompletion. Why you ask? Because you'll be trying to fit 20 gallons of addresses in a 10 gallon hat. There will likely be way too many addresses to be useful (Think about all the addresses that begin with 1 in a single ZIP Code™). If you wait for a few more characters the list will be much more user friendly.

There are four parameters you pass to the method:

  • string streetAddress - The full or partial street address.
  • string Zip - The full or partial street address.
  • mdStreet.AutoCompletionMode enumeration - Enumeration for the handling of suites.
    • AutoCompleteSingleSuite - Show each individual suite.
      (Ex: 123 Main Apt 1, 123 Main Apt 2)
    • AutoCompleteRangedSuite - Show the suite ranges.
      (Ex: 123 Main Apt 1-10, 123 Main Apt 20-30)
    • AutoCompletePlaceHolderSuite - Use a ’#’ to denote where a suite should go.
      (Ex: 123 Main #)
    • AutoCompleteNoSuite - Do not show suites.
      (Ex: 123 Main)
  • bool DPV_on_or_off - True to return only DPV™ valid street addresses. False to return all street addresses.
ResetAutoCompletion

This resets the auto-completion. You'll want to use this before you call a new record. If you don't, bad things happen. And it'll be because you didn't listen to me.

_ Check Against Results
FOR EACH Range IN LIST
IF IsAddressInRange2(StreetNum,RangeHigh,RangeLow,
    RangeOddEven) THEN
  Match Is TRUE
ENDIF
NEXT
!> But... I Want More Auto-Completion!

You can cycle through the entire list of possible street addresses by calling GetAutoCompletion until it returns an empty string.

ZipData Interface

The ZipData Interface gives you access to ZIP Code™ related information. You can:

  • Validate ZIP Code™s
  • Match ZIP Code™s to city names, latitude/longitude coordinates, county FIPS codes, and more

Using the Interface

Make sure to first set up the Address Object before you continue below and use the ZipData interface.

To use the ZipData Interface, we've grouped the methods in order of use. Follow the steps below to use the interface:

  1. Initialize
  2. Find ZIP Code™ and City Data
  3. Get Outputs
  4. Find Next Record
  5. Computation methods

The rest of this section will walk you through these different steps and expand on their implementation and use.

Initialization

After you've set your Licence Key in an Environment Variable, you need to initialize the ZipData Interface and set the path to the data files (if they are not in the same directory as the Address Object component file).

Instantiate

You have to first instantiate the ZipData Interface.

Set License String

Then you have the choice of setting the license string. But please remember that this is not recommended. Use your noodle and set the license string via Environment Variables.

  • SetLicenseString

Initialize

Once you've come to your senses and decided to set an environment variable, call the Initialize method, passing the paths to mdAddr.dat and mdAddr.nat. If Initialize returns anything other than 0 the initialization has failed and you need to check the return value of GetInitializeErrorString to find out why it failed. It's important to do this step since the data files are integral to the methodality of Address Object.

  • Initialize
  • GetInitializeErrorString

Database Expiration Methods

Have you ever went to take a sip of some nice cold milk but instead you had to chew it? That's what it's like for Address Object when you try to use old data. Use these methods to check the dates of the databases and the build number of the object.

  • GetBuildNumber
  • GetDatabaseDate
  • GetLicenseExpirationDate
!> Initialize ZipData, Not Your Standard Rodeo

Initializing the ZipData Interface is slightly different from the procedure for the AddressCheck Interface, so please proceed with caution and read through the section!

_ Instantiate ZipData
//Instantiate ZipData Interface
CALL Initialize WITH DataPaths RETURNING Result
IF Result <> 0 Then
CALL GetInitializeErrorString RETURNING ErrorString
PRINT ErrorString
END IF

Find Methods

The three main methods of the ZipData Interface retrieve information based on ZIP Code™ or city names.

Find ZIP™ Methods

These return the first record of the ZIP Code™ passed in. If GetLastLineRecord = 1 is set, they will return the last line record for the ZIP Code™ passed in.

The FindZipNext method finds the next ZIP Code™.

  • FindZip
  • FindZipNext

Find ZIP™ In City Methods

These return a list of ZIP Code™s for a given city. You must pass both a city and state (two character abbreviation).

GetAreaCode is not populated by these methods.

  • FindZipInCity
  • FindZipInCityNext

Find City In State Methods

These return a list of cities in a state, matching a set pattern. They are good for matching cities or verifying that a city exists in a state. You must supply both a city (may contain a wildcard) and a state (two character abbreviation, no wildcard allowed).

Only GetCity and GetState are populated by these methods.

  • FindCityInState
  • FindCityInStateNext

Computation Methods

These methods do not require the data files to be initialized. They can be used with the GetLatitude and GetLongitude methods to calculate distances and bearing between two records.

Both methods have the same input parameters:

  • lat1 — Latitude for point 1 in degrees 90 to –90
  • long1 — Longitude for point 1 in degrees 180 to –180
  • lat2 — Latitude for point 2 in degrees 90 to –90
  • long2 — Longitude for point 2 in degrees 180 to –180
ComputeBearing

This returns a bearing in degrees (0 to 360) representing the compass direction from point 1 to point 2.

North is 0 degrees, East is 90, South is 180, and West is 270.

ComputeDistance

The ComputeDistance method returns a distance in miles between point 1 and point 2.

!> Calling FindZipNext

If GetLastLineRecord is set to 1, you will not be able to call the FindZipNext method.

_ FindZip Pseudo Code
CALL FindZip WITH Code RETURNING Result
IF Result Is TRUE THEN
CALL GetAreaCode RETURNING AreaCode
CALL GetAutomation RETURNING Automation
CALL GetCity RETURNING City
CALL GetState RETURNING State

// Multiple Methods Returned.

CALL GetZipType RETURNING ZipType
ENDIF

WHILE FindZipNext Returns TRUE
// Call the same functions as above.
ENDWHILE
_ FindZipInCity Pseudo Code
CALL FindZipInCity WITH City, State RETURNING Result
IF Result Is TRUE
CALL GetAutomation RETURNING Automation
CALL GetCity RETURNING City

// Multiple Methods Returned.

CALL GetZip RETURNING 5
CALL GetZipType RETURNING ZipType
End If

WHILE FindZipInCityNext Returns TRUE
// Call the same functions as above.
ENDWHILE
_ FindCityInState Pseudo Code
CALL FindCityInState WITH City, State RETURNING Result
IF Result Is TRUE
CALL GetCity RETURNING City
CALL GetState RETURNING State
End If

WHILE FindCityInStateNext Returns TRUE
CALL GetCity RETURNING City
CALL GetState RETURNING State
ENDWHILE
!> Who You Gonna Call?

You do not have to call Initialize before ComputeBearing or ComputeDistance are called.

!> Your Longitude Is Showing

Negative longitudes lie west of the Greenwich Meridian, positive longitudes to the east. Longitudes for the continental U.S. are in the range from -65 to -125 degrees.

Get Outputs

  • GetAreaCode
  • GetCity
  • GetCityAbbreviation
  • GetCountyFIPS - US Only
  • GetCountyName
  • GetFacilityCode - US Only
  • GetLatitude - US Only
  • GetLongitude - US Only
  • GetState
  • GetTimeZone - US Only
  • GetTimeZoneCode - US Only
  • GetZip
  • GetZipType - US Only
GetAutomation - US Only

This returns the carrier route rate mail indicator.

GetLastLineIndicator - US Only

This returns a one-character string value. An L in this field indicates that the city name is the official U. S. Postal Service name for the ZIP Code™ (Only one record per ZIP Code™ is coded with an L).

GetLastLineNumber - US Only

This returns a six-character string value. This number is used with address matching to break ties on certain records using the city name.

GetPreferredLastLineNumber - US Only

This returns a six-character string value. This is similar to the GetLastLineNumber method mentioned earlier. If the preferred last line number is the same as the last line number, this city name is the one the Post Office will recognize as the official name for that ZIP Code™.

!> Dominant ZIP Code™s?

If a ZIP Code™ has more than one area code assigned to it, the dominant area code will be returned.

!> GetCityAbbreviation, More Than, Not Less

GetCityAbbreviation will only return a value if the city name is longer than 13 letters.

Parse Interface

The Parse Interface allows a user to separate a street address into its individual components, a process known as parsing. There are nine possible components that make up an address:

  • Range
  • PreDirection
  • StreetName
  • StreetSuffix
  • PostDirection
  • SuiteName
  • SuiteNumber
  • PrivateMailboxName
  • PrivateMailboxNumber

Addresses can usually be parsed correctly on the first try. For example, the address “100 Main St” can easily be separated so “100” is the Range, “Main” is the StreetName, and “St” is the StreetSuffix.

Some addresses require more attention. The address parser uses multiple pass parsing to handle any ambiguous addresses. If the address is not parsed correctly the first time, the parse can be called a second or third time. Each time it is called it will rearrange the tokens into a new order to try to get a match.

Using the Interface

Make sure to first set up the Address Object before you continue below and use the Parse interface.

To use the Parse Interface, we've grouped the functions in order of use. Follow the steps below to use the interface:

  1. Parse an Address
  2. Get Parsed Address Components

**Note that the Parse Interface is different from the other Address Object Interfaces and does not need to be initialized nor does it require a license string to use. You may still use GetBuildNumber to determine the build number you are using.

The rest of this section will walk you through these different steps and expand on their implementation and use.

!> Now, Why Would I Want Address Parsing?
  • You can search the StreetData database to manually correct records that AddressCheck couldn't code. Pretty nifty.
  • Address Parsing is also great if you need to sort addresses by street name and need to remove the street name from the full address.
!> Multiple Pass Parsing Example

100 N Ave C can be parsed several ways:

Range Pre Street Name Street Suffix Suite Name
100 N Ave C
100 N Avenue C
100 N Ave C
100 N Avenue C
100 N Ave C
100 North Ave C

Any of the above combinations can be correct, and all probably exist to some degree somewhere in the country.

The Parse method will return the first parse shown here and it will be correct 90 to 95% of the time. If you need a second look at the address, repeated calls to the ParseNext method will produce the additional combinations that are listed above.

!> GetBuildNumber, why you do this?

If you are running the Demo version of Address Object, DEMO will be appended to the build number.

Parse an Address

These methods parse a submitted street address and then return all possible variations on how the address can be parsed.

Parse Methods

These methods take a string of the full street address to parse. If the parsing was successful they'll return a boolean of1.

  • Parse
  • ParseCanadian - For Canadian Addresses
ParseNext

This juggles the street address components separated in your first call to either Parse or ParseCanadian. This can be useful when the first parse fails to find a matching address. While there are more possible parses ParseNext will return a boolean of 1. If there are no more parses you'll get a 0 returned.

LastLineParse

This method takes a single string and breaks it into city, state, and ZIP Code™. This can be used for both U.S. and Canadian cities.

Get Parsed Address Components

These return the parsed components of a street address after a call to the Parse, ParseCanadian, or ParseNext function.

Get Parsed Street Address Components

  • GetRange
  • GetPreDirection
  • GetStreetName
  • GetSuffix
  • GetPostDirection
  • GetSuiteName
  • GetSuiteNumber
  • GetPrivateMailboxName
  • GetPrivateMailboxNumber
  • GetRouteService - Canada Only
  • GetLockBox - Canada Only
  • GetDeliveryInstallation - Canada Only
GetGarbage

This returns any unused characters left over from the street address after it has processed, up to 50 characters.

Get Parsed Last Line Components

  • GetCity
  • GetState
  • GetZip
  • GetPlus4 - (US Only)
!> LastLineParse Does What Now?

LastLineParse does not perform address checking and will not append a Plus4 if the input address does not have one.

Glossary

These are common words you'll see when dealing with address data quality.

  • AddressPlus - Melissa add-on for Address Object for U.S. Addresses only. This appends missing secondary address information to millions of business and residential addresses based on the provided last name.
  • Carrier Route - A postal carrier route is a group of addresses that receive the same USPS® code to aid in efficient mail delivery.
  • Canada Post - Canada Post (French: Postes Canada), is a Crown corporation which functions as the primary postal operator in Canada.
  • CASS™ - Coding Accuracy Support System. CASS™ is a tool created and used by the USPS® to ensure the accuracy of software that taps into their database.
  • CASS Certified™ - A CASS Certified™ service provider accurately meets the standards of the USPS® and has passed USPS® Quality Control. A service that processes addresses according to CASS™ standards will, at the very least, fill in information missing from an address, standardize it, and update it. To become CASS Certified™ the USPS® requires that service providers' software uses DPV™ and LACS when checking addresses.
  • CASS™ Form 3553 - Form 3553 is printed by the software that is used to CASS™-certify your list. It's not a form you fill out manually.
  • CMRA - Commercial Mailing Receiving Agency. A CMRA is a private business that accepts mail from the USPS® on behalf of third parties. A customer of a CMRA can receive mail and other deliveries at the street address of the CMRA rather than the customer's own street address.
  • CPC Number - Custom Procedures Code Number. A CPC number is your reason for import or export, expressed as either a seven digit number or a six digit number and one letter. It describes the purpose of your shipment which in turn directly determines how your shipment is processed and ultimately if, how, when and from whom duties and taxes are collected.
  • DeliveryPlus - A feature of Melissa's Address Object that verifies Non-USPS® Addresses that are serviced by other delivery carriers.
  • Delivery Carriers - A private courier company that provides package delivery. For example: DHL, UPS, FedEx.
  • Delivery Installation - The building (e.g. stations or office) respoinsible for delivery to a specific postal code. There are multiple types of delivery installation, like a Postal Station or Rural Post Office.
  • Diacritic Characters - A character with a diacritical mark. A diacritical mark is a point, sign, or squiggle added or attached to a letter or character to indicate appropriate stress, special pronunciation, or unusual sounds not common in the Roman alphabet. For example, Québec.
  • DPV™ - Delivery Point Validation. DPV™ is used when you check to see if the USPS® can and will deliver to the doorstep of a specific address.
  • DSF - Delivery Sequence File. DSF identifies whether a ZIP+4® coded address is currently represented in the USPS® delivery file as a known address record. This includes vacant, residential, business or seasonal address information. This allows for more targeted mailings and is one of the approved methods for sequencing mail pieces in walk-sequence when not using a simplified address.
  • eLOT - This feature appends enhanced Line-of-Travel numbers to addresses for improved presorting and greater postage discounts when used in conjunction with Melissa Data’s Presort Object
  • EWS - Early Warning System. EWS addresses are flagged by Address Check when they are scheduled for inclusion in the USPS database but are not added yet. The addresses are typically new high rises, or new housing subdivisions that are being assigned deliverable mail addresses. The EWS file when present in the Address Object directory ensures that addresses not present in the USPS master file will not be eliminated or coded inaccurately. The EWS file is updated weekly and can be downloaded via the Melissa FTP site to give you the freshest new address information.
  • First-Class Mail® - This is a USPS® provided service used to ship letters, thick envelopes, padded envelopes, and lightweight packages.
  • License - This is the license key provided to you by your Melissa representative. It is required for the object to work.
  • MAK - Melissa Address Key. This is a globally unique and persistent key for the location, even if parts of the address change. When an address is fully validated this field returns a 10-digit proprietary key for the address. With AddressKey (US and Canada only), if an address ZIP Code™ changes, the AddressKey would also change. MAK is independent and will not change. This makes MAK a good way to permanently identify and locate addresses. Once you have a MAK it can be used as an input in most Melissa services and thus is a good tool for deduping.
  • National Postal Database - This database identifies certain primary addresses as highrises, business parks, or apartment buildings.
  • Non-USPS® Address - This is an address that is not served by the USPS®. These types of addresses are infrequent, but they do exist. They may still be serviced by other delivery carriers. These addresses will also not return the same level of information as a USPS® serviced address.
  • Parse - When Address Object parses an address it breaks it into 9 possible categories of: Range, Pre-Direction, Street Name, Suffix, Post-Direction, Suite Name, Suite Number, PMB Name, and PMB Number.
  • PAVE™ - Presort Accuracy, Validation, and Evaluation. PAVE™ is a common platform made by the USPS® to measure the quality of presort products. PAVE™ software certification is provided by the USPS® to determine the accuracy in presorting address files that are destined for bulk mail services through the Post Office™. Presorted mailing is quicker and easier for the Post Office to process, so they provide discounted pricing for mail that is accurately presorted.
  • PMB - Private Mailbox. These allow individuals or offices a private mailbox to simplify internal mail distribution, retain privacy, or have convenient hours of mail pickup. PMBs can be rented as needed through a CMRA, which may be more cost-effective than renting a box at the post office.
  • POSTNET™ - Postal Numeric Encoding Technique. This is a barcode symbology used by the USPS® to assist in directing mail.
  • Post Direction - The part of the address giving directional information for delivery. Located after the street name. (e.g. N,S,SW, etc.)
  • PO Box - Post Office™ Box. These are locked mail holding boxes at a Post Office™ location. They can be for personal or business use.
  • RBDI - Residential and Business Delivery Indicator (RBDI). RBDI can identify whether an address is a business or a residence. This may be of valuable importance for shippers who use carriers that charge differently for residences and businesses.
  • Result Codes - Each record in the response has a results field that contains a series of result codes that carry a tremendous amount of information about the output. The result codes are delimited by commas. One way we recommend using result codes is as a filter between good and bad records. Determine which codes indicate a good record for your purposes and then filter out all the records that are returned without those codes. A good simple example would be if good records are those that return an AS01, AS02, or AS03 code (these codes generally indicate a valid address record). When you process a number of records through the service you can then parse the output and filter out all of the records that do not return one of those codes in the results field.
  • Route Service - Canada Only. These are often addresses in rural areas with no street address. Instead this rural route number will be used to locate the address.
  • Secondary Address - This is information more specific than the building number. This can include suite numbers, unit numbers, and residential apartment numbers. It could also refer to a private mailbox (PMB) at a Commercial Mail Receiving Agency (CMRA).
  • SOA™ Form - Statement of Accuracy Form. This is generated when you enable SOA™ processing on your process and will be required by Canada Post.
  • Standard Mail® - Also known as bulk mail. Must be less than 16 ounces and be at least 200 pieces or 50 pounds. It is cheaper than other USPS® mail types but ships slower, on a time available basis. Often mail pieces shipped this way will be advertising, flyers, catalogs, etc.
  • Suite - A sub identifier for the specific location of an address within a building. This can be part of the secondary address.
  • Urbanization - An area, sector, or residential development within a geographic area. In Puerto Rico, identical street names and address number ranges can be found within the same ZIP Code. In these cases, the urbanization name is the only element that correctly identifies the location of a particular address. Generally, the abbreviation URB is placed before the urbanization name.
  • USPS® - United States Postal Service®. The USPS® is an independent agency of the executive branch of the United States federal government responsible for providing postal service in the United States, including its insular areas and associated states.
  • ZIP Code™ - Zone Improvement Plan Code. ZIP Code™s designate delivery routes and areas. There are three main parts of the 5-digit ZIP Code™—the national area, the region or city, and the delivery area.
  • ZIP+4® - In 1983 the USPS® changed its ZIP Code™ system to include the new ZIP+4®. A ZIP+4® Code uses the basic five-digit code plus four additional digits to identify a small delivery segment such as a street, a city block, a group of apartments, or even an individual address that receives a high volume of mail. The ZIP+4® Code is not required and is usually calculated automatically when the mail is sorted and processed.

Appendix

Intro to Addresses

If you're new to mailing, use this section to understand addresses and address parts in USA and Canada. This intro is for use with the AddressCheck Interface.

There are quite a few parts to an address! Here we'll break it down for you and explain what's going on. Buckle up!

US Addresses

Basic Address

You're probably familiar with the address format and components below, since they're present in most addresses.

Take the address below as an example:

1500 E MAIN AVE STE 201
SPRINGFIELD VA
22162-1010
Example Component Name How would I set this input in Address Object?
1500 Address Range SetParsedAddressRange
E PreDirection* SetParsedPreDirection*
MAIN Street Name SetParsedStreetName
AVE Suffix SetParsedSuffix
STE Suite Name SetParsedSuiteName
201 Suite Suffix SetParsedSuiteRange
SPRINGFIELD City SetCity
VA State SetState
22162 Zip Code SetZip
-1010 Zip+4 SetPlus4

*An address could also have a PostDirection after the suffix, which would be handled similarly.

PO Box

You can verify a PO Box or PMB as well! Not sure what those are? Check out the glossary for definitions!

Example Component Name How would I set this input in Address Object?
PO BOX 1234 Address Line 1 or Street Address SetAddress
SPRINGFIELD NY 12345 City, State, Zip Code, Zip+4 SetCity, SetState, SetZip, SetPlus4

Puerto Rico - Urbanization

Did you know some Puerto Rican addresses can have the same street address and city as another Puerto Rican Address in the same Zip Code™? To cut through the confusion, the USPS® has an an extra element, called an Urbanization. An address with an urbanization is often preceded by "URB" and lists the urbanization name.to identify locations with identical street names and address ranges found within the same ZIP Code™.

Example Component Name How would I set this input in Address Object?
URB ROYAL OAKS Urbanization SetUrbanization
123 CALLE 1 Address Line 1 or Street Address SetAddress
SAN JUAN PR 12345-6789 City, State, Zip Code, Zip+4 SetCity, SetState, SetZip, SetPlus4

Canadian Addresses

Canadian addresses have pretty similar components to US addresses - switch out a state for a province and you've pretty much got it down! However, there are a couple of different components, that we will go over in more detail here.

Delivery Installation and Lock Boxes

Canada has two different types of addresses: Civic and Postal Installation.

Civic address types are like the basic US address that you might be familiar with (if not, check out the previous section). While Postal Installation addresses consist of a description of the type of delivery, the Canada Post delivery installation name, the municipality name, the province code and postal code. We'll go into more detail about Postal Installation addresses now.

There are three types of Postal Installation addresses:

  • Lock box address*
  • General delivery address
  • Route service address

The Delivery Installation is generally preceded by an abbreviation such as STN, RPO, or LCD.

*In Canada, a Lock Box is the equivalent of a US PO Box (and it sometimes still called a PO Box or Postal Box).

Lock Box Address
Example Component Name How would I set this input in Address Object?
PO BOX 1234 STN 1 AddressLine 1 or Street Address. Delivery Installation ("STN 1") SetParsedLockBox, SetParsedDeliveryInstallation
VICTORIA BC V8P 5L4 City, State, Zip Code* SetCity, SetState, SetZip, SetPlus4

*In Canada, the Zip Code™ equivalent is called a Postal Code, but you will still use the "Zip" methods, so we will continue to refer to it as a zip code.

General Delivery Installation

A General Delivery Address will just have "GD" in one line, and the city, state, and zip code in the last line.

Example Component Name How would I set this input in Address Object?
GD Delivery Installation SetParsedDeliveryInstallation
VICTORIA BC V8P 5L4 City, State, Zip Code SetCity, SetState, SetZip, SetPlus4
Route Service

Route Service addresses are often in rural areas with no street address. To make up for this, these addresses will often use a rural route identifier (preceded by "RR").

An address with a Route Service component can include a few different elements:

  • Civic Address - A normal address. See the first row below.
  • Rural Route Number - This can be the only street data element when combined with the city, state, and zip. See the second row below.
  • Delivery Installation - The third type of address, see the section above.
Example Component Name How would I set this input in Address Object?
123 CEDAR ST Address Line 1 or Street Address SetAddress
RR 4 Route Service (also called rural route identifier) SetParsedRouteService, or as part of SetAddress
VICTORIA BC V8P 5L4 City, State, Zip Code SetCity, SetState, SetZip
!> USPS® Standard Abbreviations

These are a few common USPS® standard abbreviations. For a full list of these abbreviations, see the USPS® web site.

Primary Name USPS® Standard
AVENUE AVE
BOULEVARD BLVD
BRIDGE BRG
CIRCLE CIR
COURT CT
CROSSING XING
CROSSROAD XRD
DRIVE DR
EXPRESSWAY EXPY
FREEWAY FWY
HIGHWAY HWY
JUNCTION JCT
LANE LN
MOTORWAY MTWY
MOUNT MT
PARKWAY PKWY
ROAD RD
ROUTE RTE
STREET ST
TRAIL TRL
VILLAGE VLG
!> USPS Directional Abbreviations
Primary Name USPS Standard
North N
Northeast NE
East E
Southeast SE
South S
Southwest SW
West W
Northwest NW

Extra Postal Methods

Get CASS™ Form 3553 Methods

These methods retrieve CASS™ Form 3553 and return the information used to populate the form.

  • GetPS3553_B6_TotalRecords
  • GetPS3553_C1a_4Coded
  • GetPS3553_C1d_FiveDigitCoded
  • GetPS3553_C1e_CRRTCoded
  • GetPS3553_C1f_eLOTAssigned
  • GetPS3553_E_EWSCount
  • GetPS3553_E_HighRiseDefault
  • GetPS3553_E_HighRiseExact
  • GetPS3553_E_LACSCount
  • GetPS3553_E_RuralRouteDefault
  • GetPS3553_E_RuralRouteExact
  • GetPS3553_X_SuiteLinkCodeACount

SOA™ Get Methods

These methods return details on the SOA™ processing of your Canadian addresses.

  • GetSOAAAExpiryDate
  • GetSOAErrorString
  • GetSOASoftwareInfo
  • GetSOATotalRecords
GetSOAAAPercentage

This returns the percentage of accurate Canadian records processed since either ResetFormSOA was called or the current instance of Address Object was created.

Deprecated AddressCheck Methods

These methods have been deprecated and you should not use them. We are keeping them here just so you know what's up. But don't use them. You've been warned.

Verification Status Methods

The following methods have all been deprecated in favor of using GetResults to simplify the address verification process.

  • GetStatusCode
  • GetErrorCode
  • GetErrorString
  • GetDPVFootnotes
  • GetSuiteStatus

Deprecated Outputs

These are additional outputs available in the object that are either deprecated or not frequently used. They return information about the level and types of data matches found after calling VerifyAddress. They aren't really needed anymore, but are here for backwards compatibility.

  • GetEWSCount
  • GetEWSFlag
  • GetLACS
  • GetCMRA
  • GetLACSLinkIndicator
  • GetLACSLinkReturnCode
  • GetSuiteLinkReturnCode
  • GetELotNumber
  • GetELotOrder

Statistical Area Methods

The Metropolitan Statistical Area (MSA) and Primary Metropolitan Statistical Area (PMSA) information is no longer updated, so the following methods are deprecated.

These methods are also deprecated for the ZipData Interface.

  • GetMSA
  • GetPMSA

CASS™ Methods

The following methods were deprecated because their respective fields were removed from the CASS™ form.

  • GetPS3553_C1c_DPBCAssigned
  • GetPS3553_E_DPVCount

Deprecated StreetData Methods

IsAddressInRange

This method was deprecated because it did not consider whether the address range to be tested contained odd, even, or both types of numbers. It has been superceded with IsAddressInRange2.