Pelias and libpostal

The question

These two get one page because they are frequently met together and are frequently confused with each other. One is a geocoder assembled from services; the other is a parser that several geocoders — including the first one — use as a component. Knowing which of them you are comparing against decides what the comparison is even about.

What Pelias is

PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. is an open-data geocoder built as a set of cooperating services. Its documentation, read on 2026-08-04, describes it as:

"A modular, open-source search engine for our world." … "PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. is a search engine for places worldwide, powered by open data. It turns addresses and place namestoponymA proper name for a geographic place. into geographic coordinates, and turns geographic coordinates into places and addresses."

— Pelias documentation

Its API exposes forward 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. (/v1/search), reverse 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. (/v1/reverse), autocomplete (/v1/autocomplete), structured 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. (/v1/search/structured) and a place endpoint (/v1/place). The store is Elasticsearch, and the modularity is the design commitment: the importers, the query parser, the 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. service and the API are separate piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). you can run, replace or skip.

That modularity is the thing to weigh. It means you can import only the data you want, swap a component, and reason about each stagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). on its own — properties a monolith does not give you. It also means the system you operate is several services rather than one, and the composition is yours.

What libpostal is

libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. is not a geocoder, and its own README is direct about it:

"libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. is a C library for parsingaddress 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./normalizing streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. addresses around the world using statistical NLP and open data."

— libpostal README, read 2026-08-04

Its non-goals name "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. addresses to a lat/lon (that requires a database/search index)", and it states plainly that "libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. is not itself a full geocoder". It exposes two functions: parse_address, which 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. an address into components with a conditional random fieldCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality., and expand_address, which normalizesnormalizeStage 1 of the runtime pipeline: deterministic input preprocessing (Unicode NFC, punctuation normalization, whitespace collapse). Returns a NormalizedInput with an offsetMap that maps normalized positions back to the raw input. a messy address into standardized forms for indexing. The README gives the default 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.' as about 1.8 GB, with an alternative Senzing 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.' at about 2.2 GB.

libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. is the labeling half of the design Mailwoman implements, and it is the reason that design is well understood in this field at all. A great deal of open 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. — PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. included — is built on top of it.

Where each one sits

	PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.	libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it.	Mailwoman
What it is	A geocoder, assembled from services	A parsingaddress 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. and normalizing library	A parser with a 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. behind it
Returns a coordinate	Yes	No, by design	Yes
Returns a decomposition	Through the query parser	Yes, this is the product	Yes
Store	Elasticsearch	None — 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.' files on disk	Sealed SQLite files, read from disk
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.'	Query parsingaddress 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., then ranked retrieval	A conditional random fieldCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality.	A neural sequence labeler with 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. evidence
Autocomplete	A first-class endpoint	Not applicable	Supported, and not the design center
Deployment	Several services	A C library and its modelsneural 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.'	An npm package; HTTP servers optional

The row that matters against libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. is the second one. If what you need is a coordinate, libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. is a component of your answer rather than the answer, and comparing it to a geocoder on coordinate quality is comparing two different jobs.

The row that matters against PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. is the fifth. Both systemsexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. 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., and they 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. for different purposes: PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. parsesaddress 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. to shape a query that a ranked retrieval then answers, and the index is still consulted over everything. Mailwoman parsesaddress 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. to decide which index to consult, and the lookup that follows is constrained by the decision. The two architectures works that difference through, including what it costs each design.

When to choose Pelias

• You want autocomplete as a primary surface. A ranked list arriving as you type is what the design produces by construction, and /v1/autocomplete is a supported endpoint rather than an adaptation.
• You want to compose your own geocoder. Import the sources you want, replace a component, run the 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. service or skip it. If your requirement is unusual enough that a fixed 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. will not fit it, modularity is the property to buy.
• You already operate Elasticsearch. The store is the operational 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., and a team running it well has paid most of the cost already.
• Your queries mix addresses and place namestoponymA proper name for a geographic place.. One ranked index over both is the design; a parser has to decide which kind of query it received before it can be useful.
• You want a self-hosted geocoder over open data, with a documented API. That is what it is, and it has been doing it for a long time.

When to choose libpostal

• You need parsingaddress 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. only, in C or with C bindings. It is the direct answer, it has bindings in a long list of languages, and it is battle-tested across the field.
• You want expand_address. Normalizing an address into every standardized form for indexing is a distinct capability, and it is what makes libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. the preprocessing step in a great deal of record matchingrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring..
• Your platform is one where a C library is easier to deploy than a Node package. Sometimes the deciding factor is the runtime you already have.

When to choose Mailwoman

• You need the 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. and the coordinate from one thing. libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. stops before the coordinate; this does both, and 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. walks the 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. it produced rather than a re-derived one.
• You want the resident footprint small. The reference data is read from disk rather than held in an index, and 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. is a set of downloads.
• You want per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. evidence. 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. is claimed where a coordinate-graded evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists, and the benchmarks publish the scripts.
• You are on Node and want no second runtime. The package installs and runs; 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 file.
• You have libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. clients already written. @mailwoman/libpostal serves /parse and /expand on a compatible surface.

Run it yourself

Against libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. the comparison is 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. comparison, and it does not need our scripts — run both over your own rows and diff the component 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.. Against PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. it is a geocode comparison, and the same advice as everywhere on these pages applies: look at how each one fails on your input rather than at how each one scores on ours.

curl -fsSLO https://mailwoman.sister.software/benchmarks/fr-ban-panel.mjs
curl -fsSLO https://mailwoman.sister.software/benchmarks/fr-ban-sample.json
mailwoman data pull candidate fr
node fr-ban-panel.mjs --data-root <DATA_ROOT>

The French panel is the one to read first for a parsingaddress 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. comparison: its failure table is four streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-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. truncationstruncationCutting an input down to the max sequence length (or an LLM response to its token limit), discarding everything past the cap. and two same-name streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. collisions, which is the shape a parser-driven geocoder fails in.

Related

• The two architectures — where PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. sits, and where a libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it.-driven 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. sits.
• Drop-in replacements — the libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it.-compatible endpoint.
• Component tags — the 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. vocabularyvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it. 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. returns here.
• Benchmarks — our published measurements.