Naver Map 맛집 크롤러

네이버 지도(map.naver.com)에서 도시를 검색해, 동네(구/동)별 맛집 목록과 별점·리뷰수 등을 자동 수집하여 CSV로 저장하는 Playwright 기반 스크립트입니다.

수집 컬럼

city, district, restaurant_name, category, rating, review_count, address, phone, url, collected_at (ISO8601)

프로젝트 구조

파일	역할
main.py	진입점 (CLI, 진행바, 요약 통계, Ctrl+C 저장)
scraper.py	Playwright 크롤링 로직 (검색·스크롤·iframe 처리)
parser.py	HTML 텍스트 정제 / 데이터 구조화
exporter.py	CSV 저장
config.py	상수 · CSS 셀렉터

설치 및 실행

uv 패키지 매니저 기준입니다.

# 1. 의존성 설치
uv sync

# 2. Playwright 브라우저(Chromium) 설치 (최초 1회)
uv run playwright install chromium

# 3. 실행
uv run python main.py --city 서울 --districts 종로구

단계별 상세 설명·내부 동작·트러블슈팅은 docs/실행가이드.md를 참고하세요.

사용 예시

# 도시 전체 (동네 필터를 자동 감지해 순회)
uv run python main.py --city 부산

# 특정 구만 지정
uv run python main.py --city 서울 --districts 강남구 마포구

# 동네당 최대 200개, headless 모드
uv run python main.py --city 대구 --max 200 --headless

# 출력 파일명 지정
uv run python main.py --city 제주 --output 제주맛집.csv

CLI 옵션

옵션	설명	기본값
--city	검색할 도시 (필수)	—
--districts	특정 동네 목록 (미지정 시 지역 필터 자동 감지)	전체
--max	동네/도시당 최대 수집 개수	500 (config.MAX_PER_DISTRICT)
--headless	브라우저 백그라운드 실행	꺼짐
--output	출력 CSV 경로	{city}_맛집_{YYYYMMDD}.csv

동작 방식

1. map.naver.com 접속 → {city} 맛집 검색
2. 결과 패널에서 '음식점' 필터 선택
3. 동네 필터가 있으면 각 동네 순회, 없으면 도시 전체를 페이지네이션으로 수집
4. 각 식당 카드를 클릭해 entryIframe에서 상세 정보 추출
5. 무한 스크롤 자동 처리 (동네당 최대 --max개)
6. 완료 후 CSV 저장 및 요약 통계(총 식당 수 · 동네 수 · 평균 별점) 출력

참고 사항

• 봇 감지 회피를 위해 요청 사이 1.5~3.0초 랜덤 대기 (config.py에서 조정).
• 요소 미발견 시 해당 필드는 None 처리 후 계속 수집하며, 상세 페이지는 최대 3회 재시도합니다.
• 수집 중 Ctrl+C를 누르면 현재까지 수집된 데이터가 CSV로 저장됩니다.
• 네이버 지도 DOM은 자주 바뀝니다. 셀렉터가 맞지 않으면 config.py의 SELECTORS 딕셔너리만 수정하세요.
• 공개 정보만 수집하며, robots.txt 준수를 위해 딜레이를 1초 이상으로 유지하세요.