# Parse a Postal Address Parse a freeform postal address into street, unit, city, region, postcode, and country fields. Local, rule-based, and browser-only. ## Run it - **CLI:** `gizza tool address-parse "123 Main St Apt 4B, Springfield, IL 62704, USA"` - **Web:** https://gizza.ai/tools/address-parse/ - **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/address-parse/tool.json ## Inputs - `address` — Address _(field)_ - `country` — Country hint _(field)_ ## Output - Parsed address (text) ## Query parameters Open the tool pre-filled and auto-run via URL: - `address` — Address - `country` — Country hint Example: `https://gizza.ai/tools/address-parse/?address=123%20Main%20St%20Apt%204B%2C%20Springfield%2C%20IL%2062704%2C%20USA&country=auto` --- ## Parse a freeform address into structured fields Paste a postal address exactly as you received it — one line, comma-separated, or multi-line — and this tool extracts the pieces that are useful for forms, spreadsheets, CRM cleanup, shipping prep, and geocoding pipelines. It returns a local, rule-based split into house number, street, unit or suite, city, region, postcode, country, and ISO country code when the country is recognized. The parser is intentionally deterministic and browser-local. It does not call a geocoder, validate deliverability, or send the address to a server. That makes it useful for quick normalization and data cleanup, especially when you want a repeatable first pass before manual review. ### What it extracts - **House number** — leading numbers such as `123`, `221B`, and `12-14`; for common European hints it also recognizes trailing numbers like `Hauptstraße 5`. - **Street** — the street line with the house number and unit designator removed. - **Unit** — apartment, suite, flat, room, `#12`, and similar secondary designators. - **City/locality** — the remaining locality after postcode and region are stripped. - **Region** — US states, Canadian provinces/territories, and Australian states resolve to names plus codes such as `IL`, `ON`, or `NSW`. - **Postcode** — US ZIP and ZIP+4, UK, Canadian, Dutch, and numeric postcodes for several other countries. - **Country** — recognized country names and common aliases become canonical names plus ISO 3166-1 alpha-2 codes. ### Worked examples Input: ```text 123 Main St Apt 4B, Springfield, IL 62704, USA ``` Output includes `House number: 123`, `Street: Main St`, `Unit: Apt 4B`, `City: Springfield`, `Region: Illinois (IL)`, `Postcode: 62704`, and `Country: United States (US)`. If the country is omitted, use **Country hint** to bias postcode and region parsing. For example, `350 Fifth Avenue, New York, NY 10118` with `US` fills the country as United States and resolves `NY` as New York. ### Limits and edge cases This is a heuristic parser, not a postal authority or geocoder. It works best on common address orders and on addresses that include separators (commas or line breaks). It may be imperfect for rural route formats, building-campus addresses, non-Latin scripts, addresses where city and street are in an unusual order, or country-specific elements such as prefecture/district hierarchy that do not map cleanly to the simple street/city/region/postcode model. Always review results before mailing, billing, deduping, or compliance workflows. ## FAQ
Does this validate that an address is deliverable? No. It only parses the text into likely fields. It does not call USPS, Royal Mail, Canada Post, a geocoder, or any other delivery database, so it cannot confirm that an address exists or is deliverable. Use it as a cleanup step before validation.
What does the country hint do? The hint biases postcode and region detection and fills the country when the text omits it. For example, `ON` is treated as Ontario when the hint or detected country is Canada, while `IL` resolves as Illinois for the United States. Choose `auto` when the country is written in the address itself.
Can it parse multi-line addresses? Yes. Line breaks are treated like commas, so a pasted mailing label such as `10 Downing Street\nLondon\nSW1A 2AA\nUK` is parsed into street, city, postcode, and country fields. Blank lines and extra whitespace are ignored.
Why did a field end up blank or in the wrong place? Postal formats vary widely. The parser uses deterministic rules and conservative country tables; it avoids inventing fields when the text is ambiguous. Add commas or line breaks between major parts, provide a country hint, or review the result manually for unusual formats.
Is my address uploaded? No. The parser runs as WebAssembly in your browser tab. There is no network call, server-side parsing, account, or logging by this tool.
## Related tools - [Basic Auth Header Generator](https://gizza.ai/tools/basic-auth-header-generator/): Generate an HTTP Basic Authorization header from a username and password — base64(user:pass) per RFC 7617. Runs in your browser, nothing is sent, free. - [Calendar Free/Busy Overlap](https://gizza.ai/tools/calendar-freebusy-overlap/): Paste two .ics calendars and list the time slots where both are free — working hours, minimum meeting length, timezones and DST handled. Free and in-browser. - [CIDR Calculator](https://gizza.ai/tools/cidr-calculator/): CIDR calculator: get network address, broadcast, netmask, wildcard, usable host range and host count for any IPv4 or IPv6 prefix. Free, private, in-browser. - [Extract Emails & Phone Numbers from Text](https://gizza.ai/tools/contact-info-extractor/): Extract emails and phone numbers from pasted text. Deduplicated, counted, sorted, and private in your browser with no upload. - [cURL Command Parser](https://gizza.ai/tools/curl-command-parser/): Paste a curl command to see its method, URL, query params, headers, body, auth, cookies and flags — or rebuild clean curl. Browser-only.