Component tags
Scope
A parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. labelscomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. spansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. of the input with component tagscomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.. This page lists all 25 tags in the union, gives each one a meaning and an example, and states which of them the shipped modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' can emit.
The tag union is defined in core/types/component.ts and its design record — why each tag exists and
why the boundaries fall where they do — lives in
SCHEMA.mdx.
This page derives from both. Where a tag is added or renamed, that happens there first.
Tags appear in three places a consumer touches: as tag on each node of an AddressTree, as the keys
of the flat object decodeAsJSON and /v1/parse produce, and as the label values a libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it.-shaped
response carries.
Universal
Every localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. uses these six.
| Tag | Meaning | Example |
|---|---|---|
country | Sovereign state, by name or code | France |
region | First-level administrative division | NY |
locality | CitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., town, or commune | Portland |
dependent_locality | Sub-localitydependent localityA sub-locality (neighborhood or borough) hierarchically inside a larger locality — e.g. Brooklyn within New York City. Provides finer geographic specification below the primary locality.: neighborhood, arrondissement, ward | Brooklyn |
postcode | Postal identifier | NW1 6XE |
subregion | County-level division between regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. and localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. | Multnomah County |
Street level
| Tag | Meaning | Example |
|---|---|---|
house_number | Building number on a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. | 221B |
street | The streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. name proper, without prefix or suffix | Baker |
street_prefix | Directional or descriptive prefix | SE |
street_prefix_particle | Grammatical particle inside a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. name | de la |
street_suffix | StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-type suffix | Street |
intersection_a | The first streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. of an intersectionintersectionAn address that names a location by two crossing streets ('5th & Main') rather than a number and street. Mailwoman tags the two streets as intersection_a and intersection_b — a negative-space format that starved the early model. query | 5th Ave |
intersection_b | The second streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. of an intersectionintersectionAn address that names a location by two crossing streets ('5th & Main') rather than a number and street. Mailwoman tags the two streets as intersection_a and intersection_b — a negative-space format that starved the early model. query | 42nd St |
unit | Apartment, suite, or floor | Suite 200 |
street carries the bare base spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree.. A renderer that wants the full streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. name joins
street_prefix, street, and street_suffix. geocodeAddress does that join for you and returns
the assembled name in its street field.
Venue level
| Tag | Meaning | Example |
|---|---|---|
venue | A named placevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label.: business, landmark, or park | Eiffel Tower |
attention | An attentionattentionThe core mechanism inside a transformer encoder. Each token's representation is updated by looking at every other token, with learned weights deciding how much each one matters. or care-of line | c/o Jane Doe |
po_box | A post office boxPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise. | PO Box 1234 |
Locale-specific
cedex is French. The seven tags below it are Japanese and belong to a separate modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. — see
What the shipped model emits.
| Tag | LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. | Meaning | Example |
|---|---|---|---|
cedex | FR | A special postal routing designation | CEDEX 08 |
prefecture | JP | First-level administrative division | 東京都 |
municipality | JP | CitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. or ward | 千代田区 |
district | JP | District | 丸の内 |
block | JP | ChōmechōmeIn Japanese addressing, a district-level subdivision in the block-based chōme / banchi / gō numbering scheme, which uses area-and-block numbers instead of street names. | 1丁目 |
sub_block | JP | BanchibanchiIn Japanese addressing, a block within a chōme. The middle level of the chōme / banchi / gō hierarchy. | 1番地 |
building_number | JP | GōgōIn Japanese addressing, a building or lot number within a banchi — the finest level of the chōme / banchi / gō block-based hierarchy. | 1号 |
building_name | JP | A named building, in Latin script or kana | Tokyo Building |
The Japanese tags labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. the long form written with kanji designatorsdesignatorThe closed-vocabulary leading word of a secondary-address phrase — 'Apt', 'Suite', 'Floor', 'PO Box', 'Level' — paired with an identifier to form a complete subpremise.. A compact Japanese number such
as 2-3-16 stays one house_number spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree..
BIO labels
The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' is a sequence labeler, so each tag becomes two per-tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. labelscomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.: B-<tag> for the first
tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. of a spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. and I-<tag> for each continuation. One further labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag., O, marks a tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. outside
every component.
The union of 25 tags therefore spansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. 51 possible labelscomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.. That is the schema's capacity, not any one modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.''s output alphabet.
What the shipped model emits
A modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.''s headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. is fixed at trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. time and carries the label setlabel setA model's BIO vocabulary, per-config since CJK Phase 2: stage3 (the Latin 33), stage3-jp (STAGE3 + the seven JP tags = 47, the JP char head), stage4 (the secondary-address family — numerically also 47, a coincidence). A checkpoint persists its own id→label map; label-space mismatches raise instead of collapsing silently. that trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. used. The count is
in the model cardmodel cardA JSON metadata file (model-card.json) shipped with each weights bundle. It declares the model version, lineage, label set, required inference channels (anchor, gazetteer), calibration data, and training provenance. as architecture.num_labels.
| Modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' | Labelscomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. | Tags | What it can emit |
|---|---|---|---|
The union in core/types/component.ts | 51 | 25 | Everything on this page. The schema's capacity |
| The shipped Latin modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' | 33 | 16 | The universal six, streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. level minus street_prefix_particle, venue, po_box, cedex |
| The Japanese character modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' | 47 | 23 | The Latin set plus the seven Japanese tags. Not shipped |
Nine tags are in the schema and outside the shipped Latin headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads.: street_prefix_particle, attention,
and the seven Japanese tags. A parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. from the shipped modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' never returns them. Reading them from a
response means you are running a different headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads., not that the input lacked them.
@mailwoman/neural-weights-en-us is the base modelgolden masterThe from-scratch base model every capability comes from in ONE recipe with one provenance and zero named watches at ship — the starting line every fine-tune engagement inherits, with its Fisher artifact beside it., and the fr-fr, en-gb, en-nz, de-de,
es-es, it-it and en-in packages overlay it with localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. data rather than replacing the encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters)..
All of them therefore share the same 33-labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads..
Errors
A tag is a closed set, so the failure modes are about absence rather than about invalid values.
| Condition | What it means | Next step |
|---|---|---|
| A tag you expected is missing from the response | The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' did not find that component, or its headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. cannot emit the tag | Check the tag against the shipped-modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' row above |
street looks truncated | street is the bare base spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. by design | Join street_prefix, street and street_suffix, or read geocodeAddress's assembled street |
| A Japanese tag never appears | The shipped Latin modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' has no Japanese labelscomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. | Japanese addresses resolve by postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.; there is no parser claim today |
| Two components share one spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. | This cannot happen. SpansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. are disjoint | If you observe it, report it with the input string |
Rationale
street_prefix and street_prefix_particle are separate tags because English SE and French de la
are grammatically different things, and a synthesis pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. that treats them alike produces worse
trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data. cedex is separate from postcode because a CEDEXCEDEX (Courrier d'Entreprise à Distribution Exceptionnelle). A French postal routing for high-volume business mail: a CEDEX code delivers directly from a sorting center, bypassing the local post office. A common negative-space format Mailwoman must parse. designation is a routing
instruction rather than a postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., and folding it into postcode corrupts French postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.
statistics.
The schema is deliberately wider than any shipped headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads.. A tag enters the union when the design work for it is settled, which is earlier than when a modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' trains on it — that ordering is what lets a corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. be labeled before the headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. that consumes it exists.
See also
- Library API — where tags appear in
AddressTreeanddecodeAsJSON. - HTTP APIs — where tags appear in a
/v1/parseresponse. - Locales and tiers — which localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. carry a measured claim.
- Understand a parse — tags on a real input, walked through.
SCHEMA.mdx— the design record and the change rule.