DF

DataFact

한국 데이터, 인사이트로

개발자 — API & 임베드

DataFact의 모든 공개 데이터셋을 무인증 REST API로 가져오거나,iframe 임베드 위젯으로 어디든 삽입할 수 있습니다. CORS가 열려 있어 브라우저에서 바로 호출됩니다. 출처(원출처 + DataFact)를 명시하면 무료로 이용할 수 있습니다.

REST API

기본 주소: https://datafact.org/api/v1 · OpenAPI 3.1 spec (Postman/Insomnia/SDK 자동생성 호환)

데이터셋 목록

GET /api/v1/datasets            # 전체 공개 데이터셋
GET /api/v1/datasets?sector=auto   # 섹터 필터 (auto, population, economy …)

데이터셋 상세 (메타데이터 + 시계열)

GET /api/v1/datasets/global-ev-cars-by-country
GET /api/v1/datasets/global-ev-cars-by-country?format=csv   # CSV 다운로드

예시

curl https://datafact.org/api/v1/datasets/global-ev-cars-by-country

응답 (요약)

{
  "api": "datafact/v1",
  "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" },
  "row_count": 3358,
  "series": [ { "period": "2024", "dim1": "Korea", "dim2": "EV sales share", "dim3": null, "value": 7.4 } ],
  "links": { "html": "…", "embed": "…", "csv": "…" }
}

임베드 위젯

아래 iframe을 붙여 넣으면 인터랙티브 차트(범위·차트유형·표·CSV)가 그대로 들어갑니다.

<iframe
  src="https://datafact.org/embed/auto/global-ev-cars-by-country"
  width="100%" height="460" loading="lazy"
  style="border:1px solid #e2e8f0;border-radius:12px"
  title="DataFact 차트"></iframe>

주소 형식: /embed/<sector>/<slug>. slug·sector는 API 목록 또는 데이터셋 페이지 주소에서 확인할 수 있습니다.

인용 & DataFact-ID

각 데이터셋에는 안정적 인용 식별자 DataFact-ID가 부여됩니다 (datafact:<sector>/<slug>). API 응답의 citation.text를 그대로 사용하세요.

global-ev-cars-by-country → datafact:auto/global-ev-cars-by-country
"국가별 전기차(EV) 판매·보급 현황 (IEA) — DataFact
 (https://datafact.org/auto/global-ev-cars-by-country). 원출처: IEA, Global EV Outlook — CC BY 4.0."

알림 & Webhook

📬 이메일 알림 (사용 가능)

각 데이터셋 페이지의 “이 데이터 갱신 알림 받기” 폼으로 섹터 단위 구독. 월간 cron이 새 데이터·기사를 묶어 메일 발송. 또는 POST /api/subscribe with { email, sectors: ["auto"] } 직접 호출.

🪝 Webhook (계획)

데이터셋 갱신 시 사용자 URL로 POST 발송하는 webhook API는 향후 작업. 필요 시 hello@datafact.org으로 use case 보내주세요(우선순위 결정에 반영).

운영 정책 (rate limit · SLA · CORS)

Rate limit

캐시 & 신선도

  • CDN 캐시 s-maxage: 5분~1시간
  • 응답 헤더 Cache-Control로 신선도 확인
  • 데이터 갱신 주기는 update_frequency 필드 참조

CORS

  • Access-Control-Allow-Origin: *
  • 브라우저에서 바로 fetch 가능
  • 임베드 iframe 도메인 제한 없음

SLA & 안정성

  • Vercel edge — 99.9% best-effort
  • 무료 공개 API로 명시적 SLA 미보장
  • v1 backward-compatible 약속, breaking change 시 v2로 분리

라이선스 & 이용 안내