---
title: City/state/county lookup by ZIP
summary: Converts a ZIP code into one or more city/state/county rows by parsing a fixed-width vendor response.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Services.CleanAddress
reference_type: package
operation_id: OP-CA-04
trigger: Caller invokes clsCleanAddress.FindCityStateInfoByZip(inZIP)
---

# City/state/county lookup by ZIP

This operation resolves a ZIP code to the city, state, and county combinations the vendor recognizes for it. Because the vendor returns results as one long fixed-width text buffer rather than a structured collection, the operation preallocates that buffer, calls the vendor, and parses each fixed-width row into a typed result object.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CA-04 |
| **Trigger** | Caller invokes `clsCleanAddress.FindCityStateInfoByZip(inZIP)` |
| **Inputs** | `inZIP` — ZIP code to look up |
| **Outputs** | `List(Of clsCityStateCountyInfo)` — one entry per matched city/state/county row |
| **Primary components** | `clsCleanAddress.FindCityStateInfoByZip`, `clsCityStateCountyInfo`, `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. Preallocate a 50-row by 55-character output buffer (a 2,750-character space-filled string) to receive the vendor's fixed-width response.
3. Normalize `inZIP` to a 5-character value by padding with spaces and taking the first 5 characters; this normalized value is computed but not passed to the vendor call, which instead receives the original `inZIP` argument.*
4. Call `FindCityStateInfoByZip(inZIP, ByRef outResultsCount, ByRef outResults)` on the proxy.
5. For each of the `outResultsCount` rows returned:
   - Parse characters 1–28 of the 55-character row as `City` (trimmed).
   - Parse characters 29–30 as `State`.
   - Parse characters 31–55 as `County` (trimmed).
   - Add the populated `clsCityStateCountyInfo` to the result list.
6. Return the populated result list to the caller.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller invokes FindCityStateInfoByZip<br>with inZIP]) --> Proxy[Create clsCAServices proxy]
	Proxy --> Buffer[Preallocate 50x55<br>character output buffer]
	Buffer --> Call[Call vendor FindCityStateInfoByZip<br>ByRef outResultsCount, outResults]
	Call --> Loop{More rows to parse?}
	Loop -->|Yes| Parse[Parse 55-char row into<br>City, State, County]
	Parse --> Add[Add clsCityStateCountyInfo<br>to result list]
	Add --> Loop
	Loop -->|No| Return([Return result list])
```

## Failure and edge-case behavior

- The vendor call is not wrapped in a `Try/Catch`; a SOAP fault or transport error propagates to the caller unhandled, unlike [Address cleanse](address-cleanse.md).*
- Parsing depends entirely on the vendor returning exactly 55 characters per row up to `outResultsCount`; a mismatched row width would corrupt or truncate the parsed `City`, `State`, and `County` values with no validation in place.**
- If `outResultsCount` exceeds 50, the parser reads past the preallocated buffer size assumption; behavior in that case depends on how much data the vendor actually wrote into `outResults`.**
- A ZIP code with no matches is expected to return `outResultsCount = 0` and an empty list, though this is not explicitly tested in the source.*

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `Services\SAIF.Services.CleanAddress\clsCleanAddress.vb`
- `Services\SAIF.Services.CleanAddress\clsCityStateCountyInfo.vb`
- `Services\SAIF.Services.CleanAddress\Web References\CleanAddressSvc\Reference.vb`