# address_normalizer

**Repository Path**: computing/address_normalizer

## Basic Information

- **Project Name**: address_normalizer
- **Description**: 地址标准化库，用于识别判断标准化地址，并对该地址识别提取省市区，返回对应的code代码
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-01-08
- **Last Updated**: 2025-01-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Address Normalizer

## 概述

Address Normalizer 是一个基于中文地址的标准化工具，具有自动纠错功能。它可以将用户输入的地址进行标准化处理，并自动修正输入错误的区域名称或其他常见错误，以确保地址的准确性和规范性。

## 功能特性

- **地址标准化**：根据用户输入的地址，将其转换为标准格式，包括省、市、区（县）、以及其他详细地址信息。
- **自动纠错**：如果用户输入的地址中存在错误（例如区名拼写错误），系统会自动识别并修正这些错误。
- **地址验证**：如果输入的地址无效，系统将返回错误信息，提示用户检查地址的有效性。

## 请求示例

### 成功的标准化请求

输入地址：`福建省厦门市思明区鹭江道1020号`

标准化结果：

```json
{
  "Msg": "请求成功",
  "StandardAddress": {
    "province": "福建省",
    "city": "厦门市",
    "district": "思明区",
    "other_address": "鹭江道1020号",
    "standard_address": "福建省厦门市思明区鹭江道1020号"
  },
  "StatusCode": 200
}
```

### 无效地址示例

输入地址：`1111`

返回结果：

```json
{
  "Msg": "无效地址，请检查地址的有效性！",
  "StandardAddress": {
    "invalid_address": "1111"
  },
  "StatusCode": 500
}
```

## 安装与使用

### 安装

通过 `pip` 安装 Address Normalizer：

```bash
pip install -r requirements.txt
```

### 函数说明

`normalize_address(address: str) -> dict`

- **参数**：
    - `address`: 要标准化的地址字符串。
- **返回**：
    - 返回一个字典，包含标准化后的地址信息或错误提示信息。

## 返回结果说明

- `Msg`: 请求的状态信息。成功时返回 "请求成功"，失败时返回 "无效地址，请检查地址的有效性！"。
- `StandardAddress`: 一个字典，包含标准化后的地址信息或原始无效地址。
    - `province`: 省份名称
    - `city`: 城市名称
    - `district`: 区/县名称
    - `other_address`: 除省、市、区外的其他地址信息
    - `standard_address`: 完整的标准化后的地址
    - `invalid_address`: 原始输入的无效地址（仅在失败时返回）
- `StatusCode`: HTTP 状态码，成功为 `200`，失败为 `500`。

## 错误处理

在使用 Address Normalizer 过程中，如果输入地址无效，系统会返回带有 `StatusCode: 500` 的错误信息。请确保输入的地址格式正确，并包含省、市、区等必要信息。

## 写给开发者

### 数据文件说明

以下是 data 文件夹下每个文件的用途：

- **[address_code.xlsx](address_normalizer%2Fdata%2Faddress_code.xlsx)**：用于生成地名层级结构，如北京朝阳等。
- **[address_patterns.txt](address_normalizer%2Fdata%2Faddress_patterns.txt)**：配置 `config` 中 `TOKENIZE_MODEL` 为 `rule` 时用到的文件，主要用于 NER 识别。
- **[china_regions.json](address_normalizer%2Fdata%2Fchina_regions.json)**：用于查看层级结构是否正确。
- **[jieba_patterns.txt](address_normalizer%2Fdata%2Fjieba_patterns.txt)**：配置 `config` 中 `TOKENIZE_MODEL` 为 `jieba` 时用到的文件。
- **[province_city_district.csv](address_normalizer%2Fdata%2Fprovince_city_district.csv)**：用于纠错和补全，当提取到区域时会在该文件中查找该区，若能找到唯一一条记录，则自动补全其他省市区信息。