지식센터 / 레퍼런스

AIR™ Reporting API — BizSpring AIR™ API

# AIR™ Reporting API

리포트 데이터 획득

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

인증 토큰을 헤더(Header)에 담아 POST로 요청을 보내고, 요청 성공 시 응답 본문은 리포트 데이터를 포함한 JSON 객체를 반환합니다.

**POST /report/data

**HEADER

Content-Type: application/json

x-authorization: Bearer {AUTH TOKEN}

**-- 이하 생략 --

**

요청 URL (Endpoint)

https://growthplatform.ai/report/data

프로토콜

HTTPS

HTTP 메서드

POST

헤더

Request Body

Request Body를 JSON 형식으로 전달합니다.

> client\_seq는 AIR 에서 제공 중인 [\[AIR\] > \[API 쿼리 빌더\]](https://growthplatform.ai/front/1000/1001001) 사용 시 자동으로 입력됩니다.

>

> API 쿼리 빌더는 매체 데이터를 JSON으로 쉽게 만들고 조회(사용)한 데이터가 성공적으로 기록되었는지 확인할 수 있도록 BizSpring AIR™에서 제공하는 서비스입니다.

요청 형식

아래는 요청의 기본 형식 입니다.

**POST /report/data

**HEADER

Content-Type: application/json

x-authorization: BEARER {AUTH TOKEN}

**BODY

**{

"rpt_no": {REPORT_NO},

"client_seq": [{CLIENT_SEQ}],

"where":

[

{

"field":{FIELD},

"operation":{OPERATION},

"value":{VALUE}

},

{ ... },

{ ... }

]

"dim_cd": [{DIMENSION_CD}]

}

요청 예시

아래는 형식에 따라 임의 값을 부분적으로 제시한 예시입니다. (token 외 항목)

POST /report/data

HEADER

Content-Type: application/json

x-authorization: BEARER {AUTH TOKEN}

BODY

**{

** "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"

}

]

}

응답 데이터 항목

응답에 성공하면 JSON 형식으로 결과값이 반환됩니다.

응답 예

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
}
]
}

오류 코드

[^1]: 인증 토큰

자주 묻는 질문

리포트 데이터를 요청할 때 어떤 방식으로 인증하나요?

헤더의 x-authorization 필드에 Bearer {AUTH TOKEN} 형식으로 인증 토큰을 담아 전달합니다. Content-Type은 application/json으로 고정해야 합니다.

Request Body에 필수로 넣어야 하는 값은 무엇인가요?

rpt_no(리포트 번호)와 client_seq(사이트 그룹 고유 식별 번호)는 필수 항목입니다. where와 dim_cd는 조건절 및 분석차원을 지정할 때 사용합니다.

client_seq 값은 어떻게 알아내나요?

AIR에서 제공하는 API 쿼리 빌더를 사용하면 client_seq가 자동으로 입력됩니다. 이 도구는 매체 데이터를 JSON으로 쉽게 만들고 조회 데이터가 성공적으로 기록되었는지 확인할 수 있게 해줍니다.

응답으로 어떤 지표들을 받을 수 있나요?

노출수(m_impr), 클릭수(m_click), 광고비(m_cost), 전환수(m_conv), 매출액(m_rvn), ROAS(roas) 등 매체 제공 지표와 사용자 정의 전환지표(g1~g10)를 받을 수 있습니다.

요청이 너무 많으면 어떻게 되나요?

분당 60회를 초과하면 429 상태코드와 함께 RATE_LIMIT_EXCEEDED 오류가 반환됩니다.

다른 표현: Markdown · JSON · 최종 갱신 2026-09-03