{
  "openapi": "3.1.0",
  "info": {
    "title": "住所 API（逆ジオコーディング・郵便番号）",
    "version": "2.0.0",
    "description": "日本の住所を調べる REST API です。緯度経度から一番近い町字（都道府県・市区町村・大字・町・丁目・小字）と、郵便番号から住所の候補を返します。認証は不要で、どのサイトからも読めます（CORS）。\n\n- リソースが無いときは 404、パラメータの誤りは 400、日本の範囲外は 422、メソッド違いは 405（Allow ヘッダー付き）\n- エラーは RFC 9457 の application/problem+json（type・title・status・detail と、理由のコード error）\n- 逆ジオコーディングは町字の代表点（1 点）のうち一番近いものを返します。区域の形は使っていないので、境界の近くでは隣の町字になることがあります\n- 旧 URL（/geo/zip/?code=、/geo/reverse/?lat=&lon=）は 308 で新しい URL に転送します\n- 出典：デジタル庁 アドレス・ベース・レジストリ（CC BY 4.0）を加工して作成。日本郵便 郵便番号データ。結果を表示するときは出典を表示してください"
  },
  "servers": [
    {
      "url": "https://api.hasami.uk"
    }
  ],
  "paths": {
    "/geo/zipcodes/{zipcode}": {
      "get": {
        "summary": "郵便番号の住所",
        "operationId": "getZipcode",
        "parameters": [
          {
            "name": "zipcode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1000005",
            "description": "郵便番号 7 桁（100-0005 のようなハイフン・全角数字も可）"
          }
        ],
        "responses": {
          "200": {
            "description": "その郵便番号の住所（1 つの番号に複数の町域があることもある）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "zipcode": {
                      "type": "string"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Zip"
                      }
                    },
                    "attribution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/geo/zipcodes": {
      "get": {
        "summary": "郵便番号の前方一致",
        "operationId": "searchZipcodes",
        "description": "該当が無ければ results は空の配列（200）。",
        "parameters": [
          {
            "name": "prefix",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "100",
            "description": "郵便番号の先頭 3〜6 桁"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "一覧",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prefix": {
                      "type": "string"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Zip"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "attribution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/geo/towns/nearest": {
      "get": {
        "summary": "緯度経度に近い町字（近い順）",
        "operationId": "nearestTowns",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": 20,
              "maximum": 46.5
            },
            "example": 35.681236,
            "description": "緯度（10 進、世界測地系）"
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": 122,
              "maximum": 154.5
            },
            "example": 139.767125,
            "description": "経度（10 進、世界測地系）"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 1
            },
            "description": "近い順に返す件数"
          }
        ],
        "responses": {
          "200": {
            "description": "近い順の町字",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReverseResult"
                },
                "example": {
                  "ok": true,
                  "query": {
                    "lat": 35.681236,
                    "lon": 139.767125,
                    "limit": 1
                  },
                  "results": [
                    {
                      "address": "東京都千代田区丸の内一丁目",
                      "pref": "東京都",
                      "city": "千代田区",
                      "oaza_cho": "丸の内",
                      "chome": "一丁目",
                      "koaza": "",
                      "lg_code": "131016",
                      "machiaza_id": "0011001",
                      "lat": 35.68156,
                      "lon": 139.767201,
                      "distance_m": 37
                    }
                  ],
                  "notice": "町字の代表点のうち一番近いものです。境界の近くでは隣の町字になることがあります。",
                  "attribution": "出典：デジタル庁 アドレス・ベース・レジストリ（CC BY 4.0）を加工して作成",
                  "data_date": "20261010"
                }
              }
            }
          },
          "400": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/geo/towns/{town_id}": {
      "get": {
        "summary": "町字 1 つ",
        "operationId": "getTown",
        "parameters": [
          {
            "name": "town_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{6}-\\d{7}$"
            },
            "example": "131016-0011001",
            "description": "全国地方公共団体コード 6 桁-町字 ID 7 桁"
          }
        ],
        "responses": {
          "200": {
            "description": "町字",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Town"
                }
              }
            }
          },
          "400": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/geo/zip/": {
      "get": {
        "summary": "（旧）郵便番号 — /geo/zipcodes に 308 で転送",
        "deprecated": true,
        "operationId": "legacyZip",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "308": {
            "description": "新しい URL へ（Location）"
          },
          "400": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/geo/reverse/": {
      "get": {
        "summary": "（旧）逆ジオコーディング — /geo/towns/nearest に 308 で転送",
        "deprecated": true,
        "operationId": "legacyReverse",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "308": {
            "description": "新しい URL へ（Location）"
          },
          "400": {
            "description": "エラー（RFC 9457）",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Town": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "都道府県から小字までつなげたもの"
          },
          "pref": {
            "type": "string"
          },
          "city": {
            "type": "string",
            "description": "郡・市・区（例: 札幌市中央区、八重山郡与那国町）"
          },
          "oaza_cho": {
            "type": "string",
            "description": "大字・町"
          },
          "chome": {
            "type": "string",
            "description": "丁目（元データの書き方のまま。一丁目・１丁目など）"
          },
          "koaza": {
            "type": "string",
            "description": "小字"
          },
          "lg_code": {
            "type": "string",
            "description": "全国地方公共団体コード（6 桁）"
          },
          "machiaza_id": {
            "type": "string",
            "description": "町字 ID（7 桁）"
          },
          "lat": {
            "type": "number",
            "description": "町字の代表点"
          },
          "lon": {
            "type": "number"
          },
          "distance_m": {
            "type": "integer",
            "description": "代表点までのおおよその距離（メートル）"
          }
        }
      },
      "ReverseResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "query": {
            "type": "object"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Town"
            }
          },
          "notice": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "data_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "元データの日付 YYYYMMDD"
          }
        }
      },
      "Zip": {
        "type": "object",
        "properties": {
          "zipcode": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "pref": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "town": {
            "type": "string",
            "description": "町域。「以下に掲載がない場合」などは空"
          },
          "note": {
            "type": "string",
            "description": "町域の括弧の中など（例: １～１９丁目、（市区町村の全域））"
          },
          "kana": {
            "type": "object",
            "properties": {
              "pref": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "town": {
                "type": "string"
              }
            },
            "description": "読み（全角カタカナ。日本郵便のデータのまま。町域の括弧の部分は除く）"
          },
          "lg_code": {
            "type": "string"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "lat": {
                "type": "number"
              },
              "lon": {
                "type": "number"
              }
            },
            "description": "町域と同じ名前の町字があれば、その代表点"
          }
        }
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "error"
        ],
        "properties": {
          "type": {
            "type": "string",
            "example": "about:blank"
          },
          "title": {
            "type": "string",
            "example": "Not Found"
          },
          "status": {
            "type": "integer",
            "example": 404
          },
          "detail": {
            "type": "string"
          },
          "error": {
            "type": "string",
            "description": "理由のコード",
            "enum": [
              "invalid_zipcode",
              "zipcode_not_found",
              "invalid_prefix",
              "missing_lat",
              "missing_lon",
              "invalid_lat",
              "invalid_lon",
              "invalid_limit",
              "out_of_range",
              "not_found",
              "invalid_town_id",
              "town_not_found",
              "unknown_parameter",
              "invalid_parameter",
              "method_not_allowed",
              "internal_error"
            ]
          }
        }
      }
    }
  }
}