대중교통 길찾기 API 가이드(Public Transit Route Search API Guide)

대중교통 길찾기 API는 출발점의 경위도 좌표(SX, SY)에서 도착점의 경의도 좌표(EX, EY)로 가는 대중교통 결과를 반환합니다. 따라서 경위도 좌표(SX,SY,EX,EY)가 대중교통 길찾기 API의 필수 파라미터입니다. 필수 파라미터인 경위도 좌표는 대중교통 정류장 검색 API, 반경내 대중교통 POI 검색 API, 지도 위 대중교통 POI검색 API의 결과에서 표출되는 좌표를 이용하거나 Naver, Daum, Google을 포함한 모든 Map API 이용하여 지도 위에서 좌표를 취득할 수 있습니다.

반환 결과는 도시내/도시간으로 나뉩니다. 도시간 결과는 도시간 대중교통(고속버스, 시외버스, 기차, 항공 등)의 결과만 반환되어지므로 ‘출발점->출발도시의 터미널’, ‘도착 도시의 터미널->도착점’의 경로는 도시간 길찾기 경로의 앞, 뒤로 도시내 길찾기 경로를 반드시 다시 호출해야 출발점에서 도착점까지의 완전한 길찾기 결과가 보여집니다.

API 활용 예시(API Usage Example)

해당 예시는 임의의 출도착 경위도 좌표를 코드상에 지정하여 호출된 결과를 Naver 지도위에 표출한 예시입니다.

• 파라미터 규칙

모든 API에는 1개의 파라미터가 공통으로 존재하며, 그 목록은 아래와 같습니다.

각 API별 파라미터에는 필수(필수값 : Y) 파라미터와 선택적인(필수값 : N) 파라미터가 존재하며, 선택적 파라미터를 기재하지 않아도 자동으로 default값이 입력됩니다. (default 값은 각 API별 레퍼런스 페이지에서 확인 가능합니다.)

• API 호출 방법

{YOUR_API_KEY} 에는 발급받은 api key 가 들어갑니다.

코드

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

public class OdsayApiKeyAuthSample {

	public static void main(String[] args) throws IOException {

		// ODsay Api Key 정보
		String apiKey = "{YOUR_API_KEY}";
		
		String urlInfo = "https://api.odsay.com/v1/api/searchPubTransPathT?SX=126.9027279&SY=37.5349277&EX=126.9145430&EY=37.5499421&apiKey=" + URLEncoder.encode(apiKey, "UTF-8");

		// http 연결
		URL url = new URL(urlInfo);
		HttpURLConnection conn = (HttpURLConnection)url.openConnection();
		conn.setRequestMethod("GET");
		conn.setRequestProperty("Content-type", "application/json");

		BufferedReader bufferedReader = 
			new BufferedReader(new InputStreamReader(conn.getInputStream()));

		StringBuilder sb = new StringBuilder();
		String line;
		while ((line = bufferedReader.readLine()) != null) {
			sb.append(line);
		}
		bufferedReader.close();
		conn.disconnect();

		// 결과 출력
		System.out.println(sb.toString());

	}
}
                            

코드

function searchPubTransPathAJAX() {
	var xhr = new XMLHttpRequest();
	var url = "https://api.odsay.com/v1/api/searchPubTransPathT?SX=126.9027279&SY=37.5349277&EX=126.9145430&EY=37.5499421&apiKey={YOUR_API_KEY}";
	xhr.open("GET", url, true);
	xhr.send();
	xhr.onreadystatechange = function() {

		if (xhr.readyState == 4 && xhr.status == 200) {
			console.log( xhr.responseText ); // <- xhr.responseText 로 결과를 가져올 수 있음
		}
	}
}
                            

코드

import UIKit
class ViewController: UIViewController {
  override func viewDidLoad() {
    super.viewDidLoad()
    // ODsay Api Key 정보
    let apiKey = "{YOUR_API_KEY}"
    // 호출 URL 정보
    let urlInfo = "https://api.odsay.com/v1/api/searchPubTransPathT"
    //API 호출 (GET)
    odsayAPI(apiKey: apiKey, urlString: urlInfo, params: [
      "SX" : 126.9027279,
      "SY" : 37.5349277,
      "EX" : 126.9145430,
      "EY" : 37.5499421
    ]) { (ret, retData) in
      //응답 성공
      if ret {
        if let convertedJsonString = String(data: retData as! Data, encoding: .utf8) {
          print(convertedJsonString)
        }
      }
    }
  }
  func odsayAPI(apiKey: String, urlString: String, params: [String: Any], completion: @escaping (Bool, Any) -> Void) {
    let encodedApiKey = apiKey.addingPercentEncoding(withAllowedCharacters: .controlCharacters)!
    var queryParams = "apiKey=\(encodedApiKey)"
    for key in params.keys {
      if queryParams.isEmpty {
        queryParams = "\(key)=\(params[key]!)"
      } else {
        queryParams += "&\(key)=\(params[key]!)"
      }
    }
    let urlStr = "\(urlString)?\(queryParams)"
    var request = URLRequest(url: URL(string: urlStr)!)
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpMethod = "GET"
    URLSession.shared.dataTask(with: request) { data, response, error in
      guard error == nil else {
        print("Error: error calling GET")
        print(error!)
        completion(false, error!)
        return
      }
      guard let data = data else {
        print("Error: Did not receive data")
        return
      }
      guard let response = response as? HTTPURLResponse, (200 ..< 300) ~= response.statusCode else {
        print("Error: HTTP request failed")
        completion(false, data)
        return
      }
      completion(true, data)
    }.resume()
  }
}
                            

결과

{
"result":{
  "path":[{
       "pathType":1,
       "subPath":[{
         "trafficType":1,
         "distance":2000,
         "sectionTime":9,
         "lane":{
           "name":"수도권 2호선",
           "subwaycode":2,
           "subwayCityCode":1000
             },
           "stationCount":1,
           "passStopList":{
           "stations":[{
             "index":0,
             "stationName":"당산",
             "stationID":237,
             "x":126.902682,
             "y":37.534863
             },
             {
             "index":1,
             "stationName":"합정",
             "stationID":238,
             "x":126.914543,
             "y":37.549942
             }]
          },
      "way":"합정",
      "wayCode":2,
      "startX":126.90267725576584,
      "startY":37.534862332279936,
      "startID":237,
      "startName":"당산",
      "endExitNo":"",
      "endExitX":0.0,
      "endExitY":0.0,
      "endX":126.91454311097073,
      "endY":37.549938143345756,
      "endID":238,
      "endName":"합정"
    },
    …(중략)...
    ],
      "info":{
      "mapObj":"2:2:237:238",
      "payment":1250,
      "busTransitCount":0,
      "subwayTransitCount":1,
      "busStationCount":0,
      "subwayStationCount":1,
      "totalStationCount":1,
      "totalTime":9,
      "totalWalk":0,
      "trafficDistance":2000,
      "totalDistance":2000,
      "firstStartStation":"당산",
      "lastEndStation":"합정",
      "totalWalkTime":-1
    }
    }],
    "searchType":0,
    "startRadius":700,
    "endRadius":700,
    "subwayCount":1,
    "busCount":10,
    "subwayBusCount":0,
    "pointDistance":1967,
    "outTrafficCheck":0
  }
}
                            

주요 데이터 이름 API Reference에서 확인하기 »

HTML에 javascript로 길찾기 API를 호출하고 그 결과를 화면에 보여주는 HTML 전체 코드입니다.

코드
                           
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no">
    <title>길찾기 결과 지도에 표출하기</title>
</head>
<body>
<div id="map" style="width:100%;height:400px;"></div>
<!-- Naver Developers에서 발급받은 네이버지도 Application Key 입력  -->
<script type="text/javascript" src="https://oapi.map.naver.com/openapi/v3/maps.js?ncpClientId={YOUR_CLIENT_ID}"></script>

<script>
 
	var mapOptions = {
		center: new naver.maps.LatLng(37.3595704, 127.105399),
		zoom: 10
	};

	var map = new naver.maps.Map('map', mapOptions);
	
	var sx = 126.93737555322481;
	var sy = 37.55525165729346;
	var ex = 126.88265238619182;
	var ey = 37.481440035175375;
	
	function searchPubTransPathAJAX() {
		var xhr = new XMLHttpRequest();
		//ODsay apiKey 입력
		var url = "https://api.odsay.com/v1/api/searchPubTransPathT?SX="+sx+"&SY="+sy+"&EX="+ex+"&EY="+ey+"&apiKey={YOUR_API_KEY}";
		xhr.open("GET", url, true);
		xhr.send();
		xhr.onreadystatechange = function() {
			if (xhr.readyState == 4 && xhr.status == 200) {
			console.log( JSON.parse(xhr.responseText) ); // <- xhr.responseText 로 결과를 가져올 수 있음
			//노선그래픽 데이터 호출
			callMapObjApiAJAX((JSON.parse(xhr.responseText))["result"]["path"][0].info.mapObj);
			}
		}
	}
	
	//길찾기 API 호출
	searchPubTransPathAJAX();
	
	function callMapObjApiAJAX(mabObj){
		var xhr = new XMLHttpRequest();
		//ODsay apiKey 입력
		var url = "https://api.odsay.com/v1/api/loadLane?mapObject=0:0@"+mabObj+"&apiKey={YOUR_API_KEY}";
		xhr.open("GET", url, true);
		xhr.send();
		xhr.onreadystatechange = function() {
			if (xhr.readyState == 4 && xhr.status == 200) {
				var resultJsonData = JSON.parse(xhr.responseText);
				drawNaverMarker(sx,sy);					// 출발지 마커 표시
				drawNaverMarker(ex,ey);					// 도착지 마커 표시
				drawNaverPolyLine(resultJsonData);		// 노선그래픽데이터 지도위 표시
				// boundary 데이터가 있을경우, 해당 boundary로 지도이동
				if(resultJsonData.result.boundary){
						var boundary = new naver.maps.LatLngBounds(
				                new naver.maps.LatLng(resultJsonData.result.boundary.top, resultJsonData.result.boundary.left),
				                new naver.maps.LatLng(resultJsonData.result.boundary.bottom, resultJsonData.result.boundary.right)
				                );
						map.panToBounds(boundary);
				}
			}
		}
	}
	
	// 지도위 마커 표시해주는 함수
	function drawNaverMarker(x,y){
		var marker = new naver.maps.Marker({
		    position: new naver.maps.LatLng(y, x),
		    map: map
		});
	}
	
	// 노선그래픽 데이터를 이용하여 지도위 폴리라인 그려주는 함수
	function drawNaverPolyLine(data){
		var lineArray;
		
		for(var i = 0 ; i < data.result.lane.length; i++){
			for(var j=0 ; j <data.result.lane[i].section.length; j++){
				lineArray = null;
				lineArray = new Array();
				for(var k=0 ; k < data.result.lane[i].section[j].graphPos.length; k++){
					lineArray.push(new naver.maps.LatLng(data.result.lane[i].section[j].graphPos[k].y, data.result.lane[i].section[j].graphPos[k].x));
				}
				
			//지하철결과의 경우 노선에 따른 라인색상 지정하는 부분 (1,2호선의 경우만 예로 들음)
				if(data.result.lane[i].type == 1){
					var polyline = new naver.maps.Polyline({
					    map: map,
					    path: lineArray,
					    strokeWeight: 3,
					    strokeColor: '#003499'
					});
				}else if(data.result.lane[i].type == 2){
					var polyline = new naver.maps.Polyline({
					    map: map,
					    path: lineArray,
					    strokeWeight: 3,
					    strokeColor: '#37b42d'
					});
				}else{
					var polyline = new naver.maps.Polyline({
					    map: map,
					    path: lineArray,
					    strokeWeight: 3
					});
				}
			}
		}
	}
</script>
</body>
</html>
                           
                            

위의 코드를 실행하면 다음과 같은 결과가 지도에 표출됩니다.(네이버 지도에 최적화)

길찾기 API를 활용하는 방법은 다양하며 위 예시는 Naver Maps API에 길찾기API결과 좌표를 입력하여 Polyline과 Marker를 지도 위에 나타낸 예시입니다. 또 결과셋의 mapObj 값으로 ‘노선 그래픽 데이터 검색 API’를 사용할 경우 좀 더 정교한 대중교통 노선을 지도 위에 나타낼 수 있습니다.

에러 코드는 아래와 같습니다.

주요 데이터 이름 API Reference에서 확인하기 »

실시간 도착정보 연동 가이드(Real-time Arrival Information Linking Guide)

공공데이터포탈에서 실시간 도착정보 API를 지원하지 않는 지역의 실시간 도착정보 연동 및 경기도 마을버스 정류장 연동은 불가능합니다.

서울 지역의 경우 ODsay LAB을 통해 서울시 실시간 버스 위치/도착정보 조회 API 사용이 가능합니다. (서울 마을버스 제외)

ODsay API는 공공데이터포탈(https://www.data.go.kr/) 에서 제공하는 오픈API와 연동하여 실시간 데이터를 제공할 수 있습니다. 오픈 API는 제공사이트마다 사용방법이 상이하며 각 사이트의 가이드를 참조하시기 바랍니다. 이 가이드는 공공데이터포탈 API를 ODsay API와 연동하여 서울시의 실시간 데이터를 활용하는 예시입니다. 타 지역은 하단의 참고사항에서 확인하시길 바랍니다.

ODsay API 호출(ODsay API Call)

오픈 API 호출(Open API Call)

public class GetStationByUid{
.
.                            	
String SERVICE_KEY = "서비스 키";
String URL = "http://ws.bus.go.kr/api/rest/stationinfo/getStationByUid";
StringBuilder urlBuilder = new StringBuilder(URL);
urlBuilder.append("?" + URLEncoder.encode("ServiceKey", "UTF-8")+"="+SERVICE_KEY);
urlBuilder.append("&" + URLEncoder.encode("arsId", "UTF-8") + "=" + URLEncoder.encode("arsID값", "UTF-8"));
.
.                      	
										

결과
<ServiceResult>
	<comMsgHeader/>
	<msgHeader>
		<headerCd>0</headerCd>
		<headerMsg>정상적으로 처리되었습니다.</headerMsg>
		<itemCount>0</itemCount>
	</msgHeader>
	<msgBody>
		<itemList>
			<adirection>신도림역</adirection>
			<arrmsg1>5분11초후[1번째 전]</arrmsg1>
			<arrmsg2>14분2초후[7번째 전]</arrmsg2>
			<arrmsgSec1>5분11초후[1번째 전]</arrmsgSec1>
			<arrmsgSec2>14분2초후[7번째 전]</arrmsgSec2>
			<arsId>19182</arsId> 
			.
			.
			.
			<rtNm>영등포12</rtNm>
			.
			.
		</itemList>
		<itemList>
		.
		.
		</itemlist>
	</msgBody>
</ServiceResult>
	                            

참고사항(Note)

다국어 API 적용 가이드(Multilingual API Guide)

영문, 중문(간체,번체), 일문, 베트남어 등 다국어를 제공하고 있으며 API 파라미터에 원하는 언어의 파라미터 값을 추가하는 것만으로 번역된 API 서비스를 사용하실 수 있습니다. 현재 다국어 서비스는 유료로 제공되며 가격정책을 참고하여 주시기 바랍니다.
* 베트남어의 경우 수도권(서울,경기,인천)에 한하여 제공되는 언어입니다.

언어별 파라미터 값(Parameter Values by Language)

각 언어별은 서로 다른 파라미터 값을 가지고 있습니다.

상표사용가이드(Trademark Usage Guide)

다음의 가이드는 ODsay API를 이용해 개발한 서비스에서 ODsay 브랜드의 가치와 권리를 지키고자 안내하고 있으며, 모든 조항을 준수하면 사전허가 절차없이 상표를 사용할 수 있습니다.

ODsay BI

↓ 다운로드

1) 이용자는 ODsay API를 이용하여 개발한 서비스에서 아래와 같은 위치에 상표를 표시하여 권리 귀속문구를 사용해야 합니다.

• ODsay API를 이용하여 개발한 상품 또는 서비스 내 대중교통 컨텐츠에 대한 설명, 소개페이지
• ODsay API를 이용하여 개발한 상품 또는 서비스에 대중교통 정보가 노출되는 결과페이지
• 기타 ODsay API와 관계되어 설명이 필요한 상품 또는 서비스 내 형식에 맞게 노출

활용예시(Example)

아래 이미지 또는 텍스트로 표기하며 텍스트는 시스템폰트나 기본폰트를 사용합니다.

↓ 다운로드 powered by www.ODsay.com Text Type 복사

• 웹 서비스 Image Type Text Type

• 앱 서비스 Image Type Text Type

2) 이용자는 ODsay 상표를 수정 혹은 변형하거나, 다른 상표와 결합 혹은 조합하여 사용하면 안됩니다.

3) ODsay API를 이용하여 개발한 애플리케이션의 이름, 아이콘을 비롯하여 상품명, 서비스명, 회사명, 로고, 심볼 등에 ODsay의 상표를 사용하면 안됩니다.

4) 그 밖에 애플리케이션의 내부, 마켓, 웹페이지, 기타 광고물 등에 ODsay 상표의 식별력이나 명성을 손상할 가능성이 있는 아래의 예와 같은 사용도 허용이 되지 않습니다.

• ODsay의 상표를 보통명사처럼 사용하는 행위
• 성인컨텐츠를 제공하는 상품 또는 서비스에 ODsay의 상표를 표시하는 행위
• 도박 관련 상품 또는 서비스에 ODsay의 상표를 표시하는 행위
• ODsay의 명예 또는 타인의 명예를 훼손, 침해, 비방, 손상하는 상품 또는 서비스에 ODsay의 상표를 표시하는 행위
• 기타 관련 법을 위반하는 상품 또는 서비스에 ODsay의 상표를 표시하는 행위

5) 이용자가 직접 혹은 제3자를 통해 ODsay 및 ODsay 서비스의 명성을 훼손하거나 영업권에 손상을 줄 수 있는 경우, 이용자 혹은 제3자는 어떠한 ODsay 상표도 사용할 수 없습니다.

URI 인코딩가이드(URI Encoding Guide)

URI는 ASCII문자를 사용하여 전송할 수 있으며, 특수문자의경우 다른의미를 갖기때문에 유효한 ASCII형식으로 변환되어야합니다.
apiKey는 보안정책상 특수문자를 포함하기 때문에 직접 또는 JavaScript에서 encodeURI() 함수를 통하여 변환할 수 있습니다.

인코딩 변환 값(Encoding Conversion Value)

apiKey에 특수문자가 포함된경우 아래와같이 변환하여 요청해주시기 바랍니다.