-
Notifications
You must be signed in to change notification settings - Fork 1
Usage
아래와 같이 라이브러리를 설치합니다. python 3.8 이상을 권장하며, 이하의 버젼에서는 작동을 검증하지 않았습니다. 또, pip 20.x 이상을 권장합니다. 만약 라이브러리 설치하다가 오류가 나면 pip를 업데이트해 주세요.
pip install korean-geocoding
from korean_geocoding.geocoding import KoreanGeocoding as Kg
kg = Kg()kg 인스턴스를 이용하여 해당 라이브러리의 기능을 이용할 수 있습니다. 아래의 모든 메소드를 호출 전에 위와 같이 인스턴스를 만들어 주세요.
주어진 행정구역의 위도/경도 좌표를 반환합니다. (<위도>, <경도>)의 Tuple 형태로 반환됩니다.
-
query(Required) : 검색할 행정구역명. 각 구역은 기본적으로 띄어쓰기 하나로 구분하며 현재는 시군구/리 까지만 지원합니다. (Ex: 부산광역시 동구 범일동, 부산광역시 기장군 일광면 용천리) 도로명까지의 세부 주소를 넣지 말아주세요.
- 0.4.0부터는 시도명에 '서울특별시'와 같이 정식 명칭을 넣지 않고, '서울시' '전북' 등과 같이 축약된 명칭을 넣어도 인식합니다. -
delimiter : 각 행정구별 구분자. 기본적으로 공백 하나로 구분합니다. 만약 '부산광역시|동구|범일동' 이라는 쿼리를 넣고 싶다면, delimiter='|'로 값을 넣음으로써 정상적으로 ['부산광역시', '동구', '범일동'] 으로 인식됩니다.
-
just_fit : T/F 값을 가집니다. False라면 중간에 알 수 없는 행정구역 이름이 들어온 경우, 여기까지 인식된 곳의 주소만 가지고 좌표를 계산합니다. "부산광역시 동구 알수없는동"이라고 입력한다면, '알수없는동'은 인식할 수 없으므로 "부산광역시 동구"의 좌표를 반환합니다.
print(kg.get_coordinates('서울특별시 종로구'))
print(kg.get_coordinates('서울시 종로구'))
print(kg.get_coordinates('서울특별시:종로구', delimiter=':'))
print(kg.get_coordinates('서울특별시 종로구 알수없는동', just_fit=False))(37.5735207, 126.9788345)
(37.5735207, 126.9788345)
(37.5735207, 126.9788345)
(37.5735207, 126.9788345)
주어진 행정구역의 하위 행정구역의 list를 반환합니다.
주의: 현재 행정동과 법정동이 구분되어 있지 않아, 특히 광역시나 특별시의 하위 구에서 이 함수를 사용할 시 행정동과 법정동이 섞여서 출력되고 있습니다. 주의해 주세요. 추후 이 문제는 태깅을 통해 수정할 예정입니다. ㅠ.ㅠ 시군구나 읍면리는 정상적으로 이용 가능합니다.
파라미터는 위와 동일합니다.
from korean_geocoding.geocoding import KoreanGeocoding as Kg
kg = Kg()
print(kg.get_under_districts('서울특별시'))
print(kg.get_under_districts('부산광역시 기장군'))
print(kg.get_under_districts('세종특별자치시'))['종로구', '중구', '용산구', '성동구', '광진구', '동대문구', '중랑구', '성북구', '강북구', '도봉구', '노원구', '은평구', '서대문구', '마포구', '양천구', '강서구', '구로구', '금천구', '영등포구', '동작구', '관악구', '서초구', '강남구', '송파구', '강동구']
['기장읍', '장안읍', '정관읍', '일광면', '철마면']
['조치원읍', '연기면', '연동면', '부강면', '금남면', '장군면', '연서면', '전의면', '전동면', '소정면', '한솔동', '새롬동', '도담동', '아름동', '종촌동', '고운동', '소담동', '보람동', '대평동', '반곡동', '가람동', '나성동', '다정동', '어진동']
주어진 두 점 간의 거리를 km 단위로 반환합니다. 지구는 구형이므로, 구형의 표면에서의 두 점간의 거리를 구할 수 있는 haversine 공식을 이용하여 구합니다. query1과 query2는 (위도, 경도) 형태의 Tuple이나, get_coordinates()와 동일한 방식으로 행정구역명을 담은 문자열을 받습니다. 문자열과 튜플의 방식을 혼용해도 됩니다. 튜플에 담긴 좌표는 특정 행정구역의 좌표가 아닌 임의의 좌표여도 됩니다. 이외의 just_fit이나 delimiter는 문자열 형태의 주소를 받을 때에만 사용되며, 사용법은 위와 동일합니다. 결과값은 소수 셋째자리까지 표시됩니다.
from korean_geocoding.geocoding import KoreanGeocoding as Kg
kg = Kg()
# (37.5325225, 126.9950384) = 서울특별시 용산구 이태원동
# (37.563275, 126.973425) = 서울특별시 중구 서소문동
kg.get_distance("서울특별시 용산구 이태원동", "서울특별시 중구 서소문동")
kg.get_distance("서울특별시 용산구 이태원동", (37.563275, 126.973425))
kg.get_distance((37.5325225, 126.9950384), (37.563275, 126.973425))
kg.get_distance((34.123142, 36.333213), "서울특별시 용산구 이태원동") # 앞의 튜플은 임의의 좌표입니다..3.915
3.915
3.915
215.486
이 섹션의 메소드들은 Naver Cloud Platform(NCP)에서 제공하는 Geocoding API를 래핑 및 활용하는 메소드들입니다. 다른 기능들은 NCP 계정을 세팅하지 않아도 사용 가능하지만, 이 챕터의 기능을 사용하려면 세팅이 필요합니다. https://www.ncloud.com/?language=ko-KR 에서 계정 로그인 후, Naver Geocoding 서비스를 활성화 합니다.
자세한 방법은 공식 문서를 참조해 주세요.
참고로 2022.4월 현재 Geocoding API는 완전 무료이지만 월 300만건 한도 제한이 있습니다. 이 점 주의해 주세요.
NCP에서 발급받은 클라이언트 키와 비밀키를 세팅하여, NCP에 API를 호출할 수 있도록 키를 세팅합니다. 해당 함수 호출 후, Naver API를 사용하는 함수들을 호출할 수 있습니다. 아래와 같이 사용하면 됩니다.
주의: 만약 Github과 같은 공개된 장소에 코드를 올릴 떄, NCP에서 발급받은 client key와 client secret key가 유출되지 않도록 유의해 주세요.
from korean_geocoding.geocoding import KoreanGeocoding as Kg
kg = Kg()
# 위는 기존 세팅과 동일합니다.
kg.set_naver_api(<NAVER_CLIENT_ID>, <NAVER_CLIENT_SECRET>)query로 전달된 주소의 위경도 좌표를 불러옵니다. Naver API를 통해 불러오므로, 위의 get_coordinates()와 달리 도로명, 건물명 등 상세 주소를 이용할 수 있습니다. 도로명주소와 지번주소 모두 가능합니다.
주의! 특정 건물의 좌표를 구하는게 아니라, 행정구역에 대한 좌표를 얻는 것이라면 위의 get_coordinates()를 이용하는 것을 강력히 권장합니다. 이 함수는 네트워크를 통해 API를 호출하고 응답받는 과정이 포함되어 있기 때문에 네트워크 상태에 영향을 받으며, 기본적으로 get_coordinates()에 비해 매우 느립니다.
- query, delimiter, ignore_empty : 위와 동일합니다.
- detailed : API를 통해 반환된 결과를 정리하여, 대부분의 필요한 정보를 그대로 반환합니다. 해당 결과는 dict 자료형으로 반환되며 어떤 시군구에 속하는지, 우편번호, 영문주소, 도로명주소, 지번주소 등 다양한 정보가 들어 있습니다. 네이버 API로부터 반환되는 원본 데이터는 구조가 복잡하여 사용하기 어려웠지만, 여기서는 구조를 정리하여 필요한 부분만 추출하여 직관적으로 사용할 수 있습니다.
from korean_geocoding.geocoding import KoreanGeocoding as Kg
kg = Kg()
kg.set_naver_api(<NAVER_CLIENT_ID>, <NAVER_CLIENT_SECRET>) # 발급받은 키를 넣어야 합니다.
print(kg.get_coordinates_by_api("서울 마포구 양화로7안길 2-1")
print(kg.get_coordinates_by_api("서울 마포구 서교동 391-5")) # 동일 건물
print(kg.get_coordinates_by_api('서울시 용산구 한강대로 366', detailed=True))(37.5516895, 126.9150549)
(37.5517072, 126.9150565) # 소수점 네째 자리부터 약간 다르지만 네이버 지도에 검색하면 동일한 건물을 나타냅니다.
# detailed=True의 결과값
{'address_elements': {'BUILDING_NAME': '트윈시티 남산',
'BUILDING_NUMBER': '366',
'DONGMYUN': '동자동',
'LAND_NUMBER': '56',
'POSTAL_CODE': '04323',
'RI': '',
'ROAD_NAME': '한강대로',
'SIDO': '서울특별시',
'SIGUGUN': '용산구'},
'english_address': '366, Hangang-daero, Yongsan-gu, Seoul, Republic of Korea',
'jibun_address': '서울특별시 용산구 동자동 56 트윈시티 남산',
'latitude': '37.5511247',
'longitude': '126.9729133',
'road_address': '서울특별시 용산구 한강대로 366 트윈시티 남산'}도로명주소 DB 등 공간정보에 대한 오픈데이터를 얻을 때, 위경도를 이용한 지리좌표계가 아닌 대부분 평면에 투영하는 투영좌표계를 사용합니다. 이러한 좌표계는 한국에서 통용되는 것만 중부원점 좌표계, 동부원점 좌표계 등 수십 가지가 있어서, 각 데이터마다 활용하는 좌표계가 달라 처리하기 곤란한 경우가 있습니다.(자세한 정보) 이런 경우를 위해, pyproj 라이브러리를 래핑하여 좌표 변환을 쉽게 할수 있도록 지원합니다. 각 좌표계는, EPSG라는 고유한 번호를 가지고 있습니다. 예를 들어, 우리가 흔히 아는 위도와 경도를 사용하는 지리좌표계는 EPSG:4326 이라는 번호를 가집니다.
현재, 단순 변환 함수만 있지만 추후 변환 과정을 도와주거나 자동으로 진행하는 함수가 추가될 예정입니다.
좌표 변환 함수를 사용하려면 우선 이 함수를 먼저 불러서, 변환할 좌표계를 설정해야 합니다. from_crs의 좌표계를 to_crs의 좌표계로 변환하도록 설정되며, to_crs의 기본값인 epsg:4326은 우리가 흔히 아는 위경도 좌표계를 나타냅니다. 따라서, 특별한 일이 없다면 to_crs는 따로 값을 설정할 일이 없을 것입니다. 만약, 처음 설정한 것과 다른 좌표계로 변환해야 한다면 다시 이 함수를 호출하여 변환할 좌표계를 바꿀 수 있습니다.
from_crs에는 epsg:코드 형태의 문자열이 필요합니다. 각 좌표계마다 부여된 고유한 번호는 여기 및 구글링을 통해 검색해 주세요.
from korean_geocoding.geocoding import KoreanGeocoding as Kg
kg = Kg()
# 위는 기존 세팅과 동일합니다.
kg.set_converter("epsg:5174")coordinates로 전달된 (x좌표, y좌표) 형태의 좌표를 위에서 설정한 좌표계로 변환합니다.
from korean_geocoding.geocoding import KoreanGeocoding as Kg
kg = Kg()
coord_5174 = (451391.18, 196794.06)
kg.set_converter("epsg:5174")
lat, long = kg.convert(coord_5174)(37.5516895, 126.9150549)