> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.metric.works/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Polaris 보고 API

# 엔드포인트(Endpoints)

Polaris 보고 API는 다음 위치에서 확인하실 수 있습니다:
 
https://inc-metrics.prod.api.metric.works
 
엔드포인트는 다음과 같습니다:
 
* https://inc-metrics.prod.api.metric.works/token - 인증을 위한 보안 토큰 획득
* https://inc-metrics.prod.api.metric.works/query - 보고 데이터를 얻기 위해 쿼리 제출

---

# 제한(Limits)

API에는 다음과 같은 제한이 있습니다:

| 제한 | 값 |
| --- | --- |
| 요청 비율 | 계정당 분당 10개 요청 |
| 동시 요청 | 1 |
| 날짜 범위 | 요청당 최대 30일 |
| 앱 필터 | 요청당 앱 1개(Polaris의 전체 앱 이름을 [필터](https://help.metric.works/ko/article/polaris-api-10g7p1m/#1-filters)값으로 사용) |

---

# 인증(Authentication)

보고 API의 쿼리 엔드포인트에 대한 모든 요청은 토큰 엔드포인트에서 얻은 보안 토큰을 지정해야 합니다. 보안 토큰을 얻으려면 다음 JSON 본문이 다음 JSON 본문을 포함하는 요청을 게시하십시오:

```
{ "username": "my.email@company.com", "password": "mypassword" }
```
위의 사용자 이름 및 비밀번호 자리 표시자 값(`my.email@company.com` and `mypassword`)을 실제 Polaris 사용자 이름(이메일 주소) 및 비밀번호로 바꾸십시오.
성공하면 응답은 쿼리 요청에 다음과 같이 Authorization 헤더의 Bearer 토큰으로 지정되어야 하는 텍스트 보안 토큰이 됩니다:

```
Authorization: Bearer [security token]
```
위의 헤더 예제에서 `[security token]` 자리 표시자를 보안 토큰으로 바꿉니다. 보안 토큰은 토큰 엔드포인트에서 가져온 시점부터 1시간 동안 유효합니다. 만료된 보안 토큰을 지정하면 쿼리 엔드포인트에서 401 Unauthorized 응답이 발생합니다.

---

# 쿼링(Querying)

보고 API에서 보고 데이터를 조회 하려면 다음 속성 중 하나 이상을 포함하는 요청을 게시하십시오:

| 속성명 | 설명 | 예시 | 필수사항 |
| --- | --- | --- | --- |
| startDate | 희망 시작 날짜입니다. 형식: `yyyy-mm-dd`. | ```2021-01-01``` | 예 |
| endDate | 희망 종료 날짜입니다. 형식: `yyyy-mm-dd`. | ```2021-01-31``` | 예 |
| groupBy | 결과를 그룹화할 기준이 되는 수준을 나타내는 배열입니다. 그룹화 기준 [Group By](https://help.metric.works/ko/article/polaris-api-10g7p1m/#1-group-by)를 참조하세요. | ```["CHANNEL", "COUNTRY"]``` | 예 |
| metrics | 반환되어야 하는 지표를 나타내는 배열입니다. 측정항목 [Metrics](https://help.metric.works/ko/article/polaris-api-10g7p1m/#1-metrics)를 참조하세요. | [예시](https://help.metric.works/ko/article/polaris-api-10g7p1m/#2-metrics) | 예 |
| filters | 결과를 필터링해야 하는 값을 나타내는 배열입니다. 필터 [Filters](https://help.metric.works/ko/article/polaris-api-10g7p1m/#1-filters)를 참조하세요. | [예시](https://help.metric.works/ko/article/polaris-api-10g7p1m/#2-filters) | 아니오 |
| orderBy | 결과를 정렬해야 하는 디멘션을 나타내는 배열입니다. 주문 [Order By](https://help.metric.works/ko/article/polaris-api-10g7p1m/#1-order-by)를 참조하세요. | [예시](https://help.metric.works/ko/article/polaris-api-10g7p1m/#2-order-by) | 아니오 |

---

# 그룹화(Group By)

하기 표는 `groupBy` 속성에서 유효한 값으로 사용할 수 있는 수준을 설명합니다. 그룹화는 반환된 결과의 세분성으로 생각할 수 있습니다.

| 값 | 설명 |
| --- | --- |
| DATE | 날짜 |
| PLATFORM | 플랫폼 |
| APP | 앱 |
| CHANNEL | 채널 |
| CAMPAIGN_GROUP | 캠페인 |
| COUNTRY | 국가 |
| SITE | 사이트 |

---

# 측정 항목(Metrics)

'metrics' 속성에 나열된 각 지표 개체는 다음과 같이 지정해야 합니다.

| 속성명 | 설명 | 예시 | 필수사항 |
| --- | --- | --- | --- |
| type | 측정항목의 유형입니다. 유효값은 아래 표를 참조하십시오. | ```COHORT_REVENUE``` | 예 |
| day | 측정항목의 코호트 날짜입니다. 측정항목이 코호트 지표인 경우에만 필요합니다. | ```7``` | 아니오 |
| interval | 95% 신뢰 구간도 반환해야 하는지 여부입니다. 측정항목이 증분 지표인 경우에만 적용 가능합니다. | ```true``` | 아니오 |

아래 표는 각 지표 개체의 `type` 속성에서 유효한 값으로 사용할 수 있는 측정항목 유형을 설명합니다. `INC_`

접두사가 붙은 측정항목 유형만 증분 지표입니다. 다른 지표들는 라스트 터치입니다.

| 값 | 설명 | 코호트 여부 |
| --- | --- | --- |
| SPEND | spend | 아니오 |
| NEW_USERS | Installs or registrations | 아니오 |
| INC_NEW_USERS | Incrementality installs or registrations | 아니오 |
| COHORT_SIZE | Cohort size | 예 |
| INC_COHORT_SIZE | Incrementality cohort size | 예 |
| RETAINED_USERS | Retained users | 예 |
| INC_RETAINED_USERS | Incrementality retained users | 예 |
| COHORT_REVENUE | Cohorted revenue | 예 |
| INC_COHORT_REVENUE | Incrementality cohorted revenue | 예 |
| COHORT_AD_REVENUE | Ad revenue | 예 |
| INC_COHORT_AD_REVENUE | Incrementality ad revenue | 예 |
| COHORT_IAP_REVENUE | Purchase revenue | 예 |
| INC_COHORT_IAP_REVENUE | Incrementality purchase revenue | 예 |
| RETENTION_RATE | Retention rate | 예 |
| INC_RETENTION_RATE | Incrementality retention rate | 예 |
| COST_PER_NEW_USER | CPI or cost per acquisition | 아니오 |
| INC_COST_PER_NEW_USER | Incrementality CPI or cost per acquisition | 아니오 |
| ROAS | Return on ad spend | 예 |
| INC_ROAS | Incrementality return on ad spend | 예 |
| LTV | Lifetime value or average revenue per user (ARPU) | 예 |
| INC_LTV | Incrementality lifetime value or average revenue per user (ARPU) | 예 |
| COHORT_PURCHASES | Number of purchases or subscriptions | 예 |
| INC_COHORT_PURCHASES | Incrementality number of purchases or subscriptions | 예 |
| COHORT_SESSIONS | Cohorted sessions | 예 |
| INC_COHORT_SESSIONS | Incrementality cohorted sessions | 예 |
| COHORT_PAYING_USERS | Cohorted number of unique users with at least one purchase | 예 |
| INC_COHORT_PAYING_USERS | Incrementality cohorted number of unique users with at least one purchase | 예 |
| COHORT_PAYING_RATE | Cohorted % of users that made at least 1 purchase | 예 |
| INC_COHORT_PAYING_RATE | Incrementality cohorted % of users that made at least 1 purchase | 예 |

## Metrics 예시
```
[
  {
    "type": "INC_NEW_USERS",
    "interval": true
  },
  {
    "type": "NEW_USERS"
  },
  {
    "type": "INC_ROAS",
    "day": 3,
    "interval": false
  },
  {
    "type": "ROAS",
    "day": 3
  }
]
```

---

# 필터(Filters)

'filters' 속성에 나열된 각 필터 개체는 다음 속성을 지정해야 합니다.

| 속성명 | 설명 | 예시 | 필수사항 |
| --- | --- | --- | --- |
| type | [그룹으로 유효한 값](https://help.metric.works/ko/article/polaris-api-10g7p1m/#1-group-by)을 사용하는 필터의 디멘션입니다. | ```CHANNEL``` | 예 |
| values | 디멘션을 필터링할 값을 나타내는 배열입니다. | ```["Facebook"]``` | 예 |
| not | 필터를 무효화해야 하는지 여부입니다. | ```false``` | 아니오 |


## Filters 예시

```
[
  {
    "type": "CHANNEL",
    "values": ["Facebook"],
    "not": false
  }
]
```

---

# 주문(Order By)

'orderBy' 속성에 나열된 각 개체별 주문은 다음 속성을 지정해야 합니다.

| 속성명 | 설명 | 예시 | 필수사항 |
| --- | --- | --- | --- |
| type | [그룹으로 유효한 값](https://help.metric.works/ko/article/polaris-api-10g7p1m/#1-group-by)을 사용하여 주문의 디멘션입니다. | ```CHANNEL``` | 예 |
| descending | 기본 오름차순이 아닌 내림차순으로 정렬할지 여부입니다. | ```false``` | 아니오 |

## Order By 예시

```
[
  {
    "type": "CHANNEL",
    "descending": false
  }
]
```

---

# 코드(Code) 예시

다음은 Python으로 작성된 코드 샘플입니다. 내결함성, 오류 처리 또는 [조절(throttling)](throttling)을 구현하지 않지만 기본 사항에 대한 아이디어를 제공해야 합니다.

```
import requests

token_endpoint = "https://inc-metrics.prod.api.metric.works/token"
query_endpoint = "https://inc-metrics.prod.api.metric.works/query"

username = "username"
password = "password"

credentials = {
    "username": username,
    "password": password
}

query = {
    "groupBy": [
        "CHANNEL"
    ],
    "metrics": [
        {
            "type": "INC_NEW_USERS",
            "interval": True
        }
    ],
    "filters": [
        {
            "type": "APP",
            "values": ["App Name (iOS)"]
        }
    ],
    "order": [],
    "startDate": "2022-06-01",
    "endDate": "2022-06-01"
}

token_response = requests.request("POST", token_endpoint, json=credentials)

headers = {'Authorization': 'Bearer ' + token_response.text}

query_response = requests.request("POST", query_endpoint, headers=headers, json=query)

print(query_response.text)
```