Singular 파트너로서, Singular Reporting API를 사용하여 Singular에 연결된 광고주의 데이터를 액세스할 수 있습니다.

API를 통해 각 조직에서 액세스할 수 있는 데이터는 Partner Portal에서 사용할 수 있는 데이터와 동일합니다.

Reporting API 기본 사항

보고서를 실행하기 전에, 다음 정보가 필요합니다:

• Singular API 키. Partner Portal에서 확인할 수 있습니다. (자세한 내용은 Partner Portal 사용을 참조).
• 액세스하려는 광고주의 조직 키. 고객 계정 조회 API 엔드포인트를 쿼리하여 광고주의 이름 및 고유 조직 키 목록을 가져옵니다.
• 보고서 필터링 옵션. Filters API 엔드포인트를 쿼리하여 API 키와 광고주의 조직 키를 사용해 각 조직의 필터링 옵션을 확인합니다.
• 이벤트 및 코호트 기간. Partner Portal을 확인합니다. 특정 광고주에 대해 Portal에서 사용할 수 있는 모든 이벤트는 API를 통해서도 사용할 수 있습니다.

보고서를 실행하려면, 두 가지 주요 엔드포인트를 사용합니다:

1. 특정 조직에서 원하는 데이터를 가져오기 위해 Create Async Report를 쿼리합니다.
2. 보고서 상태를 확인하고 실행이 완료되었을 때 보고서에 액세스하려면 Get Report Status를 쿼리합니다.

고객 계정 조회 엔드포인트

사용 방법

이 엔드포인트를 사용하여 광고주 목록을 가져옵니다. 광고주 목록에는 귀사의 네트워크에서 캠페인을 운영하는 모든 Singular 고객이 포함되며, 데이터를 공유하지 않기로 선택한 고객은 제외됩니다.

이후 조직 키를 사용하여 Create Async Report 엔드포인트를 쿼리할 수 있습니다.

쿼리 매개변수

샘플 출력

"organizations":[

    {

        "display_name":"Awesome Games",

        "organization_key": "aw_games"

    },

    ...

]

출력 세부사항

Filters 엔드포인트

사용 방법

이 보조 엔드포인트를 사용하여 보고서 필터링에 사용할 수 있는 차원과 각 차원의 가능한 값을 최신 목록으로 가져옵니다. 특정 광고주의 조직 키를 지정해야 합니다.

샘플 쿼리 (Python)

import requests

url = "https://api.singular.net/api/v2.0/reporting/filters"

params = {

    "api_key": API_KEY,

    "organization_key": ORGANIZATION_KEY

}

result = requests.get(url=url, params=params)

print result.json()

쿼리 매개변수

샘플 출력

{

  "status": 0,

  "substatus": 0,

  "value": { "dimensions": [

    {

      "name": "os",

      "display_name": "OS",

      "values": [
        {"name":4,"display_name":"Android"},
        {"name":1,"display_name":"iOS"}
      ],

    },

    {

      "name": "source",

      "display_name": "Source",

      "values": [
        {"name": "adwords", "display_name": "AdWords"}
      ]

    }

  ]}

}

Create Async Report 엔드포인트

사용 방법

이 엔드포인트는 Singular에서 보고 데이터를 가져오기 위한 주요 엔드포인트입니다. 이 엔드포인트는 조직 키, 차원, 지표, 날짜, 기타 세부사항에 따라 비동기 보고서 쿼리를 생성하며 보고서 ID를 반환합니다.

이후 보고서 상태 조회 엔드포인트를 쿼리하여 보고서가 완료되었는지 확인하고 다운로드 URL을 가져옵니다.

제한사항

• 단일 날짜에 대한 API 요청은 반환되는 행 수에 제한이 없습니다.
• 단일 요청은 최대 30일을 쿼리할 수 있으며 최대 100,000개의 레코드를 조회할 수 있습니다. 100,000개 이상의 레코드를 쿼리하는 요청은 실패하며 추가 필터링이 필요합니다.
• 일별 또는 주별 데이터 가져오기를 위해 당사의 API를 통합할 때, 일반적으로 다중 일 쿼리를 단일 일로 분할하고 전체 기간을 반복적으로 쿼리하는 것을 권장합니다.

샘플 쿼리 (Python)

import requests

url = "https://api.singular.net/api/v2.0/create_async_report"

query_params = {"api_key": API_KEY}

payload = {

  "organization_key": ORGANIZATION_KEY,

  "dimensions":"app,source,os,country_field",

  "metrics": "custom_impressions,custom_clicks,custom_installs",

  "start_date":"2022-08-01",

  "end_date": "2022-08-02",

  "time_breakdown": "all",

  "format": "csv",

  "country_code_format": "iso"

}

response = requests.post(url=url, params=query_params, data=payload)

쿼리 매개변수

샘플 출력

{

    "status": 0,

    "substatus": 0,

    "value": {

        "report_id": "5cfdb747dd464cd09a9c463e5be9691f"

    }

}

지원되는 차원 및 지표

각 필드에 대한 설명은 지표 및 차원 용어집을 참조하세요.

지원되는 차원:

adn_account_id 

adn_account_name 

adn_campaign_id 

adn_campaign_name

adn_campaign_url

adn_original_currency

adn_sub_adnetwork_name

app

app_id

country_field

keyword

os

platform

publisher_id

publisher_site_name

source

tracker_campaign_name

unified_campaign_id

unified_campaign_name

지원되는 지표:

adn_clicks

adn_installs

custom_impressions

custom_clicks

custom_installs

tracker_clicks

tracker_impressions

tracker_installs

tracker_reengagements

Get Report Status 엔드포인트

사용 방법

이 엔드포인트는 Create Async Report 엔드포인트를 사용하여 생성된 특정 보고서의 상태를 반환합니다. 보고서 실행이 완료되면 다운로드 URL도 반환됩니다. 보고서 실행에 실패한 경우, 문제 해결에 사용할 수 있는 오류 메시지를 제공합니다. (자세한 내용은 오류 코드 표 및 API FAQ 및 문제 해결 가이드를 참조하세요).

샘플 쿼리 (Python)

import requests

url = "https://api.singular.net/api/v2.0/get_report_status"

querystring = {

    "report_id": REPORT_ID,

    "api_key": API_KEY

}

response = requests.get(url=url, params=querystring)

print(response.text)

쿼리 매개변수

샘플 출력

{

    "status": 0,

    "substatus": 0,

    "value": {

        "status": "DONE",

        "url_expires_in": 3600,

        "generated_url_time_in_utc": "2018-05-13T08:26:18.457690+00:00",

        "url_expired_time_in_utc": "2018-05-13T09:26:18.457690+00:00",

        "download_url": "https://singular-reports-results.s3.amazonaws.com/singular/xxxxxxxxx",

        "report_id": "5cfdb747dd45be9691f"

    }

}

출력 세부사항