Try it!
Try out the Aggregate API using your Branch data via the API Reference here.
Overview
The Branch Aggregate API allows you to programmatically query and export aggregate analytics.
Benefits of Branch Aggregate API
- Give access to agencies and ad networks to pull aggregate data themselves.
- Agencies and ad networks will only receive filtered data that they've been granted access to via user permissions.
- Support for Facebook Marketing Partners (FMP) to have some visibility through aggregate data.
API Limitations
Limitation | Details |
|---|---|
Max number of records returned by API | 50,000 |
Export Window | Rolling 2 year window |
Max number of dimensions | 11 Dimensions |
Max number of measures | 5 Measures |
Max number of days that can be queried at a time | 7 Days |
사용량 제한 |
|
Cost/Click/Impression Data
SANs CCI (Cost / Click / Impression) data is not available for Aggregate API. You can use the Query API with
xx_impressionfor getting the aggregated data of impressions for SANs.
Prerequisites & API Access
In order to use the Branch Aggregate API, you need to have completed the following:
- Created a Branch Dashboard
- Enabled Universal Ads and are already running ad campaigns for your Branch account.
- Implemented the Branch SDK into your mobile app (iOS | Android)
- Logged into the Branch Dashboard with the Aggregate Data Permission enabled.
대행사에 API 접근권한 제공하기
If you work with an agency that runs your advertising campaigns and want to give them access to export the subsequent data, you can provide them with access to the Branch Aggregate data.
To provide an agency team member with access to the Aggregate API:
- 왼쪽 메뉴의 Setup & Testing에서 Account Settings을 클릭합니다.
- Account Settings 페이지에서 Agencies 탭을 클릭합니다.
- 해당 대행사의 맴버 리스트를 펼친후 접근권한을 부여할 대행사 맴버를 찾은 다음 Actions 컬럼의 아이콘으로 마우스를 옮긴 다음 Edit을 클릭합니다.
- Edit Agency Team Member 선택창에서 다음을 실행합니다.
- Access Level에서 Export 박스를 체크합니다.
- Permissions에서 Aggregate Data 박스를 체크합니다.
- 선택 사항: 데이터 필터 추가
- Data Filters 아래의 각 항목에서 토글을 푸른색으로 전환하는 것을 통해 해당 대행사 맴버가 필요한 데이터만 추출할 수 있도록 필터링할 수 있습니다.
- Save를 클릭합니다.
대행사 태그 데이터
Only show agency-tagged data 데이터 필터를 활성화하지 않은 경우 에이전시 팀원은 캠페인의 관련 여부에 관계없이 모든 캠페인과 관련된 합산 데이터를 내보낼 수 있습니다.
권한인증
Calls to the Branch Aggregate API require an api_key query string parameter to be passed with each request. API Keys are generated on per-user bases and are permanent.
Learn how to retrieve your API key (a.k.a. Access Token)
NOTE: In order to retrieve or reset your API Key/Access Token, you must have access to the Organizational Level of the Branch account. This functionality is not present at the App Level
API Usage
내보내기 요청
POST /v2/analytics
Host: api2.branch.io
Content-Type: application/json
Request Headers:
| Header | 설명 | 필수 |
|---|---|---|
| Access-Token | Key that encapsulates the users permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication. | 예 |
Request Query Parameters:
| 파라미터 | 설명 | 필수 |
|---|---|---|
| organization_id or app_id | Unique identifier for app/organization of requested data. | 예 |
| limit | The maximum number of results to return.Default: 50000 Min: 50000 Max: 50000 (unless a higher limit is specified) | 아니오 |
| format | 반환된 데이터의 형식입니다. 기본값은 csv입니다. | 아니오 |
Request Body Parameters:
파라미터 | 설명 | 필수 |
|---|---|---|
start_date | ISO-8601 완료 날짜로 표시되는 간격 시간 범위의 시작입니다. | 예 |
end_date | ISO-8601 완료 날짜로 표시되는 간격 시간 범위의 마지막입니다. | 예 |
data_source | A string value representing the data source. See Topics for complete list. | 예 |
dimensions | 그룹화할 기준 차원을 나타내는 배열입니다. 제한은 11입니다. See Dimensions for complete list. NOTE: If you are querying | 아니오 |
filters | Keys are same as dimensions. Values are an array of values to match for the dimension. 특정 값을 매치 또는 불허하는 필터를 정의하는 객체입니다. | 아니오 |
granularity |
The time granularity that each band value will represent. Default: day Note: Do not add | 아니오 |
aggregation |
How to count events towards the final result count. When querying with a data source of "eo_commerce_event", the aggregation may also be specified as "revenue", in which case the counts returned are the sum of revenue from matching events, and not the number of events themselves. Default: total_count | 아니오 |
| enable_install_calculation | If true, then Branch will de-dupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads (result from iOS 14.5 privacy changes).Default: false | 아니오 |
Response Body Parameters
| 파라미터 | 설명 |
|---|---|
| code | The response code |
| job_id | The unique ID of the request. This is used in the Export Download Status request. |
| status_url | The URL of the export request. |
Example Request/Response:
curl --request POST \
--url 'https://api2.branch.io/v2/analytics?organization_id={organization_id}&limit=5000&format=json' \
--header 'Accept: application/json' \
--header 'Access-Token: api_org_9999999999999999999999999999' \
--header 'Content-Type: application/json' \
--data '
{
"start_date": "2021-12-12",
"end_date": "2021-12-18",
"data_source": "eo_install",
"dimensions": [
"user_data_os"
],
"filters": {
"attributed": "true",
"user_data_os": [
"IOS",
"ANDROID"
]
},
"enable_install_recalculation": true,
"granularity": "day",
"aggregation": "total_count"
}
'
{
"code": 200,
"job_id": "8a2514d5-9035-445f-b42a-948112aeb807",
"status_url": "https://api2.branch.io/v2/analytics/a38bd2f0-9740-4334-8c96-5bfd90671b06"
}
내보내기 다운로드 상태
GET /v2/analytics/{job_id}
Host: api2.branch.io
Accept: application/json
Request Headers:
| Header | 설명 | 필수 |
|---|---|---|
| Access-Token | Key that encapsulates the users permission w.r.t an org. Obtained from the Branch Dashboard. | 예 |
Response Path Parameters
| 파라미터 | 설명 | 필수 |
|---|---|---|
| job_id | The unique ID of the request.Obtained from the Export Request | 예 |
Request Query Parameters:
| 파라미터 | 설명 | 필수 |
|---|---|---|
| organization_id or app_id | Unique identifier for app/organization of requested data. | 예 |
| limit | The maximum number of results to return.Default: 50000 Min: 50000 Max: 50000 (unless a higher limit is specified) | 아니오 |
| format | 반환된 데이터의 형식입니다. 기본값은 csv입니다. | 아니오 |
Response Body Parameters
| 파라미터 | 설명 |
|---|---|
| code | The response code |
| status | The status of the original request by job_id |
| response_url | The URL of your request for download. |
Example Request/Response:
curl --request GET \
--url 'https://api2.branch.io/v2/analytics{job_id}?organization_id=787326553414456146&limit=5000&format=json' \
--header 'Accept: application/json' \
--header 'Access-Token: api_org_99999999999999999999'
{
"code": 200,
"status": "FINISHED",
"response_url": "https://branch-exports.s3.amazonaws.com/partner-query/2021-12-12-2021-12-18-eo_install-day-8a2514d5-9035-445f-b42a-948112aeb807-j6zbNS9OxQOz7spz.json?Signature=gbEoMAFAr0y7kN3stZ1zzUh60ko%3D&AWSAccessKeyId=AKIAI7A6NRHGMRDK2LIQ&Expires=1648077926"
}
부록
필터
Filters work based on AND at the top level. Each dimension can have multiple "or" filters e.g. { "user_data_os": ["IOS", "ANDROID"] }.
Topics
[
"eo_impression",
"eo_click",
"eo_branch_cta_view",
"eo_sms_sent",
"eo_open",
"eo_install",
"eo_reinstall",
"eo_web_session_start",
"eo_pageview",
"eo_commerce_event",
"eo_custom_event",
"eo_content_event",
"eo_dismissal",
"eo_user_lifecycle_event",
"cost",
"skadnetwork-valid-messages",
//Fraud Topics
"eo_click_blocked",
"eo_impression_blocked",
"eo_install_blocked",
"eo_reinstall_blocked",
"eo_open_blocked",
"eo_web_session_start_blocked",
"eo_pageview_blocked",
"eo_sms_sent_blocked",
"eo_custom_event_blocked",
"eo_content_event_blocked",
"eo_commerce_event_blocked",
"eo_user_lifecycle_event_blocked",
"eo_branch_cta_view_blocked"
]
크기
[
"name",
"origin",
"timestamp",
"deep_linked",
"from_desktop",
"attributed"
]
[
"user_data_os",
"user_data_language",
"user_data_platform",
"user_data_environment",
"user_data_geo_region_en",
"user_data_geo_dma_code",
"user_data_geo_country_code",
"user_data_country",
"user_data_opted_in",
"user_data_opted_in_status"
]
[
"last_attributed_touch_type",
"last_attributed_touch_data_tilde_tags",
"last_attributed_touch_data_tilde_secondary_publisher",
"last_attributed_touch_data_plus_current_feature",
"last_attributed_touch_data_plus_via_features",
"last_attributed_touch_data_tilde_campaign",
"last_attributed_touch_data_tilde_advertising_partner_name",
"last_attributed_touch_data_tilde_advertising_partner_id",
"last_attributed_touch_data_tilde_feature",
"last_attributed_touch_data_tilde_creative_name",
"last_attributed_touch_data_plus_web_format",
"last_attributed_touch_data_tilde_creative_id",
"last_attributed_touch_data_tilde_ad_name",
"last_attributed_touch_data_tilde_ad_id",
"last_attributed_touch_data_tilde_campaign_id",
"last_attributed_touch_data_tilde_placement",
"last_attributed_touch_data_tilde_stage",
"last_attributed_touch_data_tilde_channel",
"last_attributed_touch_data_tilde_ad_set_name",
"last_attributed_touch_data_tilde_ad_set_id",
"last_attributed_touch_data_tilde_keyword",
"last_attributed_touch_data_tilde_journey_id",
"last_attributed_touch_data_tilde_view_name",
"last_attributed_touch_data_tilde_view_id",
"last_attributed_touch_data_tilde_agency",
"last_attributed_touch_data_tilde_agency_id"
]
[
"last_cta_view_data_tilde_ad_name",
"last_cta_view_data_tilde_secondary_publisher",
"last_cta_view_data_tilde_campaign",
"last_cta_view_data_tilde_advertising_partner_name",
"last_cta_view_data_tilde_feature",
"last_cta_view_data_tilde_ad_set_name",
"last_cta_view_data_tilde_ad_set_id",
"last_cta_view_data_tilde_campaign_id",
"last_cta_view_data_tilde_creative_name",
"last_cta_view_data_tilde_creative_id",
"last_cta_view_data_plus_via_features",
"last_cta_view_data_dollar_3p",
"last_cta_view_data_tilde_tags",
"last_cta_view_data_plus_web_format",
"last_cta_view_data_tilde_channel",
"last_cta_view_data_tilde_ad_id",
"last_cta_view_data_tilde_stage"
]
[
"body_ad_network_id",
"body_campaign_id",
"body_app_id",
"body_redownload",
"body_source_app_id",
"body_conversion_value",
"body_last_attributed_touch_data_tilde_creative_name",
"body_last_attributed_touch_data_tilde_ad_set_name",
"body_last_attributed_touch_data_tilde_creative_id",
"body_last_attributed_touch_data_tilde_ad_set_id",
"body_last_attributed_touch_data_tilde_ad_name",
"body_last_attributed_touch_data_tilde_ad_id",
"body_last_attributed_touch_data_tilde_campaign_id",
"body_last_attributed_touch_data_tilde_campaign_name",
"annotation_dollar_3p",
"annotation_conversion_value_mapped_value",
"annotation_conversion_value_revision",
"annotation_campaign_id_mapped_value",
"annotation_campaign_id_revision",
"annotation_source_app_id_mapped_value",
"annotation_source_app_id_revision",
"body_last_attributed_touch_data_tilde_campaign",
"last_attributed_touch_data_tilde_creative_name",
"last_attributed_touch_data_tilde_ad_set_name",
"last_attributed_touch_data_tilde_creative_id",
"last_attributed_touch_data_tilde_ad_set_id",
"last_attributed_touch_data_tilde_ad_name",
"last_attributed_touch_data_tilde_ad_id",
"last_attributed_touch_data_tilde_campaign_id",
"last_attributed_touch_data_tilde_campaign",
"last_attributed_touch_data_tilde_agency",
"last_attributed_touch_data_tilde_agency_id",
"last_attributed_touch_data_tilde_advertising_partner_name",
"last_attributed_touch_data_tilde_advertising_partner_id",
"annotation_customer_event_alias"
]
[
"days_from_last_attributed_touch_to_event",
"days_from_last_cta_view_to_event",
"event_data_product_categories",
"first_event_for_user",
"customer_event_alias"
]