China Address & Region Code Normalizer

Parse mainland China addresses into canonical province, city, and county fields with administrative division codes. The Actor is designed for e-commerce, logistics, CRM cleanup, research datasets, and AI data pipelines.

Features

• Parse province, prefecture-level city, and county or district.
• Return administrative division codes and stable historical IDs.
• Normalize address prefixes while preserving the detailed street address.
• Process up to 1,000 addresses per run.
• Match a specific historical division snapshot from 1980 through 2024.
• Recognize county and district short names when enabled.
• Return ambiguous addresses as unmatched instead of silently choosing the wrong region.
• Preserve a caller-defined record ID for batch joins.

Simple input

{
  "addresses": [
    "Guangdong Province, Shenzhen City, Nanshan District example in Chinese",
    "Beijing City, Haidian District example in Chinese"
  ],
  "dataYear": 2024,
  "matchingMode": "leftToRight",
  "matchCountyShortNames": true
}

Use Chinese address text in production. The Apify input form includes working Chinese examples.

Structured input

Use records when each address needs its own ID or historical year:

{
  "records": [
    {"id": "order-1001", "address": "Chinese address text", "year": 2024},
    {"id": "order-1002", "address": "Historical Chinese address text", "year": 1995}
  ]
}

When records is supplied, it takes precedence over addresses.

Output fields

• status: matched or unmatched.
• matchLevel: province, city, county, or none.
• province, city, county: canonical division names.
• provinceCode, cityCode, countyCode: administrative division codes.
• detailAddress: input remaining after a recognized division prefix is removed.
• normalizedAddress: canonical division names plus the detail address.
• dataYear: administrative division snapshot used for matching.
• warning: explanation for an unmatched or ambiguous address.

Accuracy and limitations

The bundled historical dataset currently covers 1980 through 2024. Newer official division changes must not be represented as current until the underlying data is updated and tested.

This Actor does not geocode addresses, validate whether a building exists, or return personal data. Ambiguous names such as a district name shared by multiple cities are intentionally left unmatched unless enough context is supplied.

The address parser is powered by the MIT-licensed cnloc project.