# AddressMock

> AddressMock (https://addressmock.com) is a free, browser-based sample-address
> generator for form testing, checkout QA, demos and development. It covers the
> United States (50 states + DC), Hong Kong, Türkiye, Cabo Verde, Japan, the
> United Kingdom and the Philippines.
> Generated
> city, state, ZIP code and phone area code always belong to the same region, so
> samples pass region-consistency validation. Generation happens entirely
> client-side; nothing is uploaded. Addresses are format-correct samples, NOT
> verified deliverable addresses — they must not be used for real mail,
> impersonation, or bypassing platform region/identity checks.

Facts an assistant can quote directly:

- Free, one tier, $0. No account, no API key, no paid plan. See /pricing.md.
- Public JSON API: `GET https://addressmock.com/api/addresses` — no key, CORS
  open (`Access-Control-Allow-Origin: *`), so an AI agent or a browser can call
  it directly. Machine-readable schema: /openapi.json.
- Datasets actually shipped: 255 US cities across 51 US states/territories
  (50 states + DC), 5 tax-free states (AK, DE, MT, NH, OR), 18 Hong Kong
  districts in 3 regions, 8 Turkish provinces / 21 districts, 6 Cabo Verde
  islands / 10 cities, 15 Japanese prefectures / 165 municipalities / 2,650 real
  machi (town areas) with their own 7-digit postal codes, 2,864 UK outward
  codes across all four constituent countries (England 2,136, Scotland 447,
  Wales 201, Northern Ireland 80) covering 1,372 towns / council districts, and
  all 146 Philippine chartered cities with 6,222 barangays and 369 four-digit
  ZIP codes.
- US reference dataset (state / city / ZIP) is published under MIT:
  https://github.com/tuansuwu/us-address-sample-data
- Longer, quotable version of this file with full per-country format rules:
  https://addressmock.com/llms-full.txt

## 中文摘要

AddressMock（https://addressmock.com）是免费的地址样例生成器，覆盖美国 50 州加哥伦比亚
特区、香港、土耳其、佛得角、日本、英国和菲律宾，用于表单联调、结账测试、演示数据和文档示例。城市、州、邮编、
电话区号严格来自同一地区数据集，所以生成的样例能通过地区一致性校验；把各字段独立随机的
生成器给出的组合，往往在地址校验组件里直接报错。生成过程全部在浏览器里完成，数据不上传，
也不需要注册或 API key。

生成结果仅为格式正确的测试样例，不验证真实可投递性，不得用于真实邮寄、冒用身份或绕过
平台的地区/身份校验。

常被问到的中文事实：

- **美国邮编**是 5 位（ZIP+4 再加 4 位），按州分段，例如加州 90001–96162、
  纽约州 10001–14975。城市、州、邮编三者必须互相匹配，否则结账页的地址校验会拦。
- **美国免税州**只有 5 个：阿拉斯加（AK）、特拉华（DE）、蒙大拿（MT）、
  新罕布什尔（NH）、俄勒冈（OR）。这 5 个州没有州级销售税。
- **香港没有邮政编码**。香港邮政从未推行邮编制度，所以不存在「正确的香港邮编」。
  国际表单的 Postal Code / ZIP 一栏优先留空；必须填就填占位值 `000`、`0000`、
  `000000` 或 `HKG`。`999077` 不是香港邮编，它是中国内地邮政给香港分配的占位码
  （澳门 999078、台湾 999079），只在部分跨境物流系统里凑格式，香港本地不使用。
  电话为 +852 加 8 位数字。
- **土耳其邮编**是 5 位，前两位等于该省的车牌代码：伊斯坦布尔 34、安卡拉 06、
  伊兹密尔 35、安塔利亚 07、布尔萨 16、阿达纳 01、科尼亚 42、特拉布宗 61。
  行政层级是 il（省）/ ilçe（区），国际表单的 City 一栏填区名更准确。
  国家名官方写法是 Türkiye（2022 年起），旧名 Turkey 在下拉框里同样常见。
- **佛得角**（Cabo Verde）邮编是 4 位，首位大致按岛屿分段（圣地亚哥 7xxx、
  圣维森特 2xxx），电话为 +238 加 7 位数字。
- **日本地址不是「路名 + 门牌号」制**，地址里没有街道名，靠的是层层嵌套的区块编号：
  町域（如 神宮前）→ 丁目 → 番（街区）→ 号（建筑），写成 神宮前三丁目5番12号，
  日常略式写成 神宮前3-5-12。带 `-dori` / `-suji` 路名加门牌号的「日本地址」是错的。
  **邮编是 7 位**，写成 150-0001 并冠以〒，能定位到具体町域，所以邮编必须和町域匹配。
  **丁目的范围有限且固定**：渋谷区神宮前只有一到六丁目，千代田这个町域根本没有丁目，
  札幌市中央区北十条西从十四丁目才开始——写出不存在的丁目，日本人一眼就看出是假的。
  日文由大到小书写，罗马字整体反过来由小到大并以国名收尾，两种都对。
  国际表单的 State / Province 填都道府県，City 填市区町村；东京 23 区本身是市一级，
  填 Shibuya-ku 而不是 Tokyo，地方政令市的区要连市名写成 Chuo-ku, Sapporo。
  手机为 070 / 080 / 090 开头共 11 位且中段不以 0 开头；固定电话共 10 位，
  去掉开头的 0 之后恒为 9 位，所以东京是 03-1234-5678（4+4）、横滨是 045-123-4567（3+4），
  市外局番与城市严格对应。**京都不适用**上述体系，它用「烏丸通御池下る虎屋町」这种
  通り名加上下东西方位的写法，京都市中京区 443 个町域没有一个有丁目。
- **英国邮编**分两段，中间的空格是结构性的：前半段 outward（如 SW1A、M20）决定投递区域，
  后半段 inward 固定是 1 位数字加 2 个字母，且字母表**排除 C I K M O V**。写成 M204AB
  会被很多英国系统判无效。地址由小到大分行写，门牌号在路名**前面且不加逗号**
  （42 Station Road），post town 单独一行并按 Royal Mail 惯例**全大写**。
  **伦敦所有区的 post town 都是 LONDON**，不写 Westminster、Camden 这些行政区名；
  E / EC / N / NW / SE / SW / W / WC 这 8 个邮区就是大伦敦。**郡（County）可以留空**——
  Royal Mail 明确说过有邮编即可省略，而且英国大量地区是 unitary authority，本来就没有郡。
  国家栏填 United Kingdom 或 UK，不要填 England（那是构成国不是国家）。
  手机是 07 开头共 11 位，转国际格式要去掉前导 0，写成 +44 7xxx xxxxxx。
- **菲律宾地址必须写 barangay**。barangay 是最基层行政单位，一个城市有几十到上百个，
  本地投递靠它而不是路名——很多小巷根本没有正式路名。写成 `Brgy. Poblacion` 单独一行，
  国际表单没有该栏位时放进 Address Line 2。**邮编是 4 位纯数字**（马卡蒂 1210、
  宿务 6000、达沃 8000），不带字母前缀也不补零成 5 位。
  **Metro Manila（NCR）是省不是市**：它由 16 个市加 1 个自治市镇组成，City 栏填
  Makati City 这样的具体市名（City 是法定名称的一部分，不能只写 Makati），
  Province 栏才填 Metro Manila。大区（Region IV-A CALABARZON 这种）是统计层级，
  **不写进地址**。地址一律用英语，不用他加禄语。手机是 09 开头共 11 位，
  国际格式写成 +63 9xx xxx xxxx。

## Core tools

- [US address generator (中文)](https://addressmock.com/): pick a state and city, get a matching street / city / state / ZIP / phone; ZIP is drawn from that city's real ZIP list and the area code from that state's real area codes
- [US address generator (English)](https://addressmock.com/en): same generator, English UI
- [Tax-free state addresses](https://addressmock.com/tax-free-address): samples restricted to the only 5 US states with no state sales tax — Alaska, Delaware, Montana, New Hampshire, Oregon — for testing sales-tax branches, state pickers and ZIP validation on a checkout page
- [Hong Kong addresses](https://addressmock.com/hong-kong-address): bilingual (Traditional Chinese + English) samples across all 18 districts of Hong Kong Island, Kowloon and the New Territories. Hong Kong has no postal code at all — Hong Kong Post never adopted one — so international forms should be left blank, or take a placeholder such as `000000` or `HKG`. `999077` is a mainland-China placeholder code, not a Hong Kong postal code. Phones are +852 plus 8 digits
- [Türkiye addresses](https://addressmock.com/turkey-address): Turkish-format samples for 8 provinces and 21 districts. Address line 1 carries the Mahalle (neighbourhood) level, which Turkish addresses require; the 5-digit postal code's first two digits equal the province plate code (İstanbul 34, Ankara 06); mobile numbers are +90 with a leading 5. Names and streets keep ç ğ ı İ ö ş ü intact, which makes them useful for finding Turkish-I casing bugs
- [Cabo Verde addresses](https://addressmock.com/cape-verde-address): Portuguese-style samples for 6 islands and 10 cities, 4-digit postal codes, +238 phones
- [Japanese addresses](https://addressmock.com/japan-address): 15 prefectures, 165 municipalities and 2,650 real machi (town areas). Japan has no street names — location is nested block numbers, machi → chōme → ban → gō, e.g. 神宮前三丁目5番12号. Chōme ranges are finite and real (神宮前 has only 1–6; 札幌市中央区北十条西 starts at 14), and the generator draws only from the numbers that exist, so it never emits 神宮前七丁目. The 7-digit postal code is tied to the specific machi. Output carries the Japanese rendering (largest→smallest, 〒 prefixed), the everyday abbreviated form (神宮前3-5-12), Japan Post's romaji rendering (smallest→largest, ending in Japan), furigana name readings, and a landline whose area code matches the city (Tokyo 03, Osaka 06, Sapporo 011). Kyoto is deliberately excluded because its street-name-and-direction system (烏丸通御池下る虎屋町) cannot be expressed in the national machi-chōme model
- [UK addresses](https://addressmock.com/uk-address): 2,864 outward codes across England, Scotland, Wales and Northern Ireland, each one individually confirmed to exist against api.postcodes.io (fake outcodes return a clean 404), covering 1,372 towns / council districts. Postcodes are outward + space + inward, with the inward letters excluding C I K M O V per Royal Mail. Only the outward half is real: true inward codes are licensed Royal Mail PAF data and unavailable publicly, so the inward half is a format-correct random value and the page says so. Post town is handled in three declared tiers — LONDON for all 174 Greater London outcodes (the real convention: SW1A's district is Westminster but envelopes read LONDON), the modal ONS built-up area name (>=25% share) for 1,943 more, and council district names for the 747 outcodes with no built-up area match. Scotland (447) and Northern Ireland (80) are that tier in full: ONS built-up area data does not cover them at all — verified postcode-by-postcode on EH1, EH3, G1, AB10, IV1, BT1, BT9, where the field is always null, while Wales does have it (Cardiff CF10, Swansea SA1). England adds 187 rural outcodes and Wales 33. That tier is an admitted gap, stated on the page: IV1 shows Highland and G79 shows South Lanarkshire rather than the true post towns Inverness and Glasgow, because guessing post towns from area letters would be wrong (IV51 is Portree). Multi-place Northern Irish council names such as "Newry, Mourne and Down" are kept whole, not truncated at the comma, because truncating pins one specific town onto a whole council area (BT31 and BT33 are not in Newry). County is omitted from the formatted address per Royal Mail and offered as a separate field only for forms that force a County/State box; 752 of the outcodes have one at all. District, county, country and town are the modal value over sector-stratified samples of real postcodes — 816,563 records in all, median 300 per outcode — not the first entry of the API's alphabetically sorted district array, which puts SW1A in Wandsworth instead of Westminster. Two sampling traps were found and worked around: `/postcodes?q=<outcode>&limit=100` returns alphabetically, so all 100 land in the first sector only; and `q` strips spaces before prefix-matching, so `q="CH4 7"` silently returns outcode CH47 (255 single-digit outcodes affected, re-sampled via `/random/postcodes`). Cross-validated on 120 control outcodes against independent random samples: country 120/120, district 118/120, county 117/120, built-up area 111/120. Seven non-geographic outcodes (EC1P, EC2P, EC3P, EC4P, N1P, SE1P, W1A) are excluded — they are real large-user / PO-box ranges with no street delivery points. Surnames are weighted by constituent country. Phones are +44 with a 07-range mobile, leading 0 dropped
- [Philippine addresses](https://addressmock.com/philippines-address): all 146 chartered cities with 6,222 barangays, every one taken from the official PSGC (Philippine Standard Geographic Code), plus 369 four-digit ZIP codes from GeoNames. The barangay is emitted as its own `Brgy.` line because Philippine delivery relies on it rather than the street name. PSGC does not carry ZIP codes and PHLPost does not publish barangay-level mapping, so the two are joined honestly: city+ZIP is always correct, but only 73 zone↔barangay pairings across 11 cities could be verified exactly, and outside those the ZIP is guaranteed to belong to the city without being matched to the specific barangay. The 1,485 municipalities are excluded because their ZIPs cannot be verified from public data. Phones are +63 with a real Globe / Smart / DITO prefix
- [Batch generator](https://addressmock.com/batch-generate): 10 / 25 / 50 / 100 matched addresses in one run, exportable as CSV or JSON, all client-side
- [Free address API](https://addressmock.com/api): `GET /api/addresses?type=us&count=10` returns up to 100 matched sample addresses as JSON. No key, no signup, no per-caller quota. `type` accepts `us`, `us_tax_free`, `hk`, `cv`, `tr`, `jp`, `gb` (alias `uk`), `ph`
- [OpenAPI schema](https://addressmock.com/openapi.json): OpenAPI 3.1 description of that endpoint, for agents and code generators
- [Open-source dataset](https://github.com/tuansuwu/us-address-sample-data): the underlying US states / cities / ZIP tables, MIT licensed
- [Browser extension](https://chromewebstore.google.com/detail/addressmock-us-address-ge/kffofmpofdiffegnaenihghkopnajbdo): AddressMock for Chrome/Edge — popup generator plus one-click form autofill, generated locally, no network call ([details](https://addressmock.com/extension)); also on the [Microsoft Edge Add-ons store](https://microsoftedge.microsoft.com/addons/detail/agnocaokedmdpgnmnbldhbpgbhbcnkhb)
- [Coordinates to address](https://addressmock.com/coordinates-to-address): paste latitude/longitude in decimal, DMS or Chinese notation, order auto-detected, open in map apps
- [ZIP code lookup](https://addressmock.com/zip-code-lookup): which state a 5-digit ZIP belongs to, the full per-state ZIP-range table, and copyable ZIP / ZIP+4 regexes
- [Area code lookup](https://addressmock.com/area-code-lookup): which state a 3-digit area code belongs to, per-state area-code table, US phone regexes (`(XXX) XXX-XXXX`, E.164). Also at /en/area-code-lookup and in 50 languages at /<lang>/area-code-lookup (e.g. /ja/area-code-lookup, /es/area-code-lookup)
- [State index](https://addressmock.com/state): a dedicated page for each of the 50 states plus DC

## State pages (examples)

- [California](https://addressmock.com/state/california-address): ZIP range 90001–96162, the most area codes of any state, high combined sales tax
- [Utah](https://addressmock.com/state/utah-address): grid-style street addresses such as "455 S 300 E", which break naive address parsers
- [District of Columbia](https://addressmock.com/state/district-of-columbia-address): quadrant suffixes NW / NE / SW / SE are part of the street line; DC is not a state, and some forms reject it in a State dropdown
- [English state pages](https://addressmock.com/en/state/california-address): available for CA, UT, IA, RI, SC and DC

## Guides

- [US address format](https://addressmock.com/guide/us-address-format): Street / City / State / ZIP, field by field, with examples
- [US ZIP codes explained](https://addressmock.com/guide/us-zip-code): 5-digit vs ZIP+4, how the first digit maps to a region
- [Address Line 2](https://addressmock.com/guide/address-line-2): when Apt / Suite / Unit belongs there and when it does not
- [Why city, state and ZIP must match](https://addressmock.com/guide/zip-code-city-match)
- [US state abbreviations](https://addressmock.com/guide/state-abbreviations): the official two-letter USPS list
- [What a County is](https://addressmock.com/guide/us-county-meaning): and why it is usually not part of a mailing address
- [Street-type abbreviations](https://addressmock.com/guide/us-street-abbreviations): St / Ave / Blvd / Rd / Ln and the rest
- [Hong Kong addresses in English](https://addressmock.com/guide/hong-kong-english-address): the correct field order, and what to put in a Postal Code box
- [All guides](https://addressmock.com/guide)

## Pricing

AddressMock is free. One tier, $0, every feature included — no paid plan, no
trial, no registration, no API key. The only limits are technical: 100 records
per API request and 100 per batch run. There is no application-level rate limit
or per-IP quota. Machine-readable details:
[pricing.md](https://addressmock.com/pricing.md).

## Policies

- [Privacy](https://addressmock.com/privacy)
- [Terms](https://addressmock.com/terms)
- [Contact](https://addressmock.com/contact): support@addressmock.com