Tmap API를 이용한 교통시간 계산 로직 (1)

이번에, 큐시즘에서 기업 프로젝트를 진행하면서 Tmap api를 활용하여 교통시간을 계산하는 로직을 담당하였다.

우선 플로우는 다음과 같다.

1. 주소 → 좌표 변환 (Geocoding)
   • 사용자 입력 주소(도로명 주소) 및 회사 주소를 Tmap의 Full-Text Geocoding API에 전달하여 위도/경도 좌표(GeocodePoint)로 변환함.
   • API 호출 시 버전, 포맷, 좌표계(coordType) 등을 설정하며, 응답에서 정상 좌표가 나왔는지 유효성 검사를 수행함.
   • 만약 정상 좌표(lat, lon)가 비어 있거나 Null/Blank일 경우, 예비 좌표(latEntr, lonEntr) 등을 사용하거나 예외 처리 로직도 추가
2. 통근 시간 산정 (출발지, 도착지 간 시간 계산)
   • 사용자의 선호 교통수단(자동차(CAR) or 대중교통(TRANSIT))에 따라 다음 두 가지 API 중 적절한 것을 호출함: a. 자동차 경로 안내 (타임머신 자동차 길 안내 API) — 출발지와 도착지 좌표, 교통 정보 포함, 예측 시간(predictive traffic) 등을 고려해 도로 경로 소요 시간 계산 b. 대중교통 요약 (대중교통 요약 API) — 대중교통 일정을 기반으로 출발시간 또는 도착시간, 환승 및 경유 시간 등을 고려하여 전체 소요 시간 계산
     
   • 출근 시간대(예: 아침 9시 출근 기준) 또는 사용자가 설정한 최대 통근 시간(maxCommuteMinutes)을 고려하여 출발 시점을 조정함(대중교통의 경우, ‘도착시간 9시’ 기준 전 출발하도록 계산).
3. 공고 필터링 및 저장
   • 계산된 소요 시간이 “사용자가 허용한 최대 통근 시간” 이내인지 비교함.
   • 소요 시간 ≤ 최대 통근 시간인 공고만 필터링하여, 그 결과만 데이터베이스에 저장함.
   • 이렇게 함으로써 사용자에게 실질적으로 출퇴근 가능성이 있는 공고만 보여주고, 필요 없는 공고는 미리 걸러냄으로써 사용자 만족도와 효율성 향상 가능.

타임머신 자동차 길 안내 api와 대중교통 요약 api에서는, 출발 시간대를 고려하여 통근 시간을 고려할 수 있어, 해당 api를 활용하기로 했다.

참고로 Tmap api 공식문서가 친절하게 되어있어, 구현하는데 크게 헤매진 않았다 다들 공식 문서를 꼭 참고하길!
https://openapi.sk.com/

우선 Tmap api를 사용하려면, api키를 발급받아야한다.
우선 sk open api사이트에서 앱을 만든 후, 대시보드에서 확인하면 앱키를 발급받을 수 있다.

https://openapi.sk.com/products/calc?svcSeq=4&menuSeq=5

이후에는 위의 사이트에서 각자 필요한 요금제에 맞게 사용하기를 누른 후, 사용 신청을 하면, 바로 사용이 가능해진다.
참고로 나는 Tmap 대중교통, Tmap(자동차) api 두 개가 필요해서 둘 다 각각 신청해 사용중이다.
✅Tmap 대중교통은 Free 요금제가 하루에 10건만 가능하여 Premium으로 사용중이다.. 다들 참고하길

그리고 앱키와 base url, 나는 지오코딩도 사용하기에 coord-type도 yml에 추가해뒀다

tmap:
  base-url: https://apis.openapi.sk.com/
  appKey: {appKey}
  coord-type: WGS84GEO

이후 tmap api 연동 시에 사용하기위해, webClient 코드도 구현한다.

@Configuration
public class WebClientConfig {
    @Value("${tmap.base-url}")
    private String tmapBaseUrl;

    @Value("${tmap.appKey}")
    private String appKey;

    @Bean
    public WebClient tmapWebClient() {
        HttpClient httpClient = HttpClient.create()
                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS,5000)
                .doOnConnected(conn -> conn
                        .addHandlerLast(new ReadTimeoutHandler(10))
                        .addHandlerLast(new WriteTimeoutHandler(10)))
                .responseTimeout(Duration.ofSeconds(10));
        return WebClient.builder()
                .baseUrl(tmapBaseUrl)
                .defaultHeader("appKey", appKey)
                .clientConnector(new ReactorClientHttpConnector(httpClient))
                .build();
    }
}

이제 Tmap api 사용을 위한 준비를 마쳤다. 다음 편에서는 해당 로직을 어떻게 구현했는지에 대해 작성하겠다.