개발자용

공개 API — API v1

기관 24,485건 · 읽기 전용 · 무료 · 2026.06 기준

공개 데이터를 파일이 아니라 프로그램에서 바로 받아 쓰실 수 있습니다. 지역·급여종류·등급으로 걸러 받을 수 있어, 매번 전체 CSV를 내려받지 않아도 됩니다. 읽기 전용이고 무료이며, 키만 발급받으면 됩니다.

30초 요약

curl -H "x-api-key: pk_..." \
  "https://caregrade.kr/api/v1/institutions?sido=서울특별시&gugun=강서구&svc=04&limit=20"

{
  "data": [ { "key": "...", "name": "...", "grade": "A", "year": 2024 } ],
  "meta": {
    "updated": "2026-06-25",
    "source": "...",
    "license": "이용허락범위 제한 없음",
    "notice": "평가 등급이나 가산금 수령을 보장하지 않습니다 ...",
    "total": 226,
    "view": "family"
  },
  "next": "eyJvIjoyMH0"
}

meta는 항상 옵니다. 이 데이터는 언제 것인지 없이 쓰면 안 됩니다 — 연 1회 갱신이라 최근에 평가받은 기관은 표시된 등급과 다를 수 있습니다. 화면에 등급을 그리신다면 updated와 notice도 함께 그려 주시기 바랍니다.

키

종류	누구	보내는 법	한도(기본)
`pk_…`	브라우저에서 부르는 앱	`x-api-key` 헤더 · `?key=`	분 120 · 일 20,000
`sk_…`	서버에서 부르는 파트너	`Authorization: Bearer` 만	분 600 · 일 200,000

공개키는 인증이 아니라 신원 표시입니다. 번들에 들어가므로 비밀이 아니고, Origin 허용목록으로 지킵니다. 등록하지 않은 출처에서 부르면 403입니다.

비밀키는 Authorization 헤더로만 받습니다. 주소에 담으면 로그·리퍼러·브라우저 히스토리에 남고, 다른 헤더로 보내면 그 응답이 공유 캐시에 들어갈 수 있습니다. 받는 길을 하나로 좁혀 둔 이유입니다.

발급: contact@bluebutton.kr — 어디에 쓰실 것인지와 호출할 출처(도메인)를 함께 알려주세요.

점수는 기본으로 주지 않습니다

`view`	담기는 것	누구
`family` (기본)	이름·지역·주소·등급·평가연도·다음평가·설립·연차·인력· 정원·밀도·간호·이력·추이	누구나
`full`	위 + `score`·`scores`·`rank`·`pct`·`peerN`·`gap`·`target`·`anomaly`·`leak`	`sk_`만

총점과 순위는 기관 담당자용 진단 지표입니다. 보호자가 보는 화면에 총점을 놓으면 「1위 요양원」 같은 읽기를 낳습니다. 등급이 같아도 0.3점 차이로 한 곳이 배제되는데, 그 0.3점은 그런 무게를 견디지 못합니다. 이 규칙을 앱 코드에만 두면 파트너가 붙는 순간 깨지므로 API가 기본값으로 지킵니다.

엔드포인트

`GET /meta`	급여종류 코드표 · 정렬 목록 · 한도 · 담기지 않은 것
`GET /institutions`	목록 (아래 질의 참조)
`GET /institutions/{key}`	한 곳. 슬러그 붙은 키도 받습니다
`GET /institutions/batch`	`?keys=a,b,c` 최대 20건. 요청한 순서를 지킵니다
`GET /regions`	시도 → 시군구 → 건수
`GET /regions/{시도}/{시군구}`	급여종류별 건수 + 읍면동
`GET /search`	`?q=` 두 자 이상
`GET /stats`	전체 집계
`GET /guide/{급여코드}`	2026년 평가지표

기준 주소는 https://caregrade.kr/api/v1 입니다.

`/institutions` 질의

sido=       시도 이름 그대로 (서울특별시)
gugun=      시군구 ("성남시 분당구" 처럼 공백이 있는 것도 그대로)
dong=       읍면동
svc=        급여종류 코드, 쉼표. 01 02 03 = 입소, 04 방문요양 ...
grade=      A,B,C,D,E 쉼표
next_eval=  다음 정기평가 연도 (2026 · 2027 ...)
sort=       아래 표
limit=      1~100 (기본 20)
cursor=     앞 응답의 next 를 그대로
view=       family | full
closed=1    폐업 추정까지 포함 (기본은 뺍니다)

급여종류는 코드로 받습니다. 앱이 쓰는 이름(시설·주야간…)은 그쪽 어휘라 그쪽이 매핑합니다 — 「시설」이면 svc=01,02,03. 코드표는 /meta에 있습니다.

정렬

`grade` (기본)	등급 오름 → 평가연도 내림
`grade_score`	등급 오름 → 총점 내림
`care`	정원 대비 요양보호사 — 낮을수록 촘촘 → 등급
`nurse`	간호 인력 많은 순 → 등급
`name`	이름 (한글 정렬)
`score`	총점 내림 (`full`에서만 뜻이 있습니다)
`cap` · `new`	정원 · 운영 연차

grade와 grade_score가 나뉜 이유 — 보호자에게는 최근에 받은 평가가 중요하고 기관 담당자에게는 총점이 중요합니다. 둘 다 맞아서 합치지 않았습니다.

없는 것과 모르는 것

두 가지가 목록에 섞여 있어 나눠 두었습니다.

unlisted: true — 평가 기록은 있는데 시설별현황 등록부에서 확인되지 않습니다. 이때 addr·zip·since는 빈 문자열, cap·density·years·staff는 null, 그리고 nurse는 0으로 옵니다. 그 0은 간호사가 없다는 뜻이 아니라 우리가 모른다는 뜻입니다. 화면에 「없음」으로 쓰지 마세요 — 「확인되지 않음」으로 쓰시거나 그 항목을 통째로 빼는 쪽이 맞습니다.
폐업 추정 — unlisted이면서 다음 정기평가도 이미 지난 804곳입니다. 목록에서는 기본으로 뺍니다. 사이트의 지역 목록이 이들을 빼기 때문에, API가 넣으면 같은 질문에 두 답이 나옵니다. 필요하시면 closed=1로 받으세요. 다만 기관 하나를 직접 부르는 /institutions/{key}와 /batch는 그대로 드립니다 — 폐업은 저희가 단정할 수 있는 것이 아닙니다.

페이지 넘기기 · 캐시

next가 오면 그것을 cursor=로 그대로 보내세요. null이면 끝입니다. 커서 안을 들여다보지 마세요 — 지금은 오프셋을 감싼 것이지만 데이터가 커지면 정렬키 기반으로 바뀝니다. 불투명하게 두었으므로 받는 쪽을 고치지 않고 바꿀 수 있습니다.

`Cache-Control`	`public, s-maxage=86400, stale-while-revalidate=604800` (`family`) · `private, no-store` (`full`)
`ETag`	있습니다. `If-None-Match`로 아껴 쓰실 수 있습니다
`x-data-updated`	데이터 기준일. 이 값이 바뀌면 캐시를 비우시면 됩니다

연 1회 바뀌는 데이터입니다. 하루 캐시해도 낡지 않습니다.

오류

{ "error": { "code": "forbidden", "message": "..." } }

코드	상태	언제
`unauthorized`	401	키가 없거나 해지됨
`forbidden`	403	등록되지 않은 Origin · 공개키로 `view=full`
`bad_request`	400	`limit`·`view`·`cursor`·`q`가 잘못됨 · 비밀키를 헤더 아닌 곳으로
`not_found`	404	없는 기관·지역·급여코드
`rate_limited`	429	한도 초과. `Retry-After`를 보세요

코드는 고정입니다. 받는 쪽이 문자열로 분기하게 되므로 한 번 낸 코드는 바꾸지 않습니다. 문구는 다듬을 수 있습니다.

담기지 않은 것

전화번호 — 공개 데이터에 없습니다. 기관이 직접 등록한 곳만 화면에 있습니다.
좌표 — 실시간 지오코딩 API는 어느 것도 저장을 허용하지 않습니다. 파일 기반 주소DB를 받는 중입니다.
점수 예측 — 2026년부터 재가급여도 신4영역인데 그 체계로 평가받은 기관이 아직 없습니다. 가중치를 계산할 자료가 없습니다.

출처 표기

원본은 「이용허락범위 제한 없음」이라 재배포에 제약이 없습니다. 다만 받는 쪽도 출처를 밝혀 주시기 바랍니다 — 응답의 meta.source를 그대로 쓰시면 됩니다.

그리고 meta.notice는 그대로 화면에 실어 주시기 바랍니다. 등급만 떼어 보여주면 3년 전 평가가 오늘의 상태로 읽힙니다.