### Install Main Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Install the main province-city-china package using npm.

```bash
npm install province-city-china
```

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

### Install Specific Packages

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Install specific packages for complete data, utilities, or types.

```bash
# For complete data
npm install @province-city-china/data
```

```bash
# For utilities only
npm install @province-city-china/utils
```

```bash
# For types
npm install --save-dev @province-city-china/types
```

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

### Install @province-city-china/level

Source: https://github.com/uiwjs/province-city-china/blob/master/packages/level/README.md

Install the package as a development dependency using npm.

```bash
npm install @province-city-china/level --save-dev
```

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

### Install @province-city-china/town Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the township-level administrative divisions package using npm.

```bash
npm install @province-city-china/town
```

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

### Install Province Data Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the province-level administrative divisions package using npm.

```bash
npm install @province-city-china/province
```

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

### Install City Data Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the city-level administrative divisions package using npm.

```bash
npm install @province-city-china/city
```

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

### Install Province Package

Source: https://github.com/uiwjs/province-city-china/blob/master/packages/province/README.md

Install the province package as a development dependency using npm.

```bash
npm install @province-city-china/province --save-dev
```

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

### Province Data Example (JSON)

Source: https://github.com/uiwjs/province-city-china/blob/master/README.md

Example of province-level administrative data in JSON format.

```json
[
  {
    "code": "110000",
    "name": "北京市",
    "province": "11"
  },
  {
    "code": "120000",
    "name": "天津市",
    "province": "12"
  },
  // ...
]
```

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

### City Data Example (JSON)

Source: https://github.com/uiwjs/province-city-china/blob/master/README.md

Example of city-level administrative data in JSON format.

```json
[
  {
    "code": "130100",
    "name": "石家庄市",
    "province": "13",
    "city": "01"
  },
  // ...
]
```

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

### Install @province-city-china/area Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the county-level administrative divisions package using npm.

```bash
npm install @province-city-china/area
```

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

### Install Province-City-China Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/README.md

Install the main package or specific sub-packages using npm. This includes options for development dependencies.

```bash
# Main package (all-in-one)
npm install province-city-china

# Specific packages
npm install @province-city-china/data
npm install @province-city-china/utils
npm install --save-dev @province-city-china/types
```

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

### Total Data Example (JSON)

Source: https://github.com/uiwjs/province-city-china/blob/master/README.md

Example of the total administrative data structure (province, city, district, town) in JSON format.

```json
[
  {
    "code": "110000",
    "name": "北京市",
    "province": "11",
    "city": 0,
    "area": 0,
    "town": 0
  },
  // ...
]
```

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

### Install District Code Package

Source: https://github.com/uiwjs/province-city-china/blob/master/packages/district-code/README.md

Install the district-code package as a development dependency using npm.

```bash
npm install @province-city-china/district-code --save-dev
```

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

### Install @province-city-china/data Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the main data package using npm. This package contains all administrative division data.

```bash
npm install @province-city-china/data
```

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

### Install Province-City-China Area Package

Source: https://github.com/uiwjs/province-city-china/blob/master/packages/area/README.md

Install the province-city-china package as a development dependency using npm.

```bash
npm install @province-city-china/area --save-dev
```

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

### Install @province-city-china/country

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the country package using npm. This package provides international country and region codes.

```bash
npm install @province-city-china/country
```

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

### Hierarchical Data Example (JSON)

Source: https://github.com/uiwjs/province-city-china/blob/master/README.md

Example of hierarchical administrative data structure (province/city/district/town) in JSON format, showing nested 'children' arrays.

```json
[
  {
    "code": "420000",
    "name": "湖北省",
    "province": "42",
    "children": [
      {
        "code": "420100",
        "name": "武汉市",
        "province": "42",
        "city": "01",
        "children": [
          {
            "code": "420102",
            "name": "江岸区",
            "province": "42",
            "city": "01",
            "area": "02"
          },
          // ...
        ]
      }
      // ...
    ]
  }
  // ...
]
```

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

### Install @province-city-china/level

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the level package using npm. This package provides hierarchical data for Chinese provinces, cities, and areas.

```bash
npm install @province-city-china/level
```

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

### Country Data Example (JSON)

Source: https://github.com/uiwjs/province-city-china/blob/master/README.md

Example of the country data structure in JSON format. Includes country codes and names.

```json
[
  {
    "id": 1,
    "cnname": "阿富汗",
    "name": "Afghanistan",
    "fullname": "the Islamic Republic of Afghanistan",
    "alpha2": "AF",
    "alpha3": "AFG",
    "town": 4
  },
  {
    "id": 45,
    "cnname": "中国",
    "name": "China",
    "fullname": "the People's Republic of China",
    "alpha2": "CN",
    "alpha3": "CHN",
    "town": 156
  }
  // ...
]
```

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

### Province Example Data

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

An example of a Province data object, showing the structure with code, name, and province identifier.

```typescript
{
  "code": "360000",
  "name": "江西省",
  "province": "36"
}
```

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

### Area Data Structure Example

Source: https://github.com/uiwjs/province-city-china/blob/master/packages/area/README.md

An example of the structure for the full area data, showing province, city, and area codes and names.

```json
[
  {
    "code": "110101",
    "name": "东城区",
    "province": "11",
    "city": "01",
    "area": "01"
  },
  // ...
]
```

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

### Import Types from Main Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

Import all available types from the main 'province-city-china' package. Ensure the package is installed.

```typescript
import type {
  Base,
  Province,
  City,
  Area,
  Town,
  Data,
  Level,
  Country
} from 'province-city-china';
```

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

### Data Example

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

An example of a Data object, representing a complete administrative division record with all relevant codes. Used for comprehensive data lookups.

```typescript
{
  "code": "621202",
  "name": "武都区",
  "province": "62",
  "city": "12",
  "area": "02",
  "town": 0
}
```

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

### Install District Code Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Install the @province-city-china/district-code package using npm. This package provides domestic long-distance telephone area codes.

```bash
npm install @province-city-china/district-code
```

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

### Vue.js Example for Province-City-Area Selection

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Demonstrates how to use the library in a Vue.js application to create cascading dropdowns for provinces, cities, and areas. Requires importing Vue reactivity APIs and specific JSON data.

```vue
<template>
  <div>
    <select v-model="selectedProvince" @change="onProvinceChange">
      <option value="">Select Province</option>
      <option v-for="p in provinces" :key="p.code" :value="p.province">
        {{ p.name }}
      </option>
    </select>

    <select v-model="selectedCity" @change="onCityChange" :disabled="!selectedProvince">
      <option value="">Select City</option>
      <option v-for="c in cities" :key="c.code" :value="c.code">
        {{ c.name }}
      </option>
    </select>

    <select v-model="selectedArea" :disabled="!selectedCity">
      <option value="">Select Area</option>
      <option v-for="a in areas" :key="a.code" :value="a.code">
        {{ a.name }}
      </option>
    </select>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue';
import { findCityChild, findAreaChild } from 'province-city-china';
import provinces from 'province-city-china/dist/province.json';
import data from 'province-city-china/dist/data.json';

const selectedProvince = ref('');
const selectedCity = ref('');
const selectedArea = ref('');

const cities = computed(() => 
  selectedProvince.value ? findCityChild(data, selectedProvince.value) : []
);

const areas = computed(() =>
  selectedCity.value ? findAreaChild(data, selectedCity.value) : []
);

const onProvinceChange = () => {
  selectedCity.value = '';
  selectedArea.value = '';
};

const onCityChange = () => {
  selectedArea.value = '';
};
</script>
```

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

### Package.json for Type-Only Import

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Use this configuration if you only need the type definitions from the province-city-china library, for example, when working with a custom data source.

```json
{
  "dependencies": {
    "@province-city-china/data": "^8.5.8"
  },
  "devDependencies": {
    "@province-city-china/types": "^8.5.8"
  }
}
```

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

### Example Data for Country Type

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

Provides an example of a country data object, conforming to the Country type. It includes sequential ID, Chinese and English names, and ISO alpha-2, alpha-3, and numeric codes.

```typescript
{
  "id": 45,
  "cnname": "中国",
  "name": "China",
  "fullname": "the People's Republic of China",
  "alpha2": "CN",
  "alpha3": "CHN",
  "numeric": 156
}
```

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

### Town Example Data

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

An example of a Town data object, including codes for province, city, area, and town. Used for township-level data queries.

```typescript
{
  "code": "110101002000",
  "name": "景山街道",
  "province": "11",
  "city": "01",
  "area": "01",
  "town": "002000"
}
```

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

### Handling Special Province-Level Administrative Divisions

Source: https://github.com/uiwjs/province-city-china/blob/master/README.md

This example shows how to identify and process special administrative divisions within certain provinces that have their own city codes. These are often categorized under '自治区直辖县级行政区划' or '省直辖县级行政区划'.

```bash
http://www.stats.gov.cn/tjsj/tjbz/tjyqhdmhcxhfdm/2021/<省>/<省><自治区直辖县级行政区划>.html

- 42 湖北省         -> # 自治区直辖县级行政区划
- 46 海南省         -> # 自治区直辖县级行政区划
- 65 新疆维吾尔自治区 -> # 自治区直辖县级行政区划
- 41 河南省         -> # 省直辖县级行政区划
# - 46 重庆市 -> 🚧 县
# - 23 黑龙江省 -> 🚧 大兴安岭地区
```

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

### Example Data for Level Type

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

Illustrates the structure of hierarchical administrative data, including province, city, and area details with nested children. This data format is used for tree traversal.

```typescript
{
  "code": "420000",
  "name": "湖北省",
  "province": "42",
  "children": [
    {
      "code": "420100",
      "name": "武汉市",
      "province": "42",
      "city": "01",
      "children": [
        {
          "code": "420102",
          "name": "江岸区",
          "province": "42",
          "city": "01",
          "area": "02"
        }
      ]
    }
  ]
}
```

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

### District Code Data Format Example

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Example of the data format for district phone codes. Each entry includes the name of the city/region in Chinese and its corresponding telephone area code.

```typescript
{
  name: string;  // City/region name in Chinese
  code: string;  // Telephone area code (e.g., "010" for Beijing)
}

```

```typescript
[
  { "name": "北京市", "code": "010" },
  { "name": "上海市", "code": "021" },
  // ...
]

```

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

### City Example Data

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

An example of a City data object, including province and city codes. Used for city-level data and parent lookups in hierarchy.

```typescript
{
  "code": "654000",
  "name": "伊犁哈萨克自治州",
  "province": "65",
  "city": "40"
}
```

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

### Special Administrative Divisions Data Example

Source: https://github.com/uiwjs/province-city-china/blob/master/packages/core/README.md

Example of data for 'autonomous region-administered county-level administrative divisions' that have independent city codes. These are often included in the 'district' data.

```javascript
[{ code: '429004', name: '仙桃市', province: '42', city: '90' },
{ code: '429005', name: '潜江市', province: '42', city: '90' },
{ code: '429006', name: '天门市', province: '42', city: '90' },
{ code: '429021', name: '神农架林区', province: '42', city: '90' }]
```

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

### Direct Import of JSON Data

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Import the complete or minified JSON data directly from the 'dist/' directory. Ensure the module is installed in your project.

```typescript
import data from 'province-city-china/dist/data.json';
import minified from 'province-city-china/dist/data.min.json';
```

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

### Get Beijing Districts using findAreaChild

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/03-utility-functions.md

Demonstrates how to retrieve all area-level districts for Beijing, a direct-controlled municipality, using its city code '1101'. Requires importing data and the utility function.

```typescript
import { data } from 'province-city-china/data';
import { findAreaChild } from '@province-city-china/utils';

// Beijing's city code is "1101"
const beijingDistricts = findAreaChild(data, '1101');

// Result:
// [
//   { code: "110101", name: "东城区", area: "01" },
//   { code: "110102", name: "西城区", area: "02" },
//   ...
// ]
```

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

### Get Districts in a City

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Retrieve and list all districts for a given city using its code. The data package must be installed.

```typescript
import { findAreaChild } from 'province-city-china';
import { data } from 'province-city-china/data';

// Get all districts in Wuhan (code 420100)
const areas = findAreaChild(data, '420100');

areas.forEach(area => {
  console.log(`${area.code} ${area.name}`);
});
```

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

### Get All Provinces with Cities

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Retrieve and display all provinces along with their cities using the sortProvince function and imported data. Ensure the data package is installed.

```typescript
import { sortProvince } from 'province-city-china';
import { data } from 'province-city-china/data';

// Get provinces with their cities and areas
const provinces = sortProvince(data, 3);

provinces.forEach(province => {
  console.log(`${province.code} ${province.name}`);
  province.children?.forEach(city => {
    console.log(`  ${city.code} ${city.name}`);
  });
});
```

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

### Import Paths for Main Functions

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/INDEX.md

Demonstrates three ways to import the main functions (sortProvince, findCityChild, findAreaChild) from the province-city-china package.

```typescript
// Option 1: From main package
import { sortProvince, findCityChild, findAreaChild } from 'province-city-china';
```

```typescript
// Option 2: From utils package
import { sortProvince, findCityChild, findAreaChild } from '@province-city-china/utils';
```

```typescript
// Option 3: From core package
import { sortProvince, findCityChild, findAreaChild } from '@province-city-china/core';
```

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

### Importing Utilities from Main Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/03-utility-functions.md

Import the core utility functions directly from the main 'province-city-china' package.

```typescript
import { sortProvince, findCityChild, findAreaChild } from 'province-city-china';
```

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

### Accessing Data via CDN

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Access distribution files, such as the complete JSON data, using CDN links. Unpkg is a common choice, with alternatives like Githack and Statically available.

```bash
https://unpkg.com/province-city-china/dist/data.json
https://unpkg.com/province-city-china/dist/data.min.json
https://unpkg.com/province-city-china/dist/city.json
```

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

### Package.json for Library Consumer

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Include this configuration in your package.json to use the province-city-china library directly.

```json
{
  "dependencies": {
    "province-city-china": "^8.5.8"
  },
  "devDependencies": {
    "@province-city-china/types": "^8.5.8"
  }
}
```

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

### Data Import Patterns

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/INDEX.md

Illustrates various methods for importing data, including the main data module, direct JSON imports, and imports from individual data packages.

```typescript
// Option 1: From data module
const { data, province, city, area, town, level } = require('province-city-china/data');
```

```typescript
// Option 2: Direct JSON import
import data from 'province-city-china/dist/data.json';
import province from 'province-city-china/dist/province.json';
```

```typescript
// Option 3: From individual packages
import provinces from '@province-city-china/province';
import cities from '@province-city-china/city';
```

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

### Import Pattern 1: All from Main Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

This is the simplest import pattern, suitable for small projects. It imports all necessary functions and types directly from the main 'province-city-china' package.

```typescript
import {
  sortProvince,
  findCityChild,
  findAreaChild
} from 'province-city-china';

import type {
  Province,
  City,
  Area,
  Data,
  Level
} from 'province-city-china';

// Data imports (requires separate step)
const { data, province, city, area } = require('province-city-china/data');
```

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

### Area Example Data

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/01-types.md

An example of an Area data object, including province, city, and area codes. Used for county-level data and area child queries.

```typescript
{
  "code": "422827",
  "name": "来凤县",
  "province": "42",
  "city": "28",
  "area": "27"
}
```

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

### Build Administrative Index with TypeScript

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/08-advanced-patterns.md

Use this class to create indexed structures from administrative data for fast lookups by code, name, province, city, or area. Requires importing data from 'province-city-china/data'.

```typescript
import { data } from 'province-city-china/data';

class AdministrativeIndex {
  codeMap = new Map();
  nameMap = new Map();
  provinceIndex = new Map();
  cityIndex = new Map();
  areaIndex = new Map();

  constructor(data) {
    data.forEach(item => {
      // Index by code
      this.codeMap.set(item.code, item);

      // Index by name
      if (!this.nameMap.has(item.name)) {
        this.nameMap.set(item.name, []);
      }
      this.nameMap.get(item.name).push(item);

      // Index by province
      if (!this.provinceIndex.has(item.province)) {
        this.provinceIndex.set(item.province, []);
      }
      this.provinceIndex.get(item.province).push(item);

      // Index by city
      if (item.city !== 0) {
        const cityKey = `${item.province}${item.city}`;
        if (!this.cityIndex.has(cityKey)) {
          this.cityIndex.set(cityKey, []);
        }
        this.cityIndex.get(cityKey).push(item);
      }

      // Index by area
      if (item.area !== 0) {
        const areaKey = `${item.province}${item.city}${item.area}`;
        if (!this.areaIndex.has(areaKey)) {
          this.areaIndex.set(areaKey, []);
        }
        this.areaIndex.get(areaKey).push(item);
      }
    });
  }

  findByCode(code) {
    return this.codeMap.get(code);
  }

  findByName(name) {
    return this.nameMap.get(name) || [];
  }

  findInProvince(provinceCode) {
    return this.provinceIndex.get(provinceCode) || [];
  }

  findInCity(provinceCode, cityCode) {
    const key = `${provinceCode}${cityCode}`;
    return this.cityIndex.get(key) || [];
  }
}

// Usage
const index = new AdministrativeIndex(data);
const beijing = index.findByCode('110000');
const byName = index.findByName('武汉市');
const inHubei = index.findInProvince('42');
const inWuhan = index.findInCity('42', '01');
```

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

### Importing Utilities from Utils Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/03-utility-functions.md

Import utility functions from the '@province-city-china/utils' sub-package for specific utility needs.

```typescript
import { sortProvince, findCityChild, findAreaChild } from '@province-city-china/utils';
```

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

### Combined Usage Pattern for Hierarchical Navigation

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/03-utility-functions.md

Demonstrates how to use utility functions to retrieve and navigate hierarchical province, city, and area data. Ensure the 'data' is imported correctly.

```typescript
import { data } from 'province-city-china/data';
import { sortProvince, findCityChild, findAreaChild } from '@province-city-china/utils';

// Step 1: Get province hierarchy
const provinces = sortProvince(data, 0); // Provinces only
const provinceWithCities = sortProvince(data, 1); // With cities
const fullHierarchy = sortProvince(data); // Full 3-level hierarchy

// Step 2: Find cities in a province (if needed dynamically)
const citiesInHubei = findCityChild(data, '42');

// Step 3: Find areas in a city
const areasInWuhan = findAreaChild(data, '420100');

// Step 4: Navigate from the hierarchy
const firstProvince = provinces[0]; // { code: "110000", name: "北京市" }
const citiesInProvince = findCityChild(data, '11'); // Get cities dynamically
```

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

### Province Level Codes

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/07-data-codes-reference.md

Represents full province-level administrative divisions. Each entry starts with a two-digit province code.

```text
110000 | 北京市      | Province code 11
120000 | 天津市      | Province code 12
130000 | 河北省      | Province code 13
360000 | 江西省      | Province code 36
420000 | 湖北省      | Province code 42
```

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

### Get Cities in a Province

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Find and display all cities within a specific province using its code. Requires the data package.

```typescript
import { findCityChild } from 'province-city-china';
import { data } from 'province-city-china/data';

// Get all cities in Guangdong (code 44)
const cities = findCityChild(data, '44');

cities.forEach(city => {
  console.log(`${city.code} ${city.name}`);
});
```

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

### Retrieve Parent Information

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Get the parent province, city, and area information for a given data item. This involves searching the data based on hierarchical codes.

```typescript
import { data } from 'province-city-china/data';

function getParent(item) {
  // Find province
  const province = data.find(d => d.province === item.province && d.city === 0);
  
  // Find city (if applicable)
  const city = data.find(d => 
    d.province === item.province && 
    d.city === item.city && 
    d.area === 0
  );
  
  // Find area (if applicable)
  const area = data.find(d =>
    d.province === item.province &&
    d.city === item.city &&
    d.area === item.area &&
    d.town === 0
  );
  
  return { province, city, area };
}
```

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

### React Hierarchical Tree Component

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Generate a hierarchical tree structure for provinces and their cities using React. This example utilizes the sortProvince utility function to organize the data.

```typescript
import React from 'react';
import { sortProvince } from 'province-city-china';
import { data } from 'province-city-china/data';

export function ProvinceTree() {
  const hierarchy = sortProvince(data, 1); // Province + City level

  return (
    <ul>
      {hierarchy.map(province => (
        <li key={province.code}>
          {province.name}
          {province.children && (
            <ul>
              {province.children.map(city => (
                <li key={city.code}>{city.name}</li>
              ))}
            </ul>
          )}
        </li>
      ))}
    </ul>
  );
}
```

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

### Basic Usage of Province-City-China Utilities

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/README.md

Demonstrates how to import and use utility functions for sorting provinces and finding child cities or areas. Requires importing data separately.

```typescript
// Import utilities
import { sortProvince, findCityChild, findAreaChild } from 'province-city-china';
import { data } from 'province-city-china/data';

// Get provinces with hierarchy
const provinces = sortProvince(data, 3);

// Find cities in a province
const cities = findCityChild(data, '42'); // Hubei

// Find areas in a city
const areas = findAreaChild(data, '420100'); // Wuhan
```

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

### Get Nanchang Districts using findAreaChild

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/03-utility-functions.md

Shows how to find all area-level districts for Nanchang, a city within a regular province, using its full city code '360100'.

```typescript
const nanchangDistricts = findAreaChild(data, '360100');

// Result:
// [
//   { code: "360102", name: "东湖区", area: "02" },
//   { code: "360103", name: "西湖区", area: "03" },
//   ...
// ]
```

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

### Import Pattern 2: Granular Package Imports

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

This pattern is recommended for production environments with specific needs, allowing for more targeted imports from granular packages like '@province-city-china/core', '@province-city-china/types', and '@province-city-china/data'.

```typescript
// Utilities
import { sortProvince } from '@province-city-china/core';

// Types
import type { Province, City } from '@province-city-china/types';

// Data
import data from '@province-city-china/data/data.json';
import hierarchy from '@province-city-china/level/level.json';
```

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

### Build Full 3-Level Hierarchy with sortProvince

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/03-utility-functions.md

Use `sortProvince` with default parameters to convert flat administrative data into a complete 3-level hierarchy (province, city, area). Ensure the `data` is imported from `province-city-china/data` and `sortProvince` from `@province-city-china/utils`.

```typescript
import { data } from 'province-city-china/data';
import { sortProvince } from '@province-city-china/utils';

const hierarchy = sortProvince(data);

// Result structure:
// [
//   {
//     code: "110000",
//     name: "北京市",
//     children: [
//       {
//         code: "110100",
//         name: "朝阳区",
//         children: [...] 
//       }
//     ]
//   },
//   ...
// ]
```

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

### Utils/Core Modules Exports

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/06-api-reference.md

The utility modules provide the same sorting and child-finding functions as the main package, intended for direct use or as an alternative import path.

```APIDOC
## Module: @province-city-china/utils or @province-city-china/core

### Description
Provides utility functions for sorting and retrieving hierarchical location data.

### Exports

#### Functions

##### sortProvince

- **Description**: Sorts an array of hierarchical data by province level.
- **Parameters**:
  - `arr` (Level[]): The array of data to sort.
  - `level` (number, optional): The level to sort by.
- **Returns**: `Level[]` - The sorted array.

##### findCityChild

- **Description**: Finds child cities for a given province code.
- **Parameters**:
  - `arr` (Level[]): The array of data to search within.
  - `code` (string): The code of the province to find children for.
  - `level` (number, optional): The level to filter by.
- **Returns**: `City[]` - An array of child cities.

##### findAreaChild

- **Description**: Finds child areas for a given city code.
- **Parameters**:
  - `arr` (Level[]): The array of data to search within.
  - `code` (string): The code of the city to find children for.
  - `level` (number, optional): The level to filter by.
- **Returns**: `Area[]` - An array of child areas.
```

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

### Import Individual Data Packages (ES Modules)

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Import data arrays from individual packages for provinces, cities, areas, towns, levels, countries, and district codes using ES Modules.

```typescript
// Default export is the array
import provinces from '@province-city-china/province';
// OR
const provinces = require('@province-city-china/province');
```

```typescript
import cities from '@province-city-china/city';
```

```typescript
import areas from '@province-city-china/area';
```

```typescript
import towns from '@province-city-china/town';
```

```typescript
import hierarchy from '@province-city-china/level';
```

```typescript
import countries from '@province-city-china/country';
```

```typescript
import districtCodes from '@province-city-china/district-code';
```

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

### Total Data Minified Keys (JSON)

Source: https://github.com/uiwjs/province-city-china/blob/master/README.md

Mapping of minified keys to their original names for total administrative data.

```json
code: 'c'
name: 'n'
province: 'p'
city: 'y'
area: 'a'
town: 't'
```

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

### Importing Utilities from Core Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/03-utility-functions.md

Import utility functions from the '@province-city-china/core' sub-package, which may contain core functionalities.

```typescript
import { sortProvince, findCityChild, findAreaChild } from '@province-city-china/core';
```

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

### Monorepo Directory Structure

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Illustrates the hierarchical organization of packages within the monorepo. Each package serves a distinct purpose, from type definitions to specific data levels.

```text
province-city-china/
├── package.json (root/workspace config)
├── packages/
│   ├── types/           (Type definitions)
│   ├── core/            (Utility functions)
│   ├── utils/           (Utility re-exports)
│   ├── data/            (Complete administrative data)
│   ├── province/        (Province-level data)
│   ├── city/            (City-level data)
│   ├── area/            (Area-level data)
│   ├── town/            (Town-level data)
│   ├── level/           (Hierarchical data structure)
│   ├── country/         (Country/region codes)
│   └── district-code/   (Telephone area codes)
└── dist/                (Built distribution files)
```

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

### Import Data Module (CommonJS)

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Import all administrative divisions data using CommonJS from the dedicated data module.

```typescript
// CommonJS - data
const { data, province, city, area, town, level } = require('province-city-china/data');
```

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

### Import Data Module (ES Modules)

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Import individual JSON data files for administrative divisions using ES Modules.

```typescript
// ES Modules - individual files
import data from 'province-city-china/dist/data.json';
import province from 'province-city-china/dist/province.json';
import city from 'province-city-china/dist/city.json';
import area from 'province-city-china/dist/area.json';
import town from 'province-city-china/dist/town.json';
import level from 'province-city-china/dist/level.json';
```

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

### String Matching for Hierarchical Queries

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/07-data-codes-reference.md

Demonstrates how to use string prefix matching or regular expressions in TypeScript to filter data based on administrative code prefixes, useful for retrieving all entries under a specific region.

```typescript
// Code prefix matching for hierarchical queries
const code = "420100";
data.filter(item => item.code.startsWith(code))  // Gets all items under Wuhan
```

```typescript
// OR with RegExp
const pattern = new RegExp(`^${code}`);
data.filter(item => pattern.test(item.code))
```

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

### Type Imports

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/INDEX.md

Shows how to import type definitions for Province, City, Area, Data, and Level from both the main package and the dedicated types package.

```typescript
// From main package
import type { Province, City, Area, Data, Level } from 'province-city-china';
```

```typescript
// From types package
import type { Province, City, Area, Data, Level } from '@province-city-china/types';
```

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

### Import from Main Package (CommonJS)

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Import all data and utilities or specific functions from the main package using CommonJS.

```typescript
// CommonJS
const { data, province, city, area, town, level, sortProvince, findCityChild, findAreaChild } = require('province-city-china/data');

// OR with specific imports
const { sortProvince, findCityChild, findAreaChild } = require('province-city-china');
```

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

### Import Data Modules (ES Modules)

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Import data modules such as data, province, city, area, town, and level using ES module syntax. These imports point to JSON files within the dist/ directory.

```typescript
import data from 'province-city-china/dist/data.json';
import province from 'province-city-china/dist/province.json';
import city from 'province-city-china/dist/city.json';
import area from 'province-city-china/dist/area.json';
import town from 'province-city-china/dist/town.json';
import level from 'province-city-china/dist/level.json';

```

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

### Import Data Package

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/02-data-packages.md

Import the data from the package using either CommonJS or ES Modules syntax. The default export provides the full dataset.

```typescript
// CommonJS
const data = require('@province-city-china/data');

// ES Modules
import data from '@province-city-china/data/data.json';
```

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

### Import Pattern 4: Mixed CommonJS and ESM

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

This pattern demonstrates how to handle mixed CommonJS and ES Module environments, using 'require' for CommonJS modules and 'import' for ES modules, including JSON imports with bundler support.

```typescript
// CommonJS require
const { data, province, city } = require('province-city-china/data');

// ES import
import { sortProvince } from 'province-city-china';

// JSON import (with bundler support)
import areas from '@province-city-china/area/area.json';
```

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

### Package Dependency Graph

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

Visualizes the dependency relationships between the different packages in the monorepo. It shows how core utilities and data packages are consumed by higher-level packages and the main package.

```text
@province-city-china/types (base types)
├── @province-city-china/core (utilities)
├── @province-city-china/utils (utilities wrapper)
├── @province-city-china/data (complete data)
├── @province-city-china/province (province data)
├── @province-city-china/city (city data)
├── @province-city-china/area (area data)
├── @province-city-china/town (town data)
├── @province-city-china/level (hierarchical data)
├── @province-city-china/country (country data)
└── @province-city-china/district-code (telephone codes)

province-city-china (main package, includes all above)
```

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

### HTML Form with Cascading Selects

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Use this HTML structure and JavaScript to create a dynamic location selector. It populates provinces, then cities based on province selection, and finally areas based on city selection. Ensure the `province-city-china` library is imported.

```html
<form id="location-form">
  <div>
    <label for="province">Province:</label>
    <select id="province">
      <option value="">Select</option>
    </select>
  </div>
  <div>
    <label for="city">City:</label>
    <select id="city" disabled>
      <option value="">Select</option>
    </select>
  </div>
  <div>
    <label for="area">Area:</label>
    <select id="area" disabled>
      <option value="">Select</option>
    </select>
  </div>
</form>
```

```javascript
import { findCityChild, findAreaChild } from 'province-city-china';
import provinces from 'province-city-china/dist/province.json';
import data from 'province-city-china/dist/data.json';

const provinceSelect = document.getElementById('province');
const citySelect = document.getElementById('city');
const areaSelect = document.getElementById('area');

// Populate provinces
provinces.forEach(p => {
  const option = document.createElement('option');
  option.value = p.province;
  option.textContent = p.name;
  provinceSelect.appendChild(option);
});

// Update cities when province changes
provinceSelect.addEventListener('change', (e) => {
  citySelect.innerHTML = '<option value="">Select</option>';
  areaSelect.innerHTML = '<option value="">Select</option>';
  areaSelect.disabled = true;

  if (e.target.value) {
    const cities = findCityChild(data, e.target.value);
    cities.forEach(c => {
      const option = document.createElement('option');
      option.value = c.code;
      option.textContent = c.name;
      citySelect.appendChild(option);
    });
    citySelect.disabled = false;
  } else {
    citySelect.disabled = true;
  }
});

// Update areas when city changes
citySelect.addEventListener('change', (e) => {
  areaSelect.innerHTML = '<option value="">Select</option>';

  if (e.target.value) {
    const areas = findAreaChild(data, e.target.value);
    areas.forEach(a => {
      const option = document.createElement('option');
      option.value = a.code;
      option.textContent = a.name;
      areaSelect.appendChild(option);
    });
    areaSelect.disabled = false;
  } else {
    areaSelect.disabled = true;
  }
});
```

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

### Import Pattern 3: Distributed Files Only

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/04-module-structure.md

This pattern is ideal for tree-shaking and minimizing bundle size by importing directly from distributed JSON files. It also imports types from '@province-city-china/types'.

```typescript
import data from 'province-city-china/dist/data.json';
import level from 'province-city-china/dist/level.json';
import country from 'province-city-china/dist/country.json';

import type { Data, Level, Country } from '@province-city-china/types';
```

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

### Import and Use District Code Data

Source: https://github.com/uiwjs/province-city-china/blob/master/packages/district-code/README.md

Import the district code data using require and access it as a JavaScript array.

```javascript
const data = require('@province-city-china/district-code')
// => [....]
```

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

### Import Raw Data from Province-City-China

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/05-quick-start.md

Import different JSON data files for complete data, specific levels like provinces, cities, areas, or hierarchical structures. Also includes imports for country and district code data.

```typescript
// Complete data
import data from 'province-city-china/dist/data.json';

// Specific levels
import provinces from 'province-city-china/dist/province.json';
import cities from 'province-city-china/dist/city.json';
import areas from 'province-city-china/dist/area.json';

// Hierarchical structure
import hierarchy from 'province-city-china/dist/level.json';

// Other data
import countries from 'province-city-china/dist/country.json';
import districtCodes from 'province-city-china/dist/district-code.json';
```

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

### Importing Type Definitions

Source: https://github.com/uiwjs/province-city-china/blob/master/_autodocs/README.md

Import type definitions for various administrative levels and data structures from the main package.

```typescript
import type { 
  Base, Province, City, Area, Town, Data, Level, Country 
} from 'province-city-china';
```