Data licensing & provenance

The code licensing pages cover the engine: AGPL or commercial. This page covers the data, where Mailwoman's gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. comes from, the license each source carries, and the one boundary that needs your 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. before you ship anything OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names.-derived.

In short: the core gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. is built entirely from permissive sources, so a resolved coordinate carries no copyleft. One optional precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. (OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data.) is share-alike, and it is walled off from the core so its obligations never leak into the default product.

Legal sign-off: ☐ not cleared (as of 2026-06-30)

The OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. is built but not enabled in any published artifact — not on npm, not on R2, not in the demo. Turning it on is gated on counsel reviewing the questions below. When that review lands, flip this to ☑ cleared, name the reviewing counsel, and date it.

Where the data comes from

Every source below is recorded with its license at the point it enters the 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.. The authoritative catalog is address-data-sources.mdx; the legal notices ship as THIRD_PARTY_NOTICES.md in the source distribution, and each built data artifact carries its own ATTRIBUTION.json recording source, release, and license at build time.

Source	License	Obligation	Role in Mailwoman
Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. (WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.)	CC0	none (public domain)	the gazetteer anchorgazetteer anchorAn input-layer feature channel that attaches a per-token candidate-tag set from the gazetteer/codex (e.g. 'this surface is a known country-and-region') so the model conditions on lexicon membership without being overruled by it. The knowledge lives outside the weights — extend the gazetteer, no retrain. — every place keeps its WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. id
US Census TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data.	Public Domain	none	US streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. + the situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. base
Overture	CDLA-Permissive-2.0	attribution	US address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade.; coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. centroids
OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries.	per-source, varies	per-source attribution / share-alike	US gap statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. (e.g. Hawaii); cross-checked centroids
GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps.	CC-BY 4.0	attribution	the village-level + bilingual alt-name coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. fold
France BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure.	Licence Ouverte 2.0	attribution (we elect this over its dual ODbL)	FR rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. + streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. tierstierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. (26M address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade.) and the FR streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. 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. 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.
OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names.	ODbL	attribution + share-alike	optional non-US rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. — quarantined (below)
libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. dictionaries	MIT	attribution	bundled normalization data (core/data/)
libaddressinput	Apache-2.0	attribution	bundled format rules (core/data/)

The deliberate design choice is in the first row: WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. is the anchor and the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. key, and supplemental data attaches as attributes on WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.-keyed entities, never as imported foreign-id records. That keeps the permissive license of the core intact even as coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. grows.

The ODbL boundary

OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. is licensed under the ODbL, which is share-alike on a Derivative Database but draws a line at what it calls a Produced Work. That line is the whole game for a geocoder, so it's worth stating precisely:

• A Derivative Database is a database built from ODbL data; for Mailwoman, that's the OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (address-points-<cc>-<slug>.db). Redistributing one carries the full ODbL obligation: attribution, share-alike, and keeping it open.
• A Produced Work is something algorithmically derived from the database that is not itself a database — a rendered map, a report, or (the case that matters here) a single resolved coordinate handed back from a lookup. ODbL does not impose share-alike on a Produced Work; it asks only for attribution.

So the working position, the one counsel needs to confirm, is that serving a resolved coordinate is a Produced Work (attribution, no copyleft), while distributing the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. itself is a Derivative Database (full ODbL). The architecture is built around that distinction holding.

How the boundary is enforced

The quarantine is structural, not a runtime flag you could forget to set. Four mechanisms keep ODbL data from reaching the permissive core:

1. Per-row provenance. Every address point carries a source string (address-point-schema.ts:41). OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. points are stamped openstreetmap:<cc> (build-rooftop-shard.ts:88); permissive points are overture:* or openaddresses. License is attributable down to the row.

2. The core never folds an OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. byte. OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. points live in their own shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. beside the WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.-keyed gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture., never merged into it. The @mailwoman/osm workspace is code only, so it contains no OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. data and depending on it carries no obligation.

3. The tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. is dark by default. The cascade reaches the OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. only through an optional injected dependency (osmShards? in geocode-core.ts:86), consulted only for a non-US 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. with no US situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. match. The default product never injects it, so the tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. does not exist unless a caller deliberately wires it in.

4. The 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. refuses share-alike. 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 is filtered through SHARE_ALIKE_PATTERN (--exclude-share-alike), so no ODbL row can land in a proprietary weightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. build. Where a source is dual-licensed (France BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure.), we elect the permissive option.

Attribution: required, and not yet wired

ODbL requires attribution wherever the data is used. For Mailwoman that means "© OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. contributors" with an ODbL link, on:

• any geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. result that resolved through an OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., and
• the distribution of any shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. itself (a LICENSE + attribution file alongside the .db).

Three gaps stand between today and that being true. They are prerequisites for enabling the tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous., not afterthoughts:

• The Nominatim-compatible licence string (nominatim/index.ts:307) credits WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations., Overture, OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries., and TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. — it omits OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names.. It needs an ODbL clause that appears whenever an OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names.-sourced result is returned.
• The public GeocodeResult (geocode-core.ts) has no field to carry per-result attribution — the source reaches the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. node metadata but is dropped before the result is returned. Surfacing ODbL attribution per result requires adding that field first.
• THIRD_PARTY_NOTICES.md credits OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. only as reaching us via WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. and Overture (development-time). When first-party OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. ship, it needs a new entry for the @mailwoman/osm distribution. We hold that edit until the shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. actually ship — adding it sooner would document a distribution that isn't happening.

(The note in osm/README.md that "the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. surfaces © OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. contributors on any result that resolved through one" describes the target stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., not the current one. The source tag rides as far as the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. node; it is not yet emitted to a user.)

What counsel needs to confirm

The sign-off gate is these questions:

1. Produced Work vs Derivative Database. Does serving a single resolved coordinate from an OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. constitute a Produced Work (attribution only), as assumed above — or a Derivative Database hand-off (share-alike)? This determines whether API consumers inherit any obligation.
2. The opt-in-per-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. distribution. Each shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. is a separately-downloaded, per-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. artifact, and the downloader takes the share-alike obligation only on the countries they pull. Does that distribution 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.' satisfy ODbL, and what attribution + license file must ship beside each .db?
3. The attribution surface. Is "© OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. contributors (ODbL)" on the result and in the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. distribution sufficient, and where exactly must it appear (per-result, per-session, in the docs)?

When these are answered, build the three attribution prerequisites above, flip the sign-off banner, and the tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. can ship. Until then, the build and the local benchmark are fine to run; publishing is blocked.

See also

• osm/README.md — the OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. package, the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. builder, the boundary in package terms.
• address-data-sources.mdx — the full source catalog + the licensing gradientgradientThe direction and rate at which the loss would change if each parameter were nudged. Training follows the gradient downhill to reduce error. Huge gradients are tamed by gradient clipping..
• THIRD_PARTY_NOTICES.md — the formal notices shipped with the package.
• Open-source license · Commercial license — the engine's terms.