api 서비스 명세서 - koscom · 2017-11-15 · api 서비스 명세서 페이지 1 변 경 이...
TRANSCRIPT
[BC 카드]
API 서비스 명세서 코스콤 오픈 API 플랫폼 - BC 카드 업종정보 API
API 서비스 명세서
페이지 1
변 경 이 력
버전 날짜 내용 작성자
0.1 2017.11.13 BC카드 업종정보 API 명세서 초안
API 서비스 명세서
페이지 2
목 차
I. API 명세서 개요 .................................................................................................................................................................................................................................................... 4
II. API 목록 .................................................................................................................................................................................................................................................................... 4
III. API 명세서 명세서 ............................................................................................................................................................................................................................................... 5
1. { /businesstype/v1.0/index }.......................................................................................................................................................................................................................... 5
1.1 API 개요 ........................................................................................................................................................................................................................................................ 5
1.2 리소스 목록 ................................................................................................................................................................................................................................................. 5
1.3 리소스 명세 ................................................................................................................................................................................................................................................. 6
1.4 예시............................................................................................................................................................................................................................................................... 13
2. { /businesstype/v1.0/code }........................................................................................................................................................................................................................ 17
2.1 API 개요 ..................................................................................................................................................................................................................................................... 17
2.2 리소스 목록 .............................................................................................................................................................................................................................................. 18
2.3 리소스 명세 .............................................................................................................................................................................................................................................. 18
2.4 예시............................................................................................................................................................................................................................................................... 22
3. { /zscore/v1.0/index } .................................................................................................................................................................................................................................... 25
3.1 API 개요 ..................................................................................................................................................................................................................................................... 25
API 서비스 명세서
페이지 3
3.2 리소스 목록 .............................................................................................................................................................................................................................................. 27
3.3 리소스 명세 .............................................................................................................................................................................................................................................. 27
3.4 예시............................................................................................................................................................................................................................................................... 35
IV. 응답 처리 ........................................................................................................................................................................................................................................................... 39
API 서비스 명세서
페이지 4
I. API 명세서 개요
본 문서는 API 정의와 명세를 포함하며, 개발 목적으로 활용함.
II. API 목록
순번 API ID API 명 (영문) API 명 (한글)
1 businesstype/v1.0/index business type index v1.0 업종 지수 v1.0
2 businesstype/v1.0/code business type code v1.0 업종 코드 v1.0
3 zscore/v1.0/index zscore index v1.0 ZScore 지수 v1.0
API 서비스 명세서
페이지 5
III. API 명세서 명세서
1. { /businesstype/v1.0/index }
1.1 API 개요
API
정보
API ID /businesstype/v1.0/index
API 명(국문) 업종 지수 v1.0
API 명(영문) business type index v1.0
API 설명 국내 카드 가맹점들의 업종별/월별 매출 및 거래 건수에 대한 지수 정보
API 보안 API 인증/권한 [O] API Key
API URL 개발환경 (URL) https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/index
* 샌드박스는 개발을 위한 일부 과거 데이터만 제공 합니다. (최신 데이터 사용을 위해서는 별도의 계약이 필요 합니다.)
1.2 리소스 목록
일련
번호
리소스
이름
메서드
(method) API 리소스 설명
1 /businesstype/v1.0/index GET 전체 업종 지수 리스트 제공(기본 최대 200건)
API 서비스 명세서
페이지 6
2 /businesstype/v1.0/index/{code} GET 특정 업종 코드의 지수 리스트 제공
3 /businesstype/v1.0/index/{code}/detail GET 특정 업종 코드의 지수 항목 제공
1.3 리소스 명세
A. /businesstype/v1.0/index
리소스 개요
리소스 번호 1 메서드 GET
리소스 유형 목록 조회 리소스이름 업종 지수 목록
URI /businesstype/v1.0/index
설명 업종 지수 리스트(기본 최대 200건) 제공
Query String 구성
항목 데이터 형 예시 설명
page INT page=0 페이지 번호 (0부터 시작)
size INT size=10 페이지 당 목록 수
search 특정 항목으로 검색, 각각의 검색항목은 ’ ,’ 기호로 구분
API 서비스 명세서
페이지 7
세부 항목 데이터 형 예 시 설명
idxYM String search= idxYM:201510
search= idxYM <201511
search= idxYM >201509
search= idxYM >201509, idxYM
<201511
• 특정 날짜로 목록 조회
• 사용 기호
: (equal) < (less than) > (greate than)
, (검색 항목 구분)
sort
날짜 기준으로 정렬
세부 항목 데이터 형 예 시 설명
idxYM String sort= idxYM:asc
sort= idxYM:desc
• 특정 날짜로 목록 정렬
• 사용 기호
: (equal)
전문구성
응답전문
순번 항목명 데이터형 설명
1 content
List 항목 목록 리스트
서브 항목 데이터형 설명
idxYM STRING 기준년월 (YYYYMM)
tpBuzCode STRING 업종코드
amtIdx STRING 코스콤 금액 지수
cntIdx STRING 코스콤 건수 지수
2 sort - sort 정보
API 서비스 명세서
페이지 8
3 numberOfElements INT 조회된 항목(content) 건수
4 totalPages INT 전체 페이지 개수
5 first BOOLEAN 첫 페이지 여부 (true, false)
6 last BOOLEAN 마지막 페이지 여부 (true, false)
7 size INT 요청한 목록 개수
8 number INT 조회 페이지 순번 (0 부터 시작)
B. /businesstype/v1.0/index/{code}
리소스 개요
리소스 번호 2 메서드 GET
리소스 유형 목록 조회 리소스이름 코드별 업종 지수 목록
URI /businesstype/v1.0/index/{code}
설명 • 코드별 업종 지수 리스트(기본 최대 200건) 제공
• {code} 는 업종을 식별하는 ID 이다.
Query String 구성
항목 데이터 형 예시 설명
page INT page=0 페이지 번호 (0부터 시작)
API 서비스 명세서
페이지 9
size INT size=10 페이지 당 목록 수
search
특정 항목으로 검색, 각각의 검색항목은 , 기호로 구분
세부 항목 데이터 형 예 시 설명
idxYM String search= idxYM:201510
search= idxYM <201511
search= idxYM >201519
search= idxYM >201509, idxYM
<201511
• 특정 날짜로 목록 조회
• 사용 기호
: (equal) < (less than) > (greate than)
, (검색 항목 구분)
전문구성
응답전문
순번 항목명 데이터형 설명
1 content
List 항목 목록 리스트
서브 항목 데이터형 설명
idxYM STRING 기준년월 (YYYYMM)
tpBuzCode STRING 업종코드
amtIdx STRING 코스콤 금액 지수
cntIdx STRING 코스콤 건수 지수
2 sort - sort 정보
3 numberOfElements INT 조회된 항목(content) 건수
4 totalPages INT 전체 페이지 개수
5 first BOOLEAN 첫 페이지 여부 (true, false)
API 서비스 명세서
페이지 10
6 last BOOLEAN 마지막 페이지 여부 (true, false)
7 size INT 요청한 목록 개수
8 number INT 조회 페이지 순번 (0 부터 시작)
C. /businesstype/v1.0/index/{code}/detail
리소스 개요
리소스 번호 3 메서드 GET
리소스 유형 상세 조회 리소스이름 업종 지수 상세
URI /businesstype/v1.0/index/{code}/detail
설명 • 코드별 업종 지수 상세
• {code} 는 업종을 식별하는 ID 이다.
Query String 구성
항목 데이터 형 예시 설명
search
특정 항목으로 검색, 각각의 검색항목은 , 기호로 구분
세부 항목 데이터 형 예 시 설명
idxYM String search= idxYM:201510
search= idxYM <201511
search= idxYM >201509
• 특정 날짜로 목록 조회
• 사용 기호
: (equal) < (less than) > (greate than)
API 서비스 명세서
페이지 11
search= idxYM >201509, idxYM
<201511
, (검색 항목 구분)
전문구성
응답전문
순번 항목명 데이터형 설명
1 idxYM STRING 기준년월 (YYYYMM)
2 tpBuzCode STRING 업종코드
3 amtIdx STRING 코스콤 금액 지수
4 cntIdx STRING 코스콤 건수 지수
1.4 예시
• BC카드가 제공하는 2015년 11월 전체 업종지수 정보 조회
요청 예시
GET https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/index?search=idxYM:201511
Accept: application/json;charset=UTF-8
응답 예시
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
API 서비스 명세서
페이지 12
Content-Length: 44174
Date: Thu, 13 Jul 2017 07:30:38 GMT
{
"sort": [
{
"direction": "DESC",
"property": "idxYM",
"ignoreCase": false,
"nullHandling": "NATIVE",
"descending": true,
"ascending": false
}
],
"totalPages": 2,
"totalElements": 270,
"numberOfElements": 200,
"last": false,
"first": true,
"size": 200,
"content": [
{
"idxYM": "201511",
"tpBuzCode": "1001",
"amtIdx": "75.36",
API 서비스 명세서
페이지 13
"cntIdx": "73.62"
},
{
"idxYM": "201511",
"tpBuzCode": "1002",
"amtIdx": "83.85",
"cntIdx": "86"
},
.
.
.
{
"idxYM": "201511",
"tpBuzCode": "8006",
"amtIdx": "95.35",
"cntIdx": "111.8"
},
{
"idxYM": "201511",
"tpBuzCode": "8010",
"amtIdx": "57.66",
"cntIdx": "62.48"
},
API 서비스 명세서
페이지 14
{
"idxYM": "201511",
"tpBuzCode": "8013",
"amtIdx": "72.41",
"cntIdx": "74.98"
}
],
"number": 0
}
API 서비스 명세서
페이지 15
2. { /businesstype/v1.0/code }
2.1 API 개요
API
정보
API ID /businesstype/v1.0/code
API 명(국문) 업종 코드 v1.0
API 명(영문) business type code v1.0
API 설명 BC카드의 가맹점을 통해 분류한 업종 약 270개 업종 코드 및 업종 명 조회
API
보안 API 인증/권한 [O] API Key
API
URL
개발환경 (URL) https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/code
운영환경 (URL) https://apigw.koscom.co.kr/bccard/businesstype/v1.0/code
2.2 리소스 목록
일련 번호 리소스 이름 메서드
(method) API 리소스 설명
1 /businesstype/v1.0/code GET 전체 업종 코드 리스트 제공(기본 최대 200건)
2 /businesstype/v1.0/code/{code} GET 특정 업종 코드 상세 정보 제공
API 서비스 명세서
페이지 16
2.3 리소스 명세
A. /businesstype/v1.0/code
리소스 개요
리소스 번호 1 메서드 GET
리소스 유형 목록 조회 리소스이름 업종 코드 목록
URI /businesstype/v1.0/code
설명 BC카드의 가맹점으로 분류한 업종 코드 및 업종 명 리스트(기본 최대 200건)
Query String 구성
항목 데이터 형 예시 설명
page INT page=0 페이지 번호 (0부터 시작)
size INT size=10 페이지 당 목록 수
search
특정 항목으로 검색, 각각의 검색항목은 , 기호로 구분
세부 항목 데이터 형 예시 설명
tpBuzNm STRING search=tpBuzNm:주점 • 특정 업종명으로 목록 조회
• 기호
: (equal)
API 서비스 명세서
페이지 17
, (검색 항목 구분)
전문구성
응답전문
순번 항목명 데이터형 설명
1 content
List 항목 목록 리스트
서브 항목 데이터형 설명
tpBuzCode STRING 업종코드
tpBuzNm STRING 업종명
2 sort - sort 정보
3 numberOfElements INT 조회된 항목(content) 건수
4 totalPages INT 전체 페이지 개수
5 first BOOLEAN 첫 페이지 여부 (true, false)
6 last BOOLEAN 마지막 페이지 여부 (true, false)
7 size INT 요청한 목록 개수
8 number INT 조회 페이지 순번 (0 부터 시작)
B. /businesstype/v1.0/code/{code}
리소스 개요
API 서비스 명세서
페이지 18
리소스 번호 2 메서드 GET
리소스 유형 상세 조회 리소스이름 업종 코드 목록
URI /businesstype/v1.0/code/{code}
설명 • BC카드의 가맹점으로 분류한 업종 코드 및 업종 명 상세 정보 제공
• {code} 는 업종을 식별하는 ID 이다.
Query String 구성
항목 데이터 형 예시 설명
전문구성
응답전문
순번 항목명 데이터형 설명
1 tpBuzCode STRING 업종코드
2 tpBuzNm STRING 업종명
API 서비스 명세서
페이지 19
2.4 예시
• BC카드가 제공하는 약270개의 업종 분류 코드 및 업종 명을 제공 (현재 : 201711)
요청 예시
GET https://sandbox-apigw.koscom.co.kr/bccard/businesstype/v1.0/code
Accept: application/json;charset=UTF-8
응답 예시
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 44174
Date: Thu, 13 Jul 2017 07:30:38 GMT
{
"sort": [
{
"direction": "ASC",
"property": "TP_BUZ_CODE",
"ignoreCase": false,
"nullHandling": "NATIVE",
"descending": false,
"ascending": true
}
API 서비스 명세서
페이지 20
],
"totalPages": 2,
"totalElements": 270,
"numberOfElements": 200,
"last": false,
"first": true,
"size": 200,
"content": [
{
"tpBuzCode": "1001",
"tpBuzNm": "특급 호텔"
},
{
"tpBuzCode": "1002",
"tpBuzNm": "1급 호텔"
},
{
"tpBuzCode": "1003",
"tpBuzNm": "2급 호텔"
},
{
"tpBuzCode": "1010",
"tpBuzNm": "콘 도"
},
.
API 서비스 명세서
페이지 21
.
.
{
"tpBuzCode": "8010",
"tpBuzNm": "칵테일바"
},
{
"tpBuzCode": "8013",
"tpBuzNm": "주점"
}
],
"number": 0
}
3. { /zscore/v1.0/index }
3.1 API 개요
API
정보
API ID /zscore/v1.0/index
API 명(국문) ZScore 지수 v1.0
API 명(영문) zscore index v1.0.
API 설명 • 카드 빅데이터를 기반으로 상장종목의 월별 매출 추세를 추산해 지수 정보 제공
• 국제코드 종목의 작업기준년월, 가맹점명, 국제종목코드, Z스코어를 조회하는 API
API 서비스 명세서
페이지 22
• BC카드가 표준화한 z값만 제공하며, 평균/표준편차는 공개되지 않음
API 보안 API 인증/권한 [O] API Key
API URL 개발환경 (URL) https://sandbox-apigw.koscom.co.kr/bccard/zscore/v1.0/index
* 샌드박스는 개발을 위한 일부 과거 데이터만 제공 합니다. (최신 데이터 사용을 위해서는 별도의 계약이 필요 합니다.)
3.2 리소스 목록
일련 번호 리소스 이름 메서드
(method) API 리소스 설명
1 /zscore/v1.0/index GET 전체 ZScore 리스트 제공(기본 최대 200건)
2 /zscore/v1.0/index/{code} GET 특정 ZScore 코드 정보 제공
3.3 리소스 명세
A. /zscore/v1.0/index
리소스 개요
리소스 번호 1 메서드 GET
리소스 유형 목록조회 리소스이름 ZScore 목록 조회
URI /zscore/v1.0/index
API 서비스 명세서
페이지 23
설명 ZScore 리스트(기본 최대 200건) 정보 제공
Query String 구성
항목 데이터 형 예시 설명
page INT page=0 페이지 번호 (0부터 시작)
size INT size=10 페이지 당 목록 수
search
특정 항목으로 검색, 각각의 검색항목은 , 기호로 구분
세부 항목 데이터 형 예시 설명
regYm STRING
search=idxYM:201503
search=idxYM<201506
search=idxYM>201503
search=idxYM>201503, idxYM<201506
- 등록년월 기준으로 목록 조회
- 기호
: (equal)
< (less than)
> (greate than)
, (검색 항목 구분)
merNm STRING search=merNm:경동가스
- 가맹점명 기준으로 목록 조회
- 기호
: (equal)
API 서비스 명세서
페이지 24
전문구성
응답전문
순번 항목명 데이터형 설명
1 content
List 항목 목록 리스트
서브 항목 데이터형 설명
merNm STRING 가맹점명
koscomTckr STRING 국제표준 (종목코드)
intlTckr STRING 주식종목코드 (단축코드)
2 sort - sort 정보
3 numberOfElements INT 조회된 항목(content) 건수
4 totalPages INT 전체 페이지 개수
5 first BOOLEAN 첫 페이지 여부 (true, false)
6 last BOOLEAN 마지막 페이지 여부 (true, false)
7 size INT 요청한 목록 개수
8 number INT 조회 페이지 순번 (0 부터 시작)
B. /zscore/v1.0/index/{code}
리소스 개요
리소스 번호 2 메서드 GET
리소스 유형 상세 리소스이름 ZScore 상세
API 서비스 명세서
페이지 25
URI /zscore/v1.0/index
설명 종목코드별 ZScore 상세 정보 제공
Query String 구성
항목 데이터 형 예시 설명
search
특정 항목으로 검색, 각각의 검색항목은 , 기호로 구분
세부 항목 데이터 형 예시 설명
idxYm STRING
search=idxYM:201503
search=idxYM<201506
search=idxYM >201503
search=idxYM>201503,idxYM<201506
- 등록년월 기준으로 목록 조회
- 기호
: (equal)
< (less than)
> (greate than)
, (검색 항목 구분)
merNm STRING search=merNm:경동가스
- 가맹점명 기준으로 목록 조회
- 기호
: (equal)
전문구성
API 서비스 명세서
페이지 26
응답전문
순번 항목명 데이터형 설명
1 merNm String 가맹점 명
2 koscomTckr String 국제표준 (종목코드)
3 intlTckr String 주식종목코드 (단축코드)
4 idxYm String 지수 기준월
5 zScore String Z-Score 값
API 서비스 명세서
페이지 27
3.4 예시
A. /zscore/v1.0/index
• BC카드가 zScore를 산출하는 약 95개 종목에 대한 종목정보 조회 (현재 : 201711)
요청 예시
GET https://sandbox-apigw.koscom.co.kr/bccard/ zscore/v1.0/index
Accept: application/json;charset=UTF-8
응답 예시
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 44174
Date: Thu, 13 Jul 2017 07:30:38 GMT
{
"sort": [
{
"direction": "ASC",
"property": "INTL_TCKR",
"ignoreCase": false,
"nullHandling": "NATIVE",
"descending": false,
"ascending": true
API 서비스 명세서
페이지 28
}
],
"totalPages": 1,
"totalElements": 95,
"numberOfElements": 95,
"last": true,
"first": true,
"size": 200,
"content": [
{
"merNm": "메리츠화재",
"koscomTckr": "KR7000060004",
"intlTckr": "000060"
},
{
"merNm": "CJ대한통운",
"koscomTckr": "KR7000120006",
"intlTckr": "000120"
},
{
"merNm": "기아차",
"koscomTckr": "KR7000270009",
"intlTckr": "000270"
},
{
API 서비스 명세서
페이지 29
"merNm": "한화손해보험",
"koscomTckr": "KR7000370007",
"intlTckr": "000370"
},
{
"merNm": "삼화페인트",
"koscomTckr": "KR7000390005",
"intlTckr": "000390"
},
{
"merNm": "롯데손해보험",
"koscomTckr": "KR7000400002",
"intlTckr": "000400"
},
.
.
.
{
"merNm": "한국타이어",
"koscomTckr": "KR7161390000",
"intlTckr": "161390"
},
{
"merNm": "골프존",
"koscomTckr": "KR7215000001",
API 서비스 명세서
페이지 30
"intlTckr": "215000"
}
],
"number": 0
}
API 서비스 명세서
페이지 31
B. /zscore/v1.0/index/{code}
• 삼성전자의 월별 매출을 추정하여 산출한 zScore 조회
요청 예시
GET https://sandbox-apigw.koscom.co.kr/bccard/ zscore/v1.0/index/005930
Accept: application/json;charset=UTF-8
응답 예시
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 44174
Date: Thu, 13 Jul 2017 07:30:38 GMT
[
{
"merNm": "삼성전자",
"koscomTckr": "KR7005930003",
"intlTckr": "005930",
"idxYm": "201504",
"zScore": "0.433700352429091608995559325779713810457"
},
{
"merNm": "삼성전자",
"koscomTckr": "KR7005930003",
API 서비스 명세서
페이지 32
"intlTckr": "005930",
"idxYm": "201505",
"zScore": "0.5582539895105550366662095869092192641882"
},
{
"merNm": "삼성전자",
"koscomTckr": "KR7005930003",
"intlTckr": "005930",
"idxYm": "201506",
"zScore": "0.1315526673210397411042276131740144462468"
},
.
.
.
{
"merNm": "삼성전자",
"koscomTckr": "KR7005930003",
"intlTckr": "005930",
"idxYm": "201703",
"zScore": "-1.16219364316722097731611963051710195496"
}
]
API 서비스 명세서
페이지 33
IV. 응답 처리
• Header
Status Code Message Description
200 OK The request ha succeeded
201 Create The request has succeeded and a new resource has been created as a
result of it.
204 No Countent There is no content to send for this request.
400 Bad Request This response means that server could not understand the request due
to invalid syntax
401 Unauthorized Authentication is needed to get requested response.
403 Forbidden Client des not have access rights to the content so server is rejecting to
give proper response.
404 Not Found Server can not find requested resource.
405 Method Not Allowed The request method is known by the server but has been disabled and
can not be used.
500 Internal Server Error The server has encountered a situation it doesn’t know how to handle.
API 서비스 명세서
페이지 34
• BODY
항목 명 칭 예시
error 에러 코드 {
“error”: “invalid_request”,
“error_description”: “Validation error”,
“details”: “extra error messages”
}
error_description 에러 메시지
details 상세 메시지
- End of Document -