Addresses CSV import API
addresses_v1
Import this template via API. Normalize messy postal addresses from CSV into a canonical line1/city/region/country shape with optional lat/lng.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=addresses_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- Core
- FHIR resource
- —
- Risk level
- low
- Fields
- 9 (3 required, 0 validated)
Why this template?
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 & common foreign headers
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.
Schema
The canonical column set, with 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.
| Column | Type | Required | Validators | Hints |
|---|---|---|---|---|
| id | string | — | — | — |
| line1 | string | yes | — | strasse · rue · calle · via · street |
| line2 | string | — | — | — |
| city | string | yes | — | stadt · ville · ciudad · città |
| postal_code | string | — | — | plz · cp · cap · zip · postal code |
| region | string | — | — | kanton · région · región · state |
| country | string | yes | — | — |
| latitude | number | — | — | — |
| longitude | number | — | — | — |
How AdaptivMapr maps your headers to this template
Five layers run in order, cheapest first. Layer 1 (Statistics) auto-accepts headers that have been mapped the same way across past uploads. Layer 2 (Heuristic) compares your header to the column name, the optional label, and every registered hint (DE / FR / IT / EN / ES) after a Unicode-and-punctuation-normalising pass. Layer 3 (Fuzzy) catches typos and reordered words. Layer 4 (Semantic) uses cached embeddings to catch the long tail of paraphrases. Layer 5 (LLM) only fires on genuinely ambiguous columns, constrained to the template’s allowed column set so it cannot invent a field. When a layer auto-accepts, the lower-cost layers below it never run — that is the cost lever.
REST · POST /v1/uploads
Pass the template_id; the cascade picks up the rest.
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=addresses_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/addresses_v1.
MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your IDE. Schema-only calls are free and unlimited.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template: "addresses_v1",
headers: ["id", "line1", "line2", "city"]
})MCP install instructions →FAQ — Addresses CSV import
Do you geocode addresses on import?
No. Geocoding belongs in a separate step so you can swap providers (Google, Mapbox, OpenStreetMap) without re-importing. The Addresses template carries optional latitude/longitude columns if the source already has them.
How do you handle PO boxes and military addresses?
They land in line1 verbatim. The template does not parse the components; it just guarantees the buckets. Downstream parsers can take it from there.
What about non-Latin scripts (Cyrillic, CJK, Arabic)?
The cascade is Unicode-clean — accents are folded for header matching but row values are passed through untouched. Your destination column just needs to be UTF-8.
Why is line2 separate from line1?
Many countries treat apartment / floor / suite as second-class detail that does not belong on the primary address line. Splitting them avoids the most common geocoding failure: confusing an apartment number for a street number.