# AddressMock — full reference for LLMs

> AddressMock (https://addressmock.com) is a free, browser-based sample-address
> generator for form testing, checkout QA, demos, prototypes and documentation.
> Everything below is a factual description of what the site actually ships, so
> that an assistant can answer questions about it, and about the address formats
> it covers, without guessing.
>
> Generated addresses are format-correct samples, NOT verified deliverable
> addresses. City, state, ZIP code and phone area code are drawn from the same
> region so that samples pass region-consistency validation, but individual
> street numbers are not guaranteed to exist or to receive mail. They must not be
> used for real mail, fraud, impersonation, or bypassing platform region and
> identity checks.
>
> Short version of this file: https://addressmock.com/llms.txt
> Pricing as data: https://addressmock.com/pricing.md
> API schema: https://addressmock.com/openapi.json

## 1. What AddressMock is

A single-page web app served from a Cloudflare Worker. Address generation runs in
the visitor's browser against reference tables bundled with the page — there is
no generation request to a server, no account, and no stored user data. The only
server-side endpoint is a stateless read-only JSON API (section 9).

- Price: $0. One tier. No paid plan, no trial, no upsell.
- Registration: none. No sign-up, no login, no email capture.
- API key: none, and none can be created.
- Languages: Simplified Chinese and English UI; the area-code lookup page also
  exists in 50 languages under `/<lang>/area-code-lookup`.
- US reference data (state / city / ZIP) is published separately under MIT:
  https://github.com/tuansuwu/us-address-sample-data

## 2. United States

### Format

```
Full name
123 Main St Apt 4B
Los Angeles, CA 90012
United States
```

Field by field:

- **Street (Address Line 1):** house number, then street name, then street type
  (St, Ave, Blvd, Rd, Ln, Dr, Ct, Pl, Way). Directional prefixes and suffixes
  (N, S, E, W, NW …) are part of the street line.
- **Address Line 2:** secondary unit only — Apt, Suite, Ste, Unit, Fl, Rm. It is
  optional, and putting the city or a company name there is a common cause of
  address-validation failures.
- **City:** the mailing city, which is not always the legal municipality.
- **State:** the official two-letter USPS abbreviation, uppercase. There are 50
  states; DC is a federal district, not a state, and some forms reject it in a
  State dropdown.
- **ZIP:** 5 digits, optionally ZIP+4 (`90012-1234`). Leading zeros matter —
  `06103` is Hartford, CT, and storing it as an integer corrupts it. This is one
  of the most common bugs a US address sample will expose.
- **Phone:** 10 digits, `(213) 555-0142` domestically or `+1 213 555 0142` in
  E.164. The first 3 digits are the area code and are tied to a geography.

### ZIP ranges (a sample; the full table is at /zip-code-lookup)

| State | ZIP range |
| --- | --- |
| California | 90001–96162 |
| New York | 10001–14975 (plus 00501–00544 and 06390) |
| Texas | 73301, 75001–75501, 75503–79999, 88510–88589 |
| Alaska | 99501–99950 |
| Connecticut | 06001–06389, 06391–06928 |

The first digit of a US ZIP corresponds to a broad region, rising roughly west to
east: 0 = New England and Puerto Rico, 9 = the Pacific coast and Alaska/Hawaii.

### Tax-free states

Exactly five US states levy **no state-level sales tax**: **Alaska (AK),
Delaware (DE), Montana (MT), New Hampshire (NH), Oregon (OR)**. Alaska has no
state sales tax but does allow local sales taxes. Delaware, Montana, New
Hampshire and Oregon have neither. This is the entire list — the frequently seen
claim that there are "seven tax-free states" conflates sales tax with income tax.

AddressMock's `/tax-free-address` page restricts sampling to those five states,
which is what makes it useful for exercising the tax-free branch of a checkout,
a state picker, and ZIP validation at the same time.

### Coverage shipped

255 cities across 50 states plus the District of Columbia, each city carrying its
own real ZIP list, and each state its own real area codes.

## 3. Hong Kong

### Format

```
Full name
Flat A, 12/F, Block 3
88 Hennessy Road
Wan Chai
Hong Kong
```

- **There is no postal code.** Hong Kong Post has never operated a postcode
  system, so there is no such thing as a "correct Hong Kong ZIP code". When an
  international form has a required Postal Code field, leave it blank if allowed,
  otherwise use a placeholder: `000`, `0000`, `000000`, or `HKG`. These are
  format placeholders and do not affect delivery.
- **`999077` is not a Hong Kong postal code.** It is a placeholder that China's
  mainland postal system assigned to Hong Kong (Macau 999078, Taiwan 999079). It
  appears in some cross-border logistics systems purely to satisfy a field, and
  Hong Kong Post does not use it. It is also distinct from the statistical
  administrative-division code 810000.
- **Order is small-to-large in English:** flat / floor / block, then building,
  then street number and street, then district, then "Hong Kong". Chinese
  addresses run the other way, large-to-small.
- **State / Province field:** put the district (e.g. Wan Chai) or "Hong Kong".
  Hong Kong is a Special Administrative Region, not a province.
- **Phone:** `+852` plus 8 digits, no area code. Mobile numbers begin with 5, 6
  or 9. There is no trunk prefix — you do not dial a leading 0.

### The 18 districts

- **Hong Kong Island (香港島):** Central and Western 中西區, Wan Chai 灣仔區,
  Eastern 東區, Southern 南區
- **Kowloon (九龍):** Yau Tsim Mong 油尖旺區, Sham Shui Po 深水埗區,
  Kowloon City 九龍城區, Wong Tai Sin 黃大仙區, Kwun Tong 觀塘區
- **New Territories (新界):** Kwai Tsing 葵青區, Tsuen Wan 荃灣區, Tuen Mun 屯門區,
  Yuen Long 元朗區, North 北區, Tai Po 大埔區, Sha Tin 沙田區, Sai Kung 西貢區,
  Islands 離島區

AddressMock generates in all 18, in Traditional Chinese and English, using real
street names for each district.

## 4. Türkiye

### Format

```
Full name
Caferağa Mah. Bağdat Caddesi No:42
34710 Kadıköy/İstanbul
Türkiye
```

- **The Mahalle level is mandatory.** Turkish address line 1 starts with the
  neighbourhood — `Caferağa Mah.` — abbreviating *Mahallesi*. An address without
  it reads as incomplete locally. Most generators omit this layer.
- **Street types:** `Caddesi` (Cad.) is an avenue, `Sokak` (Sok.) a street,
  `Bulvarı` (Blv.) a boulevard. `No:` precedes the building number, `Daire` or
  `D:` the flat.
- **Postal code is 5 digits and its first two digits equal the province's
  vehicle-plate code.** So `34710` is necessarily in İstanbul. This makes an
  inconsistent Turkish postal code trivially detectable by a local system.
- **The slash in `34710 Kadıköy/İstanbul` is the real Turkish convention**, not
  an optional separator — it is printed that way on local invoices and waybills.
- **Administrative levels are `il` (province) and `ilçe` (district).** For an
  international form: State/Province = the province (İstanbul), City = the
  district (Kadıköy). If there is only a City field, the district is the more
  accurate value — Turks say they live in Kadıköy, not in İstanbul city.
- **Country name:** the official name is **Türkiye**, adopted at the UN in 2022.
  The older English name *Turkey* is still common in country dropdowns, so both
  are worth testing.
- **Phone:** `+90` plus 10 digits. Mobile numbers always start with 5; common
  operator prefixes are 50x, 53x, 54x, 55x. Written locally as `0` plus the same
  10 digits.
- **Turkish characters:** ç ğ ı İ ö ş ü. The notorious one is the *Turkish I*:
  lowercase `i` uppercases to dotted `İ`, and dotless `ı` uppercases to `I`.
  Locale-unaware case conversion turns `İstanbul` into `i̇stanbul` (with a stray
  combining dot) or silently drops `ı`. Turkish sample data is the fastest way to
  find casing, deduplication, sorting and email-normalisation bugs.

### Provinces shipped, with plate / postal prefix

| Province | Code | Districts shipped |
| --- | --- | --- |
| İstanbul | 34 | Kadıköy, Beşiktaş, Şişli, Bakırköy, Üsküdar |
| Ankara | 06 | Çankaya, Keçiören, Yenimahalle |
| İzmir | 35 | Konak, Bornova, Karşıyaka |
| Antalya | 07 | Muratpaşa, Konyaaltı, Alanya |
| Bursa | 16 | Osmangazi, Nilüfer |
| Adana | 01 | Seyhan, Çukurova |
| Konya | 42 | Selçuklu, Meram |
| Trabzon | 61 | Ortahisar |

Türkiye has 81 provinces; AddressMock ships 8 of them — the ones with the most
population and e-commerce volume — with real neighbourhood names and real
in-use postal codes for each district, rather than padding the count with
invented data.

## 5. Cabo Verde

- Postal code is **4 digits**, roughly segmented by island (Santiago 7xxx,
  São Vicente 2xxx).
- Portuguese-style street naming (`Rua`, `Avenida`, `Praça`).
- Phone: `+238` plus 7 digits; mobile numbers start with 9 or 5.
- Shipped: 6 islands (Santiago, São Vicente, Sal, Boa Vista, Fogo, Santo Antão)
  and 10 cities.

## 6. Japan

### Format

```
〒150-0001
東京都渋谷区神宮前三丁目5番12号 パークコート神宮前302号室
```

Romanised (Japan Post's official English rendering):

```
302 Park Court Jingumae, 3-5-12 Jingumae, Shibuya-ku, Tokyo 150-0001, Japan
```

- **Japan is not street-addressed.** There are no street names in a Japanese
  address. Location is expressed as nested block numbers: the municipality is
  divided into **machi / chō (町域)** such as 神宮前, the machi into **chōme
  (丁目)**, the chōme into **ban (番)** — a city block — and the ban into
  **gō (号)** — a building. So the address is 神宮前三丁目5番12号, colloquially
  written 神宮前3-5-12. Any "Japanese" address containing a `-dori` or `-suji`
  street name plus a house number is wrong; that is the single most common error
  in Japanese address generators.
- **Chōme ranges are finite and real.** 渋谷区神宮前 has only chōme 1 through 6;
  新宿 has 1–7; 梅田 has 1–3; the machi 千代田 has no chōme at all. Writing
  神宮前七丁目 is instantly recognisable as fake to a Japanese reader.
  AddressMock draws the chōme only from the numbers that actually exist for that
  machi — including the non-contiguous cases, such as 札幌市中央区北十条西, whose
  numbering starts at chōme **14**, not 1.
- **Postal code is 7 digits**, written `NNN-NNNN` and prefixed 〒. It resolves to
  a specific machi, so postal code and machi must agree; a randomly generated
  7-digit string is detectable by any local system. AddressMock ties every machi
  to its own real postal code.
- **Direction of writing reverses between scripts.** Japanese runs
  largest-to-smallest (postal code → prefecture → municipality → machi → chōme →
  ban → gō → building). Romaji runs smallest-to-largest and ends with the country
  name. Both are correct; which one applies depends on whether the form field is
  Japanese or English.
- **Formal versus abbreviated notation.** The formal form writes the chōme in
  kanji numerals and spells out ban and gō: 神宮前三丁目5番12号. Everyday form
  filling uses the hyphenated short form: 神宮前3-5-12. Machi without a chōme use
  **番地** instead of 番…号, e.g. 千代田1番地5.
- **Administrative levels.** State / Province on an international form takes the
  **prefecture (都道府県)**; City takes the **municipality (市区町村)**. Note that
  the 23 special wards of Tokyo are themselves municipality-level, so the value
  is `Shibuya-ku`, not `Tokyo`. Wards of the other designated cities sit *below*
  the city and are written with it: `Chuo-ku, Sapporo`, `Naka-ku, Nagoya`.
- **Furigana is a separate field.** Japanese forms almost always ask for the name
  reading in katakana (フリガナ) alongside the kanji. AddressMock emits kanji,
  katakana and romaji for every name. Official romaji name order since 2020 is
  surname first with the surname capitalised: `SATO Hina`.
- **Phone.** Mobile numbers are 11 digits starting 070 / 080 / 090, and the
  middle four-digit block never begins with 0 — 090-0xxx was never allocated.
  Landlines are 10 digits total, which after the leading 0 is always exactly 9,
  so a longer area code forces a shorter subscriber prefix: Tokyo `03-1234-5678`
  (4+4), Yokohama `045-123-4567` (3+4). The first digit of the subscriber prefix
  is 2–9; 0 and 1 are reserved for special services. Area codes are tied to the
  city: Tokyo 03, Osaka 06, Nagoya 052, Sapporo 011, Fukuoka 092.
- **Sapporo uses the jō-chōme (条丁目) system** and is shipped with a dedicated
  code path: `札幌市中央区北1条西3丁目`, with arabic numerals for both 条 and 丁目,
  which is how the city itself publishes its addresses — unlike the rest of the
  country, where the formal chōme is written in kanji numerals.
- **Kyoto is deliberately excluded.** Kyoto addresses use an
  intersection-plus-direction system built on street names —
  `烏丸通御池下る虎屋町` — which cannot be expressed in the national machi-chōme
  model. 京都市中京区 has 443 machi and not one of them has a chōme. Forcing it
  into the national format would produce addresses a local reader spots
  immediately, so AddressMock ships no Kyoto data at all rather than fake it.

### Coverage shipped

15 prefectures, 165 municipalities, 2,650 machi. Japan has 47 prefectures;
AddressMock ships the 23 special wards of Tokyo plus the wards of the designated
cities — the urban areas where consumer delivery addresses actually concentrate —
and prefers machi that have chōme, since a chōme implies the modern 住居表示
addressing scheme has been implemented there.

| Prefecture | Machi shipped |
| --- | --- |
| 神奈川県 Kanagawa | 393 |
| 東京都 Tokyo | 392 |
| 大阪府 Osaka | 390 |
| 愛知県 Aichi | 288 |
| 福岡県 Fukuoka | 227 |
| 北海道 Hokkaido | 180 |
| 兵庫県 Hyogo | 162 |
| 広島県 Hiroshima | 130 |
| 埼玉県 Saitama | 113 |
| 新潟県 Niigata | 95 |
| 宮城県 Miyagi | 90 |
| 千葉県 Chiba | 79 |
| 静岡県 Shizuoka | 54 |
| 岡山県 Okayama | 29 |
| 熊本県 Kumamoto | 28 |

What is real and what is generated: **real** — prefecture, municipality, machi
name with its katakana and romaji, the 7-digit postal code, the chōme numbers
that exist for that machi, and the telephone area code. **Generated** — ban, gō,
building name, room number, personal name, email, and the trailing digits of the
phone numbers. The result is a format-correct, internally consistent sample; it
is not a real residence and is not deliverable.

Attribution: machi names and romaji come from
[Geolonia 住所データ](https://github.com/geolonia/japanese-addresses) under
**CC BY 4.0**; postal codes come from
[jp-zipcode-lookup](https://github.com/kawanet/jp-zipcode-lookup) (**MIT**,
© 2018-2025 Yusuke Kawasaki), whose underlying data is Japan Post's published
postal-code file.

## 7. United Kingdom

Coverage: **2,864 outward codes** across all four constituent countries —
England 2,136, Scotland 447, Wales 201, Northern Ireland 80 — mapping to
**1,372 towns / council districts**. 752 of the outcodes fall in an area that
still has a county.

Format — four lines, smallest to largest:

```
42 Station Road
MANCHESTER
M20 4AB
United Kingdom
```

- **Line 1** is house number then street name, **number first, no comma**.
  `Station Road 42` is continental; `42, Station Road` is also wrong. A flat goes
  in front: `Flat 3, 42 Station Road`. Named houses with no number
  (`Rose Cottage, Church Lane`) are valid UK addresses.
- **Line 2** is the post town, which Royal Mail's addressing standard requires to
  be **in capitals on its own line**. It is a postal delivery town, not an
  administrative city: sometimes larger than the council area, sometimes smaller.
- **Line 3** is the postcode. The **space is structural** — `M204AB` is rejected
  by many UK validators.
- **Line 4** is the country: `United Kingdom` or `UK`. `England` is a constituent
  country, not a country, and some sorting systems reject it as a destination.
  `Northern Ireland` generally works for international mail.
- **County is not one of the four lines.** Royal Mail states it may be omitted
  when a postcode is present, and much of the UK is unitary authorities with no
  county tier at all. The generator exposes county as a separate field purely for
  international forms that force a County / State box.

Postcode structure: **outward code** + space + **inward code**.

```
SW1A 1AA
└┬┘└┬┘ └┬─┘
 │  │   └── inward: 1 digit + 2 letters
 │  └────── district, 1-2 characters, occasionally with a letter suffix
 └───────── area, 1-2 letters
```

The two inward letters **exclude C, I, K, M, O and V** — a long-standing Royal
Mail rule to avoid handwriting and OCR confusion. The generator obeys it.

How the outcode list was built: outward codes follow no derivable pattern (BT has
a gap at BT83–BT91 and resumes at BT92), so the list was enumerated and each
candidate confirmed individually against `api.postcodes.io/outcodes/<code>`,
which returns a clean 404 for codes that do not exist. Enumeration of an area
letter stops after 25 consecutive misses, which tolerates real gaps while still
terminating at the real ceiling. Seven **non-geographic** outcodes were then
removed: `EC1P`, `EC2P`, `EC3P`, `EC4P`, `N1P`, `SE1P`, `W1A`. Those are genuine
Royal Mail large-user / PO-box ranges with no street delivery points behind them
(W1A is the famous one — it is the BBC's), so a street address built on them
would be rejected by any system that validates delivery points.

**The post town gap, stated plainly.** The authoritative source for post towns is
Royal Mail's PAF (Postcode Address File), which is licensed commercial data and
is in no free API. Rather than guess post towns from area letters — which would
be wrong, since low IV numbers are Inverness but IV51 is Portree and the IV area
spans the entire Scottish Highlands and Skye — the generator uses three declared
tiers:

1. **Greater London** (174 outcodes in E, EC, N, NW, SE, SW, W, WC) → post town
   `LONDON`. This is the real convention: SW1A's administrative district is
   Westminster, but the envelope says LONDON.
2. **Modal ONS built-up area** → the built-up area name, cleaned, when it holds
   at least a 25% share of the outcode's sampled postcodes. 1,943 outcodes land
   here. This tier fixes cases where the district name is clearly not a town
   name: OX14's district is Vale of White Horse, its built-up area is
   Abingdon-on-Thames; B36's district is Solihull, its built-up area is
   Birmingham.
3. **No built-up area match** → the council district name. 747 outcodes land
   here: Scotland 447, England 187, Northern Ireland 80, Wales 33. Scotland and
   Northern Ireland are that tier **in full** — ONS built-up area data does not
   cover them at all. This was verified postcode-by-postcode on EH1, EH3, G1,
   AB10, IV1, BT1 and BT9, where the `bua` field is always null, while Wales does
   have it (Cardiff CF10, Swansea SA1). England's and Wales's share of this tier
   is rural outcodes — built-up area data does not cover places with no built-up
   area.

Tier 3 is an admitted shortfall, documented on the page rather than hidden: IV1
displays **Highland** and G79 displays **South Lanarkshire** (the council areas)
rather than the true post towns **Inverness** and **Glasgow**. Large cities are
unaffected — "City of Edinburgh" cleans to Edinburgh, "Aberdeen City" to
Aberdeen, and Glasgow, Belfast and Dundee coincide outright. Multi-place Northern
Irish council names such as `Newry, Mourne and Down` and
`Armagh City, Banbridge and Craigavon` are kept whole rather than truncated at
the comma: truncating pins one specific town onto an entire council area, and
BT31 and BT33 are not in Newry.

How district, county, country and town were resolved: `/outcodes/<code>` returns
`admin_district` as an alphabetically sorted **array** — one entry per council
area the outcode straddles — and 1,191 of the 2,864 outcodes straddle more than
one (97 straddle two counties, 20 two constituent countries). Taking the first
entry is systematically wrong (it puts SW1A in Wandsworth rather than
Westminster, W12 in Ealing rather than Hammersmith and Fulham). Every outcode was
therefore re-resolved from real postcode samples — **816,563 records**, median
300 per outcode, minimum 40 — taking the modal value of each field. Relative to
the first-array-entry baseline, 779 districts, 261 counties, 608 towns and 14
countries changed.

Two sampling traps had to be worked around, both verified rather than assumed:

- `/postcodes?q=<outcode>&limit=100` returns results in ascending alphabetical
  order, so all 100 land in the **first sector only** (BD15 gave 100/100 in
  sector 0, BL3 100/100 in sector 1). A mode computed that way describes one
  sector, not the outcode. Fix: query each sector separately, `q="<outcode> <n>"`
  for n = 0..9.
- `q` strips spaces before prefix-matching, so `q="CH4 7"` is equivalent to
  `q="CH47"` and returns the postcodes of the *outcode CH47*. 255 single-digit
  outcodes have such a sibling. Fix: those 255, plus 71 outcodes the sector
  queries found nothing for and 81 with too-thin samples — 407 in total — were
  sampled through `/random/postcodes?outcode=<code>`, which is unbiased.

Cross-validation: 120 control outcodes were resolved twice, once from the
sector-stratified sample and once from 60 independent random postcodes. Country
agreed 120/120, district 118/120, county 117/120, built-up area 111/120. Every
disagreement is a borderline outcode split near-evenly between two settlements
(TN5, M16, GL11, RH20, SY15), not a systematic bias. Country was additionally
checked structurally: each of the 360 council districts belongs to exactly one
constituent country, so all 360 were resolved against real postcodes and the
outcode rows recomputed from them — CH4, LD7, SY10 and nine others moved from
England to Wales, DG16, TD5, TD9 and TD12 from England to Scotland.

What is real and what is generated: **real** — the outward code, the constituent
country, the council district and county, and the town name at whichever tier
applies. **Generated** — the inward half of the postcode (format-correct, but
real inward codes are PAF-licensed and unavailable), the house number, the street
name (drawn from a pool of genuinely common British street names such as High
Street, Station Road and Church Lane, not invented per town), the personal name,
the email and the phone digits.

Surnames are weighted by constituent country: Smith leads nationally, but
Glasgow gives you Campbell and Stewart, Cardiff gives Jones, Davies and
Griffiths, and Belfast gives Murphy and O'Neill.

Phones: UK mobiles are `07xxx xxxxxx`, 11 digits. International format drops the
leading zero — `+44 7911 123456`. Writing `+44 07911 123456` is the single most
common mistake and is one digit too long.

Attribution: outward-code metadata comes from
[postcodes.io](https://postcodes.io), built on the **ONS Postcode Directory** and
**Ordnance Survey** data published under the **Open Government Licence v3**.

## 8. Philippines

Coverage: all **146 chartered cities**, **6,222 barangays** and **369 four-digit
ZIP codes**, across 17 regions and 55 province-level entries.

Format — four lines, smallest to largest:

```
1204 Kalayaan Ave.
Brgy. Poblacion
Makati City, Metro Manila 1210
Philippines
```

- **Line 1** is house number then street name, number first. Street suffixes are
  English (St. / Street / Ave. / Avenue / Road / Drive) — English is an official
  language of the Philippines and addresses are written in it, not in Tagalog.
- **Line 2** is the barangay, prefixed `Brgy.`. **This line cannot be dropped.**
  The barangay is the smallest administrative unit in the country; a city has
  dozens to hundreds of them, and local couriers navigate by barangay plus a
  landmark, because many alleys have no formal street name or numbering. On
  international forms with no barangay field, it goes in Address Line 2.
- **Line 3** is city, comma, province, space, 4-digit ZIP. **`City` is part of
  the legal name** — Makati City, Quezon City, Pasig City, Cebu City — and
  dropping it can collide with a same-named municipality.
- **Line 4** is `Philippines` (some dropdowns render it `Philippines (the)` or
  `PH`).
- **Metro Manila is a province-level entry, not a city.** It is 16 cities plus
  one municipality; City takes the specific city, Province takes Metro Manila or
  NCR. Swapping them makes local logistics fail sorting.
- **The region does not go in the address.** `Region IV-A CALABARZON` is a
  statistical and administrative tier; the generator exposes it as a separate
  field only for local systems that ask for it.

ZIP codes are **4 plain digits**, no letter prefix and no padding to 5 (`1210`,
not `01210`), roughly banded: 1000–1800 Metro Manila, 2000–2900 Central Luzon,
4000–4300 CALABARZON, 6000–6100 Cebu, 8000–8100 Davao, 9000–9800 northern and
western Mindanao. The 0400–0999 band is embassy and PO-box only, with no street
delivery points, and is excluded — the same standard applied to the seven
non-geographic UK outcodes in section 7.

**The ZIP-to-barangay join, stated plainly.** PSGC (the Philippine Statistics
Authority's geographic code) carries the full region / province / city / barangay
hierarchy but **no postal codes**; PHLPost owns postal codes and has never
published a barangay-level mapping. The two datasets are therefore joined in two
honest layers. **Guaranteed:** every one of the 369 ZIPs is known to belong to
the city it is attached to, so the city+ZIP pair — the granularity almost every
form actually validates — is always correct. **Qualified:** only **73** of those
ZIP entries, across 11 cities, carry a place name that matches a PSGC barangay of
that same city exactly. When one of those 73 verified pairings is available the
generator prefers it; otherwise the barangay and the ZIP are drawn independently,
so the ZIP definitely belongs to the city but is not matched to that specific
barangay.

One more repair worth recording: the GeoNames Philippine postal dump files all
360 Metro Manila ZIPs under `cityMunCode 133900` (City of Manila), collapsing the
whole National Capital Region into one city. That segment was rebuilt from a
separate per-city NCR ZIP source; without it Makati would draw Parañaque's ZIPs.

Why only chartered cities: the Philippines also has 1,485 municipalities, whose
ZIPs are largely missing from public data or can only be inferred from a
neighbouring city. The site's standing rule applies — **ship less rather than pad
the count with inferred data**, because an address built on a guessed ZIP is
obviously fake to any Philippine system.

What is real and what is generated: **real** — region, province, city, barangay
and ZIP code. **Generated** — house number, street name, personal name, email
and the trailing phone digits.

Names mix Spanish-derived surnames (Santos, Reyes, Cruz, dela Cruz — a legacy of
the 1849 Claveria decree that assigned Spanish surnames from a catalogue) with
Hokkien-romanised Chinese-Filipino surnames that are ordinary Philippine
surnames, not foreign ones: Uy, Tan, Lim, Sy, Ong, Chua, Go, Ang, Co.

Phones: Philippine mobiles are `09xx xxx xxxx`, 11 digits; international format
drops the leading zero to `+63 9xx xxx xxxx`. Prefixes are drawn from ranges
actually operated by Globe, Smart and DITO.

Attribution: the administrative hierarchy comes from the **PSGC** (Philippine
Standard Geographic Code, Philippine Statistics Authority) via
[psgc.gitlab.io](https://psgc.gitlab.io); postal codes come from the **GeoNames**
Philippine postal dump under **CC BY 4.0**, with the NCR segment cross-checked
against [phzips](https://github.com/kulotsystems/phzips) (**MIT**).

## 9. Public API

```
GET https://addressmock.com/api/addresses?type=us&count=10
```

- No API key, no signup, no per-caller quota. CORS is open
  (`Access-Control-Allow-Origin: *`), so it can be called straight from a browser
  or by an AI agent with plain HTTP — nothing to provision first.
- Only `GET` and `OPTIONS` are supported; any other method returns HTTP 405.
- Responses are `application/json; charset=utf-8` with `Cache-Control: no-store`.

Parameters:

| Name | Values | Default | Notes |
| --- | --- | --- | --- |
| `type` | `us`, `us_tax_free`, `hk`, `cv`, `tr`, `jp`, `gb` (alias `uk`), `ph` | `us` | anything else → HTTP 400 |
| `count` | integer 1–100 | `1` | outside the range → HTTP 400 |
| `gender` | `random`, `male`, `female` | `random` | anything else → HTTP 400 |
| `state` | two-letter US code | — | `us` / `us_tax_free` only; unknown code → 400; with `us_tax_free`, a non-tax-free state → 400 |
| `city` | US city name | — | `us` / `us_tax_free` only |

Response body:

```json
{
  "count": 1,
  "type": "us",
  "results": [
    {
      "firstName": "…", "lastName": "…", "fullName": "…",
      "gender": "male", "email": "…", "phone": "…", "phoneAlt": "…",
      "street": "…", "streetShort": "…", "unit": "…",
      "city": "…", "state": "CA", "stateName": "California",
      "zipCode": "…", "country": "United States",
      "fullAddress": "…"
    }
  ],
  "notice": "Format-correct sample data for testing and demos only…",
  "docs": "https://addressmock.com/api"
}
```

The `unit` key is always present: `Apt 4B` style for US records, `Daire 7` style
for Turkish ones, 建物名 plus 号室 for Japanese ones, `Flat 3` for UK ones,
`Unit 12B` for Philippine ones, and an empty string for Hong Kong and Cabo Verde,
so a caller never has to branch on record type. The same holds for `streetShort`
and `phoneAlt` — only `jp` records fill them, with the hyphenated short address
(`神宮前3-5-12`) and a landline whose area code matches the city — and for
`barangay`, which only `ph` records fill. Every other type returns an empty
string for those keys. `zipCode` is an empty string for Hong Kong, because Hong
Kong has no postal code; for `gb` it is the outward and inward halves separated
by a space, of which only the outward half is verified real. `country` returns
the literal strings `United States`, `Hong Kong`, `Turkey`, `Cape Verde`,
`Japan`, `United Kingdom` and `Philippines` — note that the API keeps the older
`Turkey` spelling rather than `Türkiye`, for backwards compatibility with
existing callers. Errors are `{"error": "message"}` with the corresponding
HTTP status.

Human documentation: https://addressmock.com/api
OpenAPI 3.1 schema: https://addressmock.com/openapi.json

## 10. Other tools on the site

- `/batch-generate` — 10 / 25 / 50 / 100 matched addresses in one run, CSV or
  JSON export, entirely client-side.
- `/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` — which state a 3-digit area code belongs to, the per-state
  table, and US phone regexes. Also `/en/area-code-lookup` and 50 localised
  versions at `/<lang>/area-code-lookup`.
- `/coordinates-to-address` — parses pasted latitude/longitude in decimal, DMS or
  Chinese notation, auto-detects the order, and opens the point in map apps.
- `/state` — a dedicated page per US state, 50 states plus DC.
- `/guide` — written guides on US address format, ZIP codes, Address Line 2,
  state abbreviations, counties, street-type abbreviations, and Hong Kong
  addresses in English.
- Browser extension for Chrome and Edge — popup generator plus one-click form
  autofill, generated locally with no network call. Details at `/extension`.

## 11. Intended and prohibited use

Intended: filling out and stress-testing address forms, checkout and shipping QA,
seeding demo and staging databases, screenshots and documentation, and finding
encoding, casing and validation bugs.

Prohibited: real mail, fraud, impersonation, creating accounts under a false
identity, and evading a platform's region or identity checks. AddressMock does
not generate credit-card numbers, government identifiers, or any other
credential, and does not publish guidance on circumventing regional restrictions.

## 12. Contact

- Privacy: https://addressmock.com/privacy
- Terms: https://addressmock.com/terms
- Contact: https://addressmock.com/contact — support@addressmock.com