> ## Documentation Index > Fetch the complete documentation index at: https://help.airbridge.io/llms.txt > Use this file to discover all available pages before exploring further. # Ad Spend Data 업로드 요청하기 API를 통해 직접 데이터를 업로드하고 리포트에서 데이터를 함께 볼 수 있습니다.

Ad Spend Data

API를 통해 연동할 수 없는 매체에 대해 노출, 클릭, 비용데이터를 직접 업로드하고 업로드 상태를 조회할 수 있습니다.

Metric Data

신규 메트릭 데이터를 직접 업로드하고 업로드 상태를 조회할 수 있습니다. 광고 비용 데이터를 CSV 포맷으로 업로드 요청합니다. Request Header 내 'Content-Type' 은 multipart/form-data 를 사용합니다. ```header-multipart theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}} Content-Type: multipart/form-data; charset=utf-8 ```

CSV 파일 포맷 및 스키마

CSV 파일 내 컬럼명 및 컬럼값

| Category | Column Name | Type | Description | Required | | -------- | ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | Group by | date | string | 데이터가 기록된 날짜. 'YYYY-MM-DD' 포맷의 데이터만 허용됩니다 | **Required** | | Group by | channel | string | 광고 채널. 에어브릿지와 연동된 채널은 [에어브릿지 대시보드에서 사용되는 이름](https://docs.google.com/spreadsheets/d/13ThNnryqRmZQwJVecM8lZ2OB7LzA8s3cwLlQBGpbXLg/edit#gid=1415221276\&range=B:B)으로 입력해야 합니다 | **Required** | | Group by | currency | string | 3문자 통화 코드(ISO 4217)
- KRW, USD 등 | **Required** | | Group by | campaign | string | 광고를 집행한 캠페인 이름 | **Required** | | Metric | impressions | int | 노출 수. 자리수 구분을 위한 기호(,)를 허용하지 않습니다 | **Required** | | Metric | clicks | int | 클릭 수. 자리수 구분을 위한 기호(,)를 허용하지 않습니다 | **Required** | | Metric | cost | float | 광고 등에 쓰인 비용. 자리수 구분을 위한 기호(,)를 허용하지 않습니다. | **Required** | | Group by | campaign\_id | string | 캠페인 ID | Optional | | Group by | ad\_group | string | 광고 그룹 이름 | Optional | | Group by | ad\_group\_id | string | 광고 그룹 ID | Optional | | Group by | ad\_creative | string | 광고 소재 | Optional | | Group by | ad\_creative\_id | string | 광고 소재 ID | Optional | | Group by | term | string | 광고 키워드 | Optional | | Group by | term\_id | string | 광고 키워드 ID | Optional | | Group by | ad\_account\_id | string | 광고 계정 ID | Optional | | Group by | sub\_publisher | string | 하위 광고 채널 이름 | Optional | | Group by | sub\_sub\_publisher\_1 | string | 하하위 광고 채널1 이름 | Optional | | Group by | sub\_sub\_publisher\_2 | string | 하하위 광고 채널2 이름 | Optional | | Group by | sub\_sub\_publisher\_3 | string | 하하위 광고 채널3 이름 | Optional | | Group by | country | string | 2문자 국가 코드 | Optional | | Group by | os\_name | string | OS 이름. 에어브릿지 대시보드와 대소문자까지 동일한 표기로 입력해야 함께 분석할 수 있습니다 | Optional |

Sample CSV File

* [CSV File 다운로드](https://static.airbridge.io/docs/airbridge_self_serve_ad_spend_data_sample.csv)
**주의하세요** 대소문자 입력에 주의해 주세요. Type이 string인 칼럼의 데이터들은 대소문자를 구분하여 인식합니다. Airbridge에서 측정한 모바일 OS Name은 각각 'Android', 'iOS'로 기록하고 있지만 직접 업로드한 데이터의 OS Name을 'android', 'ios'로 입력한 경우 대시보드 내 별개의 Row로 분리됩니다. 따라서 Group by 결과를 위해서 ‘Android’, 'iOS’로 기록해주셔야 합니다.

데이터 Overwrite 및 삭제

데이터 Ovewrite

비용 데이터 업로드 시 'date', 'channel', 'campaign' 3개 필드값을 기준으로 기존에 동일한 조합이 있는 경우 기존 데이터를 신규 데이터로 Overwrite합니다. ###### 예시 시나리오1 **1. 2022-08-03:** date, channel, campaign, ad\_group 레벨의 데이터 업로드 | date | channel | campaign | ad\_group | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | ------------ | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_female | KRW | 1000 | 10000 | 100000 | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_male | KRW | 800 | 12000 | 80000 | **2. 2022-08-04:** date, channel, campaign 레벨의 데이터 업로드 | date | channel | campaign | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | retargeting\_campaign | KRW | 2000 | 20000 | 150000 | **3. 최종 반영:** 8월 4일 업로드 데이터 처리 시 'date', 'channel', 'campaign' 3개 필드값을 기준으로 8월 3일에 업로드한 동일 데이터가 있기 때문에 해당 데이터 대신 최종적으로 8월 4일 업로드 데이터만 남게됩니다. (ad group 값은 null) | date | channel | campaign | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | retargeting\_campaign | KRW | 2000 | 20000 | 150000 | ###### 예시 시나리오 2 **1. 2022-08-03:** date, channel, campaign 레벨의 데이터 업로드 | date | channel | campaign | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | retargeting\_campaign | KRW | 1000 | 10000 | 100000 | **2. 2022-08-04:** date, channel, campaign, ad\_group 레벨의 데이터 업로드 | date | channel | campaign | ad\_group | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | ------------ | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_female | KRW | 2000 | 20000 | 150000 | **3. 최종 반영:** 8월 4일 업로드 데이터 처리 시 'date', 'channel', 'campaign' 3개 필드값을 기준으로 8월 3일에 업로드한 동일 데이터가 있기 때문에 해당 데이터 대신 최종적으로 8월 4일 업로드 데이터만 남게됩니다. | date | channel | campaign | ad\_group | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | ------------ | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_female | KRW | 2000 | 20000 | 150000 | ###### 예시 시나리오 3 **1. 2022-08-03:** date, channel, campaign, ad\_group 레벨의 데이터 업로드 | date | channel | campaign | ad\_group | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | ------------ | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | promotion\_campaign | 2030\_female | KRW | 1200 | 15000 | 10000 | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_female | KRW | 1000 | 10000 | 100000 | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_male | KRW | 800 | 12000 | 80000 | **2. 2022-08-04:** date, channel, campaign, ad\_group 레벨의 데이터 업로드 | date | channel | campaign | ad\_group | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | ------------ | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_male | KRW | 900 | 15000 | 90000 | | 2022-08-01 | owned\_website | ua\_campaign | 2030\_female | KRW | 1200 | 15000 | 120000 | **3. 최종 반영:** 8월 4일 업로드 데이터 처리 시 'date', 'channel', 'campaign' 3개 필드값을 기준으로 8월 3일에 업로드 데이터 중 동일 데이터는 8월 4일의 데이터로 대체되며, 나머지 데이터는 그대로 남게됩니다. | date | channel | campaign | ad\_group | currency | clicks | impressions | cost | | ---------- | -------------- | --------------------- | ------------ | -------- | ------ | ----------- | ------ | | 2022-08-01 | owned\_website | promotion\_campaign | 2030\_female | KRW | 1200 | 15000 | 10000 | | 2022-08-01 | owned\_website | retargeting\_campaign | 2030\_male | KRW | 900 | 15000 | 90000 | | 2022-08-01 | owned\_website | ua\_campaign | 2030\_female | KRW | 1200 | 15000 | 120000 |

데이터 삭제

기존에 업로드한 비용 데이터를 삭제하기 위해서는 동일한 Group by에 대해서 clicks, impressions, cost 메트릭의 값을 모두 0으로 설정하여 다시 업로드합니다.

유의 사항

* 현재 비용 데이터 업로드 요청 및 상태 조회 API는 오너, 사내마케터 권한 계정의 API Token으로만 사용 가능합니다. * CSV 파일 내 컬럼명은 정해진 소문자 값만 허용됩니다. 또한 channel, currency, country, os\_name 등은 에어브릿지 대시보드에 나오는 데이터와 동일한 표기를 사용해야 함께 조회할 수 있습니다. * 1번에 요청할 수 있는 CSV 파일의 최대 row는 10000개입니다. 또한 CSV 파일의 최대 크기는 1MB입니다. * CSV 파일의 열에 공백을 허용하지 않습니다. 값이 없는 메트릭은 0으로 입력하여 업로드해야 합니다. 예를 들어 Cost 데이터는 있지만, Clicks, Impressions 데이터는 없는 경우 Clicks, Impression 컬럼을 추가하되 값을 모두 0으로 입력하여 업로드합니다. * string 타입의 컬럼값은 1글자 이상, 256글자 이하로 제한됩니다. * 컬럼명 및 컬럼값 앞뒤로 공백이 없도록 유의해 주세요. ```text POST theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}} https://api.airbridge.io/self-serve-data/v1/ad-spend/requests ```

Request

***

Headers

API 요청 및 결과 반환에 사용할 언어를 지정할 수 있습니다. ISO-639-1 포맷을 따릅니다. 리소스의 미디어 타입을 나타냅니다. 기본값으로 `application/json`을 사용합니다. API 요청에 사용하는 키값입니다. [키값 생성 및 조회 방법](/ko/references/introduction)을 확인하여 획득할 수 있습니다. ```shellscript Request theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}} curl -X POST 'https://api.airbridge.io/self-serve-data/v1/ad-spend/requests' \ -H 'Accept-Language: ko' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AIRBRIDGE-API-TOKEN}' ```

Response

*** ### 200 | Name | Description | Example | | ---------- | ---------------------------------------------------------------------- | ------------------------------------ | | requestId | 업로드 요청에 대한 고유 ID로, 요청 시 마다 새로운 ID가 부여됩니다. 업로드 요청 상태 조회 시 해당 ID가 사용됩니다. | 08844672-62d8-4da8-9d48-e14961651e0c | | status | 업로드 요청에 대한 진행 상태값입니다. | ingested | | prevStatus | 현재 status 이전의 상태값입니다. | validated | | reason | status가 'failed'로 업로드 실패 이유에 대한 값입니다. | \{"date": \["invalid date"]} | | createdAt | 요청이 생성된 날짜 및 시간입니다. | 2022-08-09T08:59:15 | | updatedAt | 업데이트가 진행된 날짜 및 시간입니다. | 2022-08-09T08:59:15 | ```json 200 theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}} { "reason": null, "status": "uploaded", "createdAt": "2023-01-01T09:00:00", "requestId": "08844672-62d8-4da8-9d48-e14961651e0c", "updatedAt": "2023-01-01T09:00:00", "prevStatus": null } ```