USA CASS2 Engine

Our New CASS Engine

With the Loqate 2020Q2.0 release, the CASS2 engine has been made available. Loqate will target to replace the existing CASS engine for all customers over the next 12 months.

During the soft launch period, selected accounts will be contacted by their channel manager or technical account manager to discuss an evaluation of the new engine. Any other customers interested in testing the new engine should contact their channel manager.

Find documentation for the existing CASS engine here.

Platform Availability

CASS will continue to be available on Windows and Linux (32-bit and 64-bit). Depending on customer demand, versions for AIX and zLinux may be made available too. To reference the latest information about supported platforms, please always view the latest release notes.

Release Information:

As with the existing CASS engine, please run Install Manager to check for the latest version of CASS2 (both library and data).

Data will be updated on a monthly basis, and will be published with a 105 day expiration, as directed by the USPS.

CASS2 Installation

Your license key will determine whether the existing CASS engine or the new CASS V2.0 is available to download and install from Install Manager.

If CASS2 is available, the product names will be presented as “CASS2…”. It is unlikely for customers to have both CASS and CASS2 products, but it is possible. Customers wanting to evaluate old and new CASS engines side-by-side will be overseen by a member of the Professional Services team.

Important note for Windows users: Please ensure Loqate is installed outside of the Program Files folder. Even if you enable read/write permissions while inside Program Files, permissions issues may persist.

There are two methods to check if CASS2 is installed, as follows.

  1. Run the following code from the command line:
    lqtBatch.exe –d <data directory> (Windows)

    ./lqtBatch –d <data directory> (Linux)

     

     

    If CASS2 is active, your console will display the following (you may need to search for “CASS2” if the console output is very long):
    CASS API Expires: 2021-03-02

    CASS API Status: Active

    CASS Data Expires: 2021-03-02

    CASS Data Status: Active

    DataBase Date: 2020-03-15


    DataBase mdVersion: 3333

    Name: CASS2Info

  2. Open lqtDemo.exe (Windows only), click on the tab labelled “GKR”, click “Browse” and select your Loqate Data folder. When the file drop-down has populated, scroll through the list and select “CASS2Info”. The expiry date will be on the output.

Updating CASS2

As with the previous CASS engine, when you get to the certified data pack selection screen in Install Manager you will need to select both the library and USA Verify Datasets for CASS2.

Running CASS2 From the Command Line

The same parameters and requests are used in both older and new CASS engines. To use lqtBatch with CASS, pass “cass” as the parameter for the -p option, for example:

lqtBatch … -p cass2

More information about how to use the command line can be found here.

Sample command line script (Windows):

lqtBatch.exe -d <data directory> -p cass2 -r PS3553 -i <input file> -o <output file> -oh -fs off -oi -of DPVConfirmedIndicator|DPVFootnotes|ResultsString|PrimaryAddressLine|SecondaryAddressLine|DeliveryAddress|DeliveryAddress1|DeliveryAddress2|DeliveryAddress3|SubBuilding|Premise|Thoroughfare|BoxType|BoxNumber|PrivateMailbox|Locality|DependentLocality|SubAdministrativeArea|AdministrativeArea|PostalCode|PostalCodePrimary|PostalCodeSecondary|AutoZoneIndicator|Finance|CarrierRoute|CMRAIndicator|CongressionalDistrict|DefaultFlag|DeliveryPointBarCode|eLOTCode|eLOTNumber|EWSFlag|FalsePositiveIndicator|FIPSCountyCode|LACSLinkCode|LACSLinkIndicator|LACSStatus|NoStatIndicator|RecordType|ResidentialDelivery|SUITELinkFootnote|VacantIndicator|Organization|ReturnCode|ParsedGarbage"

Other Ways to Run CASS2

CASS processing is also available through the lqtDemo.exe application (Windows only), and via any of the supported Loqate APIs. Please note both the demo GUI and the APIs run processes per record, so it will not be possible to generate PS Form 3553.

To request CASS through one of the APIs, please set the process to Verify, and set the CertifiedCountryList server option to “USA”.

For Windows users, please ensure to load the respective DLL from the CASS folder where Loqate is installed. With the 2020Q2.0 release, the DLL is found in  \\[Loqate directory]\\LIBCUSA2WIN64\\mdAddr.dll.

The release notes will always provide the name and location of this dependency.

Input Record Requirements

CASS2 input is a little stricter in how to enter an address. We recommend the following:

  • Sub-building, Premise, Thoroughfare and any other delivery point information should be completed in Address1 and optionally Address2.
  • Locality, Administrative Area, and ZIP should either be entered into their respective component fields, or together in Address3 (not Address2).

For example, the address 1737 N 1st St #590, San Jose, CA 95112, may be entered in one of the following recommended ways:

Address1: 1737 N 1st St #590
Address3: San Jose, CA 95112

– OR –

Address1: 1737 N 1st St
Address2: #590
Address3: San Jose, CA 95112

– OR –

Address1: 1737 N 1st St #590
Locality: San Jose
AdministrativeArea: CA
PostalCode: 95112

 As with all address verification functionality, the process will be more successful when the input data is consistent, correct, and complete.

False Positive Address Detection

In order to detect conditions where the inputs submitted to the Loqate engine appear to be the result of artificial manufacture, and not legitimately obtained addresses, a set of artificially-manufactured reference addresses are included within the USPS data. 

An input which provides one of these “false addresses” will trigger the false positive handling.
When false positive handling is triggered,   the address that hit the trigger and all subsequent address will return the special code AS18 in the ResultsString output field and all subsequent addresses will no longer DPV verify.

Please contact Loqate technical support if this happens.

Some details from the trigger record that was detected are written to a false positive file and you may be asked to provide this file by technical support.

By default, this file is created in the same directory as the CASS2 datafiles. 

The false positive file will have a name that begins “DPVFALSE” followed by a series of numbers (e.g. DPVFALSE2021051210031 ),  which are:

The year in four digits
The month in two digits
The day in two digits
The hour in two digits
The minute in two digits
A final digit which is used to make the file unique across multiple threads.

You can control the directory where the False Positive file is created by adding a Server Option of CassFalsePosDir=’path_to_use’ . For example, CassFalsePosDir=’C:
temp’ or CassFalsePosDir=’/opt/temp’. 

PS Form 3553 Generation

To request the PS Form 3553 report file, add the following parameter to the batch command script.
-r PS3553

End users (mailers) will send PS Form 3553 to USPS along with the mailing list to receive a discount. The batch process will create a file named “PS3553_report.txt”.

Under section A1 on the PS3553 form, the Certified Company Name should be entered as LOQATE, and the CASS Certified Software Name & Version should be LOQATE ENGINE [version number] (e.g. 20.15.00.N).

Output Fields

A CASS2 processed record will match the existing output structure of the previous CASS engine, with a few exceptions described below. An output record will contain the following:

  1. All standard primary Verify fields, with the following exceptions and changes:
    • AVC and AQI fields will be populated by a default value “Z00-Z00-Z0-000” and “Z” respectively. Instead, customers should use the CASS output fields to determine the quality and accuracy of processed record.
    • PostBoxType and PostBoxNumber will not be populated or used. The respective values will be mapped to Thoroughfare and Premise.
  2. All existing CASS fields, with the following exceptions and changes:
    • ResultsString is a new field that provides infromation about the process and output address. View all possible values for this field.
    • The ResidentialDelivery field will no longer be serving the value from the USPS RDI product. Instead, Loqate will source this value from another source, which is updated by multiple signals on a more frequent basis.
    • Footnotes will not longer be returned. Typically, this field is representative of ResultsString, DPVConfirmedIndicator, and DPVFootnotes, and customers are encouraged to use these fields instead.
    • ReturnCode can now be empty.
    • PMBNumber and PMBType values will be appended to the PrimaryAddressLine and SecondaryAddressLine fields.
    • A new ParsedGarbage field will capture information that the CASS2 engine is able to parse out during the matching process.
    • FIPSCountyCode will be prefixed with the numeric state code. For example, the value for San Francisco, CA will change from 075 to 06075.

Other processing changes or notable behaviors include:

  • Thoroughfare names that may have abbreviations will almost always be returned in the longer format.
  • USPS supports both long and short names for Locality. By default, the CASS2 engine will return long names for Locality. The CassCityAbbreviation server option can be used to return the abbreviated versions of Locality names that are over 13 characters in length.

New Server Options

  • CassAvcEnable = Yes|No (Default: No)
    The default will Z00-00-00-000 (AVC) and Z (AQI), but computing the report values can be forced. Please note that if returned, these fields may not accurately reflect the changes made in the record during the CASS process.
  • CassUrbFirst = Yes|No (Default: No)
    This specifies the Urbanization location on the address lines output (Puerto Rico only). The default will put the value after the address lines(s) with premise, thoroughfare, and sub-building.
  • CassZipFields = Yes|No (Default: No)
    Populate “Finance” and “AutoZoneIndicator”. If these fields are desired, customers will expereince a moderate performance degradation (up to 20%).
  • CassCityAbbreviation = Yes|No (Default: No)
    If a Locality name is longer than 13 characters, this option can be used to return the official, short version. Both short and long versions are valid according to CASS.
  • CassFalsePosDir=’path_to_use’ 
    Allows you to control the directory where the False Positive file is created. For example: CassFalsePosDir=’C:temp’ or CassFalsePosDir=’/opt/temp’. 

 

More Information & Support

Please contact your channel manager or technical account maanger for any questions regarding the installation and evaluation of the new CASS2 product.