👍

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
Branch may define dynamic record limits based on App/Org ID

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

사용량 제한

  • 초당 요청 2개
  • 분당 요청 5개
  • 시간당 요청 150개

🚧

Cost/Click/Impression Data

SANs CCI (Cost / Click / Impression) data is not available for Aggregate API. You can use the Query API with xx_impression for 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:

  1. Created a Branch Dashboard
  2. Enabled Universal Ads and are already running ad campaigns for your Branch account.
  3. Implemented the Branch SDK into your mobile app (iOS | Android)
  4. 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:

  1. 왼쪽 메뉴의 Setup & Testing에서 Account Settings을 클릭합니다.
  2. Account Settings 페이지에서 Agencies 탭을 클릭합니다.
  3. 해당 대행사의 맴버 리스트를 펼친후 접근권한을 부여할 대행사 맴버를 찾은 다음 Actions 컬럼의 아이콘으로 마우스를 옮긴 다음 Edit을 클릭합니다.
  4. Edit Agency Team Member 선택창에서 다음을 실행합니다.
    1. Access Level에서 Export 박스를 체크합니다.
    2. Permissions에서 Aggregate Data 박스를 체크합니다.
  5. 선택 사항: 데이터 필터 추가
    1. Data Filters 아래의 각 항목에서 토글을 푸른색으로 전환하는 것을 통해 해당 대행사 맴버가 필요한 데이터만 추출할 수 있도록 필터링할 수 있습니다.
  6. Save를 클릭합니다.
12461246

🚧

대행사 태그 데이터

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

반환할 최대 결과의 수입니다.

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 skadnetwork-valid-messages, be sure to set aggregation to total_count

아니오

filters

Keys are same as dimensions. Values are an array of values to match for the dimension.

특정 값을 매치 또는 불허하는 필터를 정의하는 객체입니다.

아니오

granularity

  • "day"
  • "week"
  • "month"

The time granularity that each band value will represent.

Default: day

아니오

aggregation

  • "unique_count"
  • "total_count"
  • "revenue"
  • "cost"
  • "cost-in-local-currency"

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).

기본값: 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

반환할 최대 결과의 수입니다.

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