# Address Validator & Parser (`junipr/address-validator`) Actor Validate and parse postal addresses into structured components. Extracts street, city, state, ZIP code, and country with confidence scoring. Supports US address validation with ZIP code and state verification. Batch processing for up to 10,000 addresses per run. - **URL**: https://apify.com/junipr/address-validator.md - **Developed by:** [junipr](https://apify.com/junipr) (community) - **Categories:** Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $3.90 / 1,000 address validateds 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 ## Address Validator & Parser Validate, parse, and normalize postal addresses worldwide. Extract components (street, city, state, ZIP), standardize formatting (USPS for US), validate postal codes, and detect address types — all with **zero external API calls**. ### Why Use This Actor Address validation normally costs $2-5 per 1,000 lookups (SmartyStreets, Google Address Validation, Lob) and requires API keys. This actor uses open-source parsing logic and postal code format databases, running entirely on Apify's infrastructure. | Feature | Ours | SmartyStreets | Google | Lob | |---------|------|---------------|--------|-----| | Price per 1K | **$3.90** | $4.00 | $5.00 | $3.00 | | Batch processing | ✅ 100K+ | Limited | 1 at a time | API only | | Free-form parsing | ✅ | ✅ | ✅ | ❌ | | International support | ✅ 50+ | ✅ | ✅ | US only | | ZIP code validation | ✅ | ✅ | ✅ | ✅ | | No API key needed | ✅ | ❌ | ❌ | ❌ | **Honest limitation:** This actor performs **format validation and parsing**, not USPS CASS-certified deliverability verification. It confirms addresses are well-formed — but does NOT verify a specific address is a real, deliverable location. ### How to Use Zero-config: just provide an array of address strings. ```json { "addresses": [ "1600 Pennsylvania Ave NW, Washington, DC 20500", "123 Main St Apt 4B, New York, NY 10001", "10 Downing Street, London, SW1A 2AA, UK" ] } ```` Accepts free-form strings or structured objects: ```json { "addresses": [ { "street": "123 Main St", "city": "Chicago", "state": "Illinois", "zip": "60601", "country": "US" } ] } ``` ### Input Configuration | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `addresses` | array | Demo addresses | List of addresses (strings or objects). Max: 100,000 | | `defaultCountry` | string | `"US"` | ISO 3166-1 alpha-2 fallback country code | | `validateZipCode` | boolean | `true` | Validate ZIP/postal code format | | `normalizeFormat` | boolean | `true` | Normalize to country-standard format | | `detectAddressType` | boolean | `false` | Detect residential/commercial/po\_box | | `abbreviateState` | boolean | `true` | Convert "California" → "CA" | | `standardizeStreetSuffixes` | boolean | `true` | "Street" → "ST", "Avenue" → "AVE" | | `includeOriginal` | boolean | `true` | Include original input in output | | `onlyInvalid` | boolean | `false` | Filter to only invalid addresses | | `outputFormat` | string | `"components"` | `components`, `single_line`, or `both` | ### Output Format Each address produces one result: ```json { "original": "123 Main St Apt 4B, New York, NY 10001", "isValid": true, "confidence": 0.95, "normalized": "123 MAIN ST APT 4B, NEW YORK, NY 10001, US", "components": { "street": "123 Main St Apt 4B", "houseNumber": "123", "streetName": "MAIN", "streetSuffix": "ST", "unit": "4B", "unitType": "APT", "city": "NEW YORK", "state": "NY", "stateAbbreviation": "NY", "zipCode": "10001", "countryCode": "US" }, "addressType": "residential", "validation": { "hasStreet": true, "hasCity": true, "hasState": true, "hasZip": true, "zipFormatValid": true, "stateValid": true, "issues": [] }, "checkedAt": "2026-03-11T12:00:00.000Z" } ``` #### Confidence Score | Range | Meaning | |-------|---------| | 0.90 – 1.00 | All components present, ZIP valid, state valid | | 0.75 – 0.89 | All components present, minor issues | | 0.50 – 0.74 | Missing one non-critical component | | 0.25 – 0.49 | Missing multiple components | | 0.00 – 0.24 | Unparseable or severely malformed | #### Validation Issue Codes | Code | Severity | Description | |------|----------|-------------| | `MISSING_STREET` | error | No street address detected | | `MISSING_CITY` | error | No city detected | | `MISSING_STATE` | error | No state/province detected | | `MISSING_ZIP` | error | No postal code detected | | `INVALID_ZIP_FORMAT` | error | ZIP doesn't match country format | | `INVALID_STATE` | error | State not recognized | | `ZIP_STATE_MISMATCH` | warning | ZIP code doesn't match state | | `PO_BOX_DETECTED` | info | Address is a PO Box | ### Tips and Advanced Usage - **CRM cleanup:** Set `onlyInvalid: true` to filter a mailing list to problematic records only - **USPS formatting:** Default settings apply USPS-standard formatting (uppercase, abbreviated state and suffixes) - **International batches:** Set `defaultCountry` to your most common country for better detection - **Large batches:** Process up to 100,000 addresses in a single run — all in-memory, no external calls ### Pricing **$3.90 per 1,000 addresses validated** (PPE — pay only for what you process) Pricing includes all platform compute costs — no hidden fees. | Use Case | Addresses | Cost | |----------|-----------|------| | E-commerce daily orders | 200 | $0.78 | | CRM cleanup | 5,000 | $19.50 | | Mailing list prep | 50,000 | $195.00 | ### FAQ #### Does this verify the address actually exists (CASS certification)? No. This actor validates format and structure — it does NOT confirm the address is a real, deliverable location. For CASS certification, use SmartyStreets or Lob. #### What countries are supported? US, Canada, UK, Germany, France, Australia, Japan, and 40+ more. ZIP code format validation covers 25 countries. #### Can I input free-form addresses? Yes. Free-form strings like "1600 Pennsylvania Ave NW, Washington DC 20500" are parsed automatically. #### How does it handle apartment numbers? Unit formats handled: "Apt 4B", "#4B", "Suite 200", "Unit 3", "Floor 12". #### What's the difference between this and SmartyStreets? SmartyStreets is CASS-certified (confirms real addresses via USPS database). This actor validates address format and structure without external API calls — 3x cheaper for format validation use cases. #### Does it correct typos? No fuzzy matching. Typos are flagged with `POSSIBLE_TYPO` but not auto-corrected to avoid false corrections. *** Related actors by Junipr: [Disposable Email Checker](https://apify.com/junipr/disposable-email-checker) | [Email Validator](https://apify.com/junipr) # Actor input Schema ## `addresses` (type: `array`): List of addresses to validate. Each can be a free-form string or a structured object with components. ## `defaultCountry` (type: `string`): ISO 3166-1 alpha-2 country code. Applied when country cannot be detected from the address. ## `validateZipCode` (type: `boolean`): Validate postal/ZIP code format against country-specific patterns. ## `normalizeFormat` (type: `boolean`): Normalize address to country-standard format. ## `detectAddressType` (type: `boolean`): Attempt to detect if address is residential vs commercial. ## `abbreviateState` (type: `boolean`): Convert full state/province names to abbreviations. ## `standardizeStreetSuffixes` (type: `boolean`): Convert street suffix variations to standard forms. ## `includeOriginal` (type: `boolean`): Include the original input address in output for comparison. ## `onlyInvalid` (type: `boolean`): Only output addresses with validation issues. ## `outputFormat` (type: `string`): Output format: components (parsed fields), single\_line (normalized string), both. ## Actor input object example ```json { "addresses": [ "1600 Pennsylvania Ave NW, Washington, DC 20500", "10 Downing Street, London, SW1A 2AA, UK" ], "defaultCountry": "US", "validateZipCode": true, "normalizeFormat": true, "detectAddressType": false, "abbreviateState": true, "standardizeStreetSuffixes": true, "includeOriginal": true, "onlyInvalid": false, "outputFormat": "components" } ``` # Actor output Schema ## `results` (type: `string`): Parsed address components, validation status, confidence scores, normalized formatting, and address type classification. # 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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("junipr/address-validator").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 = {} # Run the Actor and wait for it to finish run = client.actor("junipr/address-validator").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 '{}' | apify call junipr/address-validator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=junipr/address-validator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Address Validator & Parser", "description": "Validate and parse postal addresses into structured components. Extracts street, city, state, ZIP code, and country with confidence scoring. Supports US address validation with ZIP code and state verification. Batch processing for up to 10,000 addresses per run.", "version": "1.0", "x-build-id": "GUKz5cSpAtkAQW8Wt" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/junipr~address-validator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-junipr-address-validator", "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/junipr~address-validator/runs": { "post": { "operationId": "runs-sync-junipr-address-validator", "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/junipr~address-validator/run-sync": { "post": { "operationId": "run-sync-junipr-address-validator", "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", "type": "array", "description": "List of addresses to validate. Each can be a free-form string or a structured object with components.", "default": [ "1600 Pennsylvania Ave NW, Washington, DC 20500", "10 Downing Street, London, SW1A 2AA, UK" ] }, "defaultCountry": { "title": "Default Country", "type": "string", "description": "ISO 3166-1 alpha-2 country code. Applied when country cannot be detected from the address.", "default": "US" }, "validateZipCode": { "title": "Validate ZIP/Postal Code", "type": "boolean", "description": "Validate postal/ZIP code format against country-specific patterns.", "default": true }, "normalizeFormat": { "title": "Normalize Format", "type": "boolean", "description": "Normalize address to country-standard format.", "default": true }, "detectAddressType": { "title": "Detect Address Type", "type": "boolean", "description": "Attempt to detect if address is residential vs commercial.", "default": false }, "abbreviateState": { "title": "Abbreviate State", "type": "boolean", "description": "Convert full state/province names to abbreviations.", "default": true }, "standardizeStreetSuffixes": { "title": "Standardize Street Suffixes", "type": "boolean", "description": "Convert street suffix variations to standard forms.", "default": true }, "includeOriginal": { "title": "Include Original", "type": "boolean", "description": "Include the original input address in output for comparison.", "default": true }, "onlyInvalid": { "title": "Only Invalid", "type": "boolean", "description": "Only output addresses with validation issues.", "default": false }, "outputFormat": { "title": "Output Format", "enum": [ "components", "single_line", "both" ], "type": "string", "description": "Output format: components (parsed fields), single_line (normalized string), both.", "default": "components" } } }, "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 } } } } } } } } } } ```