Outlier 비디오 검색
키워드, 틈새 시장, 지역, 조회수 대 구독자 비율을 기준으로 저장된 데이터를 검색합니다.
POST
https://api.shortsmonkey.com/v1/videos/outliers/search실제 1~20개 항목당 2크레딧
Outlier 비디오 검색#
키워드, 틈새 시장, 지역, 조회수 대 구독자 비율을 기준으로 저장된 데이터를 검색합니다.
입증#
Authorization: Bearer sm_live_...를 보냅니다. URL, 쿠키, 본문, 로그 또는 분석에 전체 키를 배치하지 마십시오.
데이터 최신성#
순위는 작업자가 게시한 안정적인 스냅샷을 읽습니다. 공개 읽기는 YouTube 새로 고침을 트리거하지 않습니다.
요구#
| 목 | 값 | 설명 |
|---|---|---|
| 방법 | POST | HTTP 요청 방법 |
| 전체 URL | https://api.shortsmonkey.com/v1/videos/outliers/search | 생산 API URL |
| 입증 | Authorization: Bearer sm_live_... | 헤더에만 전체 키를 보냅니다. |
| 콘텐츠 유형 | application/json | 요청 본문은 JSON를 사용합니다. |
| 크레딧 | 실제 1~20개 항목당 2크레딧 | 오류 응답 비용은 0크레딧입니다. |
요청 매개변수#
| 이름 | 위치 | 유형 | 필수의 | 기본 | 값 또는 한계 | 설명 |
|---|---|---|---|---|---|---|
keyword | JSON 본체 | string | 아니요 | — | 1~120자 | 저장된 제목 또는 틈새 텍스트와 일치하는 키워드 |
niche | JSON 본체 | string | 아니요 | — | 1~80자 | 틈새 시장 또는 카테고리 필터 |
video_type | JSON 본체 | string | 아니요 | all | shorts / long / all | 비디오 유형 |
region | JSON 본체 | string | 아니요 | — | 2~16자 | 지역 코드 |
max_channel_subscribers | JSON 본체 | integer | 아니요 | — | 0–10,000,000 | 최대 채널 구독자 수 |
min_views | JSON 본체 | integer | 아니요 | — | 0–1,000,000,000 | 최소 조회수 |
min_vs_ratio | JSON 본체 | number | 아니요 | 10 | 0–100,000 | 최소 조회수 대 구독자 비율 |
time_window | JSON 본체 | string | 아니요 | 7d | 24h / 3d / 7d / 30d | 영상공개 창구 |
limit | JSON 본체 | integer | 아니요 | 20 | 1–50 | 이 페이지의 최대 항목 수 |
all_cursor | JSON 본체 | string | 아니요 | — | data.all_data.next_cursor | 필터링되지 않은 다음 페이지 가져오기 |
filter_cursor | JSON 본체 | string | 아니요 | — | data.filter_data.next_cursor | 필터를 변경하지 않고 필터링된 다음 페이지를 가져옵니다. |
cursor | JSON 본체 | string | 아니요 | — | 더 이상 사용되지 않는 호환성 매개변수 | filter_cursor의 별칭; 둘 다 보내지 마세요 |
성공 응답 필드#
all_data는 안정적인 스냅샷에서 필터링되지 않은 페이지입니다. filter_data는 엔드포인트 기본값 및 요청 필터 이후 동일한 스냅샷의 페이지입니다. 각 결과는 독립적으로 페이지가 매겨집니다.
점 표기법은 중첩된 객체를 나타내고 []는 배열 항목을 나타냅니다. 알 수 없는 구독자 수는 null 및 subscriber_count_hidden: true입니다. 하나의 요청은 더 큰 반품 항목 수를 사용하여 한 번만 청구되며 두 세트의 합계가 아닙니다.
| 필드 경로 | 유형 | 널 입력 가능 | 설명 |
|---|---|---|---|
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 |
meta.request_id | string | 아니요 | 추적 ID 요청 |
meta.snapshot_id | string | 아니요 | 안정적인 스냅샷 ID |
meta.snapshot_at | string(date-time) | 아니요 | 스냅샷 타임스탬프 |
meta.data_status | string | 아니요 | 데이터 세트 상태 |
credits.cost | integer | 아니요 | 실제 청구된 크레딧 |
credits.remaining | integer | 아니요 | 남은 계정 크레딧 |
credits.period_ends_at | string(date-time) | 아니요 | 현재 신용 기간 종료 |
페이지 매김 및 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 헤더 및 키 상태 확인 |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | 구독 또는 크레딧을 사용할 수 없습니다. | 계획과 잔액, 핵심안전예산을 확인하세요 |
| 429 | RATE_LIMITED | 속도 또는 동시성 한도가 초과되었습니다. | Retry-After 간격 후 재시도 |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | 데이터 또는 서비스를 일시적으로 사용할 수 없습니다. | 나중에 다시 시도하고 request_id를 유지하세요. |
curl -X POST "https://api.shortsmonkey.com/v1/videos/outliers/search" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword":"finance","video_type":"all","time_window":"7d","min_vs_ratio":10,"limit":20}'