International Postal Address Parser & Normalizer

Turn raw international postal addresses into structured components and normalized alternatives. Submit a list of address strings and receive one ordered Dataset item per input, ready for data cleaning, matching, CRM enrichment, or geocoding preparation.

What this Actor does

The Actor parses free-form addresses into labeled parts such as road, house number, city, postcode, state, and country. It can also generate normalized expansion variants that remove formatting differences and expand common address forms across languages.

Choose parsing, normalization, or both. The Actor preserves repeated component labels as arrays, retains the input position in inputIndex, and reports when normalization variants were capped. Processing is self-contained and does not send the submitted addresses to a geocoding service.

Use cases

• Standardize addresses before CRM, database, or spreadsheet imports.
• Prepare inconsistent address text for matching and duplicate-candidate workflows.
• Split free-form international addresses into structured fields.
• Normalize address variants before geocoding or search indexing.
• Process address columns exported by business or property data Actors.

How to use

1. Open the Actor in Apify Console.
2. Add one or more raw postal addresses.
3. Choose whether to parse, normalize, or do both.
4. Optionally add language hints and adjust the variant cap.
5. Click Start and open the Dataset when the run finishes.

For a first run, use a few representative addresses in parse_and_normalize mode and leave language hints empty for automatic detection.

Input

Field	Type	Required	Default	Description
addresses	string[]	Yes	—	From 1 to 10,000 address strings, each up to 500 characters. Whitespace around each value is trimmed.
mode	string	No	parse_and_normalize	parse, normalize, or parse_and_normalize.
languages	string[]	No	[]	Up to four unique lowercase ISO language hints for normalization. Empty uses automatic language detection.
maxExpansions	integer	No	20	Maximum variants saved per address, from 1 to 100.

Language hints affect normalization only. They do not force parser labels, verify a country, or restrict an address to a geographic area.

This is the exact input used for the real output example below:

{
  "addresses": [
    "Calle de Alcalá 45, 28014 Madrid, España"
  ],
  "mode": "parse_and_normalize",
  "languages": [
    "es"
  ],
  "maxExpansions": 20
}

Output

Results are stored in the default Dataset in the same order as the submitted addresses. Each item contains the ordered parser components, a grouped parsed object, normalized variants, counts, truncation status, and an item-level error field. Results can be exported in JSON, JSONL, CSV, Excel, XML, and other formats supported by Apify.

This is the complete Dataset item from a real successful run:

{
  "inputIndex": 0,
  "status": "succeeded",
  "inputAddress": "Calle de Alcalá 45, 28014 Madrid, España",
  "mode": "parse_and_normalize",
  "languageHints": [
    "es"
  ],
  "components": [
    {
      "label": "road",
      "value": "calle de alcalá"
    },
    {
      "label": "house_number",
      "value": "45"
    },
    {
      "label": "postcode",
      "value": "28014"
    },
    {
      "label": "city",
      "value": "madrid"
    },
    {
      "label": "country",
      "value": "españa"
    }
  ],
  "parsed": {
    "road": [
      "calle de alcalá"
    ],
    "house_number": [
      "45"
    ],
    "postcode": [
      "28014"
    ],
    "city": [
      "madrid"
    ],
    "country": [
      "españa"
    ]
  },
  "componentCount": 5,
  "primaryExpansion": "calle de alcala 45 28014 madrid espana",
  "expansions": [
    "calle de alcala 45 28014 madrid espana"
  ],
  "expansionCount": 1,
  "expansionsReturned": 1,
  "expansionsTruncated": false,
  "errorMessage": null
}

components preserves parser order and repeated labels. In parsed, every label maps to an array, even when only one value exists. primaryExpansion is the first returned normalization candidate; it is not a verified canonical address.

If one address cannot be processed, its row has status: "failed", empty result arrays, and a safe errorMessage. Other addresses continue processing. Invalid run-level input, such as an empty address or unsupported mode, fails before Dataset processing begins.

Pricing

The Actor costs $0.60 per 1,000 successful addresses ($0.0006 each). A charge occurs only when an address is successfully parsed or normalized and its result is saved to the default Dataset.

There is no Actor start charge. Failed address items are saved without an address-result charge, and addresses skipped because the run reached the user's maximum charge limit are neither saved nor charged. Platform usage during the run is included in the event price. Post-run storage operations may still follow the user's Apify plan.

API and integrations

Run the Actor through Apify Console, REST API, CLI, Tasks, Schedules, or webhooks. Use the default Dataset API to feed parsed addresses into databases, spreadsheets, geocoders, matching jobs, or automation platforms. The SUMMARY record in the default key-value store reports requested, processed, remaining, succeeded, failed, charged, charge-limit status, charged event name, and mode values for monitoring.

Related Actors

Actor	Best for
Google Maps Business Scraper | $1 per 1,000	Collecting business address strings and public place details before address normalization or matching.
Fotocasa Spain Property Listings Scraper	Collecting Spanish property locations that can be standardized for analysis.
Realtor.com US Property Listings Scraper	Collecting structured US listing addresses for cross-source cleanup and comparison.

Limits and data quality

• Each run accepts up to 10,000 addresses; each address is limited to 500 characters.
• A maximum of 100 normalization variants can be retained per address. expansionCount shows how many were produced and expansionsTruncated identifies capped output.
• Address parsing is statistical. Ambiguous, incomplete, non-postal, or unusual input can produce missing or incorrect labels.
• Normalization generates possible equivalent forms. It does not choose a legally preferred or postal-authority-approved format.
• The Actor does not verify existence, occupancy, deliverability, ownership, or geographic coordinates.
• Component availability varies by address. Never assume every result contains road, house number, city, postcode, state, and country.
• Repeated labels remain separate values in components and arrays in parsed; downstream systems should not flatten them without a rule appropriate to their data.

Frequently asked questions

Does this Actor validate or geocode an address?

No. It parses and normalizes text. It does not confirm that an address exists, determine whether mail can be delivered there, or return latitude and longitude. Send the cleaned result to a suitable geocoder or postal validation service when those checks are required.

Should I provide language hints?

Usually, start with an empty languages array so language detection is automatic. Add hints when you know the intended language and want normalization to prefer it. Hints do not constrain the parser to a country.

Which normalized variant should I store?

Treat every expansion as a candidate. primaryExpansion is convenient for inspection, but it is not guaranteed to be uniquely correct. For duplicate detection, compare overlapping variants and retain the original address for provenance.

Why are some components missing or labeled unexpectedly?

Free-form addresses can be incomplete or ambiguous, and local conventions vary. Include locality and country context when available, inspect representative samples, and keep the original string alongside parsed output.

Responsible use

This Actor uses the open-source libpostal project, whose models are derived from open geographic data. Users are responsible for complying with applicable licenses, laws, privacy obligations, and data-source terms.

Postal addresses can identify people or sensitive locations. Process only data you are authorized to use, protect exported Datasets, limit retention, and avoid using probabilistic parser output as proof of identity, residence, or deliverability.

Support

If a run does not behave as expected, open an issue in the Actor's Issues tab. Include the run ID, a sanitized reproducible input, the expected result, and the observed result. Do not post personal addresses, API tokens, credentials, or confidential information.