Hans API

Appearance

주소 ​

주소(/address) 그룹입니다. 지역 코드(시도·시군구)와 영문 주소 검색 두 가지를 담습니다.

영문 주소 검색 ​

도로명주소 개발자센터(juso.go.kr)의 영문 주소 검색 API입니다. 한글 주소를 넣으면 공식 영문 표기로 바꿔 줍니다.

주소는 지어내면 안 됩니다

로마자 표기는 규칙이 까다로워(중앙대로1985번길 → Jungang-daero 1985beon-gil) 임의로 만들면 틀립니다. 이 API 는 국가가 관리하는 공식 표기를 그대로 가져옵니다.

한글 → 영문 ​

한글 주소를 keyword 로 검색하면, 매칭되는 주소를 한글·영문 함께 돌려줍니다. 영문은 순서가 뒤집힙니다 — 한글은 큰 단위→작은 단위, 영문은 작은 단위→큰 단위입니다.

부산광역시 금정구 중앙대로1985번길 1
1 Jungang-daero 1985beon-gil, Geumjeong-gu, Busan

시/도, 시/군/구, 읍/면/동도 각각 영문으로 쪼개 줍니다(sido, sigungu, eupmyeondong).

검색 제약 ​

시/도명 단독·한 글자·숫자만으로는 검색되지 않습니다. 도로명주소 API 자체의 제약이며, 이 경우 400 을 반환합니다. 결과가 없을 때는 에러가 아니라 빈 목록입니다.

데이터 출처 ​

  • 행정안전부 도로명주소 영문 검색 API (juso.go.kr)

지역 코드​

GET
/address/regions

시도 → 시군구 2단계다.

level=sido 로 시도를, level=sggu&parent=11 로 그 시도의 시군구를 받는다.

병원 검색의 region 파라미터에 시군구 코드를 넘긴다.

Request

🔒 Bearer 인증 필요 · 인증 방법
GET/address/regions

Query Parameters

NameTypeRequiredConstraintsDescription
levelstringoptionalenum: sido, sggu
parentstringoptional시도 코드 (시군구를 좁힐 때)

Response

200

ListResponse

FieldTypeRequiredConstraintsDescription
itemsRegion[]required

Region

FieldTypeRequiredConstraintsDescription
codestringrequired
namestringrequired정식 명칭. **검색·매칭은 이걸 쓴다.**
shortNamestringoptional화면 표시용 짧은 이름. 시도만 있다 — 시군구는 이미 짧다(강남구). 규칙으로 만들 수 없어 코드 테이블에 값으로 둔다 ("충청북도"→"충북", "전남광주통합특별시"→"전남").
levelstringrequiredsido | sggu
parentCodestringoptional시도 코드. 시도면 없다.
{
  "items": [
    {
      "code": "11001",
      "name": "서울특별시",
      "shortName": "서울",
      "level": "sggu",
      "parentCode": "11"
    }
  ]
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI

좌표로 지역 코드 조회​

GET
/address/regions/reverse

위경도를 주면 그 좌표가 속한 시도·시군구를 돌려준다. "내 위치" 버튼이 브라우저에서 받은 좌표를 지역 필터로 바꿀 때 쓴다.

받은 코드는 병원 검색의 region 파라미터에 그대로 넣으면 된다 — region 이 있으면 그 시군구 코드를, 없으면 sido 코드를 보낸다.

한국 밖이거나 주변에 병원이 없으면 404 다. 위치를 못 알아낸 것이지 오류가 아니니, 클라이언트는 조용히 지역 선택을 비워두면 된다.

Request

🔒 Bearer 인증 필요 · 인증 방법
GET/address/regions/reverse

Query Parameters

NameTypeRequiredConstraintsDescription
latnumberrequired위도
lonnumberrequired경도

Response

200

RegionPoint

FieldTypeRequiredConstraintsDescription
sidoRegionrequired시도. 늘 있다.
regionRegionoptional시군구. **없을 수 있다** — 세종특별자치시처럼 시군구가 없는 시도가 있다.

Region

FieldTypeRequiredConstraintsDescription
codestringrequired
namestringrequired정식 명칭. **검색·매칭은 이걸 쓴다.**
shortNamestringoptional화면 표시용 짧은 이름. 시도만 있다 — 시군구는 이미 짧다(강남구). 규칙으로 만들 수 없어 코드 테이블에 값으로 둔다 ("충청북도"→"충북", "전남광주통합특별시"→"전남").
levelstringrequiredsido | sggu
parentCodestringoptional시도 코드. 시도면 없다.
{
  "sido": {
    "code": "11001",
    "name": "서울특별시",
    "shortName": "서울",
    "level": "sggu",
    "parentCode": "11"
  },
  "region": {
    "code": "11001",
    "name": "서울특별시",
    "shortName": "서울",
    "level": "sggu",
    "parentCode": "11"
  }
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI

영문 주소 검색​

GET
/address/english

한글 주소(또는 일부)를 검색해 매칭되는 주소를 영문 표기와 함께 반환한다.

시/도명 단독·한 글자·숫자만으로는 검색되지 않는다(도로명주소 API 제약). 결과가 없으면 빈 목록을 반환한다.

Request

🔒 Bearer 인증 필요 · 인증 방법
GET/address/english

Query Parameters

NameTypeRequiredConstraintsDescription
keywordstringrequired검색할 한글 주소(또는 일부). 예: 도로명주소·건물명·지번.
pagenumberoptionaldefault 1페이지 번호
sizenumberoptionalmin 1 · max 100 · default 20페이지 크기

Response

200

PageResponse

FieldTypeRequiredConstraintsDescription
itemsAddress[]required
pagenumberrequired현재 페이지 번호
sizenumberrequired페이지 크기
totalCountnumberrequired전체 항목 수
totalPagesnumberrequired전체 페이지 수

Address

FieldTypeRequiredConstraintsDescription
korAddrstringrequired한글 도로명주소(정규화됨)
roadAddrstringrequired영문 도로명주소(전체)
jibunAddrstringoptional영문 지번주소
zipNostringoptional우편번호(5자리)
sidostringoptional영문 시도명
sigungustringoptional영문 시군구명
eupmyeondongstringoptional영문 읍면동명
roadNamestringoptional영문 도로명
{
  "items": [
    {
      "korAddr": "부산광역시 금정구 중앙대로1985번길 1",
      "roadAddr": "1 Jungang-daero 1985beon-gil, Geumjeong-gu, Busan",
      "jibunAddr": "129-13 Namsan-dong, Geumjeong-gu, Busan",
      "zipNo": "46227",
      "sido": "Busan",
      "sigungu": "Geumjeong-gu",
      "eupmyeondong": "Namsan-dong",
      "roadName": "Jungang-daero 1985beon-gil"
    }
  ],
  "page": 0,
  "size": 0,
  "totalCount": 0,
  "totalPages": 0
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI