Skip to content

[Work 61] 경로 검색에 카카오 길찾기 API를 연동했습니다. - #37

Merged
snughnu merged 23 commits into
developfrom
WORK-61
Nov 18, 2026
Merged

snughnu merged 23 commits into
developfrom
WORK-61

Conversation

@snughnu

@snughnu snughnu commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator

JIRA

📝 작업 내용

📌 요약

  • 경로 검색 화면의 Mock 경로를 실제 길찾기 API 결과로 교체
    • 걷기·대중교통: 카카오맵 경로 API
    • 자동차: 카카오모빌리티 길찾기 API
    • (모두 기존 카카오 REST 키 사용)
  • 응답을 Route / RouteStep으로 변환
  • 이동수단별 추천 경로 정렬, 결과 없음·실패·대중교통 안내 문구 추가
  • "이 경로 선택" 시 선택한 Route를 콜백으로 전달 (저장은 후속 작업)

🔍 상세

[1] 카카오 길찾기 API 연동

이동수단 API 결과
걷기 dapi.kakao.com/v2/routing/walk 경로 1개
대중교통 dapi.kakao.com/v2/routing/publictraffic 경로 여러 개
자동차 apis-navi.kakaomobility.com/v1/directions (대안 경로 포함) 경로 1~3개
자동차 (미래 출발) apis-navi.kakaomobility.com/v1/future/directions 출발 시각이 지금부터 10분 뒤보다 늦으면 사용
  • KakaoRouteEndpoint: 기존 KakaoLocalEndpoint와 같은 구조. case별로 baseURL 분기
  • 응답 모델: KakaoWalkRouteResponse, KakaoTransitRouteResponse, KakaoCarRouteResponse
    • 실패 응답(status != OK, result_code != 0)은 빈 배열로 변환
  • KakaoRouteSearchRepository를 추가하고 DI에서 Mock 대신 등록

[2] 응답 → Route / RouteStep 변환

  • 단위: 초 → 분, m → km (기존 Mock과 동일), 좌표 [경도, 위도] → Coordinate
  • 걷기·자동차: 이동수단이 하나라 RouteStep 1개. path는 전체 좌표를 이어 붙임
  • 대중교통: 카카오 steps를 RouteStep으로 1:1 변환
    • lineName: 한 구간을 여러 노선이 가는 경우 중복 제거 후 연결
    • lineColorHex: KakaoTransitLineColor 매핑
      • 지하철: 노선명 기준 24개 노선 (수도권 1~9호선, 신분당선, 수인분당선, 경의중앙선, 공항철도, GTX-A 등)
      • 버스: 종류 기준 (간선, 지선, 광역, 직행, 마을 등), 심야버스는 이름의 (심야)로 구분
  • 출발·도착 도보 구간 추정
    • 카카오 대중교통 응답에는 "출발지 → 첫 정류장", "마지막 정류장 → 목적지" 도보가 빠져 있음
    • 전체 값 - 구간 합으로 빠진 시간·거리를 구하고, 앞뒤 직선거리 비율로 나눠 도보 구간을 추가 (1분 미만은 생략)

[3] 추천 경로 정렬 (SearchRoutesUseCase)

  • 걷기·자동차: 소요시간 → 거리
  • 대중교통: 소요시간 + 환승 1회당 5분 → 도보 시간
    • 환승 횟수는 .transit 구간 수 - 1로 계산

[4] 경로 검색 화면

  • 결과 없음: "검색된 경로가 없습니다." / 실패: AppError 문구
  • 대중교통 선택 시 안내 문구: 선택한 출발 시간의 배차가 아닌, 현재 시각 기준 소요 시간으로 도착 시간을 계산한다는 내용
  • 구간 문구를 앞뒤 구간에 맞게 표시 (RouteStepItem.title)
구간 문구 예시
대중교통 4호선 서울역 > 충무로
환승 도보 (같은 역) 충무로 환승
환승 도보 (다른 지점) 고속터미널까지 도보 환승
출발·도착 도보 서울역까지 도보
걷기·자동차 (구간 1개) 판교역 > 스타벅스 강남역점
  • onRouteSelected: (() -> Void)? → ((Route) -> Void)?
    • 현재 이 콜백을 설정하는 곳은 없어서 버튼 동작은 기존과 같음

💬 리뷰 노트

API 선택

후보 장점 선택하지 않은 이유
카카오맵 (걷기·대중교통) 기존 REST 키 사용, 무료 일 1,000건, 경로 좌표가 한 번에 옴 -
ODsay (대중교통) 국내 대중교통 특화 무료 한도가 문서마다 다름(일 30건/1,000건), 좌표는 추가 호출 필요
TMAP (대중교통) 출발 시각(searchDttm), 노선 색 제공 무료 일 10건, 받은 데이터를 24시간 넘게 저장할 수 없음
카카오모빌리티 (자동차) 기존 REST 키 사용, 미래 출발 시각 지원 -
  • 카카오모빌리티는 상업적으로 사용하면 무료 쿼터 안이라도 제휴가 필요합니다.
  • 쿼터를 넘기면 HTTP 429로 차단될 뿐 과금되지 않습니다.

대중교통 출발 시간

  • 카카오 대중교통 API에는 출발 시각 파라미터가 없어서, 결과는 항상 "지금 출발" 기준입니다.
  • 이번 PR에서는 현재 기준 소요시간 + 선택한 출발 시각으로 도착 시각을 계산합니다. (배차, 첫차·막차는 반영되지 않습니다.)
  • 출발 시간 선택은 막지 않았습니다.
    • 도착 예정 시각 계산과 이후 경로 저장에 출발 시각이 필요하기 때문입니다.
    • 대신 안내 문구로 계산 기준을 알립니다.

기타

  • 지방 도시철도도 "1호선"처럼 같은 이름으로 와서 수도권 노선 색으로 표시됩니다.
  • 지하철 구간도 버스 아이콘으로 표시됩니다 (TransportType.transit 하나로 표현).
  • 노선이 여러 개인 버스 구간은 문구가 길어져 카드에서 잘릴 수 있습니다.

추후 작업

  • 필수
    • 선택한 경로 저장
      • appointments/{id}/routes/{userID}에 저장하고 onRouteSelected를 코디네이터에 연결합니다.
      • 약속 Firestore 연동이 먼저 필요합니다.
  • 선택
    • 대중교통 출발 시각 보정
    • 출발·도착 도보 구간 정확도 개선
      • 직선거리 추정 대신 도보 API로 실제 경로를 계산합니다.

📸 영상 / 이미지

build.mov

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI 코드 리뷰 - 버그 관점

카카오 길찾기 API 실제 연동을 위한 구현체(KakaoRouteSearchRepository)를 추가하고, 기존 completion 기반 인터페이스를 async/throws로 전환한 PR이다. 엔드포인트, 응답 모델, 정렬 로직, 뷰모델의 Task 취소 처리까지 포함되어 있다. 전반적으로 구조는 타당하나, Task 취소 판정 시점과 @published 프로퍼티의 스레드 안전성에 명확한 버그가 있다.

@sangYuLv sangYuLv left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

고생 많으셨습니다. 🦦
아래 내용 확인 부탁드립니다!

  • TransportType에 transit 대신 열차와 버스를 각각 둬서, 아이콘이 따로 표시되게 하면 좋을 듯 합니다.
  • 출발 시각 설정에 대해 방향을 수정하면 좋을 듯 합니다.
    카카오 대중교통 API에 출발 시각 파라미터가 없다는 점 확인했습니다.
    지금 방향대로 가면, 경로 검색 시각에 따라 결과가 달라질 것으로 예상됩니다.
    새벽과 오후에 대중교통 운영이 다르기 때문입니다.

다른 참여자에게 출발 시각을 공유하기 위해 사용자의 출발 시각 입력이 필요한 점도 이해했습니다.
그래서 다음과 같은 방향으로 가보면 어떨까 제안드립니다.

  1. 출발 시각을 입력 받되, 다른 참여자에게 공유하기 위해 입력 받는다는 것을 사용자가 인지할 수 있도록 UI 수정 (경로 검색을 위한 입력이 아님을 인지시켜야 함)
  2. 사용자가 실제 약속 시간대와 반대되는 시간대에 경로 검색을 할 경우, 약속 시간대와 경로 추천이 다를 수 있음을 알리기 -> 시간대를 비교할 기준은 논의가 필요함
  3. 2번에서 다를 수 있음을 알린 후, 비슷한 시간대에 다시 검색할 것을 제안하고 끝내거나 비슷한 시간대가 돌아왔을 때 검색해서 알려줄지 물어보기

출발 시각 설정이 안 되는 게 앱 사용성에 큰 영향을 미칠 듯 합니다...
지금 생각나는 아이디어를 적었는데, 현재 PR에서 당장 수정하기에 어려워보여 가까운 회의일에 논의하는 것이 좋아보입니다! 다른 API를 사용하는 것도 고려해봅시다...

@snughnu snughnu changed the title [WORK 61] 경로 검색에 카카오 길찾기 API를 연동했습니다. [Work 61] 경로 검색에 카카오 길찾기 API를 연동했습니다. Nov 5, 2026
@snughnu
snughnu requested a review from sangYuLv November 5, 2026 01:30
@snughnu

snughnu commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator Author

@sangYuLv
리뷰 확인했습니다!
'출발 시간'관련해서는 돌아오는 회의 때 얘기 나눠보면 좋을 것 같네요

@sangYuLv sangYuLv left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

리뷰 반영 감사합니다 🦦

@snughnu
snughnu merged commit 08a2b1f into develop Nov 18, 2026
5 checks passed
@snughnu
snughnu deleted the WORK-61 branch November 18, 2026 17:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants