address-complete-divide

About

住所を補完・分割するための API で、簡単には以下の機能を提供します。

1. 郵便番号から住所を補完する
2. 住所を分割する

Request Body

{
  [
    {
      "zipcode": "105-0011",
      "address": "芝公園４丁目２−８"
    },
    {
      "zipcode": "",
      "address": "東京都千代田区千代田1番1号"
    },
    {
      "zipcode": "1000014",
      "address": "永田町１丁目７−１国会議事堂１２３号室"
    }
  ]
}

上記リクエストに対して、下記のようなレスポンスを期待します

Response Body

{
  "completed_count": 2,
  "addresses": [
    {
      "prefecture": "東京都",
      "city": "港区",
      "town": "芝公園",
      "house_number": "4-2-8",
      "building_name": "",
      "room_number": ""
    },
    {
      "prefecture": "東京都",
      "city": "千代田区",
      "town": "千代田",
      "house_number": "1-1",
      "building_name": "",
      "room_number": ""
    },
    {
      "prefecture": "東京都",
      "city": "永田町",
      "town": "",
      "house_number": "1-7-1",
      "building_name": "国会議事堂",
      "room_number": "123号室"
    }
  ]
}

EndPoints

POST /convert/complete_and_divide_address - 郵便番号から住所を補完し、分割する

簡単な仕様については上記の通り。 詳しい仕様については、How to Complete and Divide Address を参照すること。

GET /health - 正常にサーバーが動いているかの確認

正常であるとき、

{
  "status": "ok"
}

を返す

/docs - FastAPI の Swagger UI

上の2 つのエンドポイントを実際に叩き、挙動を確認することができる。

How to get address info from zipcode

DynamoDB上に、郵便番号から一意に、都道府県・市区町村・町域の情報が決まる住所情報について保存し、郵便番号情報から、それ以外の情報を取得している。

現在（2023/07/05 23:30）は、117,712個の住所データが保存されている。

(例:)

郵便番号と住所のデータは郵便番号データ を利用している。 (DB更新のためのリポジトリ)

（参考）外部APIを叩いて住所を補完する方法

郵便番号検索 API を利用する

利用規約

禁止事項

ユーザは、本 API の利用に際して、以下の各号に定める事項を行ってはならないものとします。

1. 形態の如何を問わず、本規約の定めに反する態様で本 API を利用すること
2. 本 API により提供される機能のみを提供することを目的とした対象サイトにおいて本 API を利用すること、およびこれと同視し得るような態様にて対象サイトにて本 API を利用すること
3. 法律、規則、条例等の制定法に反する行為、又はそれを勧誘・助長する行為
4. 虚偽の情報をコンテンツに掲載し、コンテンツ閲覧者を欺く行為
5. 当社または第三者の知的財産権その他の権利を侵害する内容
6. 本 API の運営、又はネットワークやシステムを妨害する行為
7. 当社が、過度若しくは不適切と判断する商用目的の宣伝・広告行為
8. 有害なコンピュータウィルス、コード、ファイル、プログラム等を開示する行為、若しくは開示されている場所について示唆する行為
9. 犯罪行為に関わる内容、差別的表現その他公序良俗に反する内容
10. アダルトコンテンツ、不潔またはグロテスクなコンテンツ等一般人が不快感を覚える内容その他青少年も含めた不特定多数のユーザによる閲覧に適さない内容
11. 選挙の事前運動、選挙運動またはこれらに類似する行為、および公職選挙法に抵触する行為
12. その他公序良俗、一般常識に反する行為
13. その他当社が不適切であると判断する行為

endpoint は次の通り https://zipcloud.ibsnet.co.jp/api/search

（例）郵便番号「7830060」で検索する場合 https://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060

Response は以下の通り

{
  "message": null,
  "results": [
    {
      "address1": "北海道",
      "address2": "美唄市",
      "address3": "上美唄町協和",
      "kana1": "ﾎｯｶｲﾄﾞｳ",
      "kana2": "ﾋﾞﾊﾞｲｼ",
      "kana3": "ｶﾐﾋﾞﾊﾞｲﾁｮｳｷｮｳﾜ",
      "prefcode": "1",
      "zipcode": "0790177"
    },
    {
      "address1": "北海道",
      "address2": "美唄市",
      "address3": "上美唄町南",
      "kana1": "ﾎｯｶｲﾄﾞｳ",
      "kana2": "ﾋﾞﾊﾞｲｼ",
      "kana3": "ｶﾐﾋﾞﾊﾞｲﾁｮｳﾐﾅﾐ",
      "prefcode": "1",
      "zipcode": "0790177"
    }
  ],
  "status": 200
}

Merit

• DB を作成する必要がないので実装が容易(多分)
• 郵便番号と住所の対応に変動があってもこちらで対応する必要がない

Demerit

• フロント -> API -> 郵便番号検索 API は少し冗長な気がする
  • ボトルネックになって方法 2 よりも実行時間がかかる
    • 1000個の住所について補完を行う際に、自前のDBを使うと30秒で終わる処理が、この方法だと5分以上かかる

How to Complete and Divide Address

後々追記予定

How to Use

Up the docker container if change requirements.txt or Dockerfile or docker-compose.yml

docker-compose build

And

docker-compose up

And Access any endpoint, such as http://0.0.0.0:8000/docs

dependencies の更新に関しては、Python: Create requirements.txt From Poetryを参照。

References

Python

Python: 3.11.1

Poetry

Package Manager: Poetry Basic Usage

• Install a pre-existing project

  poetry init

• Install a package

  poetry add <package>

• Activate the virtual environment

  poetry shell

• Install the dependencies

  poetry install

• Run Pytest

  poetry run pytest

Create requirements.txt From Poetry

Docker 環境ではrequirements.txtを使用するため、poetryからrequirements.txtを作成する必要がある。 poetry 経由で dependencies を追加した場合は、requirements.txtを更新する必要がある。 また、docker compose は一度 build したイメージをキャッシュするため、requirements.txtを更新した場合は、docker-compose build --no-cacheを実行する必要がある。

(もしくは docker compose up --buildを実行すること)

poetry export --output requirements.txt

FastAPI

docker/development/Dockerfileにて、--reloadオプションを使用しているため、開発環境では、ファイルの変更を検知し、自動的に再起動する。

Error Solve Log