Core pack
Addresses CSV import API
Normalize messy postal addresses from CSV into a canonical line1/city/region/country shape with optional lat/lng.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=addresses_v1" \
-F "file=@your_data.csv"Canonical columns
The whole schema, printed as it ships.
Every canonical column, the type each row carries, whether it is required, the field-level validators that fire on commit, and the multilingual header hints the cascade resolves against. This is the shipped definition, not a summary of it.
addresses_v1- fields
- 9
- required
- 3
- validated
- 0
- hints
- 18
| Canonical column | Type | Required | Validators | Header hints the cascade matches |
|---|---|---|---|---|
id | string | — | — | matched on the column name |
line1 | string | yes | — | strasseruecalleviastreet |
line2 | string | — | — | matched on the column name |
city | string | yes | — | stadtvilleciudadcittà |
postal_code | string | — | — | plzcpcapzippostal code |
region | string | — | — | kantonrégionregiónstate |
country | string | yes | — | matched on the column name |
latitude | number | — | — | matched on the column name |
longitude | number | — | — | matched on the column name |
Read the same definition as JSON at GET /v1/templates/addresses_v1. A hint match resolves on layer 2 — no LLM call, no token spend, just the flat per-map fee. Hover a validator id to see what it checks.
- 9 canonical fields
- 3 required
- 0 validated
- 18 header hints, 5 languages
Why it exists
Written for the file you actually receive.
The Addresses template captures physical addresses in a shape that survives the trip from a German "Strasse" column, a French "rue" column, an Italian "via" column, and an Anglophone "street" column landing all in the same line1. It is the schema for an e-commerce shipping export, a CRM contact migration, an asset-management facility list, or a clinic site directory. Nine fields: id (optional — sometimes addresses are anonymous), line1 (the street), line2 (apartment / floor), city, postal_code, region (canton in CH, state in US, région in FR), country, latitude, longitude. The Addresses template does not attempt to validate addresses against a postal service; that is the job of a downstream geocoder. What it does is make sure every row has the parts in the right buckets so the geocoder has a clean input.
Postal-code hints cover PLZ (DE), CP (FR), CAP (IT), ZIP (US). Region hints cover Kanton, état, regione, state. Country is required because everything downstream branches on it — the validator does not enforce ISO-3166 because customer files use names ("Switzerland") as often as codes ("CH"); a downstream normaliser handles that.
Migration scenarios & the foreign headers they ship
Migration scenarios for the Addresses template: warehouse setup that ingests a fulfilment vendor's shipping list, CRM contact migrations where billing and shipping addresses are split across columns, asset-management imports of facility addresses across countries, and clinical-site directory imports for multi-site studies. Foreign headers we see daily: "Strasse / Hausnummer / Rue / Voie / Calle / Via / Stadt / Ville / Ciudad / Città / PLZ / CP / CAP / ZIP Code / Land / Pays / País / Paese / Region / Kanton / Région / Provincia / State". The cascade resolves all of these into the canonical line1 / city / postal_code / region / country buckets without escalating to the LLM — multilingual address vocabulary is where the heuristic layer earns its keep.
The cascade
Five layers, and the cheapest one wins.
Layers run in order and stop the moment a column resolves. That is the single biggest cost lever in the system: a column caught on layer 2 never reaches the metered layer 5.
- L1Statisticsno LLM
Auto-accepts a header that past confirmations already resolved the same way, at {minN:100, minRatio:0.95} or {minN:20, minRatio:1.00}.
- L2Heuristicno LLM
Normalises accents, punctuation and whitespace, then compares against the column name, the label, and every registered hint (DE / FR / IT / EN / ES).
- L3Fuzzyno LLM
Token-set ratio plus Levenshtein over the normalised strings. Auto-accepts at 0.80 — it absorbs typos and reordered words.
- L4Semanticcheap, cached
Embedding cosine between the header and the field’s label + hints. Catches the long tail of paraphrases.
- L5LLMmetered
Everything still unresolved goes up in ONE batched, collision-aware call, constrained to this template’s column set so it cannot invent a field.
Try it
One template id, two ways in.
REST for your import pipeline, MCP for your editor. Both run the same cascade and both honour the same schema-only clamp.
REST · POST /v1/uploads
Name the template; the cascade picks up the rest. The canonical definition is read-only at GET /v1/templates/addresses_v1.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=addresses_v1" \
-F "file=@your_data.csv"MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your editor and call the same cascade as a tool. Schema-only calls leave only column names and up to three clamped sample rows.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template_id: "addresses_v1",
headers: ["id", "line1", "line2", "city"]
})Questions
Addresses CSV import — FAQ
Ready when you are
Map addresses in production — without shipping raw records.
Schema-only mode leaves only headers and a handful of clamped samples. Add full-data when you need row-level AI, routed in-region under a BAA.