TMAP 서버 API 개발자 가이드

1. 서문

1.1 목적 및 대상 독자

이 문서는 SK텔레콤의 TMAP 서버 API(RESTful API)를 사용하여 위치 기반 서비스를 개발하는 개발자를 위한 공식 기술 매뉴얼이다. 본 문서는 서버 환경에서 TMAP의 방대한 데이터와 강력한 경로 탐색 기능을 통합하고자 하는 개발자에게 필요한 모든 기술적 명세를 제공하는 것을 목적으로 한다.

대상 독자는 서버 측 애플리케이션 개발에 대한 실무적 이해를 갖춘 소프트웨어 엔지니어, 시스템 아키텍트 및 기술 관리자이다. 따라서 본 문서는 클라이언트 측 개발을 위한 SDK(Software Development Kit), 즉 Android, iOS, JavaScript 라이브러리에 대한 내용을 다루지 않는다.1 대신, 서버 간(Server-to-Server) 통신을 통해 TMAP의 핵심 기능을 호출하고 응답을 처리하는 데 필요한 RESTful API의 구조, 인증 방식, 엔드포인트, 파라미터 및 데이터 형식에 대해 집중적으로 설명한다.

1.2 문서의 구성

본 문서는 개발자가 TMAP 서버 API를 이해하고 실제 애플리케이션에 효율적으로 적용하는 데 필요한 모든 정보를 체계적으로 제공하도록 설계되었다. 문서의 구성은 다음과 같다.

1. TMAP 서버 API 개요: TMAP API 플랫폼의 특징과 아키텍처, 그리고 API 사용의 기본이 되는 RESTful 원칙, 좌표계, 데이터 형식에 대해 설명한다.

2. API 인증 및 키 발급: API 사용 권한을 획득하기 위한 SK open API 포털 가입부터 App Key를 발급받고, 이를 API 요청 헤더에 포함하여 인증을 수행하는 전 과정을 상세히 안내한다.

3. 핵심 API 기능 명세: 장소(POI) 검색, 지오코딩, 경로안내 등 TMAP이 제공하는 핵심 서버 API들의 기능별 엔드포인트, 요청 파라미터, 응답 데이터 구조를 예제와 함께 심도 있게 다룬다.

4. 참조: 안정적인 서비스 운영에 필수적인 사용량 제한 정책과 API 호출 시 발생할 수 있는 다양한 오류 코드에 대한 상세한 설명 및 해결 방안을 제공한다.

각 섹션은 독립적으로 참조할 수 있으면서도 유기적으로 연결되어, 개발자가 API 연동의 전체 흐름을 파악하고 특정 기능 구현 시 필요한 정보를 신속하게 찾을 수 있도록 구성되었다.

1.3 용어 정의

본 문서에서 사용되는 주요 기술 용어는 다음과 같이 정의한다.

• API (Application Programming Interface): 애플리케이션 프로그래밍 인터페이스. 특정 프로그램의 기능이나 데이터를 다른 프로그램이 접근하여 사용할 수 있도록 미리 정해진 통신 규칙의 집합이다. TMAP API는 외부 개발자가 TMAP의 지도, 검색, 경로 탐색 기능을 자신의 서비스에서 활용할 수 있도록 제공하는 인터페이스를 의미한다.

• RESTful API: Representational State Transfer의 약자인 REST 아키텍처 스타일을 따르는 API. HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 해당 자원에 대한 생성(Create), 조회(Read), 갱신(Update), 삭제(Delete) 작업을 수행하는 방식을 의미한다.1 TMAP 서버 API는 이 원칙을 준수하여 설계되었다.

• App Key: SK open API 포털에서 사용자가 생성한 애플리케이션(프로젝트)에 부여되는 고유한 식별자 문자열이다. 모든 API 요청 시 HTTP 헤더에 이 키를 포함하여 요청자를 인증하고 권한을 확인하는 데 사용된다. 이는 API 호출의 보안과 사용량 추적의 핵심 요소이다.4

• POI (Point of Interest): 관심 장소. 지도상에 표현될 수 있는 특정 위치 정보를 가진 개체(예: 건물, 상점, 공공기관 등)를 의미한다. POI 데이터는 일반적으로 명칭, 주소, 전화번호, 카테고리, 좌표 등의 속성 정보를 포함한다.5

2. TMAP 서버 API 개요

2.1 TMAP API 플랫폼 소개

TMAP API는 티맵모빌리티(TMAP MOBILITY)가 제공하는 대한민국 1위 내비게이션 서비스 ’TMAP’의 핵심 자산과 기술력을 외부 개발자가 자신의 서비스에 통합하여 활용할 수 있도록 제공하는 Open API 플랫폼이다.5 이는 단순한 지도 이미지 제공을 넘어, 20년 이상 축적된 고정밀 지도 데이터, 약 2,000만 명의 방대한 가입자 기반에서 생성되는 실시간 교통 정보, 그리고 국내 최다 수준의 POI 데이터를 기반으로 한 강력한 위치 기반 인텔리전스를 제공한다.5 개발자는 TMAP API를 통해 지도 시각화, 장소 검색, 주소-좌표 변환, 그리고 실시간 교통 상황을 반영한 최적 경로 탐색 등 고품질의 위치 기반 서비스를 손쉽게 구축할 수 있다.

TMAP API의 활용 분야는 매우 광범위하며, 특히 B2B(Business-to-Business) 영역에서 그 가치가 두드러진다. 주요 활용 사례는 다음과 같다.

• 물류 및 배송: 실시간 교통정보를 반영한 최적 배송 경로 탐색, 다중 경유지 순서 최적화를 통해 유류비와 시간을 절감하고, 지오펜싱(Geofencing) 기술을 활용하여 관할 구역을 효율적으로 관리한다.2

• 운송 및 긴급출동: 고객 위치에서 가장 가까운 차량을 신속하게 배차하고, 목적지까지의 최적 경로를 제공하여 대응 시간을 단축한다.5

• O2O(Online to Offline) 서비스: 택시, 대리운전, 음식 배달 등 호출 기반 서비스에서 사용자와 서비스 제공자 간의 정확한 위치를 파악하고 예상 도착 시간(ETA)을 정밀하게 예측하여 고객 만족도를 높인다.1

이러한 기능들은 기업 고객의 운영 효율성을 극대화하고 비용을 절감하며, 최종적으로는 새로운 비즈니스 가치를 창출하는 데 핵심적인 역할을 수행한다.

TMAP API 플랫폼의 아키텍처는 개발자의 사용 편의성과 플랫폼의 관리 효율성을 동시에 고려하여 설계되었다. 개발자는 두 개의 주요 웹 포털과 상호작용하게 되는데, 이는 SK텔레콤의 API 제공 전략을 반영하는 이원화된 구조이다. 첫째, openapi.sk.com은 관리 및 비즈니스 포털의 역할을 수행한다.7 이곳에서 개발자는 회원 가입, 신규 프로젝트(앱) 생성, API 사용에 필수적인 App Key 발급, 그리고 서비스 사용량에 따른 유료 또는 무료 상품 구매 등의 관리 작업을 수행한다. 또한, API 호출에 대한 상세한 사용 통계와 에러 현황을 모니터링할 수 있어 서비스 운영 및 비용 관리에 필수적이다.4

둘째, https://apis.openapi.sk.com은 실제 API 요청이 전송되는 기술적인 게이트웨이(Gateway) 역할을 한다.9 모든 서버 API의 기본 URL(Base URL)은 이곳을 가리키며, 관리 포털에서 발급된 App Key로 인증된 요청만을 받아 내부 TMAP 서비스로 전달하고 그 결과를 응답하는 순수한 기술적 통로이다. 이처럼 비즈니스 로직(가입, 결제, 통계)과 기술적 서비스 제공(API 호출 처리)을 분리하는 구조는 대규모 상용 API 플랫폼에서 흔히 볼 수 있는 성숙한 아키텍처 패턴이다. 이러한 구조적 분리를 이해하는 것은 개발자에게 매우 중요하다. API 연동 중 문제가 발생했을 때, 원인이 관리 포털의 설정(예: 사용량 한도 초과, IP 접근 제한)에 있는지, 아니면 API 요청 자체의 기술적 결함(예: 잘못된 파라미터)에 있는지를 신속하게 판단하고 대응할 수 있게 해주기 때문이다.

2.2 API 기본 원칙

TMAP 서버 API를 효과적으로 사용하기 위해서는 몇 가지 핵심적인 기술 원칙을 이해해야 한다. 이 원칙들은 API의 일관성을 유지하고 개발자가 예측 가능한 방식으로 시스템과 상호작용할 수 있도록 돕는다.

2.2.1 RESTful 아키텍처 (RESTful Architecture)

TMAP 서버 API는 현대 웹 서비스의 표준 아키텍처 스타일인 REST(Representational State Transfer) 원칙을 충실히 따른다. 이는 API의 모든 기능이 ’자원(Resource)’으로 표현되고, 각 자원은 고유한 URI(Uniform Resource Identifier)를 통해 식별됨을 의미한다. 개발자는 표준 HTTP 메서드(주로 GET과 POST)를 사용하여 이러한 자원과 상호작용한다.3

• GET: 서버로부터 정보를 조회하는 데 사용된다. 예를 들어, 특정 키워드로 장소를 검색하거나 좌표에 해당하는 주소를 얻는 작업이 이에 해당한다. GET 요청은 모든 파라미터를 URL의 쿼리 문자열(Query String)에 포함하여 전송한다.

• POST: 서버에 데이터를 제출하여 새로운 자원을 생성하거나 기존 자원의 상태를 변경하는 복잡한 작업을 요청하는 데 사용된다. 예를 들어, 출발지, 목적지, 경유지 등 다수의 정보를 포함하는 경로 탐색 요청이 이에 해당한다. POST 요청은 파라미터를 HTTP 요청의 본문(Body)에 담아 전송한다.

또한, 모든 API 요청에 대한 결과는 표준 HTTP 상태 코드를 통해 전달된다. 성공적인 요청은 2xx 범위의 코드(예: 200 OK, 204 No Content)를 반환하며, 클라이언트 측의 오류(예: 잘못된 요청)는 4xx 범위의 코드(예: 400 Bad Request, 403 Forbidden), 서버 측의 오류는 5xx 범위의 코드(예: 500 Internal Server Error)를 반환한다.11 이 표준화된 접근 방식은 개발자가 오류 처리 로직을 일관되게 구현할 수 있도록 돕는다.

2.2.2 좌표계 (Coordinate Systems)

위치 기반 서비스의 핵심은 정확한 좌표 데이터이다. TMAP API는 다양한 표준 좌표계를 지원하여 여러 시스템과의 호환성을 보장한다. 개발자는 API 요청 시 reqCoordType 파라미터로 입력하는 좌표의 종류를 명시하고, resCoordType 파라미터로 받고자 하는 결과의 좌표계를 지정할 수 있다.12 서로 다른 시스템 간에 위치 데이터를 주고받을 때 발생할 수 있는 불일치를 방지하기 위해 각 좌표계의 특성을 명확히 이해하고 사용하는 것이 매우 중요하다.

TMAP API에서 주로 사용되는 좌표계는 다음과 같다.

이 표는 개발자가 API와 상호작용할 때 가장 기본이 되는 ‘위치’ 데이터의 형식을 명확히 정의한다. 예를 들어, 내부 데이터베이스는 KATECH 좌표계로 데이터를 저장하고 있지만 외부 GPS 장비로부터는 WGS84GEO 좌표를 수신하는 경우, 개발자는 이 표를 참조하여 TMAP API 호출 시 정확한 좌표계 변환 파라미터를 설정할 수 있다. 이는 위치 데이터 불일치로 인해 발생할 수 있는 심각한 오류를 사전에 방지하고 디버깅 시간을 획기적으로 단축시키는 데 결정적인 역할을 한다.

2.2.3 요청 및 응답 형식 (Request and Response Format)

TMAP 서버 API와의 모든 통신은 표준 웹 기술을 기반으로 이루어진다.

• 요청 형식: POST 메서드와 같이 요청 본문(Request Body)에 데이터를 담아 보내야 하는 경우, 데이터의 형식을 Content-Type 헤더에 명시해야 한다. 일반적으로 application/x-www-form-urlencoded(키-값 쌍 형태) 또는 application/json 형식이 사용되며, 각 API의 상세 명세에서 요구하는 형식을 따라야 한다.10

• 응답 형식: API 서버로부터의 응답은 기본적으로 JSON(JavaScript Object Notation) 형식으로 제공된다. JSON은 사람이 읽고 쓰기 쉬우며 기계가 파싱하고 생성하기에도 용이한 경량 데이터 교환 형식으로, 현대 API에서 사실상의 표준으로 사용된다. 클라이언트는 요청 시 Accept 헤더에 application/json 값을 포함하여 JSON 형식의 응답을 명시적으로 요청하는 것이 권장된다.10

3. API 인증 및 키 발급

TMAP API의 모든 기능을 사용하기 위해서는 먼저 SK open API 포털을 통해 사용자를 인증하고 API 호출에 필요한 고유한 식별자인 App Key를 발급받아야 한다. 이 과정은 API의 무단 사용을 방지하고, 사용자별로 사용량을 추적하며, 안정적인 서비스 품질을 보장하기 위한 필수적인 절차이다.

3.1 SK open API 포털 가입 및 프로젝트 생성

TMAP API 사용의 첫 단계는 SK open API 포털(https://openapi.sk.com/)에 개발자 계정을 생성하는 것이다. 포털은 개인 개발자와 사업자 모두에게 열려 있으며, 간단한 가입 절차를 통해 계정을 만들 수 있다.7

계정 생성이 완료되고 로그인하면, API를 사용하기 위한 논리적인 단위인 ‘앱(App)’ 또는 ’프로젝트(Project)’를 생성해야 한다. 이 과정은 다음과 같다.

1. 웹사이트 우측 상단의 ‘대시보드’ 메뉴로 이동한다.

2. 대시보드 좌측 메뉴에서 ’앱’을 선택한다.

3. ‘앱 만들기’ 버튼을 클릭하여 새로운 앱 생성 팝업창을 연다.

4. 개발하고자 하는 서비스나 애플리케이션을 식별할 수 있는 고유한 ’앱 이름’을 입력하고 확인 버튼을 누른다.4

이렇게 생성된 ’앱’은 API 사용의 기준점이 된다. 즉, 이후에 발급될 App Key는 이 앱에 종속되며, 특정 API 상품(예: TMAP 경로안내 API)을 이 앱에 연동(구매)하고, 해당 앱을 통해 발생한 모든 API 호출의 사용량을 모니터링하게 된다.4 따라서 여러 개의 독립적인 서비스를 개발하는 경우, 각 서비스별로 별도의 앱을 생성하여 관리하는 것이 체계적인 운영에 유리하다.

3.2 App Key 발급 및 관리

앱 생성이 완료되면, 해당 앱에 대한 고유한 App Key가 자동으로 발급된다. 이 키는 생성된 앱의 상세 정보 화면 내 ‘앱키(appKey)’ 탭에서 언제든지 확인할 수 있다.4

App Key는 API 서버가 요청자를 식별하고 인증하는 데 사용하는 비밀 정보와 같다. 따라서 이 키가 외부에 노출될 경우, 제3자가 해당 키를 도용하여 API를 무단으로 사용하고 과도한 요금을 발생시키거나 서비스 장애를 유발할 수 있다. 개발자는 App Key를 소스 코드에 직접 하드코딩하는 것을 피하고, 서버 환경 변수나 보안 관리 시스템을 통해 안전하게 저장하고 관리해야 할 책임이 있다.

보안 강화를 위해 SK open API 포털은 다음과 같은 App Key 관리 기능을 제공한다.

• 키 재발급: App Key가 유출되었거나 정기적인 보안 정책에 따라 키를 변경해야 할 경우, ‘재발급’ 버튼을 통해 새로운 키를 즉시 생성할 수 있다. 키 재발급 시, 기존 키는 즉시 비활성화되지 않고 24시간의 유예 기간을 가진다. 이 기간 동안 개발자는 자신의 애플리케이션에 새로운 키를 적용할 수 있으며, 24시간이 지나면 기존 키는 영구적으로 만료된다. 이는 서비스 중단을 최소화하면서 키를 교체할 수 있도록 돕는 중요한 기능이다.4

• IP 주소 제한 (Whitelist): App Key를 사용하여 API를 호출할 수 있는 서버의 IP 주소를 미리 등록하여, 허용된 IP에서의 요청만을 승인하는 보안 기능이다. 예를 들어, 운영 서버의 고정 IP 주소를 등록해두면, 개발 환경이나 허가되지 않은 다른 위치에서 해당 App Key를 사용한 API 호출이 원천적으로 차단된다. 이는 키 유출 시 피해를 최소화할 수 있는 강력한 보안 장치이다.11

3.3 API 요청 헤더 구성

발급받은 App Key는 모든 TMAP 서버 API 요청 시 HTTP 헤더에 포함되어야 한다. 서버는 이 헤더 값을 통해 요청의 유효성을 검증한다. 만약 appKey 헤더가 없거나 그 값이 유효하지 않으면, 서버는 요청 처리를 거부하고 401 Unauthorized 또는 403 Forbidden과 같은 인증 오류를 반환한다.10

API 요청 시 반드시 포함해야 하는 공통 HTTP 헤더는 다음과 같다.

이 표는 모든 API 호출의 ‘관문’ 역할을 하는 인증 정보를 명확하게 규정한다. 개발자는 이 표를 참조하여 API 연동의 첫 단계인 인증 요청을 올바르게 구성할 수 있으며, 이를 통해 401/403과 같은 초기 인증 실패 오류를 방지하고 개발 초기 단계의 시행착오를 크게 줄일 수 있다.

다음은 cURL을 사용한 API 요청의 기본 예시이다. {YOUR_APP_KEY} 부분은 실제 발급받은 App Key로 대체해야 한다.

# 'SKT타워'라는 키워드로 POI를 검색하는 GET 요청 예시
curl --request GET \
--url 'https://apis.openapi.sk.com/tmap/pois?version=1&searchKeyword=SKT%ED%83%80%EC%9B%8C' \
--header 'Accept: application/json' \
--header 'appKey: {YOUR_APP_KEY}'

이 예시는 appKey 헤더를 통해 인증 정보를 전달하고, Accept 헤더를 통해 JSON 형식의 응답을 요청하는 가장 기본적인 API 호출 구조를 보여준다.4

4. 핵심 API 기능 명세

TMAP 서버 API는 위치 기반 서비스의 핵심을 이루는 다양한 기능을 제공한다. 본 섹션에서는 그중 가장 빈번하게 사용되는 장소(POI) 검색, 지오코딩, 그리고 경로안내 API의 상세 명세를 다룬다.

4.1 장소(POI) 검색 API

장소(POI) 검색 API는 사용자가 입력한 키워드를 바탕으로 TMAP이 보유한 방대한 장소 데이터베이스에서 관련 정보를 찾아주는 기능이다. TMAP은 약 530만 건의 기본 POI와 1,100만 건에 달하는 별칭 POI 데이터를 보유하고 있어, 시설물명, 상호, 주소, 전화번호 등 다양한 조건으로 정밀한 검색이 가능하다.5

4.1.1 통합 검색

통합 검색은 가장 기본적이면서도 강력한 POI 검색 기능이다. 사용자가 입력한 단일 키워드를 명칭, 주소, 전화번호 등 여러 필드에서 종합적으로 검색하여 가장 연관성이 높은 결과를 반환한다.

• Endpoint: GET https://apis.openapi.sk.com/tmap/pois 9

• 설명: 이 API는 지정된 키워드와 일치하는 장소 목록을 제공한다. 추가적으로 중심 좌표를 지정하여 특정 위치 주변의 장소만 검색하거나, 검색 결과를 거리순 또는 정확도순으로 정렬하는 등 다양한 옵션을 제공하여 검색 결과를 세밀하게 제어할 수 있다.

Table 3: 장소(POI) 통합 검색 요청 파라미터

이 파라미터 표는 POI 검색 기능의 높은 유연성을 잘 보여준다. 개발자는 단순히 키워드로 검색하는 기본 기능을 넘어, centerLon과 centerLat을 조합하여 ’내 주변 맛집 찾기’와 같은 위치 기반 검색을 구현할 수 있다. 또한 count와 page 파라미터를 활용하여 대량의 검색 결과를 효율적으로 나누어 보여주는 페이징 기능을 손쉽게 구현할 수 있다. 이는 사용자에게 위치 기반의 정교하고 편리한 검색 경험을 제공하는 데 핵심적인 역할을 한다.

응답 데이터 구조

API 호출이 성공하면, 검색 조건에 부합하는 POI 목록과 관련 메타데이터를 포함하는 JSON 객체가 반환된다. 응답 구조는 다음과 같은 형태를 가진다.

{
"searchPoiInfo": {
"totalCount": "1",
"count": "1",
"page": "1",
"pois": {
"poi":
},
"radius": "0.0"
}
]
}
}
}

9

• searchPoiInfo: 검색 결과 전체를 감싸는 최상위 객체.

• totalCount: 검색 조건에 맞는 전체 POI의 개수.

• count: 현재 페이지에 반환된 POI의 개수.

• page: 현재 페이지 번호.

• pois: POI 목록을 담고 있는 객체.

• poi: 개별 POI 정보를 담은 객체의 배열. 각 객체는 id, name(명칭), telNo(전화번호), frontLat/frontLon(좌표), 그리고 newAddressList(도로명 주소 정보) 등 상세한 속성을 포함한다.

4.2 지오코딩 API

지오코딩(Geocoding)은 주소 텍스트를 지도상의 좌표(위도, 경도)로 변환하거나, 그 반대로 좌표를 주소 텍스트로 변환하는 기술이다. 이는 사용자가 입력한 주소를 지도에 표시하거나, 지도상의 특정 지점에 대한 주소를 사용자에게 알려주는 등 위치 기반 서비스의 근간을 이루는 필수 기능이다.

4.2.1 리버스 지오코딩 (Reverse Geocoding: Coordinates to Address)

리버스 지오코딩은 특정 경위도 좌표가 어떤 주소에 해당하는지를 알려주는 기능이다.

• Endpoint: GET https://apis.openapi.sk.com/tmap/geo/reversegeocoding 1

• 설명: 입력된 위도와 경도 좌표를 기반으로 해당 위치의 법정동, 행정동, 도로명 주소 등 상세한 주소 체계 정보를 반환한다. 특히 TMAP의 리버스 지오코딩 API는 다음과 같은 정교한 옵션을 제공하여 활용도를 높인다.

• navType 파라미터를 통해 동일한 건물이라도 보행자 출입구와 차량 진입로의 좌표를 구분하여 받을 수 있다. 이는 내비게이션이나 배송 서비스에서 매우 유용한 기능이다.1

• buildingDetailYn 파라미터를 ’Y’로 설정하면, 아파트 단지 좌표를 입력했을 때 단순히 단지 이름만 반환하는 것이 아니라 해당 좌표가 속한 ‘동’ 정보까지 상세하게 표출할 수 있다.18

4.3 경로안내 API

경로안내 API는 TMAP 플랫폼의 가장 핵심적인 기능으로, 출발지에서 목적지까지의 최적 경로를 탐색하는 강력한 기능을 제공한다. 실시간 교통 정보를 반영하여 가장 빠른 길을 안내하는 것은 물론, 사용자의 다양한 요구에 맞춰 무료 도로 우선, 최단 거리, 고속도로 우선 등 여러 가지 옵션을 제공한다.10

TMAP은 다양한 서비스 시나리오와 비즈니스 요구사항에 대응하기 위해 단일 API가 아닌, 계층적으로 세분화된 경로 API 제품군을 제공한다. 이는 TMAP API가 다양한 규모와 복잡성을 가진 고객층을 모두 만족시키려는 전략적 제품 설계를 반영한다. 예를 들어, 단순한 두 지점 간의 길안내가 필요한 서비스는 기본적인 ‘자동차 경로안내’ API를 사용하면 된다. 반면, 여러 배송지를 순서대로 방문해야 하는 배달 앱은 ‘다중 경유지 안내’ API가 적합하다. 더 나아가, 수십 개의 방문지점을 어떤 순서로 돌아야 가장 효율적인지를 계산해야 하는 대규모 물류 기업의 경우, 계산 비용이 매우 높은 ‘경유지 순서 최적화’ API를 사용하게 된다.17 이처럼 기능의 복잡도와 서버 자원 소모량에 따라 API를 분리하여 제공하는 것은 NP-hard 문제(외판원 문제)에 해당하는 경로 최적화 같은 고부가가치 기능에 대해 별도의 과금 모델을 적용하고, 개발자에게는 자신의 서비스 요구사항에 가장 적합한 API를 선택하여 비용과 성능을 최적화할 수 있는 유연성을 제공한다. 또한, 자동차뿐만 아니라 보행자, 화물차 등 이동 수단에 특화된 경로 API도 별도로 제공된다. 특히 화물차 경로 API는 차량의 중량, 높이, 폭 등을 고려하여 통행 제한 구간(낮은 터널, 중량 제한 교량 등)을 회피하는 경로를 탐색하는 전문적인 기능을 포함한다.1

4.3.1 자동차 경로

가장 보편적으로 사용되는 자동차 경로 탐색 기능이다.

• Endpoint: POST https://apis.openapi.sk.com/tmap/routes 10

• 설명: 출발지, 목적지, 그리고 최대 5개의 경유지를 입력받아 자동차 이동 경로를 탐색한다. 응답 결과에는 경로의 전체 형상을 나타내는 좌표열(LineString), 총 거리, 예상 소요 시간, 통행 요금, 그리고 각 구간별 상세 안내(예: “OO대교 방면으로 우회전”) 등이 포함된다.

Table 4: 자동차 경로안내 요청 파라미터

이 파라미터 표는 TMAP 경로 탐색 기능의 강력한 맞춤 설정 능력을 보여준다. 개발자는 searchOption을 통해 사용자의 선호도(시간, 비용, 운전 편의성 등)에 맞는 다양한 경로를 제공할 수 있다. 예를 들어, 유료 도로에 민감한 사용자를 위해 searchOption=1(무료우선)을, 시간에 쫓기는 사용자를 위해 searchOption=2(최소시간)를 선택적으로 제공하는 것이 가능하다. 또한, totalValue=2 옵션은 여러 대안 경로의 예상 시간과 비용만 빠르게 비교하여 사용자에게 제시하는 UI를 구현할 때 매우 유용하다. 이처럼 필요한 정보만 선택적으로 수신함으로써 불필요한 네트워크 트래픽과 클라이언트의 파싱 비용을 절감할 수 있어, 효율적이고 사용자 친화적인 서비스 개발에 직접적으로 기여한다.

응답 데이터 구조

자동차 경로안내 API의 응답은 지도에 경로를 시각화하고, 사용자에게 단계별 길안내를 제공하는 데 필요한 모든 정보를 담고 있는 GeoJSON 형식의 FeatureCollection 객체이다.

{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [126.9850, 37.5664]
},
"properties": {
"totalDistance": 20000,
"totalTime": 1800,
"totalFare": 2500,
"taxiFare": 15000,
"index": 0,
"pointType": "S"
}
},
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [126.9850, 37.5664],
[126.9851, 37.5665],
[126.9852, 37.5666]
},
"properties": {
"index": 1,
"lineIndex": 1,
"description": "을지로를 따라 200m 직진",
"distance": 200,
"time": 60,
"roadType": 7,
"turnType": 200
}
}
]
}

10

• type: “FeatureCollection“으로 고정.

• features: 경로를 구성하는 요소들의 배열.

• 첫 번째 Feature 객체는 보통 경로 전체의 요약 정보를 담는다.

• geometry: 출발지(pointType: “S”)의 좌표를 나타내는 Point 객체.

• properties: totalDistance(총 거리, 미터 단위), totalTime(총 소요 시간, 초 단위), totalFare(총 통행 요금, 원 단위), taxiFare(예상 택시 요금) 등 요약 정보를 포함한다.

• 이후의 Feature 객체들은 경로의 각 구간을 나타낸다.

• geometry: 해당 구간의 경로를 구성하는 좌표들의 배열을 담은 LineString 객체. 이 좌표들을 순서대로 연결하면 지도에 경로선이 그려진다.

• properties: description(TBT, Turn-By-Turn 안내 문구), distance(구간 거리), time(구간 소요 시간), turnType(회전 종류 코드) 등 상세한 주행 안내 정보를 포함한다.

5. 참조

본 섹션에서는 TMAP API를 사용하여 안정적이고 효율적인 서비스를 개발하고 운영하는 데 필수적인 참조 정보를 제공한다. API의 사용량 제한 정책을 이해하고, 발생 가능한 오류에 효과적으로 대응하는 것은 서비스의 품질을 유지하는 데 매우 중요하다.

5.1 사용량 제한 및 정책

TMAP API는 개발자가 초기 비용 부담 없이 서비스를 개발하고 테스트할 수 있도록 무료 사용량을 제공하며, 서비스 규모가 성장함에 따라 유연하게 확장할 수 있는 유료 요금제를 함께 운영한다.20

• 요금제: API를 처음 사용하는 개발자는 기본적으로 무료 플랜의 혜택을 받는다. 이 플랜은 각 API별로 일일 또는 월간 호출 횟수에 제한이 있다. 예를 들어, 특정 경로안내 API는 하루 1,000건까지 무료로 호출할 수 있다.21 서비스의 트래픽이 이 한도를 초과할 것으로 예상되거나 더 높은 수준의 성능과 안정성이 요구되는 경우, 사용한 만큼 비용을 지불하는 유료 종량제(Pay-as-you-go) 또는 매월 고정된 비용으로 대량의 트래픽을 처리할 수 있는 정액제 서비스로 전환할 수 있다.1 요금제에 대한 최신 정보는 SK open API 포털에서 확인해야 한다.

• 사용량 초과 처리: API 호출량이 계약된 서비스 수준 협약(SLA)의 임계값을 초과하면, API 게이트웨이는 더 이상의 요청을 처리하지 않고 429 Too Many Requests HTTP 상태 코드를 반환한다.11 이는 서버의 과부하를 방지하고 모든 사용자에게 안정적인 서비스를 제공하기 위한 필수적인 정책이다.

특히, 429 상태 코드는 두 가지 주요 상황을 구분하여 응답하므로 개발자는 이를 명확히 인지하고 대응 전략을 수립해야 한다. 첫째는 THROTTLED 오류로, 이는 ’초당 호출 건수’와 같이 단기간에 설정된 요청 빈도(Rate Limit)를 초과했을 때 발생한다. 예를 들어, 짧은 시간 안에 수백 개의 요청을 동시에 보내는 경우, 일일 총 사용량이 남아있더라도 이 오류가 발생할 수 있다. 둘째는 QUOTA_EXCEEDED 오류로, 이는 ’일일 총 호출 10,000건’과 같이 장기간에 걸쳐 할당된 총량(Quota)을 모두 소진했을 때 발생한다.11

이러한 정책은 개발자가 단순히 총 사용량만 관리해서는 안 되며, API 호출 로직을 설계할 때 순간적인 트래픽 폭증(burst traffic)을 제어하는 방어적인 프로그래밍 기법을 도입해야 함을 시사한다. 예를 들어, 429 오류를 수신했을 때 무작정 재시도하는 대신, ‘지수 백오프(exponential backoff)’ 알고리즘을 적용하여 재시도 간의 대기 시간을 점차 늘려가는 방식으로 서버에 가해지는 부담을 줄여야 한다. 안정적인 서비스 운영을 위해서는 SK open API 대시보드에서 제공하는 통계 기능을 주기적으로 확인하여 4 서비스의 트래픽 패턴을 분석하고, 예측되는 사용량에 맞춰 적절한 요금제를 선택하며,

429 오류를 우아하게 처리하는 예외 처리 로직을 애플리케이션에 반드시 구현해야 한다.

5.2 오류 코드 참조

TMAP API 호출 시 문제가 발생하면, 서버는 원인을 파악하는 데 도움이 되는 오류 코드를 포함한 응답을 반환한다. 이 오류들은 발생 원인과 위치에 따라 크게 ’API 게이트웨이 공통 오류’와 ‘TMAP 서비스 고유 오류’ 두 가지로 분류된다.

이러한 계층적 오류 아키텍처는 디버깅 효율을 극대화하기 위해 의도적으로 설계되었다. 오류 코드의 카테고리를 먼저 확인하면 문제의 발생 지점을 신속하게 파악할 수 있다. ‘gw’ (Gateway) 접두사가 붙는 오류는 API 요청이 TMAP의 핵심 비즈니스 로직에 도달하기도 전에, 가장 바깥단의 API 게이트웨이에서 거부되었음을 의미한다. 이는 주로 인증(appKey), 권한(IP 주소), 트래픽 제어(사용량 한도)와 관련된 문제이다.11 반면, ‘tmap’ 카테고리의 오류는 요청이 게이트웨이를 성공적으로 통과한 후, TMAP 서비스 내부 로직에서 처리되는 과정에서 발생한 문제이다. 이는 대부분 요청 파라미터의 데이터 형식이나 값이 유효하지 않거나(예: 잘못된 좌표), 서비스가 처리할 수 없는 조건(예: 경로 탐색 불가 지역)일 때 발생한다.11

따라서 개발자는 오류 발생 시, 먼저 오류 코드의 카테고리를 확인하는 체계적인 접근법을 취해야 한다. ‘gw’ 오류가 발생하면 자신의 App Key, SK open API 포털의 IP 설정, API 호출 빈도 등을 점검해야 한다. ‘tmap’ 오류가 발생하면 API 요청에 사용된 파라미터 값(좌표, 주소, 옵션 등)의 형식과 유효성을 API 명세와 비교하여 검토해야 한다. 이 접근법은 문제 해결 시간을 크게 단축시킨다.

5.2.1 API 게이트웨이 공통 오류 코드

다음 표는 API 게이트웨이 단에서 발생하는 주요 공통 오류 코드를 설명한다.

Table 5: API 게이트웨이 공통 오류 코드

11

5.2.2 TMAP 서비스 고유 오류 코드

다음 표는 요청이 TMAP 서비스 로직에 의해 처리되는 과정에서 발생하는 주요 오류 코드를 설명한다.

Table 6: TMAP 서비스 고유 오류 코드

11

이 두 오류 코드 표는 개발자가 서비스 개발 및 운영 과정에서 직면할 수 있는 대부분의 문제 상황에 대한 ‘응급 처치 가이드’ 역할을 한다. 명확한 오류 코드, 메시지, 그리고 구체적인 해결 방안을 함께 제공함으로써, 개발자는 추측에 의존하지 않고 체계적으로 원인을 분석하고 문제를 해결할 수 있다. 이는 개발 및 운영 과정에서 발생하는 서비스 장애 시간을 최소화하는 데 결정적인 기여를 한다.

6. 참고 자료

1. T MAP API, https://tmapapi.tmapmobility.com/
2. T map API Business - T map Trend Map 2020, https://www.tmap.co.kr/static/trendmap_2020/en/tmap-story/3-05.html
3. Azure DevOps Services REST API Reference - Microsoft Learn, https://learn.microsoft.com/en-us/rest/api/azure/devops/?view=azure-devops-rest-7.2
4. SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=126
5. TMAP - SK open API, https://openapi.sk.com/products/detail?svcSeq=4
6. SK open API 소개, https://skopenapi.readme.io/reference/%EC%86%8C%EA%B0%9C
7. T map API 사용해 지도 띄우기 - 소더코드의 개발자들 그리고, https://sothecode.tistory.com/83
8. [iOS/Swift] T-Map(티맵) 연동하기 - 스펜서 개발블로그, https://spencer.tistory.com/30
9. 장소 통합 검색 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=12
10. 자동차 경로 안내 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=46
11. 에러 코드 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=58
12. POI 검색 예시, https://skopenapi.readme.io/reference/poi-%EA%B2%80%EC%83%89-%EC%83%98%ED%94%8C%EC%98%88%EC%A0%9C
13. 자동차 경로안내 - SK open API 소개, https://skopenapi.readme.io/reference/%EC%9E%90%EB%8F%99%EC%B0%A8-%EA%B2%BD%EB%A1%9C%EC%95%88%EB%82%B4
14. TMAP - SK open API, https://openapi.sk.com/qnaCommunity/279
15. [React] T Map API (1) : 가입하기 - 개발 공부방 - 티스토리, https://zindex.tistory.com/298
16. API 키 관리 | Authentication - Google Cloud, https://cloud.google.com/docs/authentication/api-keys?hl=ko
17. 장소(POI) 통합 검색 - ReadMe, https://tmap-skopenapi.readme.io/reference/%EC%9E%A5%EC%86%8C%ED%86%B5%ED%95%A9%EA%B2%80%EC%83%89
18. 신규 TMAP API 가이드 사이트 이동하기 - Guide | T MAP API, https://tmapapi.tmapmobility.com/index_stg.html
19. 자동차경로안내 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=37
20. T맵 API Business - T map Trend Map 2020, https://www.tmap.co.kr/static/trendmap_2020/tmap-story/3-05.html
21. kminito/tmap-api-webapp - GitHub, https://github.com/kminito/tmap-api-webapp
22. API 게이트웨이 공통 에러 코드, https://openapi.sk.com/products/detail?linkMenuSeq=313
23. Error Code - SK open API 소개, https://skopenapi.readme.io/reference/error-code-12
24. Geocoding request and response | Geocoding API - Google for Developers, https://developers.google.com/maps/documentation/geocoding/requests-geocoding
25. 에러 코드 - SK open API, https://openapi.sk.com/products/detail?linkMenuSeq=318