⚙️ [기능추가][주소] 주소 입력시 위도 경도 추출 할수 있는 API 개발 필요

[Cassiiopeia]

📝 현재 문제점

• 네이버지도를 스크래핑해본결과 주소명은 추출이 가능한데 위도 경도를 바로 주지않습니다

🛠️ 해결 방안 / 제안 기능

• 주소명을 입력하면 위도 경도만 빠르게 추출해주는 API를 구현해야합니다

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260118_#12_주소_입력시_위도_경도_추출_할수_있는_API_개발_필요

커밋 메시지

주소 입력시 위도 경도 추출 할수 있는 API 개발 필요 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSee-AI/issues/12

[Cassiiopeia]

주소 입력시 위도 경도 추출 API 개발

GitHub Issue: #12
작업일: 2026-01-18
담당자: @Cassiiopeia

---

📌 작업 개요

네이버지도 스크래핑 결과에서 주소명은 추출 가능하지만 위도/경도를 직접 제공하지 않는 문제 해결.
주소명을 입력하면 위도/경도를 반환하는 Geocoding API 개발 완료.

사용 API:

• 카카오 로컬 API (메인) - 한국 주소 정확도 높음
• Nominatim (테스트용) - OpenStreetMap 기반, 무료

---

🎯 구현 목표

• 주소 문자열 → 위도/경도 변환 API 구현
• 메인 API (카카오, 인증 필요)와 테스트 API (provider 선택 가능) 분리
• 외부 HTTP 요청을 위한 공통 유틸리티 함수 구현

---

✅ 구현 내용

1. API 엔드포인트 추가

엔드포인트	용도	인증	Provider
POST /api/geocode	메인 API	X-API-Key 필요	카카오
POST /api/test/geocode	테스트 API	불필요	enum 선택 (kakao/nominatim)

요청 예시:

{
  "address": "서울시 강남구",
  "provider": "kakao"  // 테스트 API만
}

응답 예시:

{
  "address": "서울시 강남구",
  "latitude": 37.517331925853,
  "longitude": 127.047377408384,
  "provider": "kakao"
}

2. 파일 구조

신규 파일

파일	설명
src/models/geocoding_models.py	Pydantic 스키마 (GeocodingProvider, Request, Response)
src/services/geocoding_service.py	카카오/Nominatim Geocoding 서비스 로직
src/apis/geocoding_router.py	메인 API 라우터 (POST /api/geocode)

수정 파일

파일	변경 내용
src/core/config.py	KAKAO_REST_API_KEY 환경변수 추가
src/apis/test_router.py	테스트 Geocoding API 추가 (POST /api/test/geocode)
src/main.py	geocoding_router 등록
src/utils/common.py	http_get_json() 공통 함수 추가
CLAUDE.md	공통 유틸리티 사용 가이드라인 추가

---

🔧 주요 변경사항 상세

geocoding_models.py

Pydantic 스키마 정의:

• GeocodingProvider: Enum으로 kakao/nominatim 선택
• GeocodingRequest: 메인 API 요청 (address만)
• GeocodingTestRequest: 테스트 API 요청 (address + provider)
• GeocodingResponse: 응답 스키마 (address, latitude, longitude, provider)

geocoding_service.py

두 개의 Geocoding 함수 구현:

• geocode_with_kakao(): 카카오 로컬 API 호출
• geocode_with_nominatim(): Nominatim API 호출 (Rate limit: 1 req/sec)

공통 http_get_json() 함수를 사용하여 타임아웃(10초) 및 예외처리 일관성 확보.

common.py - http_get_json() 함수

외부 API 호출 시 사용하는 공통 함수 추가:

async def http_get_json(
    url: str,
    params: dict | None = None,
    headers: dict | None = None,
    timeout: float = 10.0
) -> dict:

장점:

• 타임아웃 자동 적용 (기본 10초)
• TimeoutException, HTTPStatusError, RequestError 모두 처리
• CustomError로 변환되어 API 레이어에서 일관된 에러 처리

CLAUDE.md 가이드라인 추가

• 외부 API 호출 시 http_get_json() 사용 필수 가이드
• KAKAO_REST_API_KEY 환경변수 문서화

---

📦 환경변수 변경

.env 파일에 추가 필요:

KAKAO_REST_API_KEY={API_KEY}

카카오 API 키 발급 방법:

1. https://developers.kakao.com/ 접속
2. 내 애플리케이션 → 애플리케이션 추가
3. REST API 키 복사

---

🧪 테스트 및 검증

테스트 API (인증 불필요)

# 카카오
curl -X POST http://localhost:8001/api/test/geocode \
  -H "Content-Type: application/json" \
  -d '{"address": "서울시 강남구", "provider": "kakao"}'

# Nominatim
curl -X POST http://localhost:8001/api/test/geocode \
  -H "Content-Type: application/json" \
  -d '{"address": "Seoul, South Korea", "provider": "nominatim"}'

메인 API (인증 필요)

curl -X POST http://localhost:8001/api/geocode \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {API_KEY}" \
  -d '{"address": "서울시 강남구 테헤란로 123"}'

테스트 결과

• ✅ 카카오 API: 성공 (위도 37.517331925853, 경도 127.047377408384)
• ✅ Nominatim API: 성공 (위도 37.5666791, 경도 126.9782914)

---

📌 참고사항

주의점

• 카카오 API: 월 30만 건 무료, 한국 주소 정확도 높음
• Nominatim: 완전 무료, Rate limit 1req/sec, 한국 주소 정확도 상대적으로 낮음
• 타임아웃 10초 적용됨 (외부 API 응답 지연 시 에러 반환)

향후 개선 가능 사항

• 응답 캐싱 (동일 주소 재요청 시)
• 장소명 검색 지원 (현재는 주소만)

---

📝 커밋 메시지

주소 입력시 위도 경도 추출 할수 있는 API 개발 필요 : feat : 카카오/Nominatim Geocoding API 추가 https://github.com/MapSee-Lab/MapSee-AI/issues/12

[Cassiiopeia]

• 깍뚝 검색시 나오는 주소로 위도, 경도 검색
• 카카오 API 사용

[Cassiiopeia]

Stable 정상 작동 확인했습니다 이슈완료 처리합니다

[Cassiiopeia]

카카오맵 api 사용해서 구현했습니다

[Cassiiopeia]

기존 Naver 장소추출에서 주소를 통해 위도경도를 추출해옵니다

정상 동작 확인