개발가이드
ODsay 대중교통 API 를 이용해 멋진 대중교통 애플리케이션을 만들어 보세요.
개발가이드

애플리케이션 등록

ODsay API로 개발하기 위해 우선 회원가입이 필수사항이며 회원가입 후 ‘애플리케이션-애플리케이션 등록' 메뉴에서 애플리케이션을 등록하셔야 합니다. 회원가입하기 »
애플리케이션 등록하기 »

애플리케이션 등록 시 작성 항목

애플리케이션 등록 시 작성 항목 이미지

애플리케이션 이름은 최대 20자까지 등록 가능하며 동일한 이름으로 중복 사용할 수 없습니다.
카테고리는 애플리케이션의 성격에 맞는 분류 항목을 선택하시면 됩니다.
사용자 유형은 무료와 유료 사용자로 나뉘며 선택한 유형에 따라 상세 유형을 선택하게 됩니다. 무료 사용자는 개인, 학생, 5인 이하 스타트업 기업 중 선택 가능하며 유료 사용자는 기업(5인 이하 스타트업 제외), 기관, 기타 중 선택하면 됩니다.
사용자 정보는 사용자의 이름 또는 기업명, 기관명 등을 직접 입력하는 공간이며 가입 시 기입한 연락처가 문자 알림 박스에 표출됩니다.
서비스 플랫폼 설정에서는 URL, 서버, Android, iOS 등 4가지 플랫폼을 지정할 수 있으며 플랫폼마다 1개의 API Key를 부여받을 수 있습니다. URL, IP의 경우 최대 5개, Packagename, Bundle ID는 1개만 등록 가능합니다.

애플리케이션은 추가로 등록이 가능하며 수 제한은 없습니다.

내 애플리케이션

내 애플리케이션에서는 등록한 애플리케이션의 개요, 설정, 통계, 가격 등을 확인하실 수 있습니다.

개요

애플리케이션 개요 이미지

애플리케이션 이름은 등록한 애플리케이션 이름이 자동으로 나오게 됩니다.
서비스 레벨은 가격정책에 따라 선택한 레벨이 노출 되며 레벨은 ‘내 애플리케이션-가격’에서 상세 확인이 가능합니다.
서비스 상태는 활성화와 활성화 신청하기로 나뉘며, 애플리케이션 등록 시 사용자 유형에서 유료를 선택한 사용자들은 활성화 신청하기를 통해 원활한 서비스를 사용하실 수 있습니다.
현재 호출수는 현재 호출된 수가 노출됩니다.
서비스 플랫폼별 Key 정보에서는 플랫폼별 API Key 값을 확인할 수 있습니다.

설정

애플리케이션 설정 이미지

애플리케이션 이름은 등록한 애플리케이션 이름이 자동으로 나오게 되며 수정이 불가능합니다.
카테고리는 수정이 가능하며 ‘교통’과 ‘교통 외’로 구분됩니다.
사용자 유형, 사용자 정보는 애플리케이션 등록시 선택한 항목과 작성한 내용이 나오게 되며 수정이 불가능합니다. 위 항목에 대한 수정이 필요한 경우는 별도로 문의를 하셔야 합니다.
문자 알림은 애플리케이션 등록시 작성한 경우는 작성한대로 보여지게 되며 수정, 삭제가 가능합니다.
서비스 플랫폼 환경은 수정, 추가, 삭제가 가능하며 애플리케이션 등록시 서비스 플랫폼 환경 선택과 동일합니다.
애플리케이션 삭제는 해당 애플리케이션을 삭제할 때 사용되는 기능입니다.

통계

애플리케이션 통계 이미지

제한 호출수는 서비스 레벨에 따라 제공되는 제한 호출수와 현재 호출횟수를 함께 보여줍니다.
기준일 설정은 서비스 레벨에 따라 기간설정 가능 영역이 구분되며 Basic 서비스 레벨에서는 기준 시간의 1시간 전, 6시간 전, 12시간 전 통계를 확인할 수 있으며 Standard 및 Premium에서는 1일 전, 7일 전, 30일 전 등은 물론 직접 기간을 맞춤 설정할 수도 있습니다.
Standard 및 Premium 서비스 레벨에서는 다양한 기준일 설정에 더하여 플랫폼 별 통계도 지원하고 있습니다.
호출횟수, 오류횟수, 평균응답속도를 확인할 수 있으며 각각의 항목에 따라 그래프가 다르게 표현됩니다.

가격

Basic Standard Premium
사용자 개인, 학생, 스타트업 기업 제한 없음 제한 없음
제한 호출수 3,000 / 일 100,000 / 일 100,000 초과 / 일
통계 지원 기본 통계 기능 유료 통계 기능
(기간추가, 플랫폼별 통계)
유료 통계 기능
(기간추가, 플랫폼별 통계)
가격 무료 300만원 / 월 가격문의

서비스 레벨은 일 기준 제한 호출수에 따라 Basic, Standard, Premium으로 나뉘어 집니다.
Basic은 일 기준 3,000건 이하 호출이 가능하며 Basic 레벨을 이용가능한 사용자는 개인, 학생, 5인 이하의 스타트업 기업에 한정됩니다.
Standard는 일 기준 100,000건의 호출이 가능하며 Premium의 경우는 일 기준 100,000건 초과 호출을 제공합니다. Premium의 경우 협의를 통해 제한 호출수와 가격을 결정할 수 있습니다.
업그레이드 문의는 현재 서비스 레벨에서 상위 레벨로 업그레이드 하고자 할 때, 클릭하면 담당자에게 메일을 보낼 수 있습니다.

ODsay SDK 설정 가이드

ODsay SDK for iOS 연결 방법(XCode 8.3.x 기준)

ODsay 대중교통 iOS SDK는 iOS 8.0 이상에서 정상 동작합니다.
ODsay 대중교통 iOS SDK 개발을 위한 준비사항은 아래와 같습니다.

•XCode에서 프로젝트 생성시에는 ODsaySDK 이용 신청시 등록한 ‘Bundle Identifier’와 일치하도록 주의합니다.

•다운로드 받은 SDK(ODsaySDK.framework)를 프로젝트 내 원하는 위치에 복사합니다.

•프로젝트의 General 탭에서 Linked Frameworks and Libraries 에 ODsaySDK.framework 를 추가 합니다.

  a. + 버튼을 누릅니다.
  SDK iOS guide

  b. Add Other.. 버튼을 눌러 저장한 프레임웍 파일을 지정합니다.
  SDK iOS guide

  c. ODsaySDK.framework 가 추가된 것을 확인합니다.
  SDK iOS guide

•프로젝트 Build Settings 설정에 아래의 설정을 추가 합니다.

  a. Linking > Other Linker Flags에 -ObjC
  SDK iOS guide

  b. Search Paths > Framework Search Paths에 ODsaySDK.framework 프레임웍이 있는 폴더가 추가되어 있는지 확인합니다.

•Info.plist 에 아래의 설정을 추가 합니다.

코드
<key>NSAppTransportSecurity</key>
<dict>
   	<key>NSAllowsArbitraryLoads</key>
   	<true/>
</dict>
		



****** Swift 프로젝트의 경우에는 아래의 추가 작업이 필요합니다. ******

•Objective-C Bridging Header를 아래 내용으로 생성합니다.

코드
#ifndef ODsaySDKSampleSwift_Swift_h
#define ODsaySDKSampleSwift_Swift_h

#import <ODsaySDK/ODsaySDK.h>

#endif /* ODsaySDKSampleSwift_Swift_h */
 


•프로젝트 Build 설정에 아래의 설정을 추가합니다.

  a. Swift Compiler - General > Objective-C Bridging Header에 위에서 생성한 헤더파일을 추가합니다.

ODsay SDK API 가이드

ODsay SDK는 API 호출 메서드, 비동기 통신 기능 등을 포함하여 개발자들이 보다 쉽고 간편하게 사용할 수 있도록 편의를 제공합니다.

API 항목

순번 래퍼런스 ODsayService 호출 메서드
1 버스 노선 조회 requestSearchBusLane
2 버스노선 상세정보 조회 requestBusLaneDetail
3 버스정류장 세부정보 조회 requestBusStationInfo
4 열차/KTX 운행정보 requestTrainServiceTime
5 고속버스 운행정보 검색 requestExpressServiceTime
6 시외버스 운행정보 검색 requestIntercityServiceTime
7 항공 운행정보 검색 requestAirServiceTime
8 운수회사별 버스노선 조회 requestSearchCompanyLane
9 지하철역 세부정보 조회 requestSubwayStationInfo
10 지하철역 전체시간표 조회 requestSubwayTimeTable
11 노선 그래픽 데이터 검색 requestLoadLane
12 대중교통 정류장 검색 requestSearchStation
13 반경내 대중교통 POI 검색 requestPointSearch
14 지도 위 대중교통 POI 검색 requestBoundarySearch
15 지하철 경로검색 조회(지하철 노선도) requestSubwayPath
16 대중교통 길찾기 requestSearchPubTransPath
17 지하철역 환승정보 조회 requestSubwayTransitInfo
18 고속버스 터미널 조회 requestExpressBusTerminals
19 시외버스 터미널 조회 requestIntercityBusTerminals
20 도시코드 조회 requestSearchCID

API 활용 예시

• 파라미터 규칙

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

번호 파라미터 필수값 설명 예시
1 apiKey Y 발급된 키 apiKey=xxxxxxxxxxx

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

버스노선 조회 API의 파라미터 규칙은 아래와 같습니다.

번호 파라미터 필수값 설명 예시
1 busNo Y 조회할 버스노선 번호 busNo=150
2 CID N 도시코드 CID=1000
3 stationListYn N 주요정류장 표현 옵션(default:no) stationListYn=no
4 displayCnt N 결과 갯수(default:10) displayCnt=10
5 startNO N 결과 갯수중 시작인덱스(default:1) startNO=1

각각의 API 파라미터는 레퍼런스에서 확인 가능합니다.

•초기 설정 방법

코드
[Objective-C]
	[[ODsayService sharedInst] setApiKey:{발급받은 키값}];	//SDK 인증
	[[ODsayService sharedInst] setTimeout:5000];	//통신 타임아웃 설정

[Swift]
	ODsayService.sharedInst().setApiKey({발급받은 키값}) 	//SDK 인증
	ODsayService.sharedInst().setTimeout(5000)	//통신 타임아웃 설정
		

•메서드 호출 방법

아래의 메서드는 비동기 블럭 방식으로 결과를 리턴합니다.
[Objective-C]
	[[ODsayService sharedInst] {함수명}:{파라미터들}
		responseBlock:^(int retCode, NSDictionary *resultDic){
			if(retCode == 200) {
				//응답 성공 시, 처리할 코드 입력
			} else {
				//응답 실패 시, 처리할 코드 입력
			}
		}
[Swift]
ODsayService.sharedInst().{함수명}({파라미터들}) {
	(retCode:Int32, resultDic:[AnyHashable : Any]?) in
	if retCode == 200 {
	    //응답 성공 시, 처리할 코드 입력
	} else {
	    //응답 실패 시, 처리할 코드 입력
	}
}
		

•사용방법 예제

코드
[Objective-C]
	#import <ODsaySDK/ODsaySDK.h>
	- (void)viewDidLoad {
		….. 내용 중략 ...
		[[ODsayService sharedInst] setApiKey:{발급받은 키값}];	//SDK 인증
		[[ODsayService sharedInst] setTimeout:5000];	//통신 타임아웃 설정

		//버스노선 상세정보 조회 호출
		[[ODsayService sharedInst] requestBusLaneDetail:@"12018"
			responseBlock:^(int retCode, NSDictionary *resultDic) {
			if(retCode == 200) {
				NSLog(@"%@", [resultDic description]);
			} else {
				NSLog(@"%@", [resultDic description]);
			}
		}];
	}

[Swift]
override func viewDidLoad() {
	ODsayService.sharedInst().setApiKey({발급받은 키값}) 	//SDK 인증
    ODsayService.sharedInst().setTimeout(5000)	//통신 타임아웃 설정

	//버스노선 상세정보 조회 호출
	ODsayService.sharedInst().requestBusLaneDetail("12018") {
		(retCode:Int32, resultDic:[AnyHashable : Any]?) in
		if retCode == 200 {
		   		print(resultDic!.description)
		} else {
		   		print(resultDic!.description)
		}
	}
}
		

•응답 블럭 정의

코드
typedef void (^ResponseBlock)(int retCode, NSDictionary *resultDic);
		
호출 성공 시 retCode : 200
   - retCode : 응답 코드 값을 리턴합니다.
   - resultDic : 응답 결과가 있는 Dictionary 객체를 반환합니다. (각 기능 API 응답 결과 포맷 참고)
호출 실패 시 retCode : 200 이외의 값
   - retCode : 응답 코드 값을 리턴합니다.
   - resultDic : 응답 결과가 있는 Dictionary 객체를 반환합니다. (오류 응답 결과 포맷 참고)


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

CODE 처리 message 내용
α 서버 β 서버로부터 받는 코드, 메시지
-100 SDK Network connect timeout 네트워크 연결 실패
-101 SDK Json object undefined Json 객체 생성 실패
-102 SDK SDK internal error SDK 내부 에러

ODsay SDK Sample 가이드

ODsay SDK for iOS Sample 프로젝트를 다운받습니다.

ODsay SDK for iOS Sample은 SDK 다운로드에서 함께 다운받을 수 있습니다.

압축을 해제하면 아래와 같은 폴더가 존재 합니다.

   - ODsaySDKSample : Objective-C용 샘플 프로젝트
   - ODsaySDKSampleSwift : Swift용 샘플 프로젝트
   - ODsaySDK.framework : SDK 프레임워크
   ** 개발하시는 언어에 맞는 샘플 프로젝트를 참고 하시면 됩니다.

샘플 프로젝트에 앱 등록 시 발급 되는 API Key 값과 Bundle Identifier를 동일하게 설정해야 샘플 실행이 가능합니다.

실시간 도착정보 연동 가이드

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

공공데이터포탈 일부 API의 경우 CORS 정책으로 인해 서버 단에서 API를 호출해야 합니다.
크로스도메인 관련 참고자료 : 공공데이터포탈 자료실

ODsay API 호출

ODsay API를 호출하여 얻은 결과값의 특정 데이터값을 오픈 API를 호출하기 위한 파라미터 값으로 넘겨주어 연동함으로써 실시간 데이터를 이용할 수 있습니다. 대중교통 정류장 검색 API를 이용하여 정류소을 검색하면 아래와 같은 결과를 얻을 수 있습니다.

대중교통 정류장 검색결과
위의 결과는 파라미터 값으로 stationName에 "당산유원제일1차아파트"를 입력한 결과 값 입니다. 여기서 arsID를 획득할 수 있습니다.

오픈 API 호출

공공데이터포탈(https://www.data.go.kr/) 의 가이드를 참조하여 키를 발급받은 후, 필요한 API를 검색하여 신청합니다.
신청한 API의 상세정보 하단에 해당 API를 호출하는 예시를 언어별로 제공합니다.
오픈API 코드예시
원하는 언어에 발급받은 키와 파라미터를 입력하여 API를 호출하면 실시간정보를 얻을 수 있습니다.

아래는 서울특별시에서 제공하는 정류소정보조회 서비스 중 getStationByUidItem API의 Objective-C 소스 예시 입니다.
API를 호출하는 코드 중 통신을 하기위한 URL과 파라미터값을 설정하는 부분입니다.

@implementation NSString (URLEncoding)
        //function used to encode query and matrix parameters
        -(NSString *)urlEncodeUsingEncoding:(NSStringEncoding)encoding {
            return (__bridge NSString *)CFURLCreateStringByAddingPercentEscapes(NULL,
                (CFStringRef)self,
                NULL,
                (CFStringRef)@“!*‘\\“();:@&=+$,/?%#[]% “,
                CFStringConvertNSStringEncodingToEncoding(encoding));
        }
    @end               	
										
위 소스와 같이 먼저 인코딩 함수를 추가합니다.

.
.                            	
NSString *SERVICE_KEY = “서비스 키“;
NSString *URL = @“http://ws.bus.go.kr/api/rest/stationinfo/getStationByUid“;
NSString *queryParams = [NSString stringWithFormat:@“?%@&%@“,
	[NSString stringWithFormat:@“%@=%@“, [@“ServiceKey” urlEncodeUsingEncoding:NSUTF8StringEncoding], [SERVICE_KEY urlEncodeUsingEncoding:NSUTF8StringEncoding]]
	, [NSString stringWithFormat:@“%@=%@“, [@“arsId” urlEncodeUsingEncoding:NSUTF8StringEncoding], [@“arsID값” urlEncodeUsingEncoding:NSUTF8StringEncoding]]];
NSString *reqUrl =  [NSString stringWithFormat:@“%@%@“, URL, queryParams];
.
.                      	
										
파라미터 값으로 arsID(정류소번호)에 ODsay API에서 획득한 데이터 '19-182' 를 오픈 API의 파라미터 형식에 맞게 '19182'로 문자열을 가공한 뒤 입력하고 API를 호출하면 해당 정류장의 실시간 도착정보를 조회할 수 있습니다.

결과
<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>
	                            
위의 결과는 ODsay API의 'arsID'를 이용하여 정류소의 실시간 버스도착정보를 호출한 결과값 입니다.

ODsay API의 데이터와 그 데이터를 이용해 호출한 오픈 API의 데이터를 활용해 필요한 정보를 추출하고 제공하는 실시간 서비스를 아래와 같이 만들 수 있습니다.

최종 연동결과
실제 ODsay API 호출 결과와 오픈 API 호출 결과를 조합한 예시 입니다.

참고사항

공공데이터포탈에서 실시간 도착정보 API 사용 시, 아래의 지역별 API 파라미터를 참고하길 바랍니다.

지역 서비스 명 API 명 제공기관 필요데이터 획득경로
서울특별시 정류소정보조회 서비스 getStationByUidItem 서울특별시 arsID ODsay API 중
"대중교통 정류장 검색" 결과 내
arsID 값 사용
경기도 버스도착정보 조회 서비스 버스도착정보목록조회 경기도 stationId ODsay API 중
"대중교통 정류장 검색" 결과 내
localstationID 값 사용
부산광역시 부산버스정보시스템 정류소 도착정보 조회 부산광역시 ServiceKey 공공데이터포탈에서 발급받은
서비스 키
bstopid ODsay API 중
"대중교통 정류장 검색" 결과 내
localstationID 값 사용
그 외 18개 지역 도착정보조회서비스 정류소별도착예정정보목록조회 국토교통부
TAGO
cityCode 서비스 내 API 중
"도시코드 목록 조회" 를 이용하여 조회
nodeId ODsay API 중
"대중교통 정류장 검색" 결과 내
localstationID 값 사용
공공데이터포탈에서 실시간 도착정보 API를 지원하지 않는 지역의 실시간 도착정보 연동은 불가능합니다.

상표사용가이드

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

ODsay BI

ODsay BI ↓ 다운로드

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

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

활용예시

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

powered by www.ODsay.com ↓ 다운로드 powered by www.ODsay.com 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 상표도 사용할 수 없습니다.