# AIR™ Reporting API — BizSpring AIR™ API

>  description: BizSpring AIR™ API 의 리포팅 데이터 획득 API를 설명합니다. AIR™ Reporting API 리포트 데이터 획득 BizSpring AIR™ 리포트의 분석 차원 데이터를 불러옵니다.& x20; 인증 토큰을 헤더(Header)에 담아 POST로 

## 핵심 요약


---
description: BizSpring AIR™ API 의 리포팅 데이터 획득 API를 설명합니다.
---

# AIR™ Reporting API

## 리포트 데이터  획득

BizSpring AIR™ 리포트의 분석 차원 데이터를 불러옵니다.&#x20;

인증 토큰을 헤더(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)

```http
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
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]: 인증 토큰


## FAQ


---
출처: https://bizspring.ai/kb/ref/manual/bizspring-air-api-air-reporting-api · 최종 갱신 2026-08-23T14:32:38.444294+00:00
