대한민국 법정동 코드 조회 API
법정동 목록 API는 Cloudflare Workers 환경 위에서 동작합니다. API 주소는 api.juso.dev 입니다.
코드 체계 설명
법정동 목록 조회 API는 법정동코드를 기반으로 동작합니다.
법정동코드는 총 10자리로 구성되어 있으며 규칙은 다음과 같습니다(출처).
- 가장 앞의 두 자리: [시/도]
- 그 다음 세 자리: [시/군/구]
- 그 다음 세 자리: [읍/면/동]
- 그 이후 나머지: [리]
예를 들어 서울특별시의 코드는 1100000000 이며, 서울특별시에 속한 모든 구는 11???00000 형식을 띄고 있습니다. 이 API는 이러한 코드체계의 특성을 이용하여 wildcard 구문을 지원하여 원하는 목록을 반환할 수 있습니다.
파라메터
regcode_pattern
string 타입, 검색하고자 하는 코드 패턴을 입력합니다. 예를 들어 모든 특별/광역시(도)를 조회하려면 *00000000 파라메터를 입력합니다.
is_ignore_zero
boolean 타입, regcode_pattern 파라메터만 사용할 경우 발생하는 문제점을 해결하고자 추가된 파라메터입니다.
예를 들어 종로구의 모든 동을 조회하려면 regcode_pattern 값이 1111* 형태를 띄게 될텐데 이 경우 서울특별시 종로구(1111000000)도 함께 조회가 됩니다. 종로구 그 자체가 아닌 종로구 소속만 조회하고 싶을 경우엔 is_ignore_zero 파라메터값을 true 로 설정하여 API를 호출합니다.
HTTP 호출
예제
대한민국의 모든 특별/광역시, 도 반환
https://api.juso.dev/v1/regcodes?regcode_pattern=*00000000서울특별시 소속의 모든 구, 동을 반환
https://api.juso.dev/v1/regcodes?regcode_pattern=11*서울특별시 소속의 모든 구 반환
https://api.juso.dev/v1/regcodes?regcode_pattern=11*00000서울특별시 종로구를 포함한 종로구의 모든 동 반환
https://api.juso.dev/v1/regcodes?regcode_pattern=1111*서울특별시 종로구의 모든 동"만" 반환
https://api.juso.dev/v1/regcodes?regcode_pattern=1111*&is_ignore_zero=true응답
응답 형식
조회 결과는 regcodes 배열을 가진 JSON 객체로 반환되며, 각 항목은 법정동코드(code)와 이름(name)을 가집니다.
https://api.juso.dev/v1/regcodes?regcode_pattern=1111*&is_ignore_zero=true{
"regcodes": [
{ "code": "1111010100", "name": "서울특별시 종로구 청운동" },
...
]
}빈 결과
다음의 경우 오류가 아닌 빈 배열({"regcodes": []})을 반환합니다.
regcode_pattern이 비어 있거나 전달되지 않은 경우regcode_pattern에서*를 제외한 글자 수가 법정동코드의 길이(10자)보다 많은 경우- 패턴과 일치하는 법정동코드가 없는 경우