Handle PO boxes and other edge kinds

Outcome. You can tell from a parse what shape of input you received, and you know which shapes produce a usable coordinate.

Some location strings are not street addresses. Stage 2.5 of the pipeline sorts the input into one of eight kinds before the model runs, and every result includes the kind. A kind check costs less than finding the same problem from a coordinate in the wrong hemisphere.

Prerequisites

A working parse, as in Install Mailwoman and parse your first address.
A candidate gazetteer at <data root>/db/wof/candidate.db for the geocode transcripts. Every transcript below finds it at that path, so you do not need to export a variable.
Read everything a parse returns introduces the --debug output this page reads.

1. Read the kind

--debug includes the classifier's chosen kind, its confidence and the alternatives it considered:

mailwoman parse --debug "PO Box 1234, San Francisco, CA 94119" | jq -c '{path, kind}'

{
	"path": "full",
	"kind": {
		"kind": "po_box",
		"confidence": 0.95,
		"alternatives": [
			{ "kind": "structured_address", "confidence": 0.9 },
			{ "kind": "vague", "confidence": 0.3 }
		]
	}
}

There are eight kinds, and the classifier always returns the whole ranked list instead of one answer:

Kind	What it means
`structured_address`	A conventional postal address, several segments
`postcode_only`	A postcode and little else
`locality_only`	A short place name and no other part
`po_box`	A post office box or its regional equivalent
`intersection`	Two streets joined by `and`, `&`, `@` or `at`
`landmark`	A venue name, or a relative description like `behind the gas station`
`poi_query`	A category or brand plus a spatial anchor, when a POI lexicon is wired
`vague`	The floor, always present in `alternatives` at 0.3

The top kind is a suggestion, and the pipeline does not enforce it. vague at 0.3 is always present, so read the second entry in alternatives for the meaningful runner-up.

2. PO boxes: they parse, they do not resolve to the box

mailwoman parse "PO Box 1234, San Francisco, CA 94119"

{
	"region": "CA",
	"locality": "San Francisco",
	"po_box": "PO Box 1234",
	"postcode": "94119"
}

The whole phrase, including the leader and the number, is one po_box component. The regional forms follow the same convention: BP in France, Apartado in Spain, GPO Box and Locked Bag in Australia. The tag never nests under street. It sits beside the locality.

There is no PO box resolver, and a resolver would not be useful. A box is a slot in a post office, so every box at that office would share one coordinate. A geocode of a PO box therefore resolves whatever else is in the string:

mailwoman geocode "PO Box 1234, San Francisco, CA" | jq -c '{lat, lon, resolution_tier, locality}'

{
	"lat": 37.759715,
	"lon": -122.693976,
	"resolution_tier": "admin",
	"epistemic_status": "observed",
	"locality": "San Francisco"
}

The result is San Francisco's centroid at the admin tier. That tier is the most precise one the string can support. Treat resolution_tier: "admin" on a po_box parse as "the city is right, but the point is not a delivery point", and do not route a driver to it.

3. Intersections: two tags without a crossing point

mailwoman parse "5th and Main"

{
	"intersection_a": "5th",
	"intersection_b": "Main"
}

The parse returns one component per street, and the formatter joins them with an ampersand when it renders. There is no intersection resolver either, and no step computes where the two streets cross. The coordinate again comes from whatever place name is present:

mailwoman geocode "Corner of Broadway and 42nd Street, New York, NY" | jq -c '{lat, lon, resolution_tier, locality}'

{
	"lat": 40.694457,
	"lon": -73.93045,
	"resolution_tier": "admin",
	"epistemic_status": "observed",
	"locality": "New York"
}

The classifier assigns that same string a different kind:

mailwoman parse --debug "Corner of Broadway and 42nd Street, New York, NY" | jq -c '{kind: .kind.kind, confidence: .kind.confidence}'

{ "kind": "structured_address", "confidence": 0.9 }

The kind is structured_address, not intersection. The intersection rule always scores 0.85, and the structured-address rule scores 0.9 for any input with two or more segments. A city and a state therefore make structured_address rank higher. Without them, the same phrase classifies as an intersection:

mailwoman parse --debug "5th and Main" | jq -c '{kind: .kind.kind, confidence: .kind.confidence}'

{ "kind": "intersection", "confidence": 0.85 }

The components are correct either way. If you route on the kind, check alternatives as well as the top pick, because intersection appears there at 0.85.

4. Bare postcodes: resolvable, and ambiguous across countries

A bare postcode is the only edge kind that resolves to its own coordinate. When the shape is unambiguous, it can also take a fast path that skips the model:

mailwoman parse --debug "10118-1234" | jq -c '{path, kind: .kind.kind, confidence: .kind.confidence}'
mailwoman parse --debug "10118" | jq -c '{path, kind: .kind.kind, confidence: .kind.confidence}'

{"path":"fast-path","kind":"postcode_only","confidence":1}
{"path":"full","kind":"postcode_only","confidence":0.7}

The ZIP+4 shape matches one country's format, so confidence reaches 1 and the pipeline synthesizes a single postcode node without running the classifier. Bare 10118 matches the US, French and German shapes at once, so confidence is 0.7 and the full pipeline runs.

This ambiguity affects real results. Here are five bare postcodes geocoded without a country scope:

Input	Resolves to
`20500`	`43.066, -2.492` — Spain
`10001`	`54.910, 8.311` — Germany
`02139`	`38.604, -2.166` — Spain
`75001`	`48.844, 9.367` — Germany
`SW1A 1AA`	`51.501, -0.142` — United Kingdom

Four of the five are US postcodes that a US reader would expect, and none of them resolved to the US. The alphanumeric postcode resolved correctly, because its shape belongs to one country.

Scope a bare postcode by country. A country constraint fixes some of them:

mailwoman geocode --default-country US "10001" | jq -c '{lat, lon, postcode, countryCode}'

{ "lat": 40.750634, "lon": -73.997176, "postcode": "10001", "countryCode": "US" }

That coordinate is correctly in Manhattan. A country constraint does not fix every postcode:

mailwoman geocode --default-country US "20500" | jq -c '{lat, lon, postcode, countryCode}'

{ "lat": null, "lon": null, "postcode": "20500", "countryCode": null }

The result is null. The candidate gazetteer covers only part of the US postcode set, so scoping to the right country turns a wrong answer into no answer. A null is the better failure, because your code can check for a null but cannot detect a wrong Spanish coordinate. Plan for it: a bare US ZIP Code is not a reliable geocoding input on its own, and adding a city makes it reliable.

5. Landmarks

mailwoman parse --debug "Empire State Building" | jq -c '{kind: .kind.kind, confidence: .kind.confidence}'
mailwoman parse "Empire State Building"

{"kind":"landmark","confidence":0.88}
{"locality":"Empire State Building"}

The kind is right, but the component is wrong. This configuration has no venue tier, so the name is tagged locality and matched against place names. That match finds some place with a similar name. Do not send venue names to the geocoder and expect a venue back. Use poi_query with a POI layer instead. Use annotations describes what the POI layer provides.

Verify

One command shows what shape of input you received and whether the pipeline skipped the model:

mailwoman parse --debug "$ADDRESS" | jq '{path, kind: .kind.kind, confidence: .kind.confidence, alternatives: [.kind.alternatives[] | .kind]}'

{
	"path": "full",
	"kind": "po_box",
	"confidence": 0.95,
	"alternatives": ["structured_address", "vague"]
}

Limits

The kind is mostly informational. It changes the pipeline in exactly three places. It can skip the model for a high-confidence postcode_only or locality_only, it routes a poi_query to the POI stage, and it selects the input register. Otherwise it is only reported on the result.
po_box and intersection switch the parser to the formatted register. That register turns off the gazetteer evidence channels for that parse. That setting suits record-shaped input and does not suit a search box. Override it with --input-mode fragmented if your users are typing.
Parse accuracy and geocode accuracy are separate numbers here. po_box scores 90.9 and intersection 100 on the labeling task in the shipped eval ledger. Neither number measures a coordinate, because neither kind has a resolver.
poi_query needs a lexicon. The default classifier includes the POI taxonomy, but the category must be one the taxonomy contains.

Read everything a parse returns — the rest of the --debug output.
Handle messy input — defects inside an address, as opposed to a different shape of input.
Validate an address before you use it — rejecting the ones that will not resolve, before they reach a geocoder.

Prerequisites​

1. Read the kind​

2. PO boxes: they parse, they do not resolve to the box​

3. Intersections: two tags without a crossing point​

4. Bare postcodes: resolvable, and ambiguous across countries​

5. Landmarks​

Verify​

Limits​

Related​