{"openapi":"3.1.0","info":{"title":"DataFact Public API","version":"1.0.0","description":"한국 공공·공개 통계 시계열을 무인증 REST API로 제공합니다. 출처(통계청 KOSIS·국토교통부·KAIDA·KAMA·IEA 등)별 라이선스에 따라 자유 이용 가능하며, 출처 명시(`DataFact-ID` + 원출처)가 필요합니다. 응답은 모든 도메인에서 CORS 허용.","contact":{"name":"DataFact","url":"https://datafact.org/developers","email":"hello@datafact.org"},"license":{"name":"데이터셋별 원출처 라이선스 (대부분 CC-BY-2.0/4.0)","url":"https://datafact.org/developers"},"x-rate-limit":{"anonymous":"60 req/min/IP (best-effort, soft limit)","sustained":"5,000 req/day/IP","bulk":"대량 사용 또는 webhook 필요 시 hello@datafact.org"},"x-sla":{"uptime":"Vercel edge 인프라 — 99.9% best-effort, SLA 미보장 (무료 공개 API)","cache":"CDN s-maxage 5분~1시간, 신선도는 응답 헤더 참조","breaking_changes":"v1은 backward-compatible 약속. breaking change 시 v2로 분리."}},"servers":[{"url":"https://datafact.org/api/v1","description":"Production"}],"tags":[{"name":"datasets","description":"데이터셋 메타데이터 + 시계열"}],"paths":{"/datasets":{"get":{"tags":["datasets"],"operationId":"listDatasets","summary":"공개 데이터셋 목록","description":"현재 공개된 모든 데이터셋의 메타데이터를 반환합니다. 시계열은 포함하지 않습니다(상세 endpoint 사용).","parameters":[{"name":"sector","in":"query","required":false,"description":"섹터 필터 (auto, population, economy, labor, trade, education, environment, housing)","schema":{"type":"string","enum":["auto","population","economy","labor","trade","education","environment","housing"]}}],"responses":{"200":{"description":"데이터셋 목록","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetListResponse"},"example":{"api":"datafact/v1","docs":"https://datafact.org/developers","count":45,"sector":"auto","datasets":[{"id":"datafact:auto/global-ev-cars-by-country","slug":"global-ev-cars-by-country","sector":"auto","title":"국가별 전기차(EV) 판매·보급 현황 (IEA)","unit":"%","source":{"id":"iea","name":"IEA","license":"CC-BY-4.0"},"links":{"html":"...","embed":"...","json":"...","csv":"..."}}]}}}}}}},"/datasets/{slug}":{"get":{"tags":["datasets"],"operationId":"getDataset","summary":"데이터셋 상세 + 시계열","description":"특정 데이터셋의 메타데이터와 전체 시계열(`series`)을 반환합니다. `?format=csv`로 CSV 다운로드도 가능.","parameters":[{"name":"slug","in":"path","required":true,"description":"데이터셋 슬러그 (예: global-ev-cars-by-country)","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"응답 형식. `csv`면 text/csv로 다운로드 헤더 포함.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"aggregate","in":"query","required":false,"description":"월간 시계열을 분기·연간 합계로 압축. period가 'YYYY-Qn' 또는 'YYYY'로 바뀐다. 주의: %·지수형 단위에는 sum이 부적절하며 응답 `aggregation_warning` 필드 참조.","schema":{"type":"string","enum":["quarterly","annual"]}}],"responses":{"200":{"description":"데이터셋 상세","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetDetailResponse"}},"text/csv":{"schema":{"type":"string","format":"csv"}}}},"404":{"description":"데이터셋 없음 또는 비공개","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Source":{"type":"object","properties":{"id":{"type":"string","example":"kosis"},"name":{"type":"string","example":"국가통계포털 (KOSIS)"},"name_en":{"type":"string","nullable":true},"license":{"type":"string","example":"CC-BY-2.0"},"url":{"type":"string","format":"uri","nullable":true},"redistribution":{"type":"boolean","description":"재배포 허용 여부"}}},"DatasetMeta":{"type":"object","required":["id","slug","sector","title","source"],"properties":{"id":{"type":"string","description":"DataFact-ID (예: datafact:auto/global-ev-cars-by-country)"},"slug":{"type":"string"},"sector":{"type":"string","description":"섹터 ID"},"title":{"type":"string","description":"한국어 제목"},"title_en":{"type":"string","nullable":true},"subtitle":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"unit":{"type":"string","description":"단위 (대·명·%·천달러 등)"},"unit_en":{"type":"string","nullable":true},"granularity":{"type":"string","nullable":true,"example":"annual"},"update_frequency":{"type":"string","nullable":true,"example":"monthly"},"last_updated_at":{"type":"string","format":"date-time","nullable":true},"chart_type":{"type":"string","enum":["line","bar","area"],"nullable":true},"source":{"$ref":"#/components/schemas/Source"},"links":{"type":"object","properties":{"html":{"type":"string","format":"uri","description":"HTML 데이터셋 페이지"},"embed":{"type":"string","format":"uri","description":"iframe 임베드 URL"},"json":{"type":"string","format":"uri"},"csv":{"type":"string","format":"uri"}}}}},"SeriesPoint":{"type":"object","required":["period","value"],"properties":{"period":{"type":"string","description":"기간 (YYYY · YYYY-MM · YYYY-Q1 등)"},"dim1":{"type":"string","nullable":true,"description":"차원 1 (지역·차종·연료 등)"},"dim2":{"type":"string","nullable":true,"description":"차원 2"},"dim3":{"type":"string","nullable":true,"description":"차원 3"},"value":{"type":"number","nullable":true,"description":"값. null=결측"}}},"DatasetListResponse":{"type":"object","properties":{"api":{"type":"string","const":"datafact/v1"},"docs":{"type":"string","format":"uri"},"count":{"type":"integer"},"sector":{"type":"string","description":"요청한 섹터 또는 'all'"},"datasets":{"type":"array","items":{"$ref":"#/components/schemas/DatasetMeta"}}}},"DatasetDetailResponse":{"allOf":[{"$ref":"#/components/schemas/DatasetMeta"},{"type":"object","properties":{"row_count":{"type":"integer"},"series":{"type":"array","items":{"$ref":"#/components/schemas/SeriesPoint"}}}}]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string","nullable":true}}}}}}