US-LEX-1
The Verify model. A purpose-built neural model, trained by Fieldgeist on real US addresses.
Fieldgeist is an AI lab building tools for real estate. Verify, its first tool, is built around US-LEX-1, a purpose-built neural model that Fieldgeist trains on real US addresses. The model reads a line of free text and decides what each part of it is: the house number, the street, the unit, the city. The parse endpoint is how you send it addresses today.
How it reads an address
Split
The line is split into words and punctuation, keeping what you typed.
Label
The model gives every word one of 19 labels taken from USPS Publication 28. It reads the whole line at once, so context decides each label: in 350 5th ave apt 21b, the words around 5th make it the street name rather than a house number, and 21b after apt is a unit number.
Assemble
The labeled words become components, standardized to Publication 28 abbreviations (ave becomes AVE) and rendered into delivery lines. This step follows fixed rules, so the same labels always produce the same address.
Score
confidence is the model's average certainty about the labels it gave. See Confidence and warnings.
The labels
Each label becomes a component in the parse response.
| Label | Component | Example |
|---|---|---|
| Address number | addressNumber | 350 |
| Address number suffix | addressNumberSuffix | 1/2 |
| Predirectional | predirectional | W |
| Street name | streetName | 5TH |
| Street suffix | streetSuffix | AVE |
| Postdirectional | postdirectional | NW |
| Occupancy type | occupancyType | APT |
| Occupancy ID | occupancyId | 21B |
| PO box type | poBoxType | PO BOX |
| PO box ID | poBoxId | 1234 |
| Rural route type | ruralRouteType | RR |
| Rural route ID | ruralRouteId | 2 BOX 15 |
| Firm | firm | A business name in the line |
| City | city | NEW YORK |
| State | state | NY |
| ZIP Code | zip5 | 10118 |
| ZIP+4 | zip4 | 0003 |
| Urbanization | urbanization | A Puerto Rico urbanization |
| Other | other | Words the model couldn't place |
Where it runs
The model runs at the edge, inside the request that asks for it. There is no separate model service or queue: every parse is read by the model before the response is sent.
When the model doesn't answer
If the model can't run, or its labels contradict each other, a rule-based parser answers instead, and the response says so: model names us-lex-rules with backend: "heuristic" and a warning (model_unavailable or model_output_invalid) gives the reason. The rule-based parser is less reliable on unusual lines, so treat its answers as you would a low confidence.
Versions
Every parse response names the model that read the line. In the API, US-LEX-1 is us-lex-1:
"model": { "name": "us-lex-1", "version": "0.1.0", "backend": "model" }Fieldgeist trains new versions of US-LEX-1 and releases them to the API. Each release is listed in the changelog, tagged Model. Responses keep the same fields from one version to the next; what can change is how a line is read. If you store parses, store model.version with them so you know which reading you have.
How the model improves
Fieldgeist retrains the model on new address data. Misreads found in evaluation are reviewed by people before each training round.
If Verify misreads an address, email support@fieldgeist.com with the request's x-request-id header (see Request IDs) and what you expected.
What the model doesn't do
- It doesn't correct spelling. It labels what you sent. Near-miss street names are handled by the lookup, which flags them with
fuzzy: true. - It doesn't check that an address exists. A well-formed address that doesn't exist can parse with high confidence. To match an address to a real parcel, use the lookup, which checks it against a parcel index Fieldgeist builds from public property records.