{"openapi":"3.1.0","info":{"title":"Khmer Hybrid Calendar Developer API","version":"1.0.0","description":"Official, production-grade REST API for Khmer lunar date conversions, Buddhist observances (ថ្ងៃសីល & ថ្ងៃកោរ), Cambodian national public holidays, moon phases, and multilingual calendar data.","contact":{"name":"Heng LOEM","url":"https://khc.loemheng.com/developers","email":"loemheng@gmail.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://khc.loemheng.com","description":"Production Global Edge Network"},{"url":"http://localhost:5173","description":"Local Development Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for paid plan or 14-day free trial. Pass via \"x-api-key\" header or \"?api_key=\" query param."}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1":{"get":{"summary":"API Directory & Pricing Plans (Cambodia Market)","description":"Returns available endpoints, documentation links, and Cambodia market pricing tiers ($6 Starter, $19 Business, $49 Enterprise, 14-day free trial).","security":[],"responses":{"200":{"description":"Successful response with API index and pricing plans"}}}},"/api/v1/trial":{"get":{"summary":"Generate 14-Day Free Trial API Key","description":"Generates an instant 14-day free trial API key with 10,000 requests. No credit card required.","security":[],"parameters":[{"name":"email","in":"query","required":false,"schema":{"type":"string","format":"email"},"description":"Developer email address for trial key issuance."}],"responses":{"201":{"description":"Trial API key created successfully"}}}},"/api/v1/payment/submit":{"post":{"summary":"Submit Manual QR / ABA Bank Transfer Payment Receipt","description":"Submit proof of transfer and user details for admin verification and API key issuance.","security":[],"responses":{"201":{"description":"Payment transaction proof submitted for verification"}}}},"/api/v1/payment/status":{"get":{"summary":"Check Payment & API Key Verification Status","description":"Poll verification status of an order. Returns the active API key once approved by admin.","security":[],"parameters":[{"name":"order_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order status information"}}}},"/api/v1/today":{"get":{"summary":"Get Today Calendar Details","description":"Returns complete solar, Khmer lunar, Buddhist holy day, and holiday data for today in the specified timezone.","parameters":[{"name":"timezone","in":"query","required":false,"schema":{"type":"string","default":"Asia/Phnom_Penh"},"description":"IANA Timezone (e.g., Asia/Phnom_Penh, America/New_York, UTC)."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["km","en","vi","zh"],"default":"km"},"description":"Language code for names and translations."}],"responses":{"200":{"description":"Detailed day data for today"},"400":{"description":"Invalid timezone specified"}}}},"/api/v1/date":{"get":{"summary":"Convert Gregorian Date to Khmer Lunar Date","description":"Convert any solar Gregorian date (YYYY-MM-DD) into complete Khmer lunar calendar information.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-10-24"},"description":"Gregorian date formatted as YYYY-MM-DD."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["km","en","vi","zh"],"default":"km"},"description":"Language code for localized names."}],"responses":{"200":{"description":"Successful conversion data"},"400":{"description":"Invalid date string or out of supported range"}}}},"/api/v1/lunar-to-solar":{"get":{"summary":"Convert Khmer Lunar Date to Gregorian Solar Date","description":"Reverse conversion: converts Khmer lunar day, waxing/waning phase, lunar month index, and Buddhist Era year into a Gregorian calendar date.","parameters":[{"name":"day","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":15},"description":"Lunar day number (1 to 15)."},{"name":"phase","in":"query","required":true,"schema":{"type":"string","enum":["waxing","waning"]},"description":"Waxing (កើត) or Waning (រោច)."},{"name":"month","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":13},"description":"Khmer lunar month index: 0=Migasir, 1=Boss, ..., 11=Kadeuk, 12=1st Asadh, 13=2nd Asadh."},{"name":"be_year","in":"query","required":true,"schema":{"type":"integer","example":2570},"description":"Buddhist Era (ពុទ្ធសករាជ) year between 2300 and 2800."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["km","en","vi","zh"],"default":"km"}}],"responses":{"200":{"description":"Gregorian date and full day details"},"400":{"description":"Invalid lunar day, phase, month, or BE year"}}}},"/api/v1/month":{"get":{"summary":"Get Month Calendar Grid","description":"Retrieve all calendar days for a specific Gregorian month with lunar dates and events.","parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","example":2026},"description":"Gregorian year (1800-2200)."},{"name":"month","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":12,"example":10},"description":"Gregorian month (1-12)."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["km","en","vi","zh"],"default":"km"}}],"responses":{"200":{"description":"Array of days for the requested month"},"400":{"description":"Invalid year or month"}}}},"/api/v1/holidays":{"get":{"summary":"Get Cambodian Public Holidays & Observances","description":"List public holidays and cultural observances for a given year with official status.","parameters":[{"name":"year","in":"query","required":false,"schema":{"type":"integer","default":2026},"description":"Gregorian year."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["all","national","lunar","international"],"default":"all"},"description":"Filter category: all, national (បុណ្យជាតិ), lunar (ចន្ទគតិ), or international."},{"name":"official_only","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"If true, only returns official paid public holidays."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["km","en","vi","zh"],"default":"km"}}],"responses":{"200":{"description":"List of holidays matching filters"}}}},"/api/v1/buddhist-days":{"get":{"summary":"Get Buddhist Observances & Holy Days","description":"List all Uposatha (ថ្ងៃសីល), Kaor (ថ្ងៃកោរ), Pchum Ben, Vassa, and Kathina days for the year.","parameters":[{"name":"year","in":"query","required":false,"schema":{"type":"integer","default":2026},"description":"Gregorian year."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["km","en","vi","zh"],"default":"km"}}],"responses":{"200":{"description":"List of Buddhist Holy Days"}}}}}}