# HIRA API Integration Map

Updated: 2026-05-15

## Key Policy

The project uses one data.go.kr general API key stored in Cloudflare Pages as:

```text
HIRA_SERVICE_KEY
```

Do not commit the key. All public HIRA API calls go through Cloudflare Pages Functions so the browser never sees the secret.

## Implemented Proxies

| Project proxy | Official service | Upstream operation | Main use |
| --- | --- | --- | --- |
| `/api/hira/hospitals` | 건강보험심사평가원_병원정보서비스 | `getHospBasisList` | Hospital master list, provider type, address, encrypted ykiho |
| `/api/hira/medical-detail` | 건강보험심사평가원_의료기관별상세정보서비스 | selectable `endpoint` | Facility, departments, equipment, specialists, nursing grade, special care |
| `/api/hira/clinic-top5` | 건강보험심사평가원_병원진료정보조회서비스 | `getClinicTop5List1` | Clinic-level top five public-interest diseases |
| `/api/hira/pharmacies` | 건강보험심사평가원_약국정보서비스 | `getParmacyBasisList` | Pharmacy master and local medical-network context |

## Medical Detail Endpoints

`/api/hira/medical-detail` accepts:

| endpoint | HIRA operation | Meaning |
| --- | --- | --- |
| `detail` | `getDtlInfo2.7` | 세부정보 |
| `departments` | `getDgsbjtInfo2.7` | 진료과목정보 |
| `facility` | `getEqpInfo2.7` | 시설정보 |
| `equipment` | `getMedOftInfo2.7` | 의료장비정보 |
| `specialists` | `getSpcSbjtSdrInfo2.7` | 전문과목별 전문의 수 |
| `special-care` | `getSpclDiagInfo2.7` | 특수진료정보 |
| `transport` | `getTrnsprtInfo2.7` | 교통정보 |
| `meal` | `getFoepAddcInfo2.7` | 식대가산정보 |
| `nursing` | `getNursigGrdInfo2.7` | 간호등급정보 |
| `specialty-hospital` | `getSpclHospAsgFldList2.7` | 전문병원지정분야 |
| `staff` | `getEtcHstInfo2.7` | 기타인력수 |

Example:

```text
/api/hira/medical-detail?endpoint=departments&ykiho={encrypted_ykiho}&_type=json
```

## Interpretation Rules

- These APIs do not provide hospital-level lung cancer new-patient counts.
- Use them to build a clean hospital candidate list and explain capacity/context: provider type, region, departments, equipment, specialists, special-care availability, and nearby care network.
- The hospital-level new-patient count still requires HIRA customized research data or NHIS customized DB approval.
- The encrypted `ykiho` in public APIs is useful inside the public API family, but it should not be treated as a directly reversible institution identifier for custom claims extracts.

## Deployment Note

As of 2026-05-15, Cloudflare Pages reached HIRA successfully only with the lowercase `serviceKey` parameter over the HTTP `apis.data.go.kr` endpoint. The uppercase `ServiceKey` parameter and HTTPS endpoint timed out for the approved key, even though invalid-key probes returned 401 quickly.

The proxy therefore uses:

```text
http://apis.data.go.kr/...&serviceKey={key}
```

and keeps HTTPS as a fallback.

Because the live response can still be unstable from Cloudflare, the project now supports a cache fallback:

```text
npm run fetch:hira-cache
```

The script writes JSON files to `data/processed/hira-cache/`. The dashboard first tries the live Pages Function and then falls back to these cache files if Cloudflare-to-HIRA calls time out.

Operational options:

1. Add `HIRA_SERVICE_KEY` as a GitHub Actions repository secret and run `Refresh HIRA API Cache`.
2. Run `npm run fetch:hira-cache` locally with the same key and commit the refreshed cache.
3. Keep Cloudflare Pages as the static dashboard while HIRA API data is updated by GitHub Actions, local scheduler, or a small backend.

## Official Source Pages

- HIRA hospital information service: https://www.data.go.kr/data/15001698/openapi.do
- HIRA medical institution detail service: https://www.data.go.kr/data/15001699/openapi.do
- HIRA clinic top-5 diagnosis information service: https://www.data.go.kr/data/3039508/openapi.do
- HIRA pharmacy information service: https://www.data.go.kr/data/15001673/openapi.do
- HIRA medical-detail API change notice: https://www.data.go.kr/bbs/ntc/selectNotice.do?originId=NOTICE_0000000003758