> For the complete documentation index, see [llms.txt](https://docs.bizspring.co.kr/bizspring-air-tm-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bizspring.co.kr/bizspring-air-tm-api/bizspring-air-tm-api-spec./air-tm-reporting-api.md). # AIR™ Reporting API ## 리포트 데이터 획득 BizSpring AIR™ 리포트의 분석 차원 데이터를 불러옵니다. 인증 토큰을 헤더(Header)에 담아 POST로 요청을 보내고, 요청 성공 시 응답 본문은 리포트 데이터를 포함한 JSON 객체를 반환합니다.

POST /report/data
HEADER
Content-Type: application/json
x-authorization: Bearer {AUTH TOKEN}

-- 이하 생략 --

### 요청 URL (Endpoint) ```http https://growthplatform.ai/report/data ``` ### 프로토콜 HTTPS ### **HTTP 메서드** POST ### 헤더

필드	설명
Content-type	요청 데이터 타입. application/json 으로 고정
x-authorization	사용자 인증 수단, 인증 토큰. Bearer {AUTH TOKEN}

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

키	타입	설명
rpt_no*	string	BizSpring AIR™ 리포트 번호를 의미합니다. 예) 1000000 : 광고매체리포트
client_seq*	array	사이트 그룹 (광고주) 고유 식별 번호를 의미합니다.
where	array	특정 조건을 기준으로 하기 위한 조건절을 의미합니다. `stat_date` `media_no` `ad_type` `ad_provider` `ad_platform` `ad_program` `device` campaign `adgroup` `keyword` `report_type` 항목별 스펙 참고 : /pages/debbzzZVi46K0b0UUana
dim_cd	array	AIR 리포트에서 사용하는 분석차원을 의미합니다. `by_month` `by_week` `by_day` `by_wday` `media_no` `ad_type` `ad_provider` `ad_platform` `ad_program` `campaign` `adgroup` `creative` `keyword` 항목별 스펙 참고 : /pages/htQB9NnC8g4kbD3HOPqW

{% hint style="info" %} client\_seq는 AIR 에서 제공 중인 [\[AIR\] > \[API 쿼리 빌더\]](https://growthplatform.ai/front/1000/1001001) 사용 시 자동으로 입력됩니다. **API 쿼리 빌더**는 매체 데이터를 JSON으로 쉽게 만들고 조회(사용)한 데이터가 성공적으로 기록되었는지 확인할 수 있도록 BizSpring AIR™에서 제공하는 서비스입니다. {% endhint %} ### 요청 형식 아래는 요청의 기본 형식 입니다.

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 형식으로 결과값이 반환됩니다.

키	타입	설명
m_impr	int	매체사에서 제공하는 노출수를 의미합니다.
m_click	int	매체사에서 제공하는 클릭수를 의미합니다.
m_cost	int	매체사에서 제공하는 광고비를 의미합니다.
m_rgr	int	매체사에서 제공하는 가입수를 의미합니다.
m_odr	int	매체사에서 제공하는 주문율을 의미합니다.
m_cart	int	매체사에서 제공하는 장바구니수를 의미합니다.
m_conv	int	매체사에서 제공하는 전환수를 의미합니다.
m_rvn	double	매체사에서 제공하는 매출액을 의미합니다.
m_cpc	int	매체사에서 제공하는 클릭당 비용을 의미합니다.
m_ctr	int	매체사에서 제공하는 클릭률을 의미합니다.
m_crt	double	매체사에서 제공하는 전환률을 의미합니다.
m_roas	int	매체사에서 제공하는 광고 대비 수익률을 의미합니다.
land	int	랜딩페이지를 의미합니다.
rgr	int	전환율을 의미합니다.
odr	int	주문율을 의미합니다.
rvn	int	매출액을 의미합니다.
g1	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g2	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g3	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g4	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g5	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g6	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g7	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g8	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g9	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
g10	double	사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다.
rvn_per_odr	double	주문당 매출액을 의미합니다.
rgr_per_m_click	double	매체사에서 제공하는 클릭당 전환율을 의미합니다.
odr_per_m_cost	double	매체사에서 제공하는 광고비당 주문율을 의미합니다.
roas	double	광고비 대비 발생하는 수익률을 의미합니다.

### 응답 예 ```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]: 인증 토큰 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bizspring.co.kr/bizspring-air-tm-api/bizspring-air-tm-api-spec./air-tm-reporting-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.