AIR™ Reporting API — BizSpring AIR™ API
핵심 요약
---
description: BizSpring AIR™ API 의 리포팅 데이터 획득 API를 설명합니다.
---
# AIR™ Reporting API
리포트 데이터 획득
BizSpring AIR™ 리포트의 분석 차원 데이터를 불러옵니다. 
인증 토큰을 헤더(Header)에 담아 POST로 요청을 보내고, 요청 성공 시 응답 본문은 리포트 데이터를 포함한 JSON 객체를 반환합니다.
<pre class="language-http"><code class="lang-http"><strong>POST /report/data
</strong>HEADER
Content-Type: application/json
x-authorization: <a data-footnote-ref href="#user-content-fn-1">Bearer {AUTH TOKEN}</a>
<strong>-- 이하 생략 --
</strong></code></pre>
요청 URL (Endpoint)
https://growthplatform.ai/report/data프로토콜
HTTPS
HTTP 메서드
POST
헤더
<table><thead><tr><th width="173">필드</th><th>설명</th></tr></thead><tbody><tr><td>Content-type</td><td>요청 데이터 타입. application/json 으로 고정</td></tr><tr><td>x-authorization</td><td>사용자 인증 수단, 인증 토큰. Bearer <a data-footnote-ref href="#user-content-fn-1">{</a><a data-footnote-ref href="#user-content-fn-1">AUTH TOKEN</a>}</td></tr></tbody></table>
Request Body
Request Body를 JSON 형식으로 전달합니다.
<table><thead><tr><th width="115" align="center">키</th><th width="94" align="center">타입</th><th>설명</th></tr></thead><tbody><tr><td align="center"><a href="air-tm-reporting-api/rpt_no">rpt_no</a>*</td><td align="center">string</td><td><p>BizSpring AIR™ 리포트 번호를 의미합니다.</p><ul><li>예) 1000000 : 광고매체리포트</li></ul></td></tr><tr><td align="center"><a href="air-tm-reporting-api/client_seq">client_seq</a>*</td><td align="center">array</td><td>사이트 그룹 (광고주) 고유 식별 번호를 의미합니다. </td></tr><tr><td align="center"><a href="air-tm-reporting-api/where">where</a></td><td align="center">array</td><td><p>특정 조건을 기준으로 하기 위한 조건절을 의미합니다.</p><ul><li><code>stat_date</code></li><li><code>media_no</code></li><li><code>ad_type</code></li><li><code>ad_provider</code></li><li><code>ad_platform</code></li><li><code>ad_program</code></li><li><code>device</code></li><li>campaign</li><li><code>adgroup</code></li><li><code>keyword</code></li><li><code>report_type</code></li></ul><p></p><p>항목별 스펙 참고 : <a data-mention href="air-tm-reporting-api/where">where</a></p></td></tr><tr><td align="center"><a href="air-tm-reporting-api/dim_cd">dim_cd</a></td><td align="center">array</td><td><p>AIR 리포트에서 사용하는 분석차원을 의미합니다.</p><ul><li><code>by_month</code></li><li><code>by_week</code></li><li><code>by_day</code></li><li><code>by_wday</code></li><li><code>media_no</code></li><li><code>ad_type</code></li><li><code>ad_provider</code></li><li><code>ad_platform</code></li><li><code>ad_program</code></li><li><code>campaign</code></li><li><code>adgroup</code></li><li><code>creative</code></li><li><code>keyword</code></li></ul><p>항목별 스펙 참고 : <a data-mention href="air-tm-reporting-api/dim_cd">dim_cd</a></p></td></tr></tbody></table>
{% hint style="info" %}
client\_seq는 AIR 에서 제공 중인 [\[AIR\] > \[API 쿼리 빌더\]](https://growthplatform.ai/front/1000/1001001) 사용 시 자동으로 입력됩니다.
API 쿼리 빌더는 매체 데이터를 JSON으로 쉽게 만들고 조회(사용)한 데이터가 성공적으로 기록되었는지 확인할 수 있도록 BizSpring AIR™에서 제공하는 서비스입니다.
{% endhint %}
요청 형식
아래는 요청의 기본 형식 입니다.
<pre class="language-http"><code class="lang-http"><strong>POST /report/data
</strong>HEADER
Content-Type: application/json
x-authorization: BEARER {AUTH TOKEN}
<strong>BODY
</strong>{
"rpt_no": {REPORT_NO},
"client_seq": [{CLIENT_SEQ}],
"where":
[
{
"field":{FIELD},
"operation":{OPERATION},
"value":{VALUE}
},
{ ... },
{ ... }
]
"dim_cd": [{DIMENSION_CD}]
}
</code></pre>
요청 예시
아래는 형식에 따라 임의 값을 부분적으로 제시한 예시입니다. (token 외 항목)
<pre class="language-http"><code class="lang-http">POST /report/data
HEADER
Content-Type: application/json
x-authorization: BEARER {AUTH TOKEN}
BODY
<strong>{
</strong> "rpt_no":"1000000",
"client_seq":["105580"],
"dim_cd":["by_day"]
"where":
[
{
"field":"stat_date",
"operation":"between",
"value":["2024-05-01","2024-05-08"]
},
{
"field":"ad_provider",
"operation":"in",
"value":["네이버"]
},
{
"field":"report_type",
"operation":"equal",
"value":"stat"
}
]
}
</code></pre>
응답 데이터 항목 <a href="#metric" id="metric"></a>
응답에 성공하면 JSON 형식으로 결과값이 반환됩니다.
<table><thead><tr><th width="147" align="center">키</th><th width="120" align="center">타입</th><th>설명</th></tr></thead><tbody><tr><td align="center">m_impr</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>노출수</strong></mark>를 의미합니다.</td></tr><tr><td align="center">m_click</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>클릭수</strong></mark>를 의미합니다.</td></tr><tr><td align="center">m_cost</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>광고비</strong></mark>를 의미합니다.</td></tr><tr><td align="center">m_rgr</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>가입수</strong></mark>를 의미합니다.</td></tr><tr><td align="center">m_odr</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>주문율</strong></mark>을 의미합니다.</td></tr><tr><td align="center">m_cart</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>장바구니수</strong></mark>를 의미합니다.</td></tr><tr><td align="center">m_conv</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>전환수</strong></mark>를 의미합니다.</td></tr><tr><td align="center">m_rvn</td><td align="center">double</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>매출액</strong></mark>을 의미합니다.</td></tr><tr><td align="center">m_cpc</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>클릭당 비용</strong></mark>을 의미합니다.</td></tr><tr><td align="center">m_ctr </td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>클릭률</strong></mark>을 의미합니다.</td></tr><tr><td align="center">m_crt</td><td align="center">double</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>전환률</strong></mark>을 의미합니다.</td></tr><tr><td align="center">m_roas</td><td align="center">int</td><td>매체사에서 제공하는 <mark style="background-color:yellow;"><strong>광고 대비 수익률</strong></mark>을 의미합니다.</td></tr><tr><td align="center">land </td><td align="center">int</td><td>랜딩페이지를 의미합니다.</td></tr><tr><td align="center">rgr </td><td align="center">int</td><td>전환율을 의미합니다.</td></tr><tr><td align="center">odr </td><td align="center">int</td><td>주문율을 의미합니다.</td></tr><tr><td align="center">rvn </td><td align="center">int</td><td>매출액을 의미합니다.</td></tr><tr><td align="center">g1 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g2 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g3 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g4</td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g5 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g6 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g7 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g8 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g9 </td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">g10</td><td align="center">double</td><td>사용자가 정의한 전환지표를 의미합니다.<br>* 사용자 전환지표는 최대 10개까지 사용가능합니다.</td></tr><tr><td align="center">rvn_per_odr </td><td align="center">double</td><td>주문당 매출액을 의미합니다.</td></tr><tr><td align="center">rgr_per_m_click </td><td align="center">double</td><td>매체사에서 제공하는 클릭당 전환율을 의미합니다.</td></tr><tr><td align="center">odr_per_m_cost</td><td align="center">double</td><td>매체사에서 제공하는 광고비당 주문율을 의미합니다.</td></tr><tr><td align="center">roas</td><td align="center">double</td><td>광고비 대비 발생하는 수익률을 의미합니다.</td></tr></tbody></table>
응답 예
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"data": [
{
"stat_date": "2024-05-01",
"m_impr": 9657.0,
"m_click": 486.0,
"m_cost": 172000.0,
"m_rgr": 0.0,
"m_odr": 18.0,
"m_cart": 0.0,
"m_conv": 65.0,
"m_rvn": 180.0,
"m_cpc": 353.90946502057614,
"m_ctr": 0.05032618825722274,
"m_crt": 0.1337448559670782,
"m_roas": 0.0010465116279069768,
"land": 3.0,
"rgr": 0.0,
"odr": 18.0,
"rvn": 0.0,
"g1": 5.0,
"g2": 66.0,
"g3": 0.25684913,
"g4": 23.0,
"g5": 7.0,
"g6": 55.0,
"g7": 0.3568791032652,
"g8": 0.1235698456331,
"g9": 11.0,
"g10": 2.0,
"rvn_per_odr": 10.0,
"rgr_per_m_click": 0.0,
"odr_per_m_cost": 9555.5555556,
"roas": 0.00104651162791
},
{
"stat_date": "2024-05-02",
"m_impr": 15200,
"m_click": 11,
"m_cost": 9850,
......
"odr_per_m_cost": 0,
"roas": 0
}
]
}오류 코드
| HTTP | 오류 코드 | 설명 |
|---|---|---|
| 400 | INVALID\_PARAMETER | 파라미터 오류 |
| 401 | UNAUTHORIZED | 토큰 오류/만료 |
| 403 | FORBIDDEN | 접근 권한 없음 |
| 429 | RATE\_LIMIT\_EXCEEDED | 분당 60회 초과 |
| 500 | INTERNAL\_SERVER\_ERROR | 서버 오류 |
[^1]: 인증 토큰