[snughnu]

JIRA

📝 작업 내용

📌 요약

• PR [Work 45] 장소 검색/주변 장소/역지오코딩을 카카오 로컬 API로 연동했습니다. #30 후속 이슈 해결
  1. 키워드 검색의 정확도가 낮음
  2. 주변 장소 조회 시 정확도가 낮음
• 키워드 검색: 후보를 15건에서 최대 30건으로 늘리고, 이름 일치/카테고리 대표성/거리 기준으로 재정렬
• 주변 장소: 카테고리별 상위 후보를 모아 거리와 카테고리 대표성을 함께 고려해 선택
• 늘어난 API 호출을 줄이기 위한 조치 포함

🔍 상세

[1] 문제 1: 키워드 검색 정확도가 낮음

• 원인
  • 첫 페이지 15건만 조회하고 카카오의 관련도 순서를 그대로 사용
  • 광범위한 지명 키워드에서는 기대한 장소가 밀림
• 해결
  • 후보 확대
    • 정확도순 2개 페이지를 병렬 조회해 최대 30건 확보 (참고: 최대 3개 페이지 45건 가능)
    • id 기준 중복 제거
  • 재정렬 (KakaoPlaceRanker)
    1. 이름 일치 단계: 정확히 일치 > 접두사 일치 > 포함 > 불일치 (불일치는 제거하지 않고 맨 뒤)
    2. 카테고리 대표성 가중치: 지하철역·공공기관·관광명소 4.0 / 문화시설·병원·대형마트 2.0 / 그 외 1.0
    3. 사용자와의 거리
    4. 이름 길이 비율 (거리 정보가 없을 때의 보조 기준)
    5. 카카오 원래 순서
  • 현재 위치 반영
    • 위치 권한이 허용된 경우 현재 좌표를 함께 전달하고, 거리순 1페이지를 추가 조회해 병합
      ("스타벅스"처럼 전국에 있는 상호는 가까운 지점이 앞에 옴)
    • 권한이 없거나 위치 조회에 실패하면 좌표 없이 기존 방식으로 검색

---

[2] 문제 2: 주변 장소 조회 시 정확도가 낮음

• 원인
  • 카테고리별 거리순 1건만 후보로 쓰고, 그중 가장 가까운 것을 선택해 랜드마크보다 작은 상호가 선택됨
• 해결
  • 후보 확대
    • 카테고리당 상위 5건을 후보로 수집
  • 선택 기준 변경
    • 점수 = 거리 ÷ 대표성 가중치가 가장 낮은 후보 선택 (가중치는 [1]과 동일)
  • 조회 카테고리: 6종 → 10종
    • 지하철역, 관광명소, 문화시설, 병원, 대형마트, 음식점, 카페, 편의점, 학교, 주차장

---

[3] 호출량 절감 관련

• 지도를 줌 아웃하면(줌 14 미만) 주변 장소 대신 지역명을 조회해 표시
  • 시/군/구(줌 9 이상), 시/도(줌 9 미만)
  • 지역명 상태에서도 확인 버튼으로 해당 지역을 장소로 선택 가능
  • 시/도는 카카오가 내려주는 약칭("경남")을 정식 명칭("경상남도")으로 변환해 표시
• 지도 이동 시 조회 디바운스 300ms → 500ms, 최소 이동 거리 20m → 30m

💬 리뷰 노트

현재 PR 기준 API 호출 횟수 (카카오 로컬 API)

기능	호출 시점	현재
키워드 검색	검색 버튼 1회	3 (위치 권한 없음/조회 실패 시 2)
지도 장소 선택, 상세 줌 (14 이상)	조회 1회	10
지도 장소 선택, 줌 아웃 (14 미만)	조회 1회	1
현재 위치 장소 (채팅 위치 공유, 경로 검색 출발지)	기능 사용 시 1회	10
폴백 역지오코딩	주변 장소 조회 결과가 없을 때	+1

• 키워드 검색 3회는 정확도순 2개 페이지 + 거리순 1페이지입니다.
• 현재 위치 장소가 10회인 이유는 위치 공유 확인창과 경로 출발지에 "내가 있는 곳의 장소명(POI)"을 보여주기 위해
  지도 장소 선택과 같은 주변 장소 조회(카테고리 10종 각각 호출)를 사용하기 때문입니다.

호출량 기준 수용 가능 사용자 수 (추정)

카카오 로컬 API 무료 쿼터(일 10만 건 / 월 300만 건) 기준입니다.
사용자 행동은 가정값입니다.

사용 패턴	지도 장소 선택	키워드 검색	현재 위치 장소	1인 하루 호출	수용 DAU
가벼움	10회 (100건)	3회 (9건)	1회 (10건)	약 120건	약 840명
보통	20회 (200건)	5회 (15건)	2회 (20건)	약 235건	약 420명
많이 씀	50회 (500건)	10회 (30건)	3회 (30건)	약 560건	약 180명

• 지도 장소 선택은 상세 줌 이동 1회당 10건, 키워드 검색은 1회당 3건, 현재 위치 장소는 1회당 10건으로 계산했습니다.

📸 영상 / 이미지

build.mp4

[github-actions]

🤖 AI 코드 리뷰 - 버그 관점

지도 줌 레벨에 따라 주변 장소 조회와 행정구역 역지오코딩을 전환하는 기능, 키워드 검색 시 현재 위치 기반 거리 우대 기능, 카테고리 검색에서 대표성 점수 기반 후보 선택 기능이 추가된 PR이다. KakaoPlaceRanker를 통한 검색 결과 재정렬 로직도 새로 도입되었다. 전반적으로 diff 범위 내에서 확인 가능한 버그 가능성 항목이 일부 존재한다.

[sangYuLv]

고생 많으셨습니다 🦦

[sangYuLv]

고생 많으셨습니다 🦦