{
 "openapi": "3.1.0",
 "info": {
  "title": "kWhmate · Korea Survival Kit · 계산메이트 calculators API",
  "version": "1.0.0",
  "description": "Free, read-only calculators: electricity bills (Korea, Taiwan, Philippines, Japan), LED savings, Seoul/Busan taxi fares, Korea tax refund, and Korean education/finance calculators. Every response includes the official reference date and source line and the page URL. Results are estimates."
 },
 "servers": [
  {
   "url": "https://kwhmate.com"
  }
 ],
 "paths": {
  "/api/v1/kr-electricity": {
   "get": {
    "operationId": "krElectricity",
    "summary": "Korea household electricity bill (KEPCO residential low-voltage, progressive tiers)",
    "description": "Runs the same calculator as https://kwhmate.com/ko/electricity-bill/. Reference: 기준: 2026년 4분기 요금 · 출처: 한국전력공사 주택용 전력(저압) 요금표. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "kwh",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "description": "Monthly usage in kWh",
       "default": 300
      },
      "description": "Monthly usage in kWh"
     },
     {
      "name": "season",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "normal",
        "summer"
       ],
       "description": "summer = July–August tiers",
       "default": "normal"
      },
      "description": "summer = July–August tiers"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/kr-led-savings": {
   "get": {
    "operationId": "krLedSavings",
    "summary": "Korea LED replacement savings (household tiers or shop unit price)",
    "description": "Runs the same calculator as https://kwhmate.com/ko/led-savings/. Reference: 기준: 2026년 한전 주택용 저압 요금표(기타 계절) · 가게·사무실은 고지서 단가 직접 입력. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "count",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 10000,
       "default": 10
      }
     },
     {
      "name": "hours_per_day",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 24,
       "default": 8
      }
     },
     {
      "name": "old_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "default": 64
      }
     },
     {
      "name": "new_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "default": 30
      }
     },
     {
      "name": "mode",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "home",
        "shop"
       ],
       "description": "home = KEPCO progressive tiers, shop = unit_price × kWh",
       "default": "home"
      },
      "description": "home = KEPCO progressive tiers, shop = unit_price × kWh"
     },
     {
      "name": "other_kwh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "description": "home: monthly use without these lights",
       "default": 250
      },
      "description": "home: monthly use without these lights"
     },
     {
      "name": "unit_price",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 10000,
       "description": "shop: KRW per kWh",
       "default": 200
      },
      "description": "shop: KRW per kWh"
     },
     {
      "name": "led_cost",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 10000000000,
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/tw-electricity": {
   "get": {
    "operationId": "twElectricity",
    "summary": "Taiwan electricity bill (Taipower residential progressive rates)",
    "description": "Runs the same calculator as https://kwhmate.com/tw/electricity-bill/. Reference: 依據：台灣電力公司 2025年10月1日起實施之住宅用累進電價（2026年電價審議會凍漲）. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "kwh",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "default": 300
      }
     },
     {
      "name": "summer",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean",
       "description": "June–September rates",
       "default": false
      },
      "description": "June–September rates"
     },
     {
      "name": "bimonthly",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean",
       "description": "two-month bill (brackets doubled)",
       "default": false
      },
      "description": "two-month bill (brackets doubled)"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/tw-led-savings": {
   "get": {
    "operationId": "twLedSavings",
    "summary": "Taiwan LED replacement savings (Taipower non-summer, monthly brackets)",
    "description": "Runs the same calculator as https://kwhmate.com/tw/led-savings/. Reference: 依據：台電住宅用累進電價（非夏月、單月級距）. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "count",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 10000,
       "description": "Number of lights",
       "default": 10
      },
      "description": "Number of lights"
     },
     {
      "name": "hours_per_day",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 24,
       "default": 8
      }
     },
     {
      "name": "old_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "description": "Watts of one old bulb/tube",
       "default": 60
      },
      "description": "Watts of one old bulb/tube"
     },
     {
      "name": "new_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "description": "Watts of one LED",
       "default": 9
      },
      "description": "Watts of one LED"
     },
     {
      "name": "other_kwh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "description": "Other monthly household use without these lights (kWh)",
       "default": 300
      },
      "description": "Other monthly household use without these lights (kWh)"
     },
     {
      "name": "led_cost",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1000000000,
       "description": "Total cost of the LEDs (optional, for payback)",
       "default": 0
      },
      "description": "Total cost of the LEDs (optional, for payback)"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/ph-meralco": {
   "get": {
    "operationId": "phMeralco",
    "summary": "Philippines Meralco bill (this month's residential rate)",
    "description": "Runs the same calculator as https://kwhmate.com/ph/meralco-bill-calculator/. Reference: Source: Meralco rate announcement for October 2026 · lifeline discounts and local taxes not included. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "kwh",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "default": 200
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/ph-led-savings": {
   "get": {
    "operationId": "phLedSavings",
    "summary": "Philippines LED replacement savings (Meralco rates)",
    "description": "Runs the same calculator as https://kwhmate.com/ph/led-savings/. Reference: Rates: Meralco residential rates, October 2026. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "count",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 10000,
       "description": "Number of lights",
       "default": 10
      },
      "description": "Number of lights"
     },
     {
      "name": "hours_per_day",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 24,
       "default": 8
      }
     },
     {
      "name": "old_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "description": "Watts of one old bulb/tube",
       "default": 60
      },
      "description": "Watts of one old bulb/tube"
     },
     {
      "name": "new_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "description": "Watts of one LED",
       "default": 9
      },
      "description": "Watts of one LED"
     },
     {
      "name": "other_kwh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "description": "Other monthly household use without these lights (kWh)",
       "default": 200
      },
      "description": "Other monthly household use without these lights (kWh)"
     },
     {
      "name": "led_cost",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1000000000,
       "description": "Total cost of the LEDs (optional, for payback)",
       "default": 0
      },
      "description": "Total cost of the LEDs (optional, for payback)"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/jp-electricity": {
   "get": {
    "operationId": "jpElectricity",
    "summary": "Japan electricity bill (TEPCO Juryo Dento B)",
    "description": "Runs the same calculator as https://kwhmate.com/jp/electricity-bill/. Reference: 出典：東京電力エナジーパートナー「従量電灯B・C」・燃料費調整単価等一覧、経済産業省「2026年度の賦課金単価」. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "kwh",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "default": 260
      }
     },
     {
      "name": "amperes",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "enum": [
        10,
        15,
        20,
        30,
        40,
        50,
        60
       ],
       "minimum": 10,
       "maximum": 60,
       "default": 30
      }
     },
     {
      "name": "fuel_adjustment",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": -100,
       "maximum": 100,
       "description": "Fuel cost adjustment, yen per kWh (default: this month)",
       "default": -9.3
      },
      "description": "Fuel cost adjustment, yen per kWh (default: this month)"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/jp-led-savings": {
   "get": {
    "operationId": "jpLedSavings",
    "summary": "Japan LED replacement savings (TEPCO Juryo Dento B, 30 A)",
    "description": "Runs the same calculator as https://kwhmate.com/jp/led-savings/. Reference: 出典：東京電力エナジーパートナー「従量電灯B」. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "count",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 10000,
       "description": "Number of lights",
       "default": 10
      },
      "description": "Number of lights"
     },
     {
      "name": "hours_per_day",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 24,
       "default": 8
      }
     },
     {
      "name": "old_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "description": "Watts of one old bulb/tube",
       "default": 60
      },
      "description": "Watts of one old bulb/tube"
     },
     {
      "name": "new_watts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000,
       "description": "Watts of one LED",
       "default": 9
      },
      "description": "Watts of one LED"
     },
     {
      "name": "other_kwh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000,
       "description": "Other monthly household use without these lights (kWh)",
       "default": 260
      },
      "description": "Other monthly household use without these lights (kWh)"
     },
     {
      "name": "led_cost",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1000000000,
       "description": "Total cost of the LEDs (optional, for payback)",
       "default": 0
      },
      "description": "Total cost of the LEDs (optional, for payback)"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/seoul-taxi": {
   "get": {
    "operationId": "seoulTaxi",
    "summary": "Seoul taxi fare (regular mid-size taxi meter estimate)",
    "description": "Runs the same calculator as https://koreasurvivalkit.com/taxi-fare-calculator/. Reference: Source: Seoul Metropolitan Government, mid-size taxi fares in effect since 1 February 2023 (checked September 2026). Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "km",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 500,
       "default": 10
      }
     },
     {
      "name": "slow_traffic_minutes",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 600,
       "description": "Minutes at 15 km/h or less",
       "default": 10
      },
      "description": "Minutes at 15 km/h or less"
     },
     {
      "name": "hour",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 23,
       "description": "Departure hour (late-night surcharge)",
       "default": 14
      },
      "description": "Departure hour (late-night surcharge)"
     },
     {
      "name": "outside_seoul",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean",
       "default": false
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/busan-taxi": {
   "get": {
    "operationId": "busanTaxi",
    "summary": "Busan taxi fare (regular mid-size taxi meter estimate)",
    "description": "Runs the same calculator as https://koreasurvivalkit.com/busan-taxi-fare-calculator/. Reference: Source: Busan Metropolitan City, taxi fares in effect since 1 June 2023 (checked September 2026). Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "km",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 500,
       "default": 10
      }
     },
     {
      "name": "slow_traffic_minutes",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 600,
       "default": 10
      }
     },
     {
      "name": "hour",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 23,
       "default": 14
      }
     },
     {
      "name": "outside_busan",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean",
       "default": false
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/korea-tax-refund": {
   "get": {
    "operationId": "koreaTaxRefund",
    "summary": "Korea tourist tax (VAT) refund estimate",
    "description": "Runs the same calculator as https://koreasurvivalkit.com/tax-refund-calculator/. Reference: Sources checked October 2026: VISITKOREA, Korea.net, Incheon Airport, Visit Seoul. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "amounts",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "description": "Receipt amounts in KRW (one per store receipt)"
      },
      "description": "Receipt amounts in KRW (one per store receipt)"
     },
     {
      "name": "store",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "instant",
        "regular"
       ],
       "description": "instant = store offers instant refund at the till",
       "default": "instant"
      },
      "description": "instant = store offers instant refund at the till"
     },
     {
      "name": "stay_days",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 3650,
       "default": 7
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/suneung-score": {
   "get": {
    "operationId": "suneungScore",
    "summary": "수능 표준점수·등급 (Korean CSAT standard score and grade)",
    "description": "Runs the same calculator as https://gyesanmate.com/suneung-score/. Reference: 기준: 2027학년도 수능(한국교육과정평가원) · 실제 등급컷은 해마다 채점 결과로 달라짐. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "subject",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "main",
        "inquiry"
       ],
       "description": "main = 국어·수학, inquiry = 탐구·제2외국어/한문",
       "default": "main"
      },
      "description": "main = 국어·수학, inquiry = 탐구·제2외국어/한문"
     },
     {
      "name": "raw",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100
      }
     },
     {
      "name": "mean",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100
      }
     },
     {
      "name": "sd",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100
      }
     },
     {
      "name": "percentile",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100
      }
     },
     {
      "name": "english_raw",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/naesin-grade": {
   "get": {
    "operationId": "naesinGrade",
    "summary": "내신 등급 (Korean high-school class rank → grade, 5- or 9-grade system)",
    "description": "Runs the same calculator as https://gyesanmate.com/naesin-grade/. Reference: 기준: 고교 내신 상대평가 누적 비율 · 최종 등급은 학교 성적표 기준. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "system",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "five",
        "nine"
       ],
       "description": "five = 2025 입학생부터, nine = 2024 이전",
       "default": "five"
      },
      "description": "five = 2025 입학생부터, nine = 2024 이전"
     },
     {
      "name": "rank",
      "in": "query",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100000
      }
     },
     {
      "name": "ties",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100000,
       "description": "동석차 수(본인 포함)",
       "default": 1
      },
      "description": "동석차 수(본인 포함)"
     },
     {
      "name": "students",
      "in": "query",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100000
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/gpa-converter": {
   "get": {
    "operationId": "gpaConverter",
    "summary": "학점 비례 환산 (GPA scale conversion 4.5 / 4.3 / 4.0)",
    "description": "Runs the same calculator as https://gyesanmate.com/gpa-converter/. Reference: 기준: 단순 비례 환산(참고용) · 학교·기업마다 환산식이 다르므로 지원처 기준이 우선. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "score",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 4.5
      }
     },
     {
      "name": "from_scale",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "enum": [
        4.5,
        4.3,
        4
       ],
       "minimum": 4,
       "maximum": 4.5,
       "default": 4.5
      }
     },
     {
      "name": "to_scale",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "enum": [
        4.5,
        4.3,
        4
       ],
       "minimum": 4,
       "maximum": 4.5,
       "default": 4.3
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/student-loan": {
   "get": {
    "operationId": "studentLoan",
    "summary": "학자금대출 상환 (Korean student loan: standard repayment or income-contingent ICL)",
    "description": "Runs the same calculator as https://gyesanmate.com/student-loan-repayment/. Reference: 출처: 교육부고시 제2026-12호(2026학년도 2학기, 시행 2026.7.1) · 상환율은 최신 공지 확인. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "type",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "general",
        "icl"
       ],
       "default": "general"
      }
     },
     {
      "name": "principal",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 1,
       "maximum": 10000000000,
       "default": 10000000
      }
     },
     {
      "name": "rate_percent",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 30,
       "default": 1.7
      }
     },
     {
      "name": "defer_years",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 30,
       "default": 2
      }
     },
     {
      "name": "repay_years",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 30,
       "default": 10
      }
     },
     {
      "name": "gross_salary",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000000000,
       "description": "icl: annual gross salary",
       "default": 35000000
      },
      "description": "icl: annual gross salary"
     },
     {
      "name": "degree",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "undergrad",
        "grad"
       ],
       "default": "undergrad"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/education-tax-credit": {
   "get": {
    "operationId": "educationTaxCredit",
    "summary": "교육비 세액공제 (Korean education expense tax credit, 2026 spending)",
    "description": "Runs the same calculator as https://gyesanmate.com/education-tax-credit/. Reference: 출처: 소득세법 제59조의4, 2025년 세법개정(2025.12 국회 통과). Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "items",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "description": "Per person: \"kind:spend\" in GET (e.g. school:3500000,college:8000000) or [{kind, spend}] in JSON"
      },
      "description": "Per person: \"kind:spend\" in GET (e.g. school:3500000,college:8000000) or [{kind, spend}] in JSON"
     },
     {
      "name": "decided_tax",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000000000,
       "description": "Expected decided tax (credit is capped at this)"
      },
      "description": "Expected decided tax (credit is capped at this)"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/gap-investment": {
   "get": {
    "operationId": "gapInvestment",
    "summary": "갭투자 실투자금 (Korean \"gap\" investment: acquisition tax, brokerage, cash needed)",
    "description": "Runs the same calculator as https://gyesanmate.com/gap-investment/. Reference: 출처: 지방세법 제13조의2(시행 2026.1.1)·제151조 · 1주택 세율·중개보수는 최신 공지 확인 · 투자 권유 아님. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "price",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 1,
       "maximum": 1000000000000
      }
     },
     {
      "name": "jeonse",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1000000000000
      }
     },
     {
      "name": "houses",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 99,
       "description": "Number of homes after buying",
       "default": 1
      },
      "description": "Number of homes after buying"
     },
     {
      "name": "adjusted_area",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean",
       "default": false
      }
     },
     {
      "name": "over_85m2",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean",
       "default": false
      }
     },
     {
      "name": "other_costs",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000000000,
       "default": 0
      }
     },
     {
      "name": "growth_percent",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": -50,
       "maximum": 50,
       "default": 0
      }
     },
     {
      "name": "years",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 50,
       "default": 0
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/report-reward": {
   "get": {
    "operationId": "reportReward",
    "summary": "신고 포상금·보상금 (Korean whistleblower rewards: tax evasion, hidden assets, card refusal, public interest, corruption)",
    "description": "Runs the same calculator as https://gyesanmate.com/reward/calculator/. Reference: 확인일 2026-10-12 · 출처: 국세기본법 시행령 제65조의4, 공익신고자 보호법 시행령 제22조, 부패방지권익위법 시행령 제77조 · 참고용 추정치. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "evasion",
        "hidden",
        "card",
        "public",
        "corruption"
       ],
       "description": "evasion = 탈세 제보(탈루세액등), hidden = 은닉재산(징수금액), card = 카드 결제 거부·현금영수증 미발급(거부금액), public = 공익신고, corruption = 부패신고(회복·증대 금액)",
       "default": "evasion"
      },
      "description": "evasion = 탈세 제보(탈루세액등), hidden = 은닉재산(징수금액), card = 카드 결제 거부·현금영수증 미발급(거부금액), public = 공익신고, corruption = 부패신고(회복·증대 금액)"
     },
     {
      "name": "amount",
      "in": "query",
      "required": true,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1000000000000000,
       "description": "KRW amount the reward is based on"
      },
      "description": "KRW amount the reward is based on"
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  },
  "/api/v1/travel-budget": {
   "get": {
    "operationId": "travelBudget",
    "summary": "국내 여행 예산 (Korea domestic trip budget: transport, stay, food, admission ranges)",
    "description": "Runs the same calculator as https://gyesanmate.com/travel-budget/. Reference: 확인일 KTX 2026-10-12·고속버스 2026-10-13 · 출처: 국토교통부 발표(KTX), KOBUS 시간표조회(고속버스) · 결과는 추정치. Arrays: comma-separated. Also accepts POST with a JSON body.",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "서울",
        "부산",
        "대구",
        "대전",
        "광주",
        "인천",
        "기타"
       ],
       "default": "서울"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "부산",
        "광주",
        "강릉",
        "경주",
        "전주",
        "여수",
        "대구",
        "대전",
        "목포",
        "제주",
        "기타"
       ],
       "default": "부산"
      }
     },
     {
      "name": "nights",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 30,
       "default": 1
      }
     },
     {
      "name": "people",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 30,
       "default": 2
      }
     },
     {
      "name": "mode",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "ktx",
        "bus",
        "car",
        "other"
       ],
       "default": "ktx"
      }
     },
     {
      "name": "bus_grade",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "normal",
        "deluxe",
        "premium"
       ],
       "description": "Express bus class (normal / deluxe 우등 / premium 프리미엄) for the built-in Seoul routes",
       "default": "normal"
      },
      "description": "Express bus class (normal / deluxe 우등 / premium 프리미엄) for the built-in Seoul routes"
     },
     {
      "name": "fare",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 10000000,
       "description": "One-way fare per person you checked (empty = built-in fare: KTX Seoul–Busan and Yongsan–Gwangju-Songjeong base fares, and 9 Seoul express-bus routes from KOBUS)"
      },
      "description": "One-way fare per person you checked (empty = built-in fare: KTX Seoul–Busan and Yongsan–Gwangju-Songjeong base fares, and 9 Seoul express-bus routes from KOBUS)"
     },
     {
      "name": "car_km",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 5000
      }
     },
     {
      "name": "car_km_per_l",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100
      }
     },
     {
      "name": "fuel_price",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 10000
      }
     },
     {
      "name": "toll",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1000000
      }
     },
     {
      "name": "rooms",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 30
      }
     },
     {
      "name": "stay_min",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000000
      }
     },
     {
      "name": "stay_max",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000000
      }
     },
     {
      "name": "food_min",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 10000000
      }
     },
     {
      "name": "food_max",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 10000000
      }
     },
     {
      "name": "admission_min",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000000
      }
     },
     {
      "name": "admission_max",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 100000000
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Result with source and page URL",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Result"
        }
       }
      }
     },
     "400": {
      "description": "Invalid input"
     },
     "429": {
      "description": "Rate limited (60 requests per minute)"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Result": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "calculator": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "currency": {
      "type": [
       "string",
       "null"
      ]
     },
     "input": {
      "type": "object"
     },
     "result": {
      "type": "object"
     },
     "estimate": {
      "type": "boolean"
     },
     "reference": {
      "type": "string",
      "description": "Reference date and official source"
     },
     "page": {
      "type": "string",
      "format": "uri"
     },
     "disclaimer": {
      "type": "string"
     }
    }
   }
  }
 }
}