hossam.my_gis¶

hossam.my_gis ¶

AddressNotFoundError ¶

Bases: Exception

주소를 찾을 수 없는 경우(소프트 실패). 해당 행만 건너뛰고 계속 진행합니다.

GeocodingError ¶

Bases: Exception

지오코딩 중 발생한 HTTP/API 오류.

Attributes:

Name	Type	Description
`fatal`	`bool`	True면 배치 전체를 중단해야 하는 치명적 오류(예: 인증 키 오류).

geocode ¶

geocode(
    df, addr, key, max_workers=8, requests_per_second=10.0
)

주소 컬럼을 일괄 지오코딩하여 위도/경도 컬럼을 추가합니다.

여러 요청을 스레드 풀로 병렬 처리하며, requests_per_second로 호출 속도를 제어합니다. 개별 주소의 실패(주소 없음/찾지 못함/일반 API 오류)는 해당 행만 결측 처리한 뒤 계속 진행하고, 인증 키 오류 같은 치명적 오류만 배치 전체를 중단합니다.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	입력 `DataFrame`.	required
`addr`	`str`	주소가 들어있는 컬럼명.	required
`key`	`str`	VWorld API 키.	required
`max_workers`	`int`	동시 요청 스레드 수.	`8`
`requests_per_second`	`float`	초당 최대 요청 수(0 이하면 제한 없음).	`10.0`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	위도(`latitude`), 경도(`longitude`) 컬럼이 추가된 `DataFrame`. 입력 인덱스는 0부터 시작하도록 재설정됩니다.

Raises:

Type	Description
`GeocodingError`	치명적 오류(예: 잘못된 API 키)가 발생한 경우.

Examples:

from hossam import *
result = my_gis.geocode(df, addr="address", key="YOUR_VWORLD_KEY")
set(["latitude","longitude"]).issubset(result.columns)
# True

load_shape ¶

load_shape(path)

Shapefile을 읽어 GeoDataFrame으로 로드합니다.

Parameters:

Name	Type	Description	Default
`path`	`str`	읽을 Shapefile(.shp) 경로.	required
`info`	`bool`	True면 데이터 프리뷰와 통계를 출력.	required

Returns:

Name	Type	Description
`GeoDataFrame`	`GeoDataFrame`	로드된 `GeoDataFrame`.

Raises:

Type	Description
`FileNotFoundError`	파일이 존재하지 않는 경우.

Examples:

from hossam import *
gdf = my_gis.load_shape("path/to/file.shp", info=False)

save_shape ¶

save_shape(
    gdf,
    path,
    crs=None,
    lat_col="latitude",
    lon_col="longitude",
)

전처리된 데이터(GeoDataFrame 또는 DataFrame)를 Shapefile 또는 GeoPackage로 저장합니다.

GeoDataFrame 입력:
CRS가 있으면 그대로 유지합니다.
CRS가 없으면 crs(기본 WGS84)를 지정합니다.
DataFrame 입력:
오직 이 경우에만 lat_col, lon_col을 사용해 포인트 지오메트리를 생성합니다.
좌표가 유효하지 않거나 범위를 벗어난 행은 제외되며, 유효한 좌표가 하나도 없으면 예외를 발생시킵니다.

파일 형식

.shp: ESRI Shapefile (필드명 10자 제한, ASCII 권장)
.gpkg: GeoPackage (필드명 제약 없음, 한글 가능)
확장자 없으면 .shp로 저장

Parameters:

Name	Type	Description	Default
`gdf`	`GeoDataFrame \| DataFrame`	저장할 `GeoDataFrame` 또는 `DataFrame`.	required
`path`	`str`	저장 경로(.shp 또는 .gpkg, 확장자 없으면 .shp 자동 추가).	required
`crs`	`str \| None`	좌표계 문자열(e.g., "EPSG:4326"). 미지정 시 WGS84.	`None`
`lat_col`	`str`	DataFrame 입력 시 위도 컬럼명.	`'latitude'`
`lon_col`	`str`	DataFrame 입력 시 경도 컬럼명.	`'longitude'`

Returns: None: 파일을 저장하고 반환값이 없습니다.

Raises:

Type	Description
`TypeError`	입력 타입이 잘못된 경우.
`ValueError`	경로가 잘못되었거나 CRS가 유효하지 않은 경우, 또는 DataFrame에서 유효 좌표가 하나도 없는 경우.