Gimi9 Geocoder

한국 주소 지오코딩을 위한 Python 라이브러리입니다. 주소를 좌표로 변환하거나, 좌표를 주소로 변환하는 기능을 제공하며, pandas와 geopandas를 활용한 데이터 분석과 GIS 작업에 최적화되어 있습니다.

Notebook 샘플: https://colab.research.google.com/drive/1Er7h2DsWy3cnB28xXfX78iO2v2wDnzUV?usp=sharing

API 토큰 발급

서비스를 이용하려면 API 토큰이 필요합니다. geocode.gimi9.com에서 API 토큰을 발급받으세요.

주요 기능

• 다양한 입력 형식 지원: 단일 주소(str), 주소 리스트(List[str]), pandas DataFrame 지원
• 지오코딩: 한국 주소를 위도/경도 좌표로 변환
• 역지오코딩: 좌표를 도로명주소와 지번주소로 변환
• Pandas/GeoPandas 통합: DataFrame을 활용한 대량 주소 처리
• 행정구역 정보: 한국 행정구역(시도/시군구/행정동) 형상 조회
• 이력 조회: 행정구역 변화 이력 조회
• 토큰 관리: API 토큰 사용량 통계 확인

설치

pip를 사용하여 라이브러리를 설치할 수 있습니다:

pip install gimi9-geocoder

시작하기

기본 사용법

from gimi9_geocoder.client import GeocoderClient

# 클라이언트 초기화
geocoder = GeocoderClient(token="YOUR_API_TOKEN")

# 단일 주소 지오코딩
result = geocoder.geocode("서울특별시 강남구 테헤란로 123")
print(result)

# 여러 주소 일괄 지오코딩
addresses = [
    "서울특별시 강남구 테헤란로 123",
    "부산광역시 해운대구 해운대해변로 456",
    "대구광역시 중구 동성로 789"
]
result = geocoder.geocode(addresses)
print(result)

DataFrame 활용

import pandas as pd
from gimi9_geocoder.client import GeocoderClient

# 주소가 포함된 DataFrame 생성
data = {
    "name": ["서울시청", "부산시청", "대구시청", "인천시청"],
    "address": [
        "서울특별시 중구 세종대로 110 서울특별시청",
        "부산광역시 연제구 중앙대로 1001(연산동) 부산광역시청",
        "대구광역시 중구 공평로 88 (동인동1가) 대구광역시청",
        "인천광역시 남동구 정각로29 (구월동 1138) 인천광역시청"
    ]
}
df = pd.DataFrame(data)

# DataFrame을 사용한 지오코딩
geocoder = GeocoderClient(token="YOUR_API_TOKEN")
result = geocoder.geocode(df, address_col='address')
print(result)
# 결과는 GeoPandas DataFrame으로 반환되며, 원본 데이터와 지오코딩 결과가 합쳐집니다

역지오코딩

# 단일 좌표 역지오코딩
result = geocoder.reverse_geocode(127.1146829, 37.5138498)
print(result)
# 결과: 도로명주소와 지번주소 정보가 포함된 GeoDataFrame

# DataFrame을 활용한 대량 역지오코딩
df_coords = pd.DataFrame({
    'x': [127.1146829, 129.0440854],
    'y': [37.5138498, 35.1021227]
})
result = geocoder.reverse_geocode(x_col="x", y_col="y", coordinates=df_coords)
print(result)

# GeoDataFrame을 활용한 역지오코딩
# geocode 결과를 바로 사용 가능
result = geocoder.reverse_geocode(coordinates=geocoded_gdf)
print(result)

행정구역 형상 조회

# 행정동 형상 조회
regions = geocoder.region(
    type="hd",  # 행정동
    code="1114055000,4111760000",  # 행정동 코드
    yyyymm="202506"  # 기준년월
)
print(regions)

# 시군구 형상 조회
regions = geocoder.region(
    type="h23",  # 시군구
    code="11140,41117",  # 시군구 코드
    yyyymm="202506"
)

# 시도 형상 조회
regions = geocoder.region(
    type="h1",  # 시도
    code="11,41",  # 시도 코드
    yyyymm="202506"
)

행정구역 이력 조회

# 특정 좌표의 행정구역 이력 조회
hd_history = geocoder.hd_history(
    x=127.075074, 
    y=37.143834, 
    yyyymm="202506"
)
print(hd_history)

# 전체 이력 조회 (yyyymm 생략)
hd_history = geocoder.hd_history(x=127.075074, y=37.143834)
print(hd_history)

토큰 사용량 확인

# API 토큰 사용 통계 조회
token_stats = geocoder.token_stats()
print(token_stats)

API 메서드

geocode(locations, address_col=None)

주소를 좌표로 변환합니다.

매개변수:

• locations: 단일 주소(str), 주소 리스트(List[str]), 또는 DataFrame
• address_col: DataFrame 사용 시 주소가 있는 컬럼명 (DataFrame 사용 시 필수)

반환값: GeoPandas DataFrame (geometry 컬럼에 Point 객체)

reverse_geocode(x_col, y_col, coordinates=None)

좌표를 주소로 변환합니다.

매개변수:

• x_col: X좌표 값 또는 DataFrame의 X좌표 컬럼명
• y_col: Y좌표 값 또는 DataFrame의 Y좌표 컬럼명
• coordinates: 좌표가 포함된 DataFrame 또는 GeoDataFrame

반환값: GeoPandas DataFrame (도로명주소, 지번주소 정보 포함)

region(type, code, yyyymm)

행정구역 형상을 조회합니다.

매개변수:

• type: 행정구역 유형 ("h1": 시도, "h23": 시군구, "hd": 행정동)
• code: 행정구역 코드 (쉼표로 구분하여 여러 개 가능)
• yyyymm: 기준년월 (예: "202506")

반환값: GeoPandas DataFrame (행정구역 형상 정보)

hd_history(x, y, yyyymm=None)

특정 좌표의 행정구역 이력을 조회합니다.

매개변수:

• x: X좌표 (경도)
• y: Y좌표 (위도)
• yyyymm: 기준년월 (생략 시 전체 이력)

반환값: 행정구역 이력 정보 (dict)

token_stats()

API 토큰 사용량 통계를 조회합니다.

반환값: 토큰 사용량 통계 (dict)

예제

더 자세한 사용 예제는 다음 파일들을 참고하세요:

• sample/simple.py: 기본 사용법
• sample/with_pandas.py: pandas DataFrame 활용
• sample/notebook.ipynb: Jupyter Notebook 예제 (시각화 포함)

Jupyter Notebook에서 사용하기

# 패키지 설치
%pip install gimi9-geocoder

import pandas as pd
import geopandas as gpd
import folium
from gimi9_geocoder.client import GeocoderClient

# 지오코딩 후 지도 시각화
geocoder = GeocoderClient(token="YOUR_API_TOKEN")
gdf = geocoder.geocode("서울특별시 강남구 테헤란로 123")

# Folium을 사용한 지도 시각화
m = folium.Map(location=[37.5665, 126.9780], zoom_start=10)
for idx, row in gdf.iterrows():
    folium.Marker(
        location=[row.geometry.y, row.geometry.x],
        popup=row['address']
    ).add_to(m)
m

의존성

이 패키지는 다음 라이브러리들을 사용합니다:

• httpx: HTTP 클라이언트
• pandas: 데이터 조작 및 분석
• geopandas: 공간 데이터 처리
• shapely: 기하학적 객체 조작

라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참고하세요.

기여하기

기여를 환영합니다! 개선사항이나 버그 수정을 위해 Pull Request를 제출하거나 Issue를 열어주세요.

문의

• 작성자: gisman
• 이메일: gisman@gmail.com
• GitHub: https://github.com/gisman/gimi9_geocoder