ugwanggi Partner API

소셜미디어(YouTube · Instagram) 마케팅 데이터를 제공하는 파트너용 REST API입니다. 크리에이터 · 콘텐츠 · 트렌드 데이터를 조회할 수 있습니다.

Base URL https://partner-api.ugwanggi.com

모든 응답은 application/json (UTF-8)이며, 인증은 API 키(Bearer)로 이루어집니다. 아래 Quickstart로 1분 안에 첫 요청을 보낼 수 있습니다.

Quickstart

발급받은 API 키(ug_live_로 시작)를 Authorization 헤더에 담아 요청합니다.

curl -H "Authorization: Bearer ug_live_xxxxx" \
  "https://partner-api.ugwanggi.com/v1/creators?sort=subscriber_growth&limit=10"

import requests

resp = requests.get(
    "https://partner-api.ugwanggi.com/v1/creators",
    headers={"Authorization": "Bearer ug_live_xxxxx"},
    params={"sort": "subscriber_growth", "limit": 10},
)
print(resp.json())

const params = new URLSearchParams({ sort: "subscriber_growth", limit: 10 });

const resp = await fetch(
  `https://partner-api.ugwanggi.com/v1/creators?${params}`,
  { headers: { Authorization: "Bearer ug_live_xxxxx" } },
);
const data = await resp.json();
console.log(data);

Authentication

모든 요청에 API 키를 Bearer 토큰으로 포함해야 합니다. 키는 발급 시 1회만 전달되며 안전하게 보관하세요. 노출이 의심되면 재발급(로테이션)을 요청하면 됩니다.

Authorization: Bearer ug_live_xxxxxxxxxxxxxxxxxxxxxxxx

headers = {"Authorization": "Bearer ug_live_xxxxxxxxxxxx"}

const headers = { Authorization: "Bearer ug_live_xxxxxxxxxxxx" };

키가 없거나 유효하지 않으면 401 Unauthorized를 반환합니다.

Errors

코드	의미
`401`	API 키 누락 · 유효하지 않음 · 만료
`422`	파라미터 형식 오류 (범위 초과 등)
`429`	요청 속도 제한 초과 — 잠시 후 재시도
`5xx`	서버 오류 — 지속되면 문의

크리에이터 목록 조회

조건에 맞는 YouTube 크리에이터를 정렬·필터하여 반환합니다.

GET /v1/creators

Query parameters

이름	타입	설명
`sort` optional	enum	정렬 기준 (아래 값 참고). 기본 `subscribers`
`order` optional	`asc` · `desc`	정렬 방향. 기본 `desc`
`limit` optional	integer (1–100)	가져올 개수. 기본 20
`offset` optional	integer (≥0)	페이지네이션 시작 위치
`category` optional	string	카테고리. 예: 뷰티, 패션, 푸드, 여행, 육아, 운동
`min_subscribers` optional	integer	최소 구독자 수
`max_subscribers` optional	integer	최대 구독자 수 (숨은 라이징 탐색 등)
`has_ad` optional	boolean	광고 이력 보유 여부
`country` optional	string	국가 코드. 예: `KR`
`q` optional	string	채널명 검색어

`sort` 값

subscribers 구독자 수 subscriber_growth 최근 성장률 avg_views 평균 조회수 avg_views_short 숏폼 평균 조회수 view_efficiency 구독자 대비 조회효율 ad_views 광고 평균 조회수 engagement 참여율 recent_ad 최근 광고 활동 trend 트렌드 편입

Request

curl -H "Authorization: Bearer ug_live_xxxxx" \
  "https://partner-api.ugwanggi.com/v1/creators?sort=subscriber_growth&order=desc&limit=10"

import requests

resp = requests.get(
    "https://partner-api.ugwanggi.com/v1/creators",
    headers={"Authorization": "Bearer ug_live_xxxxx"},
    params={
        "sort": "subscriber_growth",
        "order": "desc",
        "limit": 10,
        # "category": "뷰티",
        # "max_subscribers": 100000,
    },
)
print(resp.json())

const params = new URLSearchParams({
  sort: "subscriber_growth",
  order: "desc",
  limit: 10,
});

const resp = await fetch(
  `https://partner-api.ugwanggi.com/v1/creators?${params}`,
  { headers: { Authorization: "Bearer ug_live_xxxxx" } },
);
const data = await resp.json();
console.log(data);

Response

{
  "platform": "youtube",
  "total": 12345,
  "limit": 10,
  "offset": 0,
  "sort": "subscriber_growth",
  "order": "desc",
  "data": [
    {
      "channel_id": "UCxxxxxxxx",
      "title": "채널명",
      "thumbnail": "https://...",
      "email": "contact@example.com",
      "countryCode": "KR",
      "Main_tag1": "뷰티",
      "topic": "beauty",
      "subscribers": 523000,
      "totalViews": 87000000,
      "total_videos": 412,
      "average_views": 95000,
      "average_views_short": 210000,
      "average_views_subs": 0.18,
      "engagement_rate": 0.042,
      "short_ratio": 0.63,
      "subs_growth_3_months": 0.12,
      "has_ad": true,
      "average_views_ads": 88000,
      "last_ppl_diff": 5,
      "last_update": "2026-06-30"
    }
  ]
}

활용 예시

목적	파라미터
급상승 크리에이터 TOP 10	`?sort=subscriber_growth&order=desc&limit=10`
카테고리별 라이징 (예: 뷰티)	`?category=뷰티&sort=subscriber_growth&limit=10`
광고 반응이 좋은 크리에이터	`?has_ad=true&sort=ad_views&limit=10`
숏폼 도달력이 높은 크리에이터	`?sort=avg_views_short&limit=10`
최근 협찬/광고가 활발한 크리에이터	`?has_ad=true&sort=recent_ad&order=asc&limit=10`
숨은 라이징 크리에이터	`?max_subscribers=100000&sort=view_efficiency&limit=10`

Rate limits

항목	제한
한 번에 가져올 개수	`limit` 최대 100 (기본 20)
속도 제한	IP당 분당 요청 수 제한 (초과 시 `429`)
일일 허용량 추후 적용 예정	현재는 적용되지 않으며, 향후 키별 일일 요청 허용량(`daily_quota`)이 적용될 수 있습니다.