⚙️ [기능추가][지도] 장소명에 대한 지도 스크래퍼 기능 추가

[Cassiiopeia]

📝 현재 문제점

• 특정 장소명을 입력하였을때 그 장소에 대한 전제적인 정보를 전체적으로 받을수 있어야합니다

🛠️ 해결 방안 / 제안 기능

• 장소명을 검색한 후 > 최상단 장소에 대한 정보를 가져올수있어야합니다
• 네이버 지도가 보여주는 최대한 많은 정보를 가져올수있어야합니다

시나리오는 다음과같습니다

• 네이버 지도에서 키워드 검색 (예시 : 늘푸른목장)
• https://map.naver.com/p/search/%EB%8A%98%ED%91%B8%EB%A5%B8%20%EB%AA%A9%EC%9E%A5?c=15.00,0,0,0,dh

• 최상단을 클릭

• 오른쪽에 UI 표시

• 핑크색 사각형 부분의 내용을 추출할수있어야함

🙋‍♂️ 담당자

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

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260118_#11_장소명에_대한_지도_스크래퍼_기능_추가

커밋 메시지

장소명에 대한 지도 스크래퍼 기능 추가 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSee-AI/issues/11

[Cassiiopeia]

구글 지도도 추가적으로 개발해서 테스트 필요

[Cassiiopeia]

장소명에 대한 지도 스크래퍼 기능 추가

이슈: #11 ⚙️ [기능추가][지도] 장소명에 대한 지도 스크래퍼 기능 추가
작성일: 2026-01-18
담당자: @Cassiiopeia

---

📌 작업 개요

장소명을 입력하면 네이버 지도/구글 지도에서 해당 장소의 상세 정보를 스크래핑하여 반환하는 기능 구현. Playwright 기반 웹 스크래핑으로 검색 결과 최상단 장소의 정보를 추출.

---

🎯 구현 목표

• 네이버 지도에서 장소 검색 후 상세 정보 추출
• 구글 지도에서 장소 검색 후 상세 정보 추출
• 테스트용 API 엔드포인트 제공
• 공통 유틸리티 함수 분리로 코드 재사용성 확보

---

✅ 구현 내용

1. 공통 유틸리티 모듈 생성

• 파일: src/services/scraper/common_util.py
• 변경 내용: 두 스크래퍼에서 공통으로 사용하는 함수 및 상수 분리
• 이유: 코드 중복 제거 및 유지보수성 향상

추가된 상수:

상수	값	설명
SCRAPE_TIMEOUT_MS	60000	스크래핑 타임아웃 (밀리초)
PAGE_LOAD_WAIT_SEC	3	페이지 로드 대기 시간 (초)
ELEMENT_WAIT_TIMEOUT_MS	10000	요소 대기 타임아웃 (밀리초)
MAX_IMAGE_COUNT	10	이미지 최대 추출 개수

추가된 함수:

함수	설명
parse_review_count()	리뷰 텍스트에서 숫자 추출
parse_rating()	별점 텍스트 파싱
parse_aria_label_value()	aria-label에서 값 추출
parse_price_level()	가격대 파싱 (₩, ₩₩, ₩₩₩)
extract_coordinates_from_url()	URL에서 위도/경도 추출
extract_google_place_id_from_url()	구글 Place ID 추출
extract_naver_place_id_from_url()	네이버 Place ID 추출

---

2. 네이버 지도 스크래퍼 구현

• 파일: src/services/scraper/platforms/naver_map_scraper.py
• 변경 내용: NaverMapScraper 클래스 구현
• 이유: 네이버 지도 iframe 구조에 맞춘 스크래핑 로직 필요

스크래핑 흐름:

1. 검색 URL 생성 (map.naver.com/p/search/{query})
2. Playwright 브라우저 초기화
3. searchIframe에서 첫 번째 검색 결과 클릭
4. entryIframe에서 장소 상세 정보 추출
5. NaverPlaceInfo 모델로 반환

추출 정보 (NaverPlaceInfo):

필드	타입	설명
place_id	str	네이버 Place ID
name	str	장소명
category	str	카테고리
naver_map_url	str	네이버 지도 URL
latitude, longitude	float	좌표
address, road_address	str	주소
subway_info	str	지하철 정보
directions_text	str	찾아가는 길
rating	float	별점 (0.0~5.0)
visitor_review_count	int	방문자 리뷰 수
blog_review_count	int	블로그 리뷰 수
business_status	str	영업 상태
business_hours	str	영업 시간
open_hours_detail	list[str]	요일별 상세 영업시간
holiday_info	str	휴무일 정보
phone_number	str	전화번호
homepage_url	str	홈페이지 URL
reservation_available	bool	예약 가능 여부
description	str	한줄 설명
amenities	list[str]	편의시설 목록
keywords	list[str]	키워드/태그
tv_appearances	list[str]	TV 방송 출연 정보
menu_info	list[str]	대표 메뉴
image_url	str	대표 이미지 URL
image_urls	list[str]	이미지 URL 목록 (최대 10개)

---

3. 구글 지도 스크래퍼 구현

• 파일: src/services/scraper/platforms/google_map_scraper.py
• 변경 내용: GoogleMapScraper 클래스 구현
• 이유: 구글 지도 DOM 구조에 맞춘 스크래핑 로직 필요

스크래핑 흐름:

1. 검색 URL 생성 (google.com/maps/search/{query})
2. Playwright 브라우저 초기화
3. 검색 결과에서 첫 번째 장소 클릭
4. 상세 페이지에서 정보 추출 (JavaScript evaluate)
5. GooglePlaceInfo 모델로 반환

추출 정보 (GooglePlaceInfo):

필드	타입	설명
place_id	str	구글 Place ID
name	str	장소명
category	str	카테고리
google_map_url	str	구글 지도 URL
latitude, longitude	float	좌표 (URL에서 추출)
address	str	주소
plus_code	str	Plus Code
rating	float	별점 (0.0~5.0)
review_count	int	리뷰 수
price_level	str	가격대 (₩₩₩)
business_status	str	영업 상태
business_hours	dict	요일별 영업 시간
phone_number	str	전화번호
website_url	str	웹사이트 URL
description	str	장소 설명/소개
amenities	list[str]	편의시설/서비스 옵션
popular_times	str	인기 시간대 정보
image_url	str	대표 이미지 URL
image_urls	list[str]	이미지 URL 목록 (최대 10개)

---

4. Pydantic 모델 정의

• 파일: src/models/naver_place_info.py, src/models/google_place_info.py
• 변경 내용: NaverPlaceInfo, GooglePlaceInfo Pydantic 모델 정의
• 이유: API 응답 타입 안정성 및 OpenAPI 스키마 자동 생성

---

5. 테스트 API 엔드포인트 추가

• 파일: src/apis/test_router.py
• 변경 내용: 네이버/구글 지도 스크래핑 테스트 엔드포인트 추가

추가된 엔드포인트:

메서드	경로	설명
POST	/api/test/naver-map	네이버 지도 장소 스크래핑
POST	/api/test/google-map	구글 지도 장소 스크래핑

요청 형식:

{
  "query": "늘푸른목장"
}

응답 형식:

• 성공: 200 + NaverPlaceInfo / GooglePlaceInfo
• 실패: 500 + {"detail": "스크래핑에 실패했습니다"}

---

🔧 주요 구현 상세

네이버 지도 iframe 구조 처리

네이버 지도는 iframe 중첩 구조 사용:

• #searchIframe: 검색 결과 목록
• #entryIframe: 장소 상세 정보

각 iframe에 대해 frame_locator 또는 frame(name=...) 사용하여 컨텍스트 전환

좌표 추출 방식

구글 지도: URL에서 정규식으로 추출

!3d{latitude}!4d{longitude}
또는
@{lat},{lng}

네이버 지도: JavaScript window.__APOLLO_STATE__ 또는 meta 태그에서 추출

에러 처리 개선

내부 에러 메시지가 API 응답에 노출되지 않도록 처리:

except Exception as error:
    logger.error(f"스크래핑 오류: {error}", exc_info=True)
    raise HTTPException(status_code=500, detail="스크래핑에 실패했습니다")

• 실제 에러는 로그에만 기록 (exc_info=True로 스택 트레이스 포함)
• 사용자에게는 일반화된 메시지만 반환

이미지 URL 지속성

플랫폼	이미지 URL 도메인	지속성
네이버	pstatic.net	영구적 (삭제 전까지)
구글	googleusercontent.com	영구적 (삭제 전까지)

인스타그램과 달리 만료 토큰이 없어 URL 저장 후 재사용 가능

---

📦 의존성 변경

없음 (기존 Playwright 라이브러리 활용)

---

🧪 테스트 및 검증

테스트 방법

1. 개발 서버 실행:

uv run uvicorn src.main:app --host 0.0.0.0 --port 8001 --reload

2. 네이버 지도 테스트:

curl -X POST http://localhost:8001/api/test/naver-map \
  -H "Content-Type: application/json" \
  -d '{"query": "늘푸른목장"}'

3. 구글 지도 테스트:

curl -X POST http://localhost:8001/api/test/google-map \
  -H "Content-Type: application/json" \
  -d '{"query": "늘푸른목장"}'

검증 항목

• 장소명 검색 후 첫 번째 결과 선택
• 장소명, 별점, 리뷰 수 추출
• 주소, 전화번호, 영업시간 추출
• 좌표 (위도/경도) 추출
• 이미지 URL 추출 (최대 10개)
• 에러 발생 시 적절한 HTTP 상태 코드 반환

실제 테스트 결과

늘푸른목장 (네이버 지도)

{
  "place_id": "11679241",
  "name": "늘푸른목장 잠실본점",
  "category": "소고기구이",
  "rating": 4.42,
  "visitor_review_count": 1510,
  "blog_review_count": 1173,
  "address": "서울 송파구 백제고분로9길 34 1F",
  "phone_number": "02-3431-4520",
  "business_status": "영업 중",
  "tv_appearances": ["줄서는식당 14회...", "식객남녀잘먹었습니다 1회..."],
  "image_urls": [10개 URL]
}

스타벅스 역삼역 (네이버 지도)

{
  "place_id": "1877146204",
  "name": "스타벅스 센터필드R점",
  "category": "카페",
  "rating": 2.0,
  "reservation_available": true,
  "homepage_url": "http://www.starbucks.co.kr/",
  "image_urls": [10개 URL]
}

---

📌 참고사항

CSS 셀렉터 의존성

구글/네이버 지도의 CSS 클래스명은 난독화되어 있어 UI 변경 시 셀렉터 업데이트 필요할 수 있음:

• 구글: .DUwDvf, .F7nice, .mgr77e 등
• 네이버: .GHAhO, .lnJFt, .PXMot 등

여러 셀렉터를 fallback으로 사용하여 안정성 확보

향후 개선 사항

• 검색 결과가 없을 때 예외 처리 개선
• 캐싱 적용으로 동일 검색어 재요청 시 성능 향상
• 장소명 + 지역명 조합 검색 지원

---

📊 파일 변경 요약

파일	상태	설명
src/services/scraper/common_util.py	신규	공통 유틸리티 함수
src/services/scraper/platforms/naver_map_scraper.py	신규	네이버 지도 스크래퍼
src/services/scraper/platforms/google_map_scraper.py	신규	구글 지도 스크래퍼
src/models/naver_place_info.py	신규	네이버 장소 정보 모델
src/models/google_place_info.py	신규	구글 장소 정보 모델
src/apis/test_router.py	수정	테스트 API 엔드포인트 추가

[Cassiiopeia]

Stable 적용 완료 이슈 완료처리합니다