{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan Luggage Check API",
    "version": "1.0.0",
    "description": "Will your suitcase fit on the Shinkansen, and what does it cost to forward it? Bags over 160 cm need an oversized-baggage seat on the Tokaido, Sanyo and Kyushu Shinkansen (¥1,000 fee if you skip it). Yamato TA-Q-BIN from Tokyo to Kyoto for a Size 160 suitcase is ¥3,160 cash / ¥2,870 cashless at current rates.\n\nFree, no API key, CORS open. Fair use: about 120 requests per minute per IP. Also available as MCP tools at https://free-agent-tools.vercel.app/mcp"
  },
  "servers": [
    {
      "url": "https://japan-luggage.vercel.app"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "japanLuggageCheck",
        "summary": "Japan suitcase check: Shinkansen oversized-baggage rule + Yamato TA-Q-BIN forwarding cost (current 2025-10 rates)",
        "description": "For a bag's outside dimensions (length + width + height incl. wheels) and weight: (1) Shinkansen rule — on the Tokaido, Sanyo, Kyushu and Nishi-Kyushu Shinkansen bags of 161–250 cm need a reserved oversized-baggage seat (free; ¥1,000 fee if unreserved), over 250 cm / 30 kg not allowed; JR East-area lines (Tohoku, Hokuriku, Joetsu, etc.) have no reservation. (2) Yamato TA-Q-BIN size class (60–200, larger of size or weight) and the one-way price between any two prefectures, or to an airport with Airport TA-Q-BIN (+¥660, send 2 days before departure), from Yamato's current cash and cashless tables (revised 2025-10-01; Yamato's English table is outdated). Returns verdict, prices, send-by date, recommendation, sources, rulesAsOf, disclaimer.\n\nExample: https://japan-luggage.vercel.app/api/check?lengthCm=75&widthCm=50&heightCm=30&weightKg=22&from=tokyo&to=kyoto&line=tokaido",
        "parameters": [
          {
            "name": "lengthCm",
            "in": "query",
            "required": false,
            "description": "Outside length in cm incl. wheels/handles. With widthCm + heightCm, or use totalCm.",
            "schema": {
              "type": "number",
              "description": "Outside length in cm incl. wheels/handles. With widthCm + heightCm, or use totalCm."
            }
          },
          {
            "name": "widthCm",
            "in": "query",
            "required": false,
            "description": "Outside width in cm.",
            "schema": {
              "type": "number",
              "description": "Outside width in cm."
            }
          },
          {
            "name": "heightCm",
            "in": "query",
            "required": false,
            "description": "Outside depth/height in cm.",
            "schema": {
              "type": "number",
              "description": "Outside depth/height in cm."
            }
          },
          {
            "name": "totalCm",
            "in": "query",
            "required": false,
            "description": "Length + width + height in cm, if you only know the total (e.g. 158).",
            "schema": {
              "type": "number",
              "description": "Length + width + height in cm, if you only know the total (e.g. 158)."
            }
          },
          {
            "name": "weightKg",
            "in": "query",
            "required": false,
            "description": "Packed weight in kg. Optional; Yamato uses the larger of size and weight class.",
            "schema": {
              "type": "number",
              "description": "Packed weight in kg. Optional; Yamato uses the larger of size and weight class."
            }
          },
          {
            "name": "pieces",
            "in": "query",
            "required": false,
            "description": "Number of identical bags.",
            "schema": {
              "type": "integer",
              "description": "Number of identical bags.",
              "default": 1,
              "minimum": 1,
              "maximum": 20
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Origin: prefecture (tokyo, kyoto, 東京都), common city (hakone, kanazawa, hiroshima), or airport id.",
            "schema": {
              "type": "string",
              "description": "Origin: prefecture (tokyo, kyoto, 東京都), common city (hakone, kanazawa, hiroshima), or airport id."
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Destination: prefecture, city, or airport id (haneda, narita, kix, itami, centrair, new-chitose, fukuoka-airport, naha-airport) for Airport TA-Q-BIN.",
            "schema": {
              "type": "string",
              "description": "Destination: prefecture, city, or airport id (haneda, narita, kix, itami, centrair, new-chitose, fukuoka-airport, naha-airport) for Airport TA-Q-BIN."
            }
          },
          {
            "name": "line",
            "in": "query",
            "required": false,
            "description": "Shinkansen line you will ride, or none.",
            "schema": {
              "type": "string",
              "description": "Shinkansen line you will ride, or none.",
              "enum": [
                "tokaido",
                "sanyo",
                "kyushu",
                "nishi-kyushu",
                "tohoku",
                "hokkaido",
                "joetsu",
                "hokuriku",
                "yamagata",
                "akita",
                "none"
              ],
              "default": "tokaido"
            }
          },
          {
            "name": "payment",
            "in": "query",
            "required": false,
            "description": "cash or cashless (credit card, QR, e-money, Apple Pay: cheaper).",
            "schema": {
              "type": "string",
              "description": "cash or cashless (credit card, QR, e-money, Apple Pay: cheaper).",
              "enum": [
                "cash",
                "cashless"
              ],
              "default": "cash"
            }
          },
          {
            "name": "dropOff",
            "in": "query",
            "required": false,
            "description": "You bring the bag to a Yamato office, agency or convenience store (¥100 off). Hotel front desk / pickup = false.",
            "schema": {
              "type": "boolean",
              "description": "You bring the bag to a Yamato office, agency or convenience store (¥100 off). Hotel front desk / pickup = false.",
              "default": false
            }
          },
          {
            "name": "departureDate",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD flight date when sending to an airport; returns the send-by date.",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD flight date when sending to an airport; returns the send-by date."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      },
      "post": {
        "operationId": "japanLuggageCheckPost",
        "summary": "Japan suitcase check: Shinkansen oversized-baggage rule + Yamato TA-Q-BIN forwarding cost (current 2025-10 rates) (JSON body)",
        "description": "For a bag's outside dimensions (length + width + height incl. wheels) and weight: (1) Shinkansen rule — on the Tokaido, Sanyo, Kyushu and Nishi-Kyushu Shinkansen bags of 161–250 cm need a reserved oversized-baggage seat (free; ¥1,000 fee if unreserved), over 250 cm / 30 kg not allowed; JR East-area lines (Tohoku, Hokuriku, Joetsu, etc.) have no reservation. (2) Yamato TA-Q-BIN size class (60–200, larger of size or weight) and the one-way price between any two prefectures, or to an airport with Airport TA-Q-BIN (+¥660, send 2 days before departure), from Yamato's current cash and cashless tables (revised 2025-10-01; Yamato's English table is outdated). Returns verdict, prices, send-by date, recommendation, sources, rulesAsOf, disclaimer.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "lengthCm": {
                    "type": "number",
                    "description": "Outside length in cm incl. wheels/handles. With widthCm + heightCm, or use totalCm."
                  },
                  "widthCm": {
                    "type": "number",
                    "description": "Outside width in cm."
                  },
                  "heightCm": {
                    "type": "number",
                    "description": "Outside depth/height in cm."
                  },
                  "totalCm": {
                    "type": "number",
                    "description": "Length + width + height in cm, if you only know the total (e.g. 158)."
                  },
                  "weightKg": {
                    "type": "number",
                    "description": "Packed weight in kg. Optional; Yamato uses the larger of size and weight class."
                  },
                  "pieces": {
                    "type": "integer",
                    "description": "Number of identical bags.",
                    "default": 1,
                    "minimum": 1,
                    "maximum": 20
                  },
                  "from": {
                    "type": "string",
                    "description": "Origin: prefecture (tokyo, kyoto, 東京都), common city (hakone, kanazawa, hiroshima), or airport id."
                  },
                  "to": {
                    "type": "string",
                    "description": "Destination: prefecture, city, or airport id (haneda, narita, kix, itami, centrair, new-chitose, fukuoka-airport, naha-airport) for Airport TA-Q-BIN."
                  },
                  "line": {
                    "type": "string",
                    "description": "Shinkansen line you will ride, or none.",
                    "enum": [
                      "tokaido",
                      "sanyo",
                      "kyushu",
                      "nishi-kyushu",
                      "tohoku",
                      "hokkaido",
                      "joetsu",
                      "hokuriku",
                      "yamagata",
                      "akita",
                      "none"
                    ],
                    "default": "tokaido"
                  },
                  "payment": {
                    "type": "string",
                    "description": "cash or cashless (credit card, QR, e-money, Apple Pay: cheaper).",
                    "enum": [
                      "cash",
                      "cashless"
                    ],
                    "default": "cash"
                  },
                  "dropOff": {
                    "type": "boolean",
                    "description": "You bring the bag to a Yamato office, agency or convenience store (¥100 off). Hotel front desk / pickup = false.",
                    "default": false
                  },
                  "departureDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD flight date when sending to an airport; returns the send-by date."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      }
    },
    "/api/rules": {
      "get": {
        "operationId": "japanLuggageRules",
        "summary": "Full rules: Shinkansen oversized-baggage rules by line, Yamato size classes, full cash and cashless TA-Q-BIN rate tables by region (revised 2025-10-01), airports",
        "description": "Returns the dated rules, rate tables, prefecture→region map, airports, sources, and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}