{
  "openapi": "3.1.0",
  "info": {
    "title": "シルギア 住所の表記をそろえるAPI",
    "version": "1.0.0",
    "description": "登録不要・無料の、住所の表記をそろえるAPI。住所の書き方の違い（全角・半角、漢数字と算用数字、ヶ・が、丁目・番・号、都道府県名・郡名・政令指定都市の区名の省略、先頭の郵便番号）を、日本郵便の郵便番号データの正式な書き方にそろえ、都道府県・市区町村・町域・丁目・番地・建物名に分けて返します。郵便番号と市区町村コード（5桁・検査数字付き6桁）も返します。番地・建物名が実在するかは確かめません。「1-2-3」の最初の数が丁目かどうかは推測しません（「◯丁目」と書いてあるときだけ chome）。かな書きの町名は対象外です。住所が見つからなくても 404 にはせず、200 で level = 0 を返します。入力した住所はシルギアの利用の記録には残しません（記録するのは URL のパスだけで、?q= 以降は残しません）。ただし、サーバー会社の標準のアクセスログには URL が一定期間残ります。説明: https://api.shirugear.com/address/ 。v1 の中では項目を足すことはあっても、名前や意味は変えません（知らない項目は無視してください）。",
    "termsOfService": "https://api.shirugear.com/terms/",
    "contact": {
      "name": "アナライズギア株式会社（シルギア）",
      "url": "https://shirugear.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.shirugear.com"
    }
  ],
  "paths": {
    "/address/v1/normalize.json": {
      "get": {
        "summary": "住所の表記をそろえて、都道府県・市区町村・町域・番地に分ける",
        "operationId": "normalizeAddress",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "住所（200文字まで・URLエンコード）。例: 東京都千代田区一番町1-2-3",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "example": "東京都千代田区一番町１－２－３"
          }
        ],
        "responses": {
          "200": {
            "description": "結果（見つからないときも 200 で level = 0）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Address"
                }
              }
            }
          },
          "400": {
            "description": "q が無い・空・200文字を超える",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Zipcode": {
        "type": "object",
        "required": [
          "zipcode",
          "note"
        ],
        "properties": {
          "zipcode": {
            "type": "string",
            "pattern": "^[0-9]{7}$"
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "郵便番号データの但し書き（例: １〜１９丁目）"
          }
        }
      },
      "Candidate": {
        "type": "object",
        "required": [
          "prefecture",
          "city",
          "jiscode"
        ],
        "properties": {
          "prefecture": {
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "type": "string"
          },
          "jiscode": {
            "type": "string",
            "pattern": "^[0-9]{5}$"
          }
        }
      },
      "Address": {
        "type": "object",
        "required": [
          "input",
          "level",
          "normalized",
          "prefecture",
          "prefecture_kana",
          "prefcode",
          "city",
          "city_kana",
          "jiscode",
          "lgcode",
          "town",
          "town_kana",
          "street",
          "chome",
          "banchi",
          "building",
          "rest",
          "zipcode",
          "zipcodes",
          "candidates",
          "data_version"
        ],
        "properties": {
          "input": {
            "type": "string",
            "description": "受け取った住所（全角の英数字・記号を半角にし、前後の空白と先頭の郵便番号を外したもの）"
          },
          "level": {
            "type": "integer",
            "enum": [
              0,
              1,
              2,
              3
            ],
            "description": "0＝見つからない（または決まらない）、1＝都道府県まで、2＝市区町村まで、3＝町域まで"
          },
          "normalized": {
            "type": [
              "string",
              "null"
            ],
            "description": "そろえた住所。level 0 のときは null"
          },
          "prefecture": {
            "type": [
              "string",
              "null"
            ]
          },
          "prefecture_kana": {
            "type": [
              "string",
              "null"
            ],
            "description": "読み（カタカナ）"
          },
          "prefcode": {
            "type": [
              "string",
              "null"
            ],
            "description": "都道府県コード（2桁）"
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "description": "市区町村名（郡・政令指定都市の区を含む）"
          },
          "city_kana": {
            "type": [
              "string",
              "null"
            ]
          },
          "jiscode": {
            "type": [
              "string",
              "null"
            ],
            "description": "市区町村コード（5桁）"
          },
          "lgcode": {
            "type": [
              "string",
              "null"
            ],
            "description": "検査数字付きの6桁の地方公共団体コード"
          },
          "town": {
            "type": [
              "string",
              "null"
            ],
            "description": "町域名（郵便番号データの書き方）"
          },
          "town_kana": {
            "type": [
              "string",
              "null"
            ]
          },
          "street": {
            "type": [
              "string",
              "null"
            ],
            "description": "京都市の通り名。ほかは null"
          },
          "chome": {
            "type": [
              "integer",
              "null"
            ],
            "description": "丁目の数（「◯丁目」と書いてあるときだけ）"
          },
          "banchi": {
            "type": [
              "string",
              "null"
            ],
            "description": "番地・号を - でつないだもの（例: 1-2-3）"
          },
          "building": {
            "type": [
              "string",
              "null"
            ],
            "description": "番地のあとに残った部分（建物名など）"
          },
          "rest": {
            "type": [
              "string",
              "null"
            ],
            "description": "町域が見つからなかったときの残りの部分"
          },
          "zipcode": {
            "type": [
              "string",
              "null"
            ],
            "description": "郵便番号（7桁）。1つに決まったときだけ"
          },
          "zipcodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Zipcode"
            },
            "description": "町域の郵便番号すべて"
          },
          "candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Candidate"
            },
            "description": "市区町村が1つに決まらないときの候補"
          },
          "data_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "郵便番号データの版（YYYY-MM）"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_query",
                  "region_not_allowed",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
