Main APIYouTube 트렌드
트렌드 레코드 목록
일자·지역별 flat 레코드를 반환합니다. 하단 데이터 테이블용.
트렌드 레코드 목록 (테이블용)
지정 일자(또는 최신일)의 트렌드 영상을 flat 목록으로 반환합니다. 리포트 하단의 데이터 테이블에 그대로 렌더합니다.
HTTP 요청
GET /api/youtube/trend/records?date=2026-07-27®ion=KR&slot=BEAUTY&is_shorts=true&sort=view_count&limit=100&offset=0Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
date | String | 아니오 | 조회 일자(YYYY-MM-DD), 기본 최신 수집일 |
region | String | 아니오 | 지역 코드, 기본 KR |
slot | String | 아니오 | 분야 필터: BEAUTY·FASHION·TRAVEL (현재 수집 3개 분야) |
ad_flag | String | 아니오 | 광고여부 필터: O(협찬/공구) / X(일반) |
is_shorts | Boolean | 아니오 | 쇼츠 필터 |
sort | String | 아니오 | 정렬: view_count(기본) · velocity(급상승) · rank |
limit | Integer | 아니오 | 페이지 크기(1~500, 기본 100) |
offset | Integer | 아니오 | 오프셋(기본 0) |
응답 (200 OK)
표준 ApiResponse 래퍼. 실제 데이터는 data.
{
"status": 200, "code": null, "message": "조회 완료",
"data": {
"region": "KR",
"date": "2026-07-27",
"total": 54,
"limit": 100,
"offset": 0,
"records": [
{
"keyword_slot": "BEAUTY",
"ad_flag": "X",
"is_shorts": true,
"rank": 1,
"video_id": "5xQI8KouLPc",
"title": "여자들이 한순간에 반한 이유 #메이크업 #makeup",
"description": "한국틴트 하나로 완벽한 화장하는 법 ...",
"channel_id": "UC7hNqbyhyN5FLro2pbbc_tw",
"channel_title": "스타템픽",
"category_id": "22",
"view_count": 450050,
"like_count": 12030,
"comment_count": 210,
"duration_sec": 14,
"velocity": 305718.6,
"view_delta": 8400,
"snapshot_count": 3,
"has_paid_placement": false,
"published_at": "2026-07-25T12:00:00+09:00",
"url": "https://www.youtube.com/watch?v=5xQI8KouLPc",
"thumbnail": "https://i.ytimg.com/vi/5xQI8KouLPc/hqdefault.jpg",
"tags": ["메이크업", "화장법", "메이크업튜토리얼"],
"topic_categories": ["https://en.wikipedia.org/wiki/Lifestyle_(sociology)"],
"default_audio_language": null,
"hashtag_n": 2,
"eng_rate": 0.027197,
"status": "public",
"sound": {
"title": "Catch Catch",
"artist": "@YENA_OFFICIAL",
"source_video_id": "sjtyqmA-pH4"
}
}
]
}
}데이터가 없는 일자·지역이면 data.total: 0, data.records: [].
추가 필드
| 필드 | 설명 |
|---|---|
description | 영상 설명 |
channel_id | 채널 ID(채널 링크·식별용) |
tags | 영상 태그 배열(없으면 null) |
topic_categories | 위키피디아 토픽 URL 배열(= "주제" 축, 없으면 null) |
default_audio_language | 음성 언어 코드(목업 lang). 유튜브가 잘 안 채워 대부분 null |
hashtag_n | 제목·설명의 해시태그 #xxx 개수(목업 hashtag_n, 서버 계산) |
eng_rate | 인게이지먼트율 (like_count + comment_count) / view_count(목업 eng_rate, 서버 계산·소수 6자리). 조회수 없으면 null |
status | 공개 상태 privacyStatus(목업 status, raw에서 추출). 검색 노출분이라 대개 public |
전체 목업 23필드 대응은 필드 매핑 참고.
🔴 v3 쿼터 소진 시 YT-API fallback으로 수집된 행은 description은 채워지지만 tags·topic_categories·like_count·comment_count·category_id는 null일 수 있습니다(YT-API 검색 응답 미제공). 이 경우 eng_rate도 null, hashtag_n은 제목/설명 기준으로만 계산됩니다.
조회수 증가분 (view_delta)
수집은 매일(24시간 주기) 돌며, 같은 영상은 하루 1행을 유지하면서 조회수를 갱신합니다(롤링).
| 필드 | 설명 |
|---|---|
view_count | 최신 조회수 |
view_delta | 직전 수집(≈하루 전) 대비 조회수 증가분. 첫 수집은 null |
snapshot_count | 갱신된 스냅샷 횟수 |
sound 필드 (쇼츠 음원)
sound 는 쇼츠가 사용한 음원 정보입니다(파이썬 수집기가 RapidAPI YT-API 로 보강).
| 필드 | 설명 |
|---|---|
sound.title | 곡명 |
sound.artist | 아티스트/원작 채널 |
sound.source_video_id | 사운드 원본 영상 id |
- 일반 영상은 사운드 보강 대상이 아니므로 항상
sound: null. - 크리에이터가 자체 오리지널 사운드를 쓴 쇼츠는 음원 식별이 불가해
sound: null(유튜브 구조상 한계).