{"openapi":"3.1.0","info":{"title":"KoreaKit","version":"0.1.0","description":"Korean holidays, business days, lunar calendar and Hangul utilities. Pay per call with x402.","contact":{"name":"WiseLake Inc","email":"wiselake@wiselake.ai"}},"servers":[{"url":"https://koreakit.celee.workers.dev"}],"paths":{"/v1/holidays":{"get":{"summary":"All Korean public holidays of a year","description":"South Korea public holidays for a year (2015-2050): 설날·추석 (lunar), 대체공휴일 substitute holidays, election days, temporary holidays, and the 2026 additions 노동절 (May 1) and 제헌절 (Jul 17). Korean and English names. KASI lunar data. Price: $0.003 USDC via x402.","parameters":[{"name":"year","in":"query","required":true,"description":"Gregorian year, 2015-2050","schema":{"type":"string","pattern":"^\\d{4}$"},"example":"2026"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"},"holidays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"weekday":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"},"type":{"type":"string"}}}},"meta":{"type":"object","properties":{"as_of":{"type":"string"},"basis":{"type":"string"},"supported_years":{"type":"string"},"note":{"type":"string"}}}}},"example":{"year":2026,"holidays":[{"date":"2026-01-01","weekday":"Thu","name":"신정","name_en":"New Year's Day","type":"public"},{"date":"2026-02-16","weekday":"Mon","name":"설날 연휴","name_en":"Seollal Holiday","type":"public"},{"date":"2026-02-17","weekday":"Tue","name":"설날","name_en":"Seollal","type":"public"},{"date":"2026-02-18","weekday":"Wed","name":"설날 연휴","name_en":"Seollal Holiday","type":"public"},{"date":"2026-03-01","weekday":"Sun","name":"삼일절","name_en":"Independence Movement Day","type":"public"},{"date":"2026-03-02","weekday":"Mon","name":"대체공휴일","name_en":"Substitute Holiday","type":"substitute","substitute_for":"삼일절"},{"date":"2026-05-01","weekday":"Fri","name":"노동절","name_en":"Labor Day","type":"public"},{"date":"2026-05-05","weekday":"Tue","name":"어린이날","name_en":"Children's Day","type":"public"},{"date":"2026-05-24","weekday":"Sun","name":"부처님오신날","name_en":"Buddha's Birthday","type":"public"},{"date":"2026-05-25","weekday":"Mon","name":"대체공휴일","name_en":"Substitute Holiday","type":"substitute","substitute_for":"부처님오신날"},{"date":"2026-06-03","weekday":"Wed","name":"제9회 전국동시지방선거","name_en":"Local Election Day","type":"election"},{"date":"2026-06-06","weekday":"Sat","name":"현충일","name_en":"Memorial Day","type":"public"},{"date":"2026-07-17","weekday":"Fri","name":"제헌절","name_en":"Constitution Day","type":"public"},{"date":"2026-08-15","weekday":"Sat","name":"광복절","name_en":"Liberation Day","type":"public"},{"date":"2026-08-17","weekday":"Mon","name":"대체공휴일","name_en":"Substitute Holiday","type":"substitute","substitute_for":"광복절"},{"date":"2026-09-24","weekday":"Thu","name":"추석 연휴","name_en":"Chuseok Holiday","type":"public"},{"date":"2026-09-25","weekday":"Fri","name":"추석","name_en":"Chuseok","type":"public"},{"date":"2026-09-26","weekday":"Sat","name":"추석 연휴","name_en":"Chuseok Holiday","type":"public"},{"date":"2026-10-03","weekday":"Sat","name":"개천절","name_en":"National Foundation Day","type":"public"},{"date":"2026-10-05","weekday":"Mon","name":"대체공휴일","name_en":"Substitute Holiday","type":"substitute","substitute_for":"개천절"},{"date":"2026-10-09","weekday":"Fri","name":"한글날","name_en":"Hangul Day","type":"public"},{"date":"2026-12-25","weekday":"Fri","name":"성탄절","name_en":"Christmas Day","type":"public"}],"meta":{"as_of":"2026-10-28","basis":"공휴일에 관한 법률 · 관공서의 공휴일에 관한 규정 (incl. 2026 노동절·제헌절, 대체공휴일 rules)","supported_years":"2015-2050","note":"Temporary holidays (임시공휴일) are added when officially designated; future ones are not predictable."}}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/holidays"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/holidays/check":{"get":{"summary":"Is a date a Korean public holiday / business day?","description":"Check whether a date is a South Korea public holiday, weekend, or business day (영업일), with holiday names. Includes 대체공휴일 and 2026 노동절·제헌절. Price: $0.003 USDC via x402.","parameters":[{"name":"date","in":"query","required":true,"description":"YYYY-MM-DD","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-05-01"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"weekday":{"type":"string"},"is_holiday":{"type":"boolean"},"is_weekend":{"type":"boolean"},"is_business_day":{"type":"boolean"},"holidays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"weekday":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string"},"type":{"type":"string"}}}},"meta":{"type":"object","properties":{"as_of":{"type":"string"},"basis":{"type":"string"},"supported_years":{"type":"string"},"note":{"type":"string"}}}}},"example":{"date":"2026-05-01","weekday":"Fri","is_holiday":true,"is_weekend":false,"is_business_day":false,"holidays":[{"date":"2026-05-01","weekday":"Fri","name":"노동절","name_en":"Labor Day","type":"public"}],"meta":{"as_of":"2026-10-28","basis":"공휴일에 관한 법률 · 관공서의 공휴일에 관한 규정 (incl. 2026 노동절·제헌절, 대체공휴일 rules)","supported_years":"2015-2050","note":"Temporary holidays (임시공휴일) are added when officially designated; future ones are not predictable."}}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/holidays/check"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/business-days/add":{"get":{"summary":"Add or subtract Korean business days","description":"Add or subtract N South Korea business days (영업일) to a date, skipping weekends and all Korean public holidays incl. substitute holidays. Use for payment due dates, delivery and contract deadlines. Price: $0.003 USDC via x402.","parameters":[{"name":"date","in":"query","required":true,"description":"Start date YYYY-MM-DD (not counted)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-09-23"},{"name":"days","in":"query","required":true,"description":"Business days to add; negative to subtract (|days| <= 3650)","schema":{"type":"string","pattern":"^-?\\d{1,4}$"},"example":"3"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"days":{"type":"integer"},"result":{"type":"string"},"meta":{"type":"object","properties":{"as_of":{"type":"string"},"basis":{"type":"string"},"supported_years":{"type":"string"},"note":{"type":"string"}}}}},"example":{"date":"2026-09-23","days":3,"result":"2026-09-30","meta":{"as_of":"2026-10-28","basis":"공휴일에 관한 법률 · 관공서의 공휴일에 관한 규정 (incl. 2026 노동절·제헌절, 대체공휴일 rules)","supported_years":"2015-2050","note":"Temporary holidays (임시공휴일) are added when officially designated; future ones are not predictable."}}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/business-days/add"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/business-days/count":{"get":{"summary":"Count Korean business days between two dates","description":"Count South Korea business days (영업일) between two dates, inclusive of both ends, excluding weekends and Korean public holidays. Price: $0.003 USDC via x402.","parameters":[{"name":"from","in":"query","required":true,"description":"YYYY-MM-DD (inclusive)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-09-21"},{"name":"to","in":"query","required":true,"description":"YYYY-MM-DD (inclusive)","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-09-30"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"inclusive":{"type":"boolean"},"business_days":{"type":"integer"},"meta":{"type":"object","properties":{"as_of":{"type":"string"},"basis":{"type":"string"},"supported_years":{"type":"string"},"note":{"type":"string"}}}}},"example":{"from":"2026-09-21","to":"2026-09-30","inclusive":true,"business_days":6,"meta":{"as_of":"2026-10-28","basis":"공휴일에 관한 법률 · 관공서의 공휴일에 관한 규정 (incl. 2026 노동절·제헌절, 대체공휴일 rules)","supported_years":"2015-2050","note":"Temporary holidays (임시공휴일) are added when officially designated; future ones are not predictable."}}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/business-days/count"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/lunar/to-solar":{"get":{"summary":"Korean lunar date → Gregorian","description":"Convert a Korean lunar calendar date (음력) to the Gregorian date (양력) with 간지 (sexagenary) names, KASI standard. For birthdays, 제사, traditional events. Price: $0.003 USDC via x402.","parameters":[{"name":"date","in":"query","required":true,"description":"Lunar date YYYY-MM-DD","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-08-15"},{"name":"leap","in":"query","required":false,"description":"true if the lunar month is a leap month (윤달)","schema":{"type":"string","enum":["true","false"]},"example":"false"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lunar":{"type":"object","properties":{"date":{"type":"string"},"leap_month":{"type":"boolean"}}},"solar":{"type":"string"},"gapja":{"type":"object","properties":{"year":{"type":"string"},"month":{"type":"string"},"day":{"type":"string"},"intercalation":{"type":"string"}}},"gapja_hanja":{"type":"object","properties":{"year":{"type":"string"},"month":{"type":"string"},"day":{"type":"string"},"intercalation":{"type":"string"}}}}},"example":{"lunar":{"date":"2026-08-15","leap_month":false},"solar":"2026-09-25","gapja":{"year":"병오년","month":"정유월","day":"임인일","intercalation":""},"gapja_hanja":{"year":"丙午年","month":"丁酉月","day":"壬寅日","intercalation":""}}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/lunar/to-solar"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/lunar/from-solar":{"get":{"summary":"Gregorian → Korean lunar date","description":"Convert a Gregorian date (양력) to the Korean lunar calendar date (음력), leap-month flag and 간지 names, KASI standard. Price: $0.003 USDC via x402.","parameters":[{"name":"date","in":"query","required":true,"description":"Gregorian date YYYY-MM-DD","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"example":"2026-09-25"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"solar":{"type":"string"},"lunar":{"type":"object","properties":{"date":{"type":"string"},"leap_month":{"type":"boolean"}}},"gapja":{"type":"object","properties":{"year":{"type":"string"},"month":{"type":"string"},"day":{"type":"string"},"intercalation":{"type":"string"}}},"gapja_hanja":{"type":"object","properties":{"year":{"type":"string"},"month":{"type":"string"},"day":{"type":"string"},"intercalation":{"type":"string"}}}}},"example":{"solar":"2026-09-25","lunar":{"date":"2026-08-15","leap_month":false},"gapja":{"year":"병오년","month":"정유월","day":"임인일","intercalation":""},"gapja_hanja":{"year":"丙午年","month":"丁酉月","day":"壬寅日","intercalation":""}}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/lunar/from-solar"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/text/amount":{"get":{"summary":"Number → Korean amount in words (금액 한글 표기)","description":"Write a number as a Korean amount in words: spoken form, formal 일금…원정 contract form for invoices and contracts, and 갖은자 hanja (壹貳參). Up to 20 digits. Price: $0.003 USDC via x402.","parameters":[{"name":"n","in":"query","required":true,"description":"Non-negative integer, commas allowed","schema":{"type":"string","pattern":"^[0-9,\\s]+$"},"example":"1234500"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string"},"formatted":{"type":"string"},"plain":{"type":"string"},"formal":{"type":"string"},"contract":{"type":"string"},"hanja":{"type":"string"}}},"example":{"number":"1234500","formatted":"1,234,500","plain":"백이십삼만 사천오백","formal":"일백이십삼만사천오백","contract":"금 일백이십삼만사천오백원정 (₩1,234,500)","hanja":"壹佰貳拾參萬肆仟伍佰"}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/text/amount"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/text/josa":{"get":{"summary":"Pick the right Korean particle (조사) for a word","description":"Choose the grammatically correct Korean particle (은/는, 이/가, 을/를, 과/와, 으로/로 …) for a word, number or acronym, based on its final consonant (받침). For templated Korean text generation. Price: $0.003 USDC via x402.","parameters":[{"name":"word","in":"query","required":true,"description":"Word, number or acronym","schema":{"type":"string","minLength":1},"example":"서울"},{"name":"josa","in":"query","required":true,"description":"Either form of the particle, e.g. 을 or 을/를","schema":{"type":"string","pattern":"^(은|는|이|가|을|를|과|와|으로|로|이랑|랑|아|야|이나|나|이라고|라고|이에요|예요)(/.*)?$"},"example":"으로"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"word":{"type":"string"},"josa":{"type":"string"},"result":{"type":"string"},"has_final_consonant":{"type":"boolean"},"confidence":{"type":"string"}}},"example":{"word":"서울","josa":"로","result":"서울로","has_final_consonant":true,"confidence":"high"}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/text/josa"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/text/romanize":{"get":{"summary":"Hangul → Revised Romanization","description":"Romanize Korean (Hangul) text with the official Revised Romanization rules incl. sound changes (종로 jongno, 신라 silla). mode=name for personal names with common surname spellings (Kim, Lee, Park). Price: $0.003 USDC via x402.","parameters":[{"name":"text","in":"query","required":true,"description":"Korean text, up to 2000 chars","schema":{"type":"string","minLength":1,"maxLength":2000},"example":"경복궁"},{"name":"mode","in":"query","required":false,"description":"general (default) or name","schema":{"type":"string","enum":["general","name"]},"example":"general"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"mode":{"type":"string"},"result":{"type":"string"},"standard":{"type":"string"}}},"example":{"text":"경복궁","mode":"general","result":"gyeongbokgung","standard":"Revised Romanization of Korean (국어의 로마자 표기법, 2000)"}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/text/romanize"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}},"/v1/validate/brn":{"get":{"summary":"Validate a Korean business registration number (사업자등록번호)","description":"Validate the checksum of a South Korea business registration number (사업자등록번호, 10 digits) and classify the entity type (individual, corporation HQ/branch, non-profit). Offline checksum only. Price: $0.003 USDC via x402.","parameters":[{"name":"number","in":"query","required":true,"description":"10 digits, hyphens allowed","schema":{"type":"string","minLength":1},"example":"220-81-62517"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string"},"formatted":{"type":"string"},"valid_format":{"type":"boolean"},"valid_checksum":{"type":"boolean"},"entity_type":{"type":"string"},"entity_type_ko":{"type":"string"},"note":{"type":"string"}}},"example":{"input":"220-81-62517","formatted":"220-81-62517","valid_format":true,"valid_checksum":true,"entity_type":"for_profit_corporation_hq","entity_type_ko":"영리법인 본점","note":"Checksum only. Does not confirm the business is registered or active (국세청 상태조회 required)."}}}},"400":{"description":"Invalid parameters (free, never charged; also when a payment is attached to a request with missing parameters)","content":{"application/json":{"example":{"error":"date must be YYYY-MM-DD","docs":"https://koreakit.celee.workers.dev/#/v1/validate/brn"}}}},"402":{"description":"Payment required (x402 v2, see PAYMENT-REQUIRED header). Also returned for the bare URL with no parameters, for discovery."}}}}}}