### Working with Zipcode Data

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

Illustrates how to utilize the 'zipcodes' array provided by the twzipcode library for detailed postal code information. Examples cover finding a specific district's postal code, filtering zipcodes by county, validating a given zipcode, and building a helper function to get districts by county.

```javascript
import twzipcode from 'twzipcode-data'

const data = twzipcode('en')

// Find postal code by district
const zhongzheng = data.zipcodes.find(z =>
  z.county === 'Taipei City' && z.city === 'Zhongzheng District'
)
console.log(zhongzheng)
// Output: {
//   id: '100臺北市中正區',
//   zipcode: 100,
//   county: 'Taipei City',
//   city: 'Zhongzheng District'
// }

// Get all districts for a county
const taipeiDistricts = data.zipcodes.filter(z => z.county === 'Taipei City')
console.log(taipeiDistricts.length)
// Output: 12
taipeiDistricts.forEach(d => {
  console.log(`${d.zipcode} - ${d.city}`)
})
// Output:
// 100 - Zhongzheng District
// 103 - Daton District
// 104 - Zhongshan District
// ...

// Validate a postal code
const zipcodeToValidate = 100
const isValid = data.zipcodes.some(z => z.zipcode === zipcodeToValidate)
console.log(`Zipcode ${zipcodeToValidate} is valid: ${isValid}`)
// Output: Zipcode 100 is valid: true

// Build an address form helper
function getDistrictsByCounty(countyId, locale = 'en') {
  const data = twzipcode(locale)
  const county = data.counties.find(c => c.id === countyId)
  if (!county) return []

  return data.zipcodes
    .filter(z => z.county === county.name)
    .map(z => ({
      value: z.zipcode,
      label: `${z.zipcode} - ${z.city}`
    }))
}

const taipeiOptions = getDistrictsByCounty('臺北市', 'en')
console.log(taipeiOptions[0])
// Output: { value: 100, label: '100 - Zhongzheng District' }
```

--------------------------------

### Load Taiwan Address Data by Locale (JavaScript)

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

Demonstrates how to import and use the twzipcode-data library to fetch Taiwan address information. Supports explicit locale codes ('zh-TW', 'en') or Accept-Language header strings for automatic locale negotiation. Outputs zipcode details or county names based on the selected locale. Includes examples for browser and server-side (Express.js) usage.

```javascript
import twzipcode from 'twzipcode-data'

// Explicit Chinese locale
const zhData = twzipcode('zh-TW')
console.log(zhData.zipcodes[0])
// Output: {
//   id: '100臺北市中正區',
//   zipcode: 100,
//   county: '臺北市',
//   city: '中正區'
// }

// Explicit English locale
const enData = twzipcode('en')
console.log(enData.zipcodes[0])
// Output: {
//   id: '100臺北市中正區',
//   zipcode: 100,
//   county: 'Taipei City',
//   city: 'Zhongzheng District'
// }

// Browser Accept-Language header example
const browserLang = 'en-US,en;q=0.9,zh-TW;q=0.8,zh;q=0.7'
const autoData = twzipcode(browserLang)
console.log(autoData.counties[0].name)
// Output: Taipei City (English chosen based on priority)

// Server-side usage with Express.js
function handleAddressRequest(req, res) {
  const acceptLang = req.headers['accept-language'] || 'zh-TW'
  const data = twzipcode(acceptLang)
  res.json({
    counties: data.counties,
    zipcodes: data.zipcodes
  })
}
```

--------------------------------

### Accessing and Processing County Data

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

Shows how to access the 'counties' array from the twzipcode library to work with Taiwan's administrative divisions. Examples include iterating through all counties, finding a specific county by its ID, and mapping county data into a format suitable for dropdown menus.

```javascript
import twzipcode from 'twzipcode-data'

const data = twzipcode('en')

// Iterate through all counties
data.counties.forEach(county => {
  console.log(`${county.id} - ${county.name}`)
})
// Output:
// 臺北市 - Taipei City
// 基隆市 - Keelung City
// 新北市 - New Taipei City
// ...

// Find a specific county
const taipei = data.counties.find(c => c.id === '臺北市')
console.log(taipei)
// Output: { id: '臺北市', name: 'Taipei City' }

// Get all county names for a dropdown
const countyOptions = data.counties.map(c => ({
  value: c.id,
  label: c.name
}))
console.log(countyOptions[0])
// Output: { value: '臺北市', label: 'Taipei City' }
```

--------------------------------

### Build Cascading Address Forms with TwZipcode Data (JavaScript)

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

Illustrates how to use the twzipcode-data library to build interactive address forms. Features a class `AddressForm` that fetches locale-specific data and provides methods to get counties, retrieve districts filtered by county, and validate addresses. Includes usage examples for populating dropdowns and validating user input. Assumes a 'zh-TW' locale by default but can be configured.

```javascript
import twzipcode from 'twzipcode-data'

class AddressForm {
  constructor(locale = 'zh-TW') {
    this.data = twzipcode(locale)
  }

  getCounties() {
    return this.data.counties.map(c => ({
      value: c.id,
      label: c.name
    }))
  }

  getDistrictsByCounty(countyId) {
    const county = this.data.counties.find(c => c.id === countyId)
    if (!county) return []

    return this.data.zipcodes
      .filter(z => z.county === county.name)
      .map(z => ({
        value: z.zipcode,
        label: z.city,
        fullLabel: `${z.zipcode} ${z.city}`
      }))
  }

  validateAddress(countyId, zipcode) {
    const county = this.data.counties.find(c => c.id === countyId)
    if (!county) return { valid: false, error: 'Invalid county' }

    const district = this.data.zipcodes.find(
      z => z.zipcode === zipcode && z.county === county.name
    )

    if (!district) {
      return { valid: false, error: 'Invalid zipcode for county' }
    }

    return { valid: true, district: district.city }
  }
}

// Usage example
const form = new AddressForm('en')

// Populate county dropdown
const counties = form.getCounties()
console.log(counties[0])
// Output: { value: '臺北市', label: 'Taipei City' }

// When user selects Taipei, populate district dropdown
const districts = form.getDistrictsByCounty('臺北市')
console.log(districts[0])
// Output: { value: 100, label: 'Zhongzheng District', fullLabel: '100 Zhongzheng District' }

// Validate user input
const validation = form.validateAddress('臺北市', 100)
console.log(validation)
// Output: { valid: true, district: 'Zhongzheng District' }

const invalidValidation = form.validateAddress('臺北市', 800)
console.log(invalidValidation)
// Output: { valid: false, error: 'Invalid zipcode for county' }
```

--------------------------------

### Import and Use TwZipcode Data

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

Demonstrates how to import the twzipcode library and retrieve postal code data for Taiwan. It shows fetching data in English, Traditional Chinese (default), and automatically based on Accept-Language headers. It also illustrates accessing the total counts of counties and zipcodes.

```javascript
import twzipcode from 'twzipcode-data'

// Get English data
const dataEn = twzipcode('en')
console.log(dataEn.counties[0])
// Output: { id: '臺北市', name: 'Taipei City' }

// Get Traditional Chinese data (default)
const dataTw = twzipcode()
console.log(dataTw.counties[0])
// Output: { id: '臺北市', name: '臺北市' }

// Use Accept-Language header for automatic detection
const dataAuto = twzipcode('zh-TW,zh;q=0.8,en-US;q=0.5,en;q=0.3')
console.log(dataAuto.counties[0])
// Output: { id: '臺北市', name: '臺北市' }

// Access all available data
console.log(`Total counties: ${dataTw.counties.length}`)
// Output: Total counties: 22
console.log(`Total zipcodes: ${dataTw.zipcodes.length}`)
// Output: Total zipcodes: 371
```

--------------------------------

### Default Import Function

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

The main export of the twzipcode-data library is a function that returns postal code data. It accepts a locale string (e.g., 'en', 'zh-TW') or an Accept-Language header string to automatically determine the language. The function returns an object containing 'counties' and 'zipcodes' arrays.

```APIDOC
## Default Import Function

### Description
This function is the primary way to access the Taiwan postal code data. It intelligently negotiates the locale based on the input provided, defaulting to Traditional Chinese if no locale is specified or detected.

### Method
`twzipcode(locale?: string | string[])`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import twzipcode from 'twzipcode-data';

// Get English data
const dataEn = twzipcode('en');
console.log(dataEn.counties[0]);

// Get Traditional Chinese data (default)
const dataTw = twzipcode();
console.log(dataTw.counties[0]);

// Use Accept-Language header for automatic detection
const dataAuto = twzipcode('zh-TW,zh;q=0.8,en-US;q=0.5,en;q=0.3');
console.log(dataAuto.counties[0]);
```

### Response
#### Success Response (200)
An object containing two arrays: `counties` and `zipcodes`.
- **counties** (Array<Object>) - An array of county objects. Each object has `id` (string, Chinese name) and `name` (string, localized name).
- **zipcodes** (Array<Object>) - An array of zipcode objects. Each object has `id` (string), `zipcode` (number), `county` (string, localized name), and `city` (string, localized name).

#### Response Example
```json
{
  "counties": [
    { "id": "臺北市", "name": "Taipei City" },
    // ... more counties
  ],
  "zipcodes": [
    { "id": "100臺北市中正區", "zipcode": 100, "county": "Taipei City", "city": "Zhongzheng District" },
    // ... more zipcodes
  ]
}
```
```

--------------------------------

### Zipcodes Array

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

The `zipcodes` array provides comprehensive postal code data for all 371 districts and townships in Taiwan. Each entry includes the postal code, county, and city/district names, enabling features like address validation and autocomplete.

```APIDOC
## Zipcodes Array

### Description
This array provides detailed postal code information for all 371 districts and townships in Taiwan. Each object in the array contains the 3-digit zipcode, county name, and city/district name, along with a combined `id` field. This data is crucial for address validation, autocomplete features, and geographic filtering.

### Method
Access via the `zipcodes` property of the object returned by the main `twzipcode` function.

### Endpoint
N/A (This is a data structure, not an HTTP endpoint)

### Parameters
None

### Request Example
```javascript
import twzipcode from 'twzipcode-data';

const data = twzipcode('en');

// Find postal code by district
const zhongzheng = data.zipcodes.find(z =>
  z.county === 'Taipei City' && z.city === 'Zhongzheng District'
);
console.log(zhongzheng);

// Get all districts for a county
const taipeiDistricts = data.zipcodes.filter(z => z.county === 'Taipei City');
console.log(taipeiDistricts.length);

// Validate a postal code
const zipcodeToValidate = 100;
const isValid = data.zipcodes.some(z => z.zipcode === zipcodeToValidate);
console.log(`Zipcode ${zipcodeToValidate} is valid: ${isValid}`);

// Build an address form helper
function getDistrictsByCounty(countyId, locale = 'en') {
  const data = twzipcode(locale);
  const county = data.counties.find(c => c.id === countyId);
  if (!county) return [];

  return data.zipcodes
    .filter(z => z.county === county.name)
    .map(z => ({
      value: z.zipcode,
      label: `${z.zipcode} - ${z.city}`
    }));
}

const taipeiOptions = getDistrictsByCounty('臺北市', 'en');
console.log(taipeiOptions[0]);
```

### Response
#### Success Response (200)
- **zipcodes** (Array<Object>) - An array of zipcode objects.
  - **id** (string) - A combined string of zipcode, county, and city (e.g., "100臺北市中正區").
  - **zipcode** (number) - The 3-digit postal code.
  - **county** (string) - The localized name of the county.
  - **city** (string) - The localized name of the city or district.

#### Response Example
```json
[
  { "id": "100臺北市中正區", "zipcode": 100, "county": "Taipei City", "city": "Zhongzheng District" },
  { "id": "103臺北市大同區", "zipcode": 103, "county": "Taipei City", "city": "Daton District" },
  // ... more zipcode objects
]
```
```

--------------------------------

### Counties Array

Source: https://context7.com/yyc1217/twzipcode-data/llms.txt

The `counties` array within the returned data object contains information about all 22 administrative divisions of Taiwan. Each county object provides a unique identifier and a localized name, facilitating easy integration into dropdowns or selection components.

```APIDOC
## Counties Array

### Description
This array contains detailed information for all 22 administrative divisions in Taiwan, including special municipalities, provincial cities, and counties. Each entry allows for consistent identification using its `id` while supporting localized display names via the `name` property.

### Method
Access via the `counties` property of the object returned by the main `twzipcode` function.

### Endpoint
N/A (This is a data structure, not an HTTP endpoint)

### Parameters
None

### Request Example
```javascript
import twzipcode from 'twzipcode-data';

const data = twzipcode('en');

// Iterate through all counties
data.counties.forEach(county => {
  console.log(`${county.id} - ${county.name}`);
});

// Find a specific county
const taipei = data.counties.find(c => c.id === '臺北市');
console.log(taipei);

// Get all county names for a dropdown
const countyOptions = data.counties.map(c => ({
  value: c.id,
  label: c.name
}));
console.log(countyOptions[0]);
```

### Response
#### Success Response (200)
- **counties** (Array<Object>) - An array of county objects.
  - **id** (string) - The unique identifier for the county (typically the Chinese name).
  - **name** (string) - The localized name of the county.

#### Response Example
```json
[
  { "id": "臺北市", "name": "Taipei City" },
  { "id": "新北市", "name": "New Taipei City" },
  // ... more county objects
]
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.