오늘의 인기 영상
최신의 안정적인 핫비디오 스냅샷을 읽어보세요.
GET
https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=200 Credits
오늘의 인기 영상#
최신의 안정적인 핫비디오 스냅샷을 읽어보세요.
인증#
Authorization: Bearer sm_live_...를 보냅니다. URL, 쿠키, 본문, 로그 또는 분석에 전체 키를 배치하지 마십시오.
데이터 최신성#
순위는 작업자가 게시한 안정적인 스냅샷을 읽습니다. 공개 읽기는 YouTube 새로 고침을 트리거하지 않습니다.
요구#
| 목 | 값 | 설명 |
|---|---|---|
| 방법 | GET | HTTP 요청 방법 |
| 전체 URL | https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20 | 생산 API URL |
| 인증 | Authorization: Bearer sm_live_... | 헤더에만 전체 키를 보냅니다. |
| 콘텐츠 유형 | 요청 본문 없음 | GET 요청에는 요청 본문이 없습니다. |
| 크레딧 | 0 Credits | 모든 작업의 비용은 0 Credits입니다. 월별 크레딧 지급이나 상업용 크레딧 차감은 없습니다. |
요청 매개변수#
| 이름 | 위치 | 유형 | 필수의 | 기본 | 값 또는 한계 | 설명 |
|---|---|---|---|---|---|---|
region | 질문 | string | 아니요 | 모든 지역 | 2~16자 | US 또는 JP와 같은 지역 코드 |
tier | 질문 | string | 아니요 | all | S / A / B / C / all | 핫 티어 필터 |
limit | 질문 | integer | 아니요 | 20 | 1–50 | 이 페이지의 최대 항목 수 |
all_cursor | 질문 | string | 아니요 | — | data.all_data.next_cursor | 필터링되지 않은 다음 페이지 가져오기 |
filter_cursor | 질문 | string | 아니요 | — | data.filter_data.next_cursor | 필터를 변경하지 않고 필터링된 다음 페이지를 가져옵니다. |
cursor | 질문 | string | 아니요 | — | 더 이상 사용되지 않는 호환성 매개변수 | filter_cursor의 별칭; 둘 다 보내지 마세요 |
성공 응답 필드#
all_data는 안정적인 스냅샷에서 필터링되지 않은 페이지입니다. filter_data는 엔드포인트 기본값 및 요청 필터 이후 동일한 스냅샷의 페이지입니다. 각 결과는 독립적으로 페이지가 매겨집니다.
모든 작업의 비용은 0 Credits입니다. 월별 크레딧 지급이나 상업용 크레딧 차감은 없습니다.
| 필드 경로 | 유형 | 널 입력 가능 | 설명 |
|---|---|---|---|
data.all_data.items | array<object> | 아니요 | 현재 페이지의 필터링되지 않은 비디오 항목 |
data.all_data.items[].video_id | string | 아니요 | YouTube 비디오 ID |
data.all_data.items[].title | string | 아니요 | 비디오 제목 |
data.all_data.items[].video_url | string | 아니요 | YouTube 비디오 URL |
data.all_data.items[].channel.id | string | 예 | 채널 ID |
data.all_data.items[].channel.title | string | 아니요 | 채널 제목 |
data.all_data.items[].channel.subscribers | integer | 예 | 구독자 수; 숨겨진 경우 null |
data.all_data.items[].channel.subscriber_count_hidden | boolean | 아니요 | 구독자 수 숨김 여부 |
data.all_data.items[].views | integer | 아니요 | 조회수 스냅샷 |
data.all_data.items[].views_to_subscribers_ratio | number | 예 | 조회수 대 구독자 비율 |
data.all_data.items[].opportunity_score | number | 예 | 기회 점수 |
data.all_data.items[].duration_seconds | integer | 아니요 | 비디오 재생 시간(초) |
data.all_data.items[].published_at | string(date-time) | 예 | UTC ISO 8601 기준 비디오 게시 시간 |
data.all_data.items[].snapshot_at | string(date-time) | 예 | 데이터 수집 시간 |
data.all_data.items[].niche | string | 예 | 틈새 시장 또는 카테고리 |
data.all_data.items[].track | string | 예 | 데이터세트 트랙 식별자 |
data.all_data.items[].region | string | 예 | 지역 코드 |
data.all_data.items[].reasons | array<string> | 아니요 | 순위 이유 |
data.all_data.items[].video_type | string | 아니요 | shorts 또는 long |
data.all_data.next_cursor | string | 예 | 이 결과 세트에 대한 다음 페이지 cursor; 완료되면 null |
data.filter_data.items | array<object> | 아니요 | 기본값 및 요청 필터 이후의 비디오 항목 |
data.filter_data.items[].video_id | string | 아니요 | YouTube 비디오 ID |
data.filter_data.items[].title | string | 아니요 | 비디오 제목 |
data.filter_data.items[].video_url | string | 아니요 | YouTube 비디오 URL |
data.filter_data.items[].channel.id | string | 예 | 채널 ID |
data.filter_data.items[].channel.title | string | 아니요 | 채널 제목 |
data.filter_data.items[].channel.subscribers | integer | 예 | 구독자 수; 숨겨진 경우 null |
data.filter_data.items[].channel.subscriber_count_hidden | boolean | 아니요 | 구독자 수 숨김 여부 |
data.filter_data.items[].views | integer | 아니요 | 조회수 스냅샷 |
data.filter_data.items[].views_to_subscribers_ratio | number | 예 | 조회수 대 구독자 비율 |
data.filter_data.items[].opportunity_score | number | 예 | 기회 점수 |
data.filter_data.items[].duration_seconds | integer | 아니요 | 비디오 재생 시간(초) |
data.filter_data.items[].published_at | string(date-time) | 예 | UTC ISO 8601 기준 비디오 게시 시간 |
data.filter_data.items[].snapshot_at | string(date-time) | 예 | 데이터 수집 시간 |
data.filter_data.items[].niche | string | 예 | 틈새 시장 또는 카테고리 |
data.filter_data.items[].track | string | 예 | 데이터세트 트랙 식별자 |
data.filter_data.items[].region | string | 예 | 지역 코드 |
data.filter_data.items[].reasons | array<string> | 아니요 | 순위 이유 |
data.filter_data.items[].video_type | string | 아니요 | shorts 또는 long |
data.filter_data.next_cursor | string | 예 | 이 결과 세트에 대한 다음 페이지 cursor; 완료되면 null |
data.all_data.items[].tier | string | 아니요 | 핫 티어 S / A / B / C |
data.filter_data.items[].tier | string | 아니요 | 핫 티어 S / A / B / C |
meta.request_id | string | 아니요 | 추적 ID 요청 |
meta.snapshot_id | string | 아니요 | 안정적인 스냅샷 ID |
meta.snapshot_at | string(date-time) | 아니요 | 스냅샷 타임스탬프 |
meta.data_status | string | 아니요 | 데이터 세트 상태 |
credits.cost | integer | 아니요 | 모든 작업의 비용은 0 Credits입니다. 월별 크레딧 지급이나 상업용 크레딧 차감은 없습니다. |
credits.remaining | integer | null | 예 | null |
credits.period_ends_at | string(date-time) | null | 예 | null |
credits.unlimited | boolean | 아니요 | true |
페이지 매김 및 cursor#
all_data.next_cursor를 all_cursor로 보내고 filter_data.next_cursor를 filter_cursor로 보냅니다. cursor는 독립적이고 불투명하며 서명되어 있으며 24시간 동안 유효합니다. 레거시 cursor는 filter_cursor의 별칭일 뿐입니다.
E태그#
순위는 If-None-Match를 지원합니다. 적중은 X-Credits-Cost: 0와 함께 HTTP 304를 반환합니다.
오류 및 비율 제한#
모든 오류에는 code, 안정적인 영어 message, request_id 및 details가 포함되어 있습니다. 모든 4xx/5xx 응답에는 크레딧이 없습니다.
| HTTP 상태 | 암호 | 원인 | 권장 조치 |
|---|---|---|---|
| 400 | INVALID_REQUEST | 잘못된 매개변수 형식, 조합 또는 범위 | details.issues를 사용하여 매개변수를 수정하세요. |
| 401 | INVALID_API_KEY | 키가 유효하지 않거나 비활성 상태입니다. | Bearer 헤더 및 키 상태 확인 |
| 429 | API_DAILY_LIMIT_REACHED | 한 계정의 모든 API 키는 하루 10회의 REST 데이터 호출 한도를 공유합니다. Asia/Shanghai 기준 00:00에 초기화됩니다. 웹사이트 검색은 별도로 하루 10회입니다. MCP는 두 한도를 사용하지 않습니다. | REST 데이터 호출이 10회에 도달하면 HTTP 429와 API_DAILY_LIMIT_REACHED를 반환합니다. Asia/Shanghai 기준 다음 00:00까지 기다리세요. 키를 만들거나 교체해도 계정 한도는 초기화되지 않습니다. |
| 429 | RATE_LIMITED | 속도 또는 동시성 한도가 초과되었습니다. | Retry-After 간격 후 재시도 |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | 데이터 또는 서비스를 일시적으로 사용할 수 없습니다. | 나중에 다시 시도하고 request_id를 유지하세요. |
curl -X GET "https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"