{
  "slug": "ref/manual/bizspring-air-api-air-reporting-api",
  "doc_type": "ref",
  "title": "AIR™ Reporting API — BizSpring AIR™ API",
  "title_en": null,
  "one_liner": "BizSpring AIR™ API 의 리포팅 데이터 획득 API를 설명합니다. AIR™ Reporting API 리포트 데이터 획득 BizSpring AIR™ 리포트의 분석 차원 데이터를 불러옵니다. 인증 토큰을 헤더(Header)에 담아 POST로",
  "summary_bullets": [
    "AIR™ Reporting API는 BizSpring AIR™ 리포트의 분석 차원 데이터를 조회하는 POST 방식 API입니다.",
    "헤더에 Content-Type과 x-authorization(Bearer 인증 토큰)을 담아 요청하며, Body에는 rpt_no, client_seq, where, dim_cd를 JSON으로 전달합니다.",
    "client_seq는 AIR의 API 쿼리 빌더 사용 시 자동으로 입력되며, 이 도구로 JSON 생성과 조회 데이터 기록 확인이 가능합니다.",
    "응답 데이터는 노출수, 클릭수, 광고비, 전환수, 매출액, ROAS 등 다양한 매체 지표와 사용자 정의 전환지표(g1~g10, 최대 10개)를 포함한 JSON으로 반환됩니다.",
    "오류 발생 시 400, 401, 403, 429, 500 등의 HTTP 상태코드와 오류 코드로 원인을 구분할 수 있습니다."
  ],
  "body_md": "# AIR™ Reporting API\n\n## 리포트 데이터 획득\n\nBizSpring AIR™ 리포트의 분석 차원 데이터를 불러옵니다.\n\n인증 토큰을 헤더(Header)에 담아 POST로 요청을 보내고, 요청 성공 시 응답 본문은 리포트 데이터를 포함한 JSON 객체를 반환합니다.\n\n**POST /report/data\n**HEADER\nContent-Type: application/json\nx-authorization: Bearer {AUTH TOKEN}\n\n**-- 이하 생략 --\n**\n\n### 요청 URL (Endpoint)\n\n```http\nhttps://growthplatform.ai/report/data\n```\n\n### 프로토콜\n\nHTTPS\n\n### **HTTP 메서드**\n\nPOST\n\n### 헤더\n\n| 필드 | 설명 |\n| --- | --- |\n| Content-type | 요청 데이터 타입. application/json 으로 고정 |\n| x-authorization | 사용자 인증 수단, 인증 토큰. Bearer {AUTH TOKEN} |\n\n### Request Body\n\nRequest Body를 JSON 형식으로 전달합니다.\n\n| 키 | 타입 | 설명 |\n| --- | --- | --- |\n| rpt_no* | string | BizSpring AIR™ 리포트 번호를 의미합니다. 예) 1000000 : 광고매체리포트 |\n| client_seq* | array | 사이트 그룹 (광고주) 고유 식별 번호를 의미합니다. |\n| where | array | 특정 조건을 기준으로 하기 위한 조건절을 의미합니다. stat_date media_no ad_type ad_provider ad_platform ad_program device campaign adgroup keyword report_type 항목별 스펙 참고 : where |\n| 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 항목별 스펙 참고 : dim_cd |\n\n> client\\_seq는 AIR 에서 제공 중인 [\\[AIR\\] > \\[API 쿼리 빌더\\]](https://growthplatform.ai/front/1000/1001001) 사용 시 자동으로 입력됩니다.\n>\n> **API 쿼리 빌더**는 매체 데이터를 JSON으로 쉽게 만들고 조회(사용)한 데이터가 성공적으로 기록되었는지 확인할 수 있도록 BizSpring AIR™에서 제공하는 서비스입니다.\n\n### 요청 형식\n\n아래는 요청의 기본 형식 입니다.\n\n**POST /report/data\n**HEADER\nContent-Type: application/json\nx-authorization: BEARER {AUTH TOKEN}\n\n**BODY\n**{\n\"rpt_no\": {REPORT_NO},\n\"client_seq\": [{CLIENT_SEQ}],\n\"where\":\n[\n{\n\"field\":{FIELD},\n\"operation\":{OPERATION},\n\"value\":{VALUE}\n},\n{ ... },\n{ ... }\n]\n\"dim_cd\": [{DIMENSION_CD}]\n}\n\n### 요청 예시\n\n아래는 형식에 따라 임의 값을 부분적으로 제시한 예시입니다. (token 외 항목)\n\nPOST /report/data\nHEADER\nContent-Type: application/json\nx-authorization: BEARER {AUTH TOKEN}\n\nBODY\n**{\n** \"rpt_no\":\"1000000\",\n\"client_seq\":[\"105580\"],\n\"dim_cd\":[\"by_day\"]\n\"where\":\n[\n{\n\"field\":\"stat_date\",\n\"operation\":\"between\",\n\"value\":[\"2024-05-01\",\"2024-05-08\"]\n},\n{\n\"field\":\"ad_provider\",\n\"operation\":\"in\",\n\"value\":[\"네이버\"]\n},\n{\n\"field\":\"report_type\",\n\"operation\":\"equal\",\n\"value\":\"stat\"\n}\n]\n}\n\n### 응답 데이터 항목\n\n응답에 성공하면 JSON 형식으로 결과값이 반환됩니다.\n\n| 키 | 타입 | 설명 |\n| --- | --- | --- |\n| m_impr | int | 매체사에서 제공하는 **노출수** 를 의미합니다. |\n| m_click | int | 매체사에서 제공하는 **클릭수** 를 의미합니다. |\n| m_cost | int | 매체사에서 제공하는 **광고비** 를 의미합니다. |\n| m_rgr | int | 매체사에서 제공하는 **가입수** 를 의미합니다. |\n| m_odr | int | 매체사에서 제공하는 **주문율** 을 의미합니다. |\n| m_cart | int | 매체사에서 제공하는 **장바구니수** 를 의미합니다. |\n| m_conv | int | 매체사에서 제공하는 **전환수** 를 의미합니다. |\n| m_rvn | double | 매체사에서 제공하는 **매출액** 을 의미합니다. |\n| m_cpc | int | 매체사에서 제공하는 **클릭당 비용** 을 의미합니다. |\n| m_ctr | int | 매체사에서 제공하는 **클릭률** 을 의미합니다. |\n| m_crt | double | 매체사에서 제공하는 **전환률** 을 의미합니다. |\n| m_roas | int | 매체사에서 제공하는 **광고 대비 수익률** 을 의미합니다. |\n| land | int | 랜딩페이지를 의미합니다. |\n| rgr | int | 전환율을 의미합니다. |\n| odr | int | 주문율을 의미합니다. |\n| rvn | int | 매출액을 의미합니다. |\n| g1 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g2 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g3 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g4 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g5 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g6 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g7 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g8 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g9 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| g10 | double | 사용자가 정의한 전환지표를 의미합니다. * 사용자 전환지표는 최대 10개까지 사용가능합니다. |\n| rvn_per_odr | double | 주문당 매출액을 의미합니다. |\n| rgr_per_m_click | double | 매체사에서 제공하는 클릭당 전환율을 의미합니다. |\n| odr_per_m_cost | double | 매체사에서 제공하는 광고비당 주문율을 의미합니다. |\n| roas | double | 광고비 대비 발생하는 수익률을 의미합니다. |\n\n### 응답 예\n\n```http\nHTTP/1.1 200 OK\nContent-Type: application/json;charset=UTF-8\n\n{\n\"data\": [\n{\n\"stat_date\": \"2024-05-01\",\n\"m_impr\": 9657.0,\n\"m_click\": 486.0,\n\"m_cost\": 172000.0,\n\"m_rgr\": 0.0,\n\"m_odr\": 18.0,\n\"m_cart\": 0.0,\n\"m_conv\": 65.0,\n\"m_rvn\": 180.0,\n\"m_cpc\": 353.90946502057614,\n\"m_ctr\": 0.05032618825722274,\n\"m_crt\": 0.1337448559670782,\n\"m_roas\": 0.0010465116279069768,\n\"land\": 3.0,\n\"rgr\": 0.0,\n\"odr\": 18.0,\n\"rvn\": 0.0,\n\"g1\": 5.0,\n\"g2\": 66.0,\n\"g3\": 0.25684913,\n\"g4\": 23.0,\n\"g5\": 7.0,\n\"g6\": 55.0,\n\"g7\": 0.3568791032652,\n\"g8\": 0.1235698456331,\n\"g9\": 11.0,\n\"g10\": 2.0,\n\"rvn_per_odr\": 10.0,\n\"rgr_per_m_click\": 0.0,\n\"odr_per_m_cost\": 9555.5555556,\n\"roas\": 0.00104651162791\n},\n{\n\"stat_date\": \"2024-05-02\",\n\"m_impr\": 15200,\n\"m_click\": 11,\n\"m_cost\": 9850,\n......\n\"odr_per_m_cost\": 0,\n\"roas\": 0\n}\n]\n}\n```\n\n### 오류 코드\n\n| HTTP | 오류 코드 | 설명 |\n| ---- | ----------------------- | --------- |\n| 400 | INVALID\\_PARAMETER | 파라미터 오류 |\n| 401 | UNAUTHORIZED | 토큰 오류/만료 |\n| 403 | FORBIDDEN | 접근 권한 없음 |\n| 429 | RATE\\_LIMIT\\_EXCEEDED | 분당 60회 초과 |\n| 500 | INTERNAL\\_SERVER\\_ERROR | 서버 오류 |\n\n[^1]: 인증 토큰",
  "related_slugs": [],
  "keywords": [],
  "faq": [
    {
      "a": "헤더의 x-authorization 필드에 Bearer {AUTH TOKEN} 형식으로 인증 토큰을 담아 전달합니다. Content-Type은 application/json으로 고정해야 합니다.",
      "q": "리포트 데이터를 요청할 때 어떤 방식으로 인증하나요?"
    },
    {
      "a": "rpt_no(리포트 번호)와 client_seq(사이트 그룹 고유 식별 번호)는 필수 항목입니다. where와 dim_cd는 조건절 및 분석차원을 지정할 때 사용합니다.",
      "q": "Request Body에 필수로 넣어야 하는 값은 무엇인가요?"
    },
    {
      "a": "AIR에서 제공하는 API 쿼리 빌더를 사용하면 client_seq가 자동으로 입력됩니다. 이 도구는 매체 데이터를 JSON으로 쉽게 만들고 조회 데이터가 성공적으로 기록되었는지 확인할 수 있게 해줍니다.",
      "q": "client_seq 값은 어떻게 알아내나요?"
    },
    {
      "a": "노출수(m_impr), 클릭수(m_click), 광고비(m_cost), 전환수(m_conv), 매출액(m_rvn), ROAS(roas) 등 매체 제공 지표와 사용자 정의 전환지표(g1~g10)를 받을 수 있습니다.",
      "q": "응답으로 어떤 지표들을 받을 수 있나요?"
    },
    {
      "a": "분당 60회를 초과하면 429 상태코드와 함께 RATE_LIMIT_EXCEEDED 오류가 반환됩니다.",
      "q": "요청이 너무 많으면 어떻게 되나요?"
    }
  ],
  "jsonld": null,
  "image_url": null,
  "caption": null,
  "width": null,
  "height": null,
  "video_url": null,
  "duration_sec": null,
  "thumbnail_url": null,
  "solution_slug": null,
  "source_id": "gitbook:UJ9uzvHT9r6QImnjP8p4:xAP2LIyeqYh2gVPsMNz0",
  "created_at": "2026-08-23T14:32:38.444294+00:00",
  "updated_at": "2026-09-03T04:35:59.118+00:00",
  "backlinks": [],
  "html_url": "https://bizspring.ai/kb/ref/manual/bizspring-air-api-air-reporting-api",
  "markdown_url": "https://bizspring.ai/kb/ref/manual/bizspring-air-api-air-reporting-api.md"
}