Hans API

Appearance

교통정보 ​

병원 상세의 교통정보를 화면에 표시할 때 쓰는 참조 데이터입니다.

병원 상세(GET /healthcare/hospitals/{id})의 transport 는 원본이 준 한국어 자유 텍스트입니다.

json
{
  "transport": {
    "subway": [
      { "kindName": "지하철", "line": "4호선", "arrival": "총신대입구역 3번 출구", "distance": "500m" }
    ]
  }
}

arrival 이 "총신대입구역 3번 출구" 처럼 문장입니다. 이걸 영어·일본어 화면에 그대로 뿌리면 한국어가 튀어나옵니다. 지하철역 목록은 그 역명을 공식 표기로 바꾸기 위한 것입니다.

쓰는 법 ​

  1. arrival 에서 역명을 뽑습니다. ("총신대입구역 3번 출구" → "총신대입구역")
  2. 목록에서 ko 로 찾습니다. 역 접미사와 부역명 괄호는 떼고 맞춥니다. ("총신대입구역" → "총신대입구")
  3. 찾은 항목에서 화면 언어에 맞는 필드(ko / en / ja)를 골라 씁니다.
json
{ "ko": "총신대입구", "en": "Chongshin Univ.(Isu)", "ja": "チョンシンデイック", "lines": ["4호선"] }

버전으로 캐시하세요 ​

응답에 version 이 함께 옵니다. 원본 데이터셋의 배포일자입니다.

json
{
  "version": "20260701",
  "items": [
    { "ko": "강남", "en": "Gangnam", "ja": "カンナム", "lines": ["2호선", "신분당선"] }
  ]
}

version 이 그대로면 역 목록도 그대로입니다. 저장해 둔 버전과 같으면 다시 파싱할 필요가 없습니다. 원본 갱신 주기가 길어(연 1~2회) 자주 바뀌지 않습니다.

같은 값이 ETag 로도 나갑니다. If-None-Match 로 재검증하면 바뀐 게 없을 때 304 가 오고 본문이 아예 안 내려옵니다 — 76KB 를 아낍니다. fetch 는 브라우저가 알아서 해 줍니다.

ETag: "1-20260701"

이 API 만 Accept-Language 를 보지 않습니다

다른 API 는 서버가 언어를 골라 평문으로 주지만(다국어), 지하철역 목록은 세 언어를 한 번에 다 내립니다. 화면에 나온 역명을 찾아 바꾸는 용도라 그렇습니다 — 클라이언트가 통째로 받아 맵으로 들고 쓰기 때문에, 언어를 바꿀 때마다 다시 받게 만들 이유가 없습니다.

필터도 페이징도 없습니다. 세 언어를 다 담아도 응답은 gzip 십수 KB 밖에 안 됩니다. Cache-Control: private, max-age=3600 이 붙어 브라우저가 한 시간 캐시합니다.

알고 있어야 할 것 ​

ja 가 없는 역이 있습니다

대구·대전·인천공항은 원본이 일본어 표기를 주지 않습니다. 그 역들은 ja 필드가 아예 없이 옵니다 (빈 문자열이 아니라 생략입니다).

json
{ "ko": "감삼", "en": "Gamsam station", "lines": ["2호선"] }

ja 가 없으면 ko 를 대신 보여주세요. 한국어라도 보이는 편이 빈칸보다 낫습니다.

목록에 없는 역명이 있습니다

원본(HIRA) 교통정보에는 오타(선능역)와 옛 역명(신남역 → 현 청라언덕역)이 섞여 있습니다. 목록에서 못 찾으면 원문(한국어)을 그대로 보여주세요. 지어내면 안 됩니다 — 틀린 역명은 환자를 다른 역에 내리게 합니다.

  • 역코드가 없습니다. 환승역은 노선마다 원본 코드가 달라 역을 식별하지 못합니다. 한국어 역명(ko)이 키입니다.
  • 환승역은 lines 에 노선이 여러 개 들어옵니다. (["2호선", "신분당선"])

데이터 출처 ​

  • 국가철도공단 전국 도시광역철도 역사정보 (공공데이터포털 표준데이터)
  • 전국 도시철도를 모두 덮습니다 — 수도권·부산·대구·대전·광주.
  • 원본 갱신 주기가 길어(연 1~2회) 배포 시점에 반영됩니다.

데이터 정확성

표기는 원본(정부 표기)을 그대로 씁니다. 우리가 고치지 않습니다. 그래서 체계가 다른 표기가 섞여 있습니다 — 일본어는 대부분 가타카나 음차인데 (강남 → カンナム), 부산 일부 역은 한자로 옵니다 (괴정 → 槐亭).

지하철역 목록​

GET
/transport/subway-stations

병원 상세의 교통정보(transport.subway[].arrival)에 나오는 하차역명을 화면에서 다국어로 보여줄 때 쓴다.

세 언어를 한 번에 반환한다. 다른 API 와 달리 Accept-Language 를 보지 않는다 — 역명을 찾아 바꾸는 용도라 클라이언트가 전체를 받아 두고 쓰기 때문이며, 화면 언어를 바꿔도 다시 받을 필요가 없다.

필터도 페이징도 없다. 전체를 한 번에 받는다.

Cache-Control: private, max-age=3600 이 붙는다. 브라우저가 한 시간 캐시한다.

응답의 version 과 ETag 에 원본 데이터의 배포일자가 담긴다. If-None-Match 로 재검증하면 바뀐 게 없을 때 304 가 오고 본문은 안 내려온다. 원본 갱신 주기가 길어(연 1~2회) 대부분의 재검증이 304 로 끝난다.

출처: 국가철도공단 전국 도시광역철도 역사정보 (표준데이터). 전국 도시철도를 모두 덮는다 — 수도권·부산·대구·대전·광주.

Request

🔒 Bearer 인증 필요 · 인증 방법
GET/transport/subway-stations

Response

200

SubwayStationList

FieldTypeRequiredConstraintsDescription
versionstringrequired원본 데이터셋의 배포일자 (`YYYYMMDD`). **이 값이 그대로면 역 목록도 그대로다.** 저장해 둔 버전과 같으면 다시 파싱할 필요가 없다. 원본 갱신 주기가 길어(연 1~2회) 자주 바뀌지 않는다.
itemsSubwayStation[]required역 목록

SubwayStation

FieldTypeRequiredConstraintsDescription
kostringrequired한국어 역명. **이게 키다.** 병원 상세의 `transport.subway[].arrival`(예: '총신대입구역 3번 출구')에서 역명을 뽑아 이 값과 맞춘다. '역' 접미사와 부역명 괄호는 이미 떼어져 있다.
enstringoptional영문 역명. 원본이 전 역에 주므로 사실상 항상 있다. **없으면 `ko` 를 대신 보여줘라.** 지어내면 안 된다.
jastringoptional일문 역명. **대구·대전·인천공항 역들은 비어 있다** — 원본이 주지 않는다. **없으면 `ko` 를 대신 보여줘라.** 빈칸을 그대로 두면 화면이 빈다.
linesstring[]required이 역을 지나는 노선. 환승역이면 여러 개다.
{
  "version": "20260701",
  "items": [
    {
      "ko": "총신대입구",
      "en": "Chongshin Univ.(Isu)",
      "ja": "チョンシンデイック",
      "lines": [
        "4호선"
      ]
    }
  ]
}

Playground​

Server
Authorization

Samples​

Powered by VitePress OpenAPI