# China Address & Region Code Normalizer (`prizable_aster/china-address-region-code-normalizer`) Actor Parses mainland China addresses into province, city, county, administrative codes, and normalized detail addresses. - **URL**: https://apify.com/prizable\_aster/china-address-region-code-normalizer.md - **Developed by:** [Vaque Wei](https://apify.com/prizable_aster) (community) - **Categories:** Developer tools, Automation, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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 ```json { "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: ```json { "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. # Actor input Schema ## `addresses` (type: `array`): Simple list of mainland China address strings to normalize. ## `records` (type: `array`): Optional records with id, address, and an optional historical data year. ## `dataYear` (type: `integer`): Snapshot used when a record does not specify its own year. ## `matchingMode` (type: `string`): Left-to-right is conservative; lower-to-higher can infer parent divisions from a specific place. ## `matchCountyShortNames` (type: `boolean`): Recognize inputs such as Shenzhen Nanshan without requiring the full district suffix. ## Actor input object example ```json { "addresses": [ "广东省深圳市南山区深南大道10000号", "北京市海淀区中关村大街1号" ], "dataYear": 2024, "matchingMode": "leftToRight", "matchCountyShortNames": true } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "addresses": [ "广东省深圳市南山区深南大道10000号", "北京市海淀区中关村大街1号" ] }; // Run the Actor and wait for it to finish const run = await client.actor("prizable_aster/china-address-region-code-normalizer").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "addresses": [ "广东省深圳市南山区深南大道10000号", "北京市海淀区中关村大街1号", ] } # Run the Actor and wait for it to finish run = client.actor("prizable_aster/china-address-region-code-normalizer").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "addresses": [ "广东省深圳市南山区深南大道10000号", "北京市海淀区中关村大街1号" ] }' | apify call prizable_aster/china-address-region-code-normalizer --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=prizable_aster/china-address-region-code-normalizer", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "China Address & Region Code Normalizer", "description": "Parses mainland China addresses into province, city, county, administrative codes, and normalized detail addresses.", "version": "0.0", "x-build-id": "YYr8eqcPyhXiuMpA8" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/prizable_aster~china-address-region-code-normalizer/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-prizable_aster-china-address-region-code-normalizer", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/prizable_aster~china-address-region-code-normalizer/runs": { "post": { "operationId": "runs-sync-prizable_aster-china-address-region-code-normalizer", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/prizable_aster~china-address-region-code-normalizer/run-sync": { "post": { "operationId": "run-sync-prizable_aster-china-address-region-code-normalizer", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "addresses": { "title": "Addresses", "maxItems": 1000, "type": "array", "description": "Simple list of mainland China address strings to normalize.", "items": { "type": "string" } }, "records": { "title": "Structured address records", "maxItems": 1000, "type": "array", "description": "Optional records with id, address, and an optional historical data year.", "items": { "type": "object", "properties": { "id": { "title": "Record ID", "description": "Optional caller-defined identifier returned unchanged.", "type": "string" }, "address": { "title": "Address", "description": "Chinese address text to normalize.", "type": "string" }, "year": { "title": "Historical data year", "description": "Administrative division snapshot from 1980 through 2024.", "type": "integer", "minimum": 1980, "maximum": 2024 } }, "required": [ "address" ] } }, "dataYear": { "title": "Default administrative division year", "minimum": 1980, "maximum": 2024, "type": "integer", "description": "Snapshot used when a record does not specify its own year.", "default": 2024 }, "matchingMode": { "title": "Matching mode", "enum": [ "leftToRight", "lowerToHigher" ], "type": "string", "description": "Left-to-right is conservative; lower-to-higher can infer parent divisions from a specific place.", "default": "leftToRight" }, "matchCountyShortNames": { "title": "Match county short names", "type": "boolean", "description": "Recognize inputs such as Shenzhen Nanshan without requiring the full district suffix.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```