{
  "openapi": "3.1.0",
  "info": {
    "title": "シルギア 郵便番号API",
    "version": "1.0.0",
    "description": "登録不要・無料の郵便番号API。日本郵便の郵便番号データをもとに、郵便番号から住所、住所から郵便番号を引けます。説明: https://api.shirugear.com/zip/ 。v1 の中では項目を足すことはあっても、名前や意味は変えません（知らない項目は無視してください）。",
    "termsOfService": "https://api.shirugear.com/terms/",
    "contact": {
      "name": "アナライズギア株式会社（シルギア）",
      "url": "https://shirugear.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.shirugear.com"
    }
  ],
  "paths": {
    "/zip/v1/{zipcode}.json": {
      "get": {
        "summary": "郵便番号から住所",
        "operationId": "getZip",
        "parameters": [
          {
            "name": "zipcode",
            "in": "path",
            "required": true,
            "description": "郵便番号（半角数字7桁・ハイフンなし）",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{7}$",
              "examples": [
                "1000001"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "見つかった（廃止された番号を含む）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ZipResponse"
                }
              }
            }
          },
          "400": {
            "description": "郵便番号の形が正しくない（invalid_zipcode）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "存在しない番号（zipcode_not_found）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/zip/v1/pref/{prefcode}.json": {
      "get": {
        "summary": "都道府県の市区町村の一覧",
        "operationId": "getPref",
        "parameters": [
          {
            "name": "prefcode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{2}$",
              "examples": [
                "13"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "市区町村の一覧",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrefResponse"
                }
              }
            }
          },
          "400": {
            "description": "invalid_prefcode",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "prefcode_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/zip/v1/city/{jiscode}.json": {
      "get": {
        "summary": "市区町村の町域と郵便番号の一覧",
        "operationId": "getCity",
        "parameters": [
          {
            "name": "jiscode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{5}$",
              "examples": [
                "13101"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "町域の一覧",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CityResponse"
                }
              }
            }
          },
          "400": {
            "description": "invalid_jiscode",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "jiscode_not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/zip/v1/meta.json": {
      "get": {
        "summary": "データの版と件数",
        "operationId": "getMeta",
        "responses": {
          "200": {
            "description": "データの版と件数",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetaResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ZipResult": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "description": "area=地域 / office=大口事業所 / pobox=私書箱",
            "enum": [
              "area",
              "office",
              "pobox"
            ]
          },
          "prefcode": {
            "type": "string",
            "description": "都道府県コード（2桁）",
            "pattern": "^[0-9]{2}$"
          },
          "jiscode": {
            "type": "string",
            "description": "全国地方公共団体コード（5桁）",
            "pattern": "^[0-9]{5}$"
          },
          "prefecture": {
            "type": "string"
          },
          "prefecture_kana": {
            "type": [
              "string",
              "null"
            ],
            "description": "全角カタカナ。事業所で補えないときは null"
          },
          "city": {
            "type": "string"
          },
          "city_kana": {
            "type": [
              "string",
              "null"
            ],
            "description": "全角カタカナ。事業所で補えないときは null"
          },
          "town": {
            "type": "string",
            "description": "町域名。町域が決まらない番号では空文字"
          },
          "town_kana": {
            "type": [
              "string",
              "null"
            ],
            "description": "全角カタカナ。town が空なら空文字。事業所で補えないときは null"
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "町域の注記。無ければ null。office/pobox では常に null"
          },
          "street": {
            "type": [
              "string",
              "null"
            ],
            "description": "番地以降（office/pobox のみ）"
          },
          "office_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "事業所名（office/pobox のみ）"
          },
          "office_name_kana": {
            "type": [
              "string",
              "null"
            ],
            "description": "事業所名のカナ（office/pobox のみ）"
          },
          "post_office": {
            "type": [
              "string",
              "null"
            ],
            "description": "取り扱う郵便局（office/pobox のみ）"
          }
        },
        "required": [
          "kind",
          "prefcode",
          "jiscode",
          "prefecture",
          "prefecture_kana",
          "city",
          "city_kana",
          "town",
          "town_kana",
          "note",
          "street",
          "office_name",
          "office_name_kana",
          "post_office"
        ]
      },
      "ZipResponse": {
        "type": "object",
        "required": [
          "zipcode",
          "results",
          "abolished",
          "data_version"
        ],
        "properties": {
          "zipcode": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "description": "地域 → 事業所 の順。廃止された番号では空",
            "items": {
              "$ref": "#/components/schemas/ZipResult"
            }
          },
          "abolished": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "month",
                  "previous",
                  "new_zipcodes"
                ],
                "properties": {
                  "month": {
                    "type": "string",
                    "description": "廃止された年月 YYYY-MM"
                  },
                  "previous": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string",
                          "enum": [
                            "area",
                            "office",
                            "pobox"
                          ]
                        },
                        "prefecture": {
                          "type": "string"
                        },
                        "city": {
                          "type": "string"
                        },
                        "town": {
                          "type": "string"
                        },
                        "office_name": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  },
                  "new_zipcodes": {
                    "type": "array",
                    "description": "移った先と考えられる番号（推定）。分からなければ空",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            ]
          },
          "data_version": {
            "type": "string",
            "description": "取り込んだ日本郵便のデータの月",
            "pattern": "^[0-9]{4}-[0-9]{2}$",
            "examples": [
              "2026-10"
            ]
          }
        }
      },
      "PrefResponse": {
        "type": "object",
        "required": [
          "prefcode",
          "prefecture",
          "prefecture_kana",
          "cities",
          "data_version"
        ],
        "properties": {
          "prefcode": {
            "type": "string"
          },
          "prefecture": {
            "type": "string"
          },
          "prefecture_kana": {
            "type": "string"
          },
          "cities": {
            "type": "array",
            "description": "全国地方公共団体コードの順",
            "items": {
              "type": "object",
              "properties": {
                "jiscode": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "city_kana": {
                  "type": "string"
                }
              }
            }
          },
          "data_version": {
            "type": "string",
            "description": "取り込んだ日本郵便のデータの月",
            "pattern": "^[0-9]{4}-[0-9]{2}$",
            "examples": [
              "2026-10"
            ]
          }
        }
      },
      "CityResponse": {
        "type": "object",
        "required": [
          "jiscode",
          "prefcode",
          "prefecture",
          "prefecture_kana",
          "city",
          "city_kana",
          "towns",
          "data_version"
        ],
        "properties": {
          "jiscode": {
            "type": "string"
          },
          "prefcode": {
            "type": "string"
          },
          "prefecture": {
            "type": "string"
          },
          "prefecture_kana": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "city_kana": {
            "type": "string"
          },
          "towns": {
            "type": "array",
            "description": "地域の番号の町域（事業所は含まない）。日本郵便のデータの並び。同じ町域名が別の番号で出ることがある",
            "items": {
              "type": "object",
              "properties": {
                "zipcode": {
                  "type": "string"
                },
                "town": {
                  "type": "string"
                },
                "town_kana": {
                  "type": "string"
                },
                "note": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "data_version": {
            "type": "string",
            "description": "取り込んだ日本郵便のデータの月",
            "pattern": "^[0-9]{4}-[0-9]{2}$",
            "examples": [
              "2026-10"
            ]
          }
        }
      },
      "MetaResponse": {
        "type": "object",
        "properties": {
          "data_version": {
            "type": "string",
            "description": "取り込んだ日本郵便のデータの月",
            "pattern": "^[0-9]{4}-[0-9]{2}$",
            "examples": [
              "2026-10"
            ]
          },
          "built_at": {
            "type": "string",
            "description": "データを作った日時（ISO 8601・UTC）",
            "format": "date-time"
          },
          "source": {
            "type": "string"
          },
          "counts": {
            "type": "object",
            "properties": {
              "zipcodes": {
                "type": "integer",
                "description": "住所が返る郵便番号の数（廃止を除く）"
              },
              "areas": {
                "type": "integer"
              },
              "offices": {
                "type": "integer"
              },
              "abolished": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer"
              },
              "code": {
                "type": "string",
                "description": "エラーの種類（固定値）",
                "enum": [
                  "invalid_zipcode",
                  "invalid_prefcode",
                  "invalid_jiscode",
                  "invalid_request",
                  "zipcode_not_found",
                  "prefcode_not_found",
                  "jiscode_not_found",
                  "not_found",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string",
                "description": "日本語の説明"
              }
            }
          }
        }
      }
    }
  }
}