API 리포팅 레퍼런스

Getting Started with the Singular Reporting API를 통해 API의 개념에 대해 익숙해진 후 귀사의 케이스에 해당하는 알맞은 쿼리를 찾으세요.  

참고 자료: SKAdNetwork API Reference, Ad Monetization API Reference

일반 정보

인증

모든 API 요청들은 API 키가 필요합니다. 키를 가져오려면, 어카운트로 로그인하시고 Settings > API로 가세요. 요청 내 api_key 파라미터에 해당 키를 기재하거나, Authorization HTTP 헤더에 토큰을 기재할 수 있습니다.   

제한 사항

Singular API의 디폴트 제한은 다음과 같습니다.

  • 비동기 리포트: 100개의 비동기 리포트까지 동시에 실행할 수 있습니다.
  • 동기 리포트: 3개의 동기 리포트까지 동시에 실행할 수 있습니다.
  • 한 리포트 별 열 제한: 쿼리 당 200K 열까지 사용할 수 있습니다.
  • 일별 글로벌 열 제한: 하루에 3M 열까지 사용할 수 있습니다. (쿼리 간 공유 가능)

Singular는 모든 고객들에게 높은 수준의 서비스를 제공하기 위해 주어진 엔드포인트에 대한 제한 사항을 설정할 수 있습니다. 만약 디폴트 제한을 초과하여 사용해야만 하는 특별한 요구 사항이 있다면 문의하세요. 

리포팅 API 엔드포인트 목록

다음과 같은 API 엔드포인트를 사용할 수 있습니다.

비동기 리포트 생성  POST https://api.singular.net/api/v2.0/create_async_report

집계된 통계를

반환합니다.

데이터 가용성 GET https://api.singular.net/api/v2.0/data_availability_status

비동기 리포트 생성을 쿼리 하기 전, 엔드포인트를 통하여 해당 날짜에  소스(데이터 커넥터)에서 데이터가 사용 가능한 상태인지를 확인할 있습니다. 

리포트 현황 취득

GET https://api.singular.net/api/v2.0/get_report_status 주어진 리포트의 현황을 반환합니다.
필터 GET https://api.singular.net/api/v2.0/reporting/filters 리포트에서 사용 가능한 모든 필터링 옵션을 반환합니다.

커스텀

디멘션

GET https://api.singular.net/api/custom_dimensions 리포트에서 사용 가능한 모든 커스텀 디멘션을 반환합니다.
코호트 메트릭 GET https://api.singular.net/api/cohort_metrics 리포트에서 사용 가능한 코호트 기간과 모든 코호트 메트릭을 반환합니다.
컨버젼 메트릭 GET https://api.singular.net/api/conversion_metrics 리포트에서 사용 가능한 컨버젼 메트릭을 모두 반환합니다.

비동기 리포트 엔드포인트 생성

POST https://api.singular.net/api/v2.0/create_async_report

이용 사례

이 엔드포인트가 Singular로부터 리포팅 데이터를 획득하는 주된 엔드포인트입니다. 이 엔드포인트는 리포팅 디멘션, 메트릭, 날짜, 그리고 명시한 디테일들에 기반하여 비동기 리포트 쿼리를 생성하고, Report ID를 반환합니다. 그다음 단계로 리포트 상태 엔드포인트 획득을 쿼리 하여 리포트가 언제 생성되는지 확인하고 다운로드 URL를 획득할 수 있습니다.

Screen_Shot_2020-07-01_at_0.17.35.png

더 많은 정보는, Singular 리포팅 API 가이드쿼리 프로세스 구문을 참고하세요.

제한 사항

  • 하루 동안의 API 요청은 반환하는 열 수에 대한 제한이 없습니다.
  • 한 요청은 최대 30일 동안 100,000건의 기록까지 쿼리할 수 있습니다. 100,000건을 초과한 기록에 대한 요청은 수행되지 않음으로 추가적인 필터링이 필요합니다.
  • 데이터 풀링을 위해 일별 혹은 주별로 API와 연동할 때에는 쿼리를 하루씩 여러 날로 분할하고 이를 반복하여 필요한 기간만큼 실행하는 것을 권장합니다. 

샘플 쿼리

import requests
url = "https://api.singular.net/api/v2.0/create_async_report"
query_params = {"api_key": "<API KEY>"}
payload = {
  "dimensions":"app,source,os,country_field",
  "metrics": "custom_impressions,custom_clicks,custom_installs",
  "start_date":"2020-01-01",
  "end_date": "2020-01-01",
  "time_breakdown": "all",
  "format": "csv",
  "country_code_format": "iso"
}
response = requests.post(url=url, params=query_params, data=payload)
print(response.text)

쿼리 파라미터

파라미터 형식 설명
기본 파라미터
api_key 문자열 Singular 콘솔에서 제공된 API 키  
start_date 날짜    
end_date 날짜    
time_breakdown 문자열 'day', 'week', 'month', 'all'로 세분화하여 모든 시간에 걸친 집계 데이터를 표기합니다.  
필드 부분 파라미터
dimensions 문자열 쉼표로 분리한 디멘션 리스트입니다. 찾고 있는 데이터 종류에 기반하여 API 리포트 종류에서 사용 가능한 디멘션 리스트를 확인하세요. 메트릭과 디멘션에서 각 디멘션에 대한 정보를 참고하세요.  
metrics 문자열 쉼표로 분리한 메트릭 리스트입니다. 찾고 있는 데이터 종류에 기반하여 API 리포트 종류에서 사용 가능한 메트릭 리스트를 확인하세요. 메트릭과 디멘션에서 각 메트릭에 대한 정보를 참고하세요.  
cohort_metrics 문자열 이름에 따라 쉼표로 나눠진 코호트 메트릭 목록입니다. (코호트 메트릭이란? 참고). 코호트 메트릭이란 이벤트 페이지에서 정의한 컨버전 이후의 이벤트들을 모두 포함합니다. 어카운트에서 사용 가능한 코호트 메트릭 목록을 검색하려면, 코호트 메트릭 엔드포인트를 사용하세요. 'cohort_metrics': '815782610a1ddf,revenue'
cohort_periods 문자열 쉼표로 분리한 코호트 기간 리스트입니다. (코호트 메트릭이란?을 참고하세요). 사용 가능한 코호트 기간 리스트를 검색하려면, 코호트 메트릭 엔드포인트를 사용하세요. 'cohort_periods': '7d,14d,ltv'
파라미터 필터링
app 문자열 쉼표로 분리한 앱 명에 대한 목록을 쿼리 결과에 따라 필터합니다. 앱 명에 대한 목록을 검색하려면, 엔드포인트 필터를 사용하세요. 'app': 'my_app1,my_app2'
Source 문자열 쉼표로 분리한 광고 매체(와 다른 소스들)를 목록으로 필터합니다. 광고 매체로 검색하려면, 필터 엔드포인트(Filter endpoint)를 사용하세요. 'source': 'facebook,adwords'
filters JSON 각 디멘션, 오퍼레이터, 값을 갖는 오브젝트를 필터하는 JSON 목록입니다. 고급 필터를 적용하려면 이 파라미터를 적용하세요. 주의할 점은 만약 두 개 이상의 필터를 지정하면 AND 관계가 됩니다. 필터할 수 있는 전체 파라미터 목록이나 가능한 값을 검색하려면, 필터 엔드포인트(Filter endpoint)를 사용하세요. 'filters': '[{"dimension": "os", "operator": "in","values": [1, 4]}, {"dimension": "source", "operator": "not in", "values": ["adwords"]}]'
파라미터 서식
format 문자열 쿼리 결과가 전송될 형식입니다. 옵션은 다음과 같습니다. "json" (디폴트) 또는 "csv". 'format':'csv'
country_code_format 문자열 "iso3" (디폴트) 또는 "iso"  
display_alignment 불리언 (Boolean) 만약 "true"로 설정할 경우, 캠페인과 크리에이티브 통계의 차이점을 설명하는 정렬 행이 추가됩니다. 정보를 더 보려면, 왜 크리에이티브 메트릭은 음수 값을 포함할까요? 를 참고하세요.  

샘플 출력

{
    "status": 0,
    "substatus": 0,
    "value": {
        "report_id": "5cfdb747dd464cd09a9c463e5be9691f"
    }
}

사용 가능 한 디멘션과 메트릭

메트릭과 디멘션 용어집을 참고하여 각 필드에 대한 설명을 참조하세요.

네트워크 데이터 

네트워크 디멘션
기본 디멘션 (전 네트워크에 걸쳐 사용 가능):

app
source
adn_campaign_id
adn_campaign_name
adn_campaign_url
data_connector_id
data_connector_source_name
data_connector_username
data_connector_timestamp_utc

선택사항 추가 디멘션 (네트워크에 따라 지원 여부 상이):

os
platform
country_field
region_field
city_field
dma_id_field
dma_name_field
adn_sub_adnetwork_name
adn_account_id
adn_account_name
adn_sub_campaign_id
adn_sub_campaign_name

키워드 또는 퍼블리셔 세부사항 (네트워크에 따라 지원 여부가 상이하며, 크리에이티브 상세사항과 동일한 쿼리에 가져올 수 없음):

keyword_id
keyword
publisher_id
publisher_site_id
publisher_site_name

크리에이티브 세부사항 (네트워크에 따라 지원 여부가 상이하며, 키워드/퍼블리셔와 동일한 쿼리에 가져올 수 없음):

creative_type
adn_creative_id
adn_creative_name
creative_url
creative_image
creative_text
creative_width
creative_height
creative_is_video
asset_id
asset_name

캠페인 특징 (더 보기):

bid_type
bid_strategy
bid_amount
campaign_objective
standardized_bid_type
standardized_bid_strategy
original_bid_amount
campaign_status
min_roas
original_metadata_currency

커스텀 디멘션:

커스텀 디멘션을 네트워크 디멘션에 기반하여 정의했다면, ID를 사용하여 가져올 수 있습니다. 어카운트와 ID에 정의된 모든 커스텀 디멘션을 가져오려면 커스텀 디멘션 엔드포인트를 사용하세요.
네트워크 메트릭
adn_cost
adn_original_cost
adn_original_currency
adn_impressions
adn_clicks
adn_installs

트래커 데이터

트래커 디멘션
기본 디멘션 (전 네트워크에 걸쳐 사용 가능):

app
source
tracker_campaign_id

선택사항 추가 디멘션 (트래커에 따라 지원 여부 상이):

tracker_campaign_name
os
platform
country_field

커스텀 디멘션:

디폴트 트래커 디멘션에 기반한 커스텀 디멘션을 정의했다면, ID를 사용하여 가져올 수 있습니다. 어카운트와 ID에 정의된 모든 커스텀 디멘션을 가져오려면 커스텀 디멘션 엔드포인트를 사용하세요.  
트래커 메트릭
기본 메트릭:

tracker_impressions
tracker_clicks
tracker_installs
tracker_conversions
tracker_reengagements
daily_active_users

코호트 메트릭:

revenue
original_revenue


사용할 수 있는 코호트 메트릭 목록을 보려면, 코호트 메트릭 엔드포인트(Cohort Metrics Endpoint)를 참고하세요. 더 많은 정보는 코호트 메트릭(Cohort Metrics) 및 코호트 기간(Cohort Periods)은 무엇입니까? 를 참고하세요.

코호트 메트릭은 비율에 기반하여 계산하는 CPE와 CPI를 포함합니다. 이 지표들은 API 리포트에 사용하지 않는 것을 권장합니다. (더 보기).

이벤트:

정의한 모든 이벤트에 대한 통계를 가져올 수 있습니다. Singular 앱 내 정의한 이벤트 명 대신에 코호트 메트릭 엔드포인트(Cohort Metrics Endpoint)에서 가져올 수 있는 이벤트의 자동 생성 ID를 사용하세요.  

결합 데이터

디멘션
기본 디멘션 (전 네트워크와 트래커에 걸쳐 사용할 수 있습니다):

app
source
unified_campaign_id
unified_campaign_name

선택사항 추가 디멘션 (네트워크/트래커에 따라 지원여부 상이):

os
platform
country_field
adn_sub_adnetwork_ name
adn_account_id
adn_account_name
sub_campaign_id
sub_campaign_name

키워드 또는 퍼블리셔 세부사항 (네트워크/트래커에 따라 지원 여부가 상이하며, 크리에이티브 세부사항과 동일한 쿼리에 가져올 수 없음):

keyword_id
keyword
publisher_id
publisher_site_id
publisher_site_name

크리에이티브 상세사항 (네트워크에 따라 지원 여부가 상이하며, Singular의 어트리뷰션 서비스 사용자들에게만 제공):

creative_type
adn_creative_id
adn_creative_name
creative_url
creative_image
creative_text
creative_width
creative_height
creative_is_video
asset_id
asset_name

커스텀 디멘션:

디폴트 네트워크 디멘션에 기반하여 커스텀 디멘션을 정의했다면, ID를 사용하여 가져올 수 있습니다. 어카운트와 ID에 정의된 커스텀 디멘션을 모두 가져오려면 커스텀 디멘션 엔드포인트를 사용하세요.
메트릭
기본 메트릭:

adn_cost
adn_original_cost
adn_original_currency
custom_impressions
custom_clicks
custom_installs
tracker_conversions
tracker_reengagements
daily_active_users

비디오 크리에이티브와 비디오 기반 캠페인에 관한 메트릭:

video_views
video_views_25pct
video_views_50pct
video_views_75pct
completed_video_views
completed_video_view_rate

코호트 메트릭:

revenue
original_revenue

사용할 수 있는 모든 코호트 메트릭에 대한 목록을 보려면, 코호트 메트릭 엔드포인트를 참고하세요. 추가 정보는, What are cohort metrics?를 참고하세요.

코호트 메트릭은 비율에 기반하여 계산하는 CPE와 CPI를 포함합니다. 이 지표들은 API 리포트에 사용하지 않는 것을 권장합니다. (더보기).

이벤트:

정의한 모든 이벤트에 관한 통계를 가져올 수 있습니다. Singular 앱 내 정의한 이벤트 명 대신 코호트 메트릭 엔드포인트(Cohort Metrics Endpoint)에서 가져올 수 있는 이벤트의 자동 생성 ID를 사용하세요.  

참고:

  • Singular는 가능한 높은 수준의 세분성을 제공하려 하지만, 모든 네트워크와 트래커가 모든 세부내역을 지원하지는 않습니다. 데이터 커넥터 세부사항을 참고하여 Singular가 각 소스로부터 가져오는 데이터가 무엇인지 확인하세요.
  • 광고 매체로부터 보고되는 노출(impression), 클릭, 인스톨과 같은 통계는 트래커에 의해 보고되는 통계와 일치하지 않을 수 있습니다. 
  • 크리에이티브 수준 통합 리포트(Creative-level combined reports)는 싱귤러의 어트리뷰션 서비스를 사용하는 유저들에 한하여 사용할 수 있습니다. 
  • 커스텀 메트릭은 크리에이티브 세부사항에 사용할 수 없습니다. 네트워크 메트릭 ("adn_…") 또는 트래커 메트릭 ("tracker_…")을 선택하여 확인하세요.

사용 가능한 데이터 엔드포인트

GET https://api.singular.net/api/v2.0/data_availability_status

사용법

이 엔드포인트는 특정한 날에 대하여 각 소스와 데이터 커넥터로부터 데이터를 확인할 수 있는 지의 여부를 반환합니다.

일별 리포트를 실행하기 전에 이 엔드포인트로 전일 데이터를 확인할 수 있는지 확인하는 것을 권장합니다. 

샘플 쿼리 (파이썬)

import requests
url = "https://api.singular.net/api/v2.0/data_availability_status" queryparams = { "api_key":"<API_KEY>", "expanded":"true", "format": "json", "data_date":"2021-02-01", "display_non_active_sources":"true" } response = requests.get(url=url, params=queryparams)

쿼리 파라미터

파라미터 형식 설명
api_key 문자열 Singular 콘솔에 제공된 API 키입니다.
expanded
불리안(Boolean) data_connector_id field를 포함한 각 데이터 커넥터 결과를 가져오기 위해서 "true"로 설정합니다. 그 후 비동기 리포트 엔드포인트 내 리포트를 실행하실 때, 결과 값을 data_connector_id로 필터할 수 있습니다. 백워드 호환성의 디폴트 값은 "false"입니다.
format 문자열 출력 형식: "json" 또는 "csv"입니다.
data_date 날짜 데이터 호환성을 확인한 날짜입니다.
display_non_active_sources 불리안(Boolean) [선택 사항] 활성화되지 않은 데이터 커넥터(과거 30일 동안, 데이터가 없던 데이터 커넥터)를 포함하려면 "true"를 설정하세요. 

샘플 출력 (expanded = true일 때)

{
    "status": 0, 
    "substatus": 0, 
    "value": {
        "is_all_data_available": false,
        "data_connectors": [{
            "data_connector_id": "dgd7934875", 
            "data_connector_source_name": "Vungle", 
            "data_connector_username": "ua@mycompany.com", 
            "is_active_last_30_days": true, 
            "is_available": true, 
            "is_empty_data": false, 
            "last_updated_utc": "2021-02-08T10:10:07", 
            "data_connector_timestamp_utc": "2021-02-08T10:10:07", 
            "status": "data populated"
        }, {
            "data_connector_id": "youi293478", 
            "data_connector_source_name": "IronSource", 
            "data_connector_username": "ua@mycompany.com", 
            "is_active_last_30_days": true, 
            "is_available": false, 
            "is_empty_data": "N/A", 
            "last_updated_utc": "N/A", 
            "data_connector_timestamp_utc": "N/A", 
            "status": "data not populated"
        }]
    }
}

출력 파라미터

파라미터 형식 설명
is_all_data_available 불리안(Boolean) 주어진 기간에 대하여 모든 데이터 커넥터로부터 데이터가 사용 가능할 경우 true이며, 이 외의 경우는 false입니다.
data_connectors
  각 데이터 커넥터의 JSON 오브젝트를 포함하는 배열입니다.
데이터 커넥터 당 파라미터
data_connector_id
문자열 데이터 커넥터의 고유 확장자입니다. 이 확장자를 사용하여 비동기 리포트 생성(Create Async Report) 내 리포트를 필터 할 수 있습니다.
is_available 불리안(Boolean) 주어진 기간에 특정 데이터 커넥터에 데이터가 있다면 true입니다. 
data_connector_timestamp_utc 타임 스탬프

주어진 기간 중 데이터 커넥터로부터 데이터를 가져온 가장 마지막 날짜와 시간을 의미합니다. 기록 데이터를 검사할 때 Singular에 현재 BI 플랫폼에 있는 데이터 외 새로운 데이터가 있는지 확인하려면 이 필드를 사용합니다. 

is_empty_data 불리안(Boolean) 특정 데이터 커넥터에서 데이터를 성공적으로 추출했지만, 데이터가 비어 있는 경우(모두 0 또는 N/A 값) true입니다. 데이터를 가져왔고 실제 값이 포함된 경우 False입니다. 데이터를 아직 가져오지 않은 경우 이 필드는 "N/A"를 포함합니다.
status 문자열

데이터 상태에 관한 추가 정보입니다. 가능한 값들은 다음과 같습니다. 

  • "Data Populated": 데이터가 채워졌습니다.
  • "Data not Populated": 아직 데이터도 없고, 문제도 없습니다.
  • "Login Error": 인증 정보에 문제가 있어 Singular에서 데이터를 가져오지 못했습니다.
  • "Setup" 또는 "Not configured": 소스에 데이터 커넥터가 설정되지 않았거나, 구성에 문제가 있습니다.
  • "Disabled": 데이터가 수동으로 비활성화되었습니다.
is_active_last_30_days 불리안(Boolean) 지난 30일 동안, 이 데이터 커넥터에 적어도 한 번 이상 데이터가 모두 채워진 경우 true입니다.
last_updated_utc 타임 스탬프 데이터 커넥터에 대하여 가장 최근 Singular 데이터베이스에 데이터가 저장된 시간을 나타냅니다. 주의: 데이터 커넥터에서 데이터를 가져온 시간으로부터 데이터베이스에 데이터가 저장된 시간까지 몇 시간 정도 간격이 있을 수 있습니다. 

샘플 출력 ("expanded" 파라미터가 포함되지 않거나 false로 설정된 경우)

{'is_all_data available': false,
'data_sources': [
{'username': u'facebook@singular.net',
 'status': 'data populated',
 'is_empty_data': false,
 'is_active_last_30_days': true,
 'last_updated_utc': '2018-05-03T10:12:18'
 'source': u'Facebook',
 'is_available': true},
 {'username': u'vungle@singular.net',
 'status': 'data populated',
 'is_empty_data': true,
 'is_active_last_30_days': true,
 'last_updated_utc': '2018-05-03T10:12:18'
 'source': u'Vungle',
 'is_available': true},
 {'username': u'applovin@singular.net',
 'status': 'data not populated',
 'is_empty_data': N/A,
 'is_active_last_30_days': true,
 'last_updated_utc': N/A
 'source': u'Applovin',
 'is_available': false}
]}

출력 파라미터

파라미터 형식 설명
is_all_data_available 불리안(Boolean) 주어진 날짜에 모든 데이터 커넥터에 데이터가 있는 경우 true입니다. 이 외의 경우는 false입니다. 
is_available 불리안(Boolean) 주어진 날짜에 특정한 데이터 커넥터에 데이터가 있는 경우 true입니다. 이 외의 경우는 false입니다.
is_empty_data 불리안(Boolean) 특정 소스에서 데이터가 성공적으로 추출되었지만, 데이터가 비어 있는 경우(모두 0 또는 "N/A" 값) true입니다.
status 문자열 데이터에 관한 추가 정보입니다. 가능한 값은 다음과 같습니다. 
  • "Data Populated": 데이터가 채워졌습니다.
  • "Data not Populated": 아직 데이터도 없고, 문제도 없습니다.
  • "Login Error": 인증 정보에 문제가 생겨 Singular에서 데이터를 가져오지 못했습니다.
  • "Setup" 또는 "Not configured": 이 소스의 데이터 커넥터가 설정되지 않았거나, 구성에 문제가 있습니다.
  • "Disabled": 데이터 커넥터가 수동으로 비활성화되었습니다.
데이터 가용성 엔드포인트(Data Availability Endpoint)를 쿼리 했고 한 개 이상의 데이터가 누락되었습니다. 어떡할까요?를 참고하세요.
is_active_last_30_days 불리안(Boolean) 지난 30일 동안 적어도 하루 이상의 데이터가 0이 아니었다면 true입니다. 이 외의 경우는 모두 false입니다.
last_updated_utc 타임스탬프 데이터 커넥터에 대하여 Singular 데이터베이스에서 데이터를 저장한 가장 최근 시간을 나타냅니다. 주의: 데이터를 데이터 커넥터로부터 가져온 시간으로부터 데이터가 데이터베이스에 저장된 시간까지 몇 간 정도의 간격이 있을 수 있습니다. 

리포트 상태 엔드포인트 획득

GET https://api.singular.net/api/v2.0/get_report_status

사용법

이 엔드포인트는 비동기 리포트 생성 엔드포인트를 사용하여 생성된 리포트의 상태를 반환합니다. 리포트 실행이 끝나면, 엔드포인트가 다운로드 URL를 반환합니다.

Screen_Shot_2020-07-01_at_0.17.35.png

리포트 실행이 실패했다면, 엔드포인트는 문제를 확인할 수 있는 에러 메시지를 반환합니다. (에러 코드 테이블, API FAQ와 트러블슈팅 가이드를 참고하세요).

더 많은 정보는, Singular 리포팅 API 가이드쿼리 프로세스 구문을 참고하세요.

중요한 사항

  • 리포트가 완료되기까지 몇 분 정도 소요될 수 있습니다.
  • 리포트 상태 엔드포인트(report status endpoint)는 각 리포트 당 10초 이상의 간격을 두고 쿼리하세요.  
  • 타임아웃을 설정하세요. 드문 경우이나, 리포트가 "Queued" 또는 "Started" 상태에 걸릴 수 있습니다. 만약 상태 리포트가 30분 이후에도 "완료"되지 않거나 "실패"한 경우, 리포트를 다시 제출하는 것을 권장합니다. (이는 쿼리를 위한 새 리포트 ID를 제공합니다).

샘플 쿼리

import requests
url = "https://api.singular.net/api/v2.0/get_report_status"
querystring = {
  "report_id":"5cfdb747dd45be9691f",
  "api_key": "<API KEY>"
}
response = requests.get(url=url, params=querystring)
print(response.text)

쿼리 파라미터

파라미터 형식 설명
api_key 문자열 Singular 콘솔 내 제공된 API key입니다.
report_id 문자열 비동기 리포트 엔드포인트 생성(Create Async Report endpoint) 에 의해 반환된 리포트 ID입니다.

샘플 출력

{
  "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"
  }
}

출력 파라미터

출력 파라미터

형식 설명
status 문자열 가능한 값들은 다음과 같습니다.
  • "QUEUED": 리포트가 큐(queue)에서 대기 중입니다.
  • "STARTED": 리포트가 실행 중입니다.
  • "DONE": 리포트가 준비되었습니다. download_URL 파라미터를 참조하여 리포트 파일을 다운로드할 수 있는 URL을 확인하세요.
  • "FAILED": 리포트가 실패했습니다. 첨부된 에러 메시지 및  에러 코드 테이블을 참조하고 API FAQ와 트러블슈팅 페이지에서 도움을 구하세요.
generated_url_time_in_utc 타임 스탬프  
url_expires_in 정수 다운로드 URL이 만료되기까지 걸리는 시간(초)입니다.
url_expired_time_in_utc

타임스 탬프

 
download_url URL  
report_id 문자열  

엔드포인트 필터

GET https://api.singular.net/api/v2.0/reporting/filters

사용법 

이 엔드포인트 도우미를 사용하여 필터할 수 있는 디멘션과 각 디멘션에 관해 사용할 수 있는 값의 최신 목록을 검색할 수 있습니다. 

샘플 쿼리

import requests
url = "https://api.singular.net/api/v2.0/reporting/filters"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

쿼리 파라미터

파라미터 형식 설명
api_key 문자열 Singular 콘솔에 제공된 API 키입니다.

샘플 출력

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

커스텀 디멘션 엔드포인트

GET https://api.singular.net/api/custom_dimensions

사용법

어카운트에 설정된 모든 커스텀 디멘션들의 ID를 검색하기 위해 이 엔드포인트를 사용하세요. 비동기 리포트 생성(Create Asnyc Report)을 쿼리 할 때 (디폴트 디멘션 대신 또는 추가로) 이 커스텀 디멘션 ID를 사용할 수 있습니다. 

커스텀 디멘션에 대한 정보와 생성하는 법을 알아보려면, 커스텀 디멘션 FAQ를 참고하세요.

샘플 쿼리

import requests
url = "https://api.singular.net/api/custom_dimensions"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

쿼리 파라미터

파라미터 형식 설명
api_key 문자열 Singular 콘솔에 제공된 API key입니다.

샘플 출력

{
  "status": 0,
  "substatus": 0,
  "value": {
    "custom_dimensions": [
      {"display_name": "Channel Type", "id": "e471cb6b83684532e5e83cd"},
      {"display_name": "Region", "id": "1dcfdb1ad861fba4b098e2"}
    ]
  }
}

코호트 메트릭 엔드포인트

GET https://api.singular.net/api/cohort_metrics

사용법

이 엔드포인트를 사용해서 어카운트에 관한 모든 코호트 메트릭과 사용할 수 있는 코호트 기간에 대하여 검색하세요. 이것은 귀사가 Singular에서 트래킹하도록 설정한 모든 인앱 이벤트를 포함합니다. (이벤트 FAQ 참고). 쿼리를 비동기 리포트 생성 엔드포인트(Create Async Report endpoint)에서 쿼리할 때 이 메트릭과 기간을 명시할 수 있습니다.

비동기 리포트 생성(Create Async Report endpoint)에서는 "display name"이 아닌 "name"을 사용하세요. 

샘플 쿼리

import requests
url = "https://api.singular.net/api/cohort_metrics"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

쿼리 파라미터

파라미터 형식 설명
api_key 문자열 Singular 콘솔에 제공된 API 키입니다.

샘플 출력

{
    "status": 0,
    "substatus": 0,
    "value": {
        "metrics": [
            {"display_name": "ROI","name": "roi"},
            {"display_name": "Revenue","name": "revenue"}
        ],
        "periods": ["1d","3d","5d","7d","14d","30d","actual"]
    }
}

출력 파라미터

출력 파라미터  형식 설명
display_name 문자열 Singular 웹 앱에 나타나는 메트릭 명입니다.
name 문자열 API 쿼리에 사용하는 메트릭 식별자입니다.
periods 배열 어카운트에 지원되는 모든 코호트 기간입니다. 더 많은 정보는, 코호트 메트릭과 코호트 기간이란 무엇인가요? 를 참고하세요.

컨버전 메트릭 엔드포인트

GET https://api.singular.net/api/conversion_metrics

사용법

이 엔드포인트를 사용하여 어카운트에서 사용 가능한 모든 컨버전 이벤트를 검색하는 데 사용하세요.  비동기 리포트 생성 엔드포인트(Create Async Report endpoint)의 쿼리를 실행할 때 이 이벤트를 메트릭으로써 명시할 수 있습니다.    

비동기 리포트 생성 쿼리에서는 "display name"이 아니라 메트릭의 "name"을 사용하여 쿼리 해야 합니다.

샘플 쿼리

import requests
url = "https://api.singular.net/api/conversion_metrics"
params = {'api_key': "<API KEY>"}
result = requests.get(url=url, params=params)
print result.json()

쿼리 파라미터

파라미터 형식 설명
api_key 문자열 Singular 콘솔에 제공된 API 키입니다

샘플 출력

{
  "status": 0, 
  "substatus": 0, 
  "value": {
    "metrics": [
      {"display_name": "5-second video view", "name": "87dfg34453hsfg6f"}, 
      {"display_name": "5-second video view CPE", "name": "87dfg34453hsfg6fCPE"},   
      {"display_name": "Sign up", "name": "iuq353fidr76w846fha"}, 
      {"display_name": "Sign up CPE", "name": "iuq353fidr76w846fhaCPE"}, 
      {"display_name": "Post engagement", "name": "b59cje9fcgw0th"}, 
      {"display_name": "Post engagement CPE", "name": "b59cje9fcgw0thCPE"},
    ]
  }
}

출력 파라미터

출력 파라미터 형식 설명
display_name 문자열 이벤트 페이지 내에 설정된 컨버전 이벤트 명입니다.
name 문자열 이벤트의 자동 생성 식별자입니다. 리포트를 쿼리 할 때 이 식별자를 사용하세요.

에러 코드

Singular는 HTTP 응답을 기준으로 API 요청이 성공 또는 실패하였는지 판단합니다. 일반적으로, 200 코드는 성공을 의미하며, 4xx 범위의 코드는 주어진 정보에 대해 실패하여 일어난 에러를 의미하며 (예, 필수 파라미터 누락), 5xx 코드는 다른 이슈가 있음을 나타냅니다.

다음 리포팅 API FAQ와 트러블슈팅 문서도 참고하세요.

코드 에러 내용 추가 정보
400 An invalid timestamp was given. The timestamp must be of the format: YYYY-MM-DD hh:mm:ss. 다음과 같은 타임 스탬프를 명시합니다.
2018-01-01 00:00:01
400 An invalid date was given. The date must be of the format: YYYY-MM-DD. 다음과 같은 날짜를 명시합니다.
2018-01-20
400 An invalid date range was given. End date must be later than start date.  
400 An invalid time breakdown was given. 쿼리에서 time breakdown 파라미터가 누락되었거나 지원하는 옵션이 아닌 경우입니다. 지원 옵션: "day", "week", "month", "all"
400 An invalid filter was given. 쿼리 내 사용 할 수 있는 필터 목록을 확인하기 위하여 필터 엔드포인트(Filters endpoint)를 사용합니다.
400 At least one metric must be used. 쿼리 내 적어도 한 메트릭을 포함합니다.
400 The requested data set includes publisher dimensions and extends beyond a single day. Please run single day queries with publisher dimensions. 퍼블리셔에 의해 세분화된 리포트들로 다량의 데이터를 포함합니다. 이 리포트들의 실행은 하루에 한 번으로 제한됩니다.
400 An invalid result format was given. Please select between JSON and CSV.  
400 An invalid country_code_format was given. Please use "iso3" or "iso".  
400 The request contains invalid dimensions:. 쿼리에서 요청한 하나 이상의 디멘션이 곧 사라지는 기능이거나 사용할 수 없는 경우입니다. 만약 커스텀 디멘션을 (커스텀 디멘션 엔드포인트를 통해) 사용했다면, 그 디멘션이 사용 가능한지 확인하고 디멘션 ID(display name이 아닌)를 사용했는지 다시 한번 확인하세요.
400 The request contains duplicate fields:. [list]  
400 The request contains invalid metrics:. 쿼리에서 요청한 하나 이상의 메트릭이 곧 사라지는 기능이거나 사용할 수 없는 경우입니다. 만약 코호트 메트릭 또는 컨버전 이벤트를 (코호트 메트릭과 컨버전 이벤트 엔드포인트를 통해) 사용했다면, 사용 가능 여부를 다시 한번 확인하고 메트릭 명(display name이 아닌)을 사용했는지 다시 한번 확인하세요.  
400 The request contains invalid cohort periods:. 코호트 메트릭 엔드포인트를 사용하여 어카운트에서 어떤 코호트 기간을 사용할 수 있는지 확인하세요.
400 We could not find cohort periods for the following cohort metrics:. 코호트 메트릭에 대한 코호트 기간을 추가하세요.
400 The request contains dimensions from an old API version:. Please use dimensions from the v2 API endpoint only. 여러 API 버전의 디멘션을 포함한 요청은 지원되지 않습니다.
400 The request is missing the following parameter:.  
401 An invalid API Key was given. 해당 API 키가 누락되었거나 사용할 수 없습니다. API 키를 획득하려면 Singular 어카운트로 로그인하여 Settings에서 확인하세요.
401 The provided API key has been previously deactivated. Please contact your administrator. 비활성화된 유저의 API 키를 사용하고 있습니다. API 키를 획득하려면 Singular 어카운트로 로그인하여 Settings에서 확인하세요.
403 The provided API key does not have permissions to view the field:. 제공된 해당 API 키는 요청한 디멘션이나 메트릭을 열람할 수 있는 권한이 없습니다. 해당 권한이 있는지 귀사의 관리자를 통해 확인하세요.
403 The request is denied access. Please contact your administrator. 요청이 거부되었습니다. 자세한 정보는 귀사의 관리자를 통해 확인하세요.
404 Report ID is not found. Please correct it or create a new report. 비동기 리포트 생성 엔드포인트(Create Async Report endpoint)로부터 반환된 리포트 ID를 사용했는지 다시 한번 확인하세요. 계속하여 에러가 난다면, 새 리포트를 생성하세요.
404 Report ID was created with a different key. Please use the same key when requesting status. 리포트 상태를 쿼리 하려면, 리포트를 생성할 때 사용한 API를 사용하세요.
405 METHOD NOT ALLOWED http 요청에서 POST 대신 GET을 사용하거나 반대로 사용하고 있을 수 있습니다.
429 Query quota is exceeded: only <> reports are currently allowed. The following report IDs are active:. 동시에 실행 가능한 비동기 리포트양을 초과했습니다. 이전 요청이 완료될 때까지 기다리세요.
429 Too many requests. Only <> requests per second is currently allowed. 요청 제한을 초과했습니다. 이전 요청이 완료될 때까지 기다리세요.
500 The request has failed due to an internal error. 일반적으로, API 콜을 다시 시도하라는 의미입니다. 500 에러는 어떡해야 할까요?를 참고하세요.
도움이 되었습니까?