Skip to content

Address cleanse

Address cleanse is the library's primary operation. It submits a caller-supplied address to the CorrectAddress vendor service, tolerates vendor call failures by falling back to a sentinel return code, decodes the vendor's USPS error-code string into human-readable descriptions, classifies the result as cleaned, unmatched, or multiple matches, and derives a POSTNET barcode when the returned check digit supports it.

Field Value
Operation ID OP-CA-05
Trigger Caller invokes clsCleanAddress.CleanAddress(inLine1, inLine2, inCity, inState, inZip, inZip4, inMixedCase)
Inputs inLine1, inLine2, inCity, inState, inZip, inZip4, inMixedCase
Outputs clsCleanAddressInfo containing normalized address fields, USPS return code, error codes/descriptions, classification flags, and POSTNET barcode
Primary components clsCleanAddress.CleanAddress, clsCleanAddressInfo, CleanAddressSvc.clsCAServices
Entry point Services\SAIF.Services.CleanAddress\clsCleanAddress.vb

Steps

  1. Create a new CleanAddressSvc.clsCAServices proxy instance and set AllowAutoRedirect = True and UseDefaultCredentials = True.
  2. Call the vendor CleanAddress operation, passing the seven input parameters and receiving over twenty by-reference output fields (normalized address lines, county, USPS return code, USPS error codes, firm name, urbanization, DPC, check digit, carrier route, and related fields).
  3. On failure: if the SOAP call raises an exception (observed in production with malformed vendor XML), set outUSPSReturnCode = -999 instead of propagating the exception to the caller, per BR-003.
  4. Parse the vendor's concatenated outUSPSErrorCodes string into a list of two-character codes, and resolve each code to a fixed description using a hardcoded lookup table from the vendor's CorrectAddress user manual (version 9.0, page C-2).
  5. If code 11 is present, set the internal HaveCode11 flag used in step 4.
  6. If a code does not match a known entry, describe it as "<code> - Code description not available".
  7. Classify the address as cleaned according to BR-001: the address is cleaned when USPSReturnCode = 1, or when USPSReturnCode = -1 and error code 11 was not present.
  8. When the address is not cleaned, classify it as unmatched or multiple matches according to BR-002:
  9. If USPSReturnCode is -1, -99, or -999: set Unmatched = True.
  10. Otherwise: set MultipleMatches = True.
  11. Derive the POSTNET barcode according to BR-005:
  12. If the returned check digit is a single numeric character (0–9): concatenate the 5-digit ZIP, the 4-digit ZIP+4 extension (when present), the 2-character DPC (when present), and the check digit itself into the barcode string.
  13. Otherwise: leave the barcode empty.
  14. Return a new clsCleanAddressInfo populated with the normalized city, county, county code, address lines, state, ZIP, ZIP+4, the parsed USPS error codes and descriptions, the USPS return code, the derived POSTNET barcode, and the three classification flags (CleanedAddress, Unmatched, MultipleMatches).

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Caller invokes CleanAddress]) --> Proxy[Create clsCAServices proxy]
    Proxy --> Call[Call vendor CleanAddress]
    Call --> Exception{Exception raised?}
    Exception -->|Yes| Fallback[Set USPS return code to -999]
    Exception -->|No| Parse[Parse USPS error-code string<br>into codes and descriptions]
    Fallback --> Parse
    Parse --> Classify{Cleaned address?<br>code 1, or -1 without code 11}
    Classify -->|Yes| Cleaned[CleanedAddress = True]
    Classify -->|No| Sub{Code -1, -99, or -999?}
    Sub -->|Yes| Unmatched[Unmatched = True]
    Sub -->|No| Multiple[MultipleMatches = True]
    Cleaned --> Barcode{Check digit numeric?}
    Unmatched --> Barcode
    Multiple --> Barcode
    Barcode -->|Yes| Derive[Derive POSTNET barcode]
    Barcode -->|No| Empty[Leave barcode empty]
    Derive --> Return([Return clsCleanAddressInfo])
    Empty --> Return

Failure and edge-case behavior

  • CleanAddress() converts service-call exceptions into return code -999 and continues result classification instead of rethrowing, per BR-003.
  • -999 is treated as unmatched by BR-002, so a transport-level failure surfaces to the caller as a normal "unmatched" result rather than as an error.
  • The POSTNET barcode is left empty whenever the check digit is not a single numeric character, without raising an error.
  • USPS error codes not present in the hardcoded lookup table still produce a description ("<code> - Code description not available") rather than failing.
  • A commented-out block for reintroducing vendor-discarded "extraneous" address information into Line2/Line1 remains in source but is not executed.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • Services\SAIF.Services.CleanAddress\clsCleanAddress.vb
  • Services\SAIF.Services.CleanAddress\clsCleanAddressInfo.vb
  • Services\SAIF.Services.CleanAddress\Web References\CleanAddressSvc\Reference.vb