일반 정보

인증

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

제한 사항

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

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

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

리포팅 API 엔드포인트 목록

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

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

이용 사례

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

더 많은 정보는, 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)

쿼리 파라미터

샘플 출력

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

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

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

네트워크 데이터 

트래커 데이터

결합 데이터

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

사용법

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

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

샘플 쿼리 (파이썬)

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)

쿼리 파라미터

샘플 출력 (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': 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}
]}

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

사용법

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

리포트 실행이 실패했다면, 엔드포인트는 문제를 확인할 수 있는 에러 메시지를 반환합니다. (에러 코드 테이블, 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)

쿼리 파라미터

샘플 출력

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

출력 파라미터

엔드포인트 필터

사용법 

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

샘플 쿼리

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

쿼리 파라미터

샘플 출력

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

커스텀 디멘션 엔드포인트

사용법

어카운트에 설정된 모든 커스텀 디멘션들의 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()

쿼리 파라미터

샘플 출력

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

코호트 메트릭 엔드포인트

사용법

이 엔드포인트를 사용해서 어카운트에 관한 모든 코호트 메트릭과 사용할 수 있는 코호트 기간에 대하여 검색하세요. 이것은 귀사가 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()

쿼리 파라미터

샘플 출력

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

출력 파라미터

컨버전 메트릭 엔드포인트

사용법

이 엔드포인트를 사용하여 어카운트에서 사용 가능한 모든 컨버전 이벤트를 검색하는 데 사용하세요.  비동기 리포트 생성 엔드포인트(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()

쿼리 파라미터

샘플 출력

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

출력 파라미터

에러 코드

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

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