구글 트렌드 실시간 인기 (윈도우 수집기)
플레이그라운드에서 수집 →채널 코드 google_trends_trending · 수집 환경 windows
구글 트렌드 실시간 인기(trends.google.co.kr/trending) 목록을 수집합니다 — 트렌드 1개 = 결과 1건(순위 · 검색량 · 증가율 · 시작/종료 · 활성 여부 · 카테고리 · 트렌드 분석(함께 검색된 말) · 탐색 링크). 위치(125개국, 43개국은 시/도까지) · 기간(4/24/48/168시간) · 카테고리 · 활성 트렌드만 · 정렬을 화면에서 고른 뒤 [내보내기 → CSV 다운로드]로 그 조건의 전체 목록을 받습니다(약 10~30초). server 를 비우면 허브가 지금 가능한 트렌드 수집 서버를 골라 배정합니다. ⚠️ 구글 보안 확인(캡차)·쿠키 동의 화면이 뜨면 기다리지 않고 failed 로 끝나고(재시도 없음 — 수집 PC 의 Chrome 에서 사람이 푼 뒤 다시 요청), 구글이 요청을 잠시 거절(429)하면 수집 PC 가 쉬었다가 다시 하고, 그래도 안 되면 그 요청만 실패해 약 10분 뒤 자동으로 다시 시도합니다(막힘 아님).
요청 파라미터
아래 값들을 POST /api/v1/collect 의 params 객체에 담아 보냅니다.
| 키 | 타입 | 필수 | 기본 | 설명 |
|---|---|---|---|---|
| server | text | — | — | 비우면 허브가 지금 구글 트렌드 수집이 가능한 서버(온라인 · 접속 막힘 아님 · 대기 작업 적은 순)를 골라 배정하고, 응답의 server 로 알려줌. 특정 서버로 보내려면 그 서버 ID(GET /trends-servers 로 조회) |
| geo | text | — | KR | 코드 또는 이름 — KR · KR-11 · US · US-CA · JP · 미국 · 서울특별시 (125개국 + 43개국은 시/도까지). 비우면 KR. 전 세계는 없음(422) |
| hours | enum | — | 24 | 기간 |
| category | enum | — | 0 | 실시간 인기 카테고리(탐색 카테고리 ID 와 다른 목록 — 12 없음) |
| active_only | bool | — | false | 활성 트렌드만 |
| sort | enum | — | relevance | 정렬 |
| limit | number | — | 0 | 정렬한 목록 앞에서부터 몇 개 — 0 = 화면 목록 전체(보통 50~300개), 최대 1000 |
선택 칸 값 목록
아래 칸은 이 값만 받습니다(그 밖의 값은 422 invalid_params). 비우면 기본값입니다.
| 키 | 값 | 뜻 |
|---|---|---|
| hours | 4 | 지난 4시간 |
| 24 | 지난 24시간 — 기본 | |
| 48 | 지난 48시간 | |
| 168 | 지난 7일 | |
| category | 0 | 모든 카테고리 — 기본 |
| 1 | 자동차 | |
| 2 | 미용 및 패션 | |
| 3 | 비즈니스 및 금융 | |
| 4 | 엔터테인먼트 | |
| 5 | 식음료 | |
| 6 | 게임 | |
| 7 | 건강 | |
| 8 | 취미 및 레저 | |
| 9 | 취업 및 교육 | |
| 10 | 법률 및 정부 | |
| 11 | 기타 | |
| 13 | 반려동물 및 동물 | |
| 14 | 정치 | |
| 15 | 과학 | |
| 16 | 쇼핑 | |
| 17 | 스포츠 | |
| 18 | 기술 | |
| 19 | 여행 및 교통 | |
| 20 | 기후 | |
| sort | relevance | 관련성(중요 · 최신) — 기본 |
| title | 제목 | |
| volume | 검색량 | |
| recency | 날짜순 |
카테고리 ID 는 탐색과 다릅니다 — 실시간 인기의
category 는 위 목록의 ID 만 받습니다(17 = 스포츠, 12 는 없음, 이름은 받지 않음). 탐색(google_trends_explore)의 카테고리는 다른 목록입니다(탐색에서는 20 = 스포츠).요청 예시
curl -X POST https://scraper.conbus.co.kr/api/v1/collect \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "google_trends_trending",
"params": {
"geo": "KR",
"hours": "24",
"category": "17",
"active_only": true,
"sort": "volume",
"limit": 50
}
}'
응답 (202 Accepted)
요청은 즉시 큐에 적재되고 request_id 를 돌려줍니다. 실제 수집은 워커가 비동기로 처리합니다.
{ "success": true, "data": { "request_id": 42, "channel": "google_trends_trending",
"status": "pending", "status_url": "https://scraper.conbus.co.kr/api/v1/requests/42" } }
결과 조회 — GET /requests/{id}
같은 API 키로 request_id 를 조회합니다. 상태에 따라 응답이 달라집니다.
결과(items)는 요청별로 보관되므로 같은 글이 다른 요청(다른 키워드·재수집)에 겹쳐도 이 요청의 결과는 그대로입니다 —
여러 요청에 걸친 중복 정리는 post_id로 호출 쪽에서 하세요.
보존 기간은 완료 후 7일입니다. 이 채널은 '지금 상태'가 중요한 데이터라 짧게 보관합니다 — 결과는 받은 즉시 저장하세요.
보존 기간이 지나면 items 는 빈 배열이고 items_expired: true, items_keep_days 가 함께 옵니다(status 는 그대로 done).
진행 중 (pending / running)
아직 끝나지 않았으면 progress 로 진행 상황만 옵니다(items 없음).
{
"success": true,
"data": {
"request_id": 42,
"channel": "google_trends_trending",
"status": "running",
"external_ref": null,
"result_count": null,
"started_at": "2026-10-14T13:07:20+09:00",
"finished_at": null,
"duration_ms": null,
"duration_sec": null,
"created_at": "2026-10-14T13:07:19+09:00",
"updated_at": "2026-10-14T13:07:31+09:00",
"progress": {
"count": 2,
"phase": "trending"
},
"elapsed_ms": 11000,
"server": "win-trends-01",
"server_online": true
}
}
progress.count 는 끝낸 단계 수입니다(0 화면 여는 중 → 1 위치 · 기간 · 카테고리 · 정렬 고르는 중 → 2 내보내기 · CSV 받는 중 → 끝나면 done). 고정 배정 채널이라 server(배정된 수집 서버)와 server_online 이 함께 옵니다 — 대기가 길면 수집 서버가 온라인인지 확인하세요. 구글 요청 제한(429)으로 실패해 다시 시도를 기다리는 동안에도 pending 으로 보입니다(수집 PC 가 429 로 잠깐 쉬는 동안은 running).
완료 (done)
status 가 done 이면 data.items[] 에 결과가 담깁니다.
실패 시엔 status: "failed" 와 error 가 옵니다.
{
"success": true,
"data": {
"request_id": 42,
"channel": "google_trends_trending",
"status": "done",
"external_ref": null,
"result_count": 1,
"started_at": "2026-10-14T13:07:20+09:00",
"finished_at": "2026-10-14T13:07:45+09:00",
"duration_ms": 25000,
"duration_sec": 25,
"created_at": "2026-10-14T13:07:19+09:00",
"updated_at": "2026-10-14T13:07:45+09:00",
"items": [
{
"post_id": "trend|KR|아틀레티코 대 맨유|2026-10-14T03:00:00+09:00",
"url": "https://trends.google.co.kr/trends/explore?q=%EC%95%84%ED%8B%80%EB%A0%88%ED%8B%B0%EC%BD%94%20%EB%8C%80%20%EB%A7%A8%EC%9C%A0&hl=ko&geo=KR",
"title": "아틀레티코 대 맨유",
"author": null,
"posted_at": "2026-10-14T03:00:00+09:00",
"posted_at_raw": "2026년 10월 14일 오전 3시 0분 0초 UTC+9",
"views": null,
"comment_count": null,
"recommends": null,
"body": "검색량 5만+ (50,000) · ↑1,000% · 시작 2026-10-14 03:00 · 활성\n카테고리: 스포츠\n트렌드 분석: 아틀레티코 대 맨유, 이강인, 맨유",
"source": "Google 트렌드 실시간 인기 · 대한민국",
"extra": {
"kind": "trends_trending",
"source_kind": "google_trends_trending",
"rank": 3,
"title": "아틀레티코 대 맨유",
"status": "ok",
"volume": 50000,
"volume_text": "5만+",
"increase_pct": 1000,
"started_at": "2026-10-14T03:00:00+09:00",
"started_text": "2026년 10월 14일 오전 3시 0분 0초 UTC+9",
"ended_at": null,
"active": true,
"categories": [
{
"id": 17,
"name": "스포츠"
}
],
"breakdown": [
"아틀레티코 대 맨유",
"이강인",
"맨유"
],
"explore_link": "https://trends.google.co.kr/trends/explore?q=%EC%95%84%ED%8B%80%EB%A0%88%ED%8B%B0%EC%BD%94%20%EB%8C%80%20%EB%A7%A8%EC%9C%A0&hl=ko&geo=KR",
"news_count": 9,
"geo": {
"code": "KR",
"name": "대한민국"
},
"hours": 24,
"filters": {
"hours": 24,
"category": 17,
"active_only": true,
"sort": "volume"
},
"collected_at": "2026-10-14T13:07:44+09:00",
"source": "csv+data"
}
}
]
}
}
예시는 items 를 한 건만 보였습니다 — 실제로는 조건에 맞는 트렌드가 화면 순서대로 오고(extra.rank), limit 이 있으면 앞에서부터 그 수만큼입니다. 조건에 맞는 트렌드가 없으면 done + 0건입니다.
실패 (failed)
status 가 failed 면 error 에 사유가 옵니다(items 없음).
실패는 두 가지입니다 — 사람이 처리해야 하거나 다시 해도 같은 결과인 것은 바로 failed, 잠시 뒤 풀릴 수 있는 것은 자동으로 다시 시도합니다(요청당 3번까지 — 그동안 pending 으로 보이고, 다 쓰면 마지막 사유 + 시도 3회 모두 실패해 종결했습니다).
| error 의 시작 | 뜻 | 재시도 |
|---|---|---|
| 구글 트렌드 보안 확인(캡차) 화면이 떠 수집을 멈췄습니다 … | 수집 중 구글 보안 확인(쿠키 동의 화면도 같은 꼴) — 수집 PC 에서 사람이 처리할 때까지 그 서버는 새 요청을 409 account_blocked 로 거절 | 없음 |
| [blocked] 구글 트렌드 보안 확인(캡차)으로 멈춘 상태라 … | 막힌 동안 수집 서버가 받은 요청 — 구글에 접속하지 않고 돌려보냄 | 없음 |
| 구글 트렌드 보안 확인 필요 — 수집 서버 … | 막힌 서버에 배정돼 기다리던 요청을 허브가 끝냄(쿠키 동의면 구글 트렌드 쿠키 동의 필요 — …) | 없음 |
| [invalid_payload] … | 수집 PC 가 요청 값을 받지 못함 — 예: 알 수 없는 지역입니다: '…' · 위치 이름 '…' 이 여러 곳입니다 · 알 수 없는 카테고리입니다: '…' — 코드 · ID 로 다시 요청 | 없음 |
| 결과가 허브 본문 한도를 넘었습니다(413, …) | 결과가 너무 큼 — 검색어 수 · limit 을 줄여 다시 요청 | 없음 |
| 수집 서버(로컬)에서 취소됨 | 수집 PC 에서 사람이 취소 | 없음 |
| 연속 실패로 멈춤 … / 모든 검색이 실패했습니다 … | 구글이 요청을 계속 거절(429 — 쉬었다가 다시 해도 같음, 문구에 429: 예 연속 실패로 멈춤(구글이 요청을 거절(429) — 쉬었다가 다시 해도 같음) — …) 또는 화면 변경 · 일시 오류 의심 — 받은 검색이 하나라도 있으면 failed 가 아니라 done + warnings | 10분 뒤 |
| 수집용 Chrome 문제 — … | 수집 PC 의 수집용 Chrome 실행 · 연결 문제 | 5분 뒤 |
| 작업 시간 상한(…분) 초과로 중단 — 모은 결과 없음 | 수집 PC 의 시간 상한(기본 60분)까지 아무것도 받지 못함(받은 검색이 있으면 done + warnings.not_run) | 잠시 뒤 |
{
"success": true,
"data": {
"request_id": 42,
"channel": "google_trends_trending",
"status": "failed",
"external_ref": null,
"result_count": 0,
"started_at": "2026-06-16T09:00:05+09:00",
"finished_at": "2026-06-16T09:00:16+09:00",
"duration_ms": 11000,
"duration_sec": 11,
"created_at": "2026-06-16T09:00:00+09:00",
"updated_at": "2026-06-16T09:00:16+09:00",
"error": "구글 트렌드 보안 확인(캡차) 화면이 떠 수집을 멈췄습니다(기다리지 않음) — 수집 PC 의 수집용 Chrome 에서 사람이 확인한 뒤 앱의 [이상 없음 확인] 을 누르고 다시 요청하세요 (Google 보안 확인(캡차)이 떠서 수집을 멈췄습니다(실패) — 수집용 Chrome 창에서 직접 확인을 끝낸 뒤 앱에서 [이상 없음 확인] 을 누르세요)"
}
}
최상위 data에는 항상 request_id·channel·status·external_ref·result_count·started_at·finished_at·duration_ms·duration_sec·created_at·updated_at이 포함되고, 상태에 따라 items(done)·progress+elapsed_ms(진행 중)·error(failed/cancelled)가 추가됩니다. duration_*는 허브가 잰 수집 소요 시간(시작~종료) — 자세히는 비동기 & 콜백. 요청을 잘못 시작했다면 취소 API로 중단할 수 있습니다.
결과 필드 (items[])
| 필드 | 설명 |
|---|---|
| post_id | 트렌드 — trend|위치코드|제목|시작시각(190자가 넘으면 앞 150자 + | + sha1 앞 20자). 결과는 트렌드 1개 = 1건(화면 순서 그대로, limit 이 있으면 앞에서부터). 같은 트렌드(위치 · 제목 · 시작)는 허브 축적본에서 최신 값(검색량 · 종료)으로 바뀝니다 |
| url | 그 트렌드의 탐색 화면 주소(extra.explore_link 와 같음) |
| title / body | title=트렌드 제목 / body=사람이 읽는 요약(검색량 · 증가율 · 시작 · 활성 또는 종료 시각 · 카테고리 · 트렌드 분석 앞 20개) |
| author | 항상 null |
| posted_at | 작성 시각 (ISO8601, KST) — 이 채널은 트렌드 시작 시각입니다. posted_at_raw 는 구글 CSV 의 원문(2026년 10월 13일 오후 8시 50분 0초 UTC+9) |
| views / comment_count | 항상 null — 검색량은 extra.volume |
| recommends | 항상 null |
| source | Google 트렌드 실시간 인기 · 위치 이름 |
| extra.kind / source_kind | trends_trending / google_trends_trending |
| extra.rank / title / status | 화면 순서(1부터, 요청 정렬 기준) · 트렌드 제목 · ok |
| extra.volume / volume_text | 검색량 — 숫자(구간 하한, 예 50000) · 화면 표기(5만+) |
| extra.increase_pct | 증가율 %(화면의 ↑1,000% → 1000) — CSV 만 받았으면 null |
| extra.started_at / started_text / ended_at / active | 시작 시각(ISO) · 원문 · 종료 시각(진행 중이면 null) · 활성 여부 |
| extra.categories[] | {id, name} — 실시간 인기 카테고리(탐색 카테고리와 다른 목록) |
| extra.breakdown[] | 트렌드 분석 — 함께 검색된 말 |
| extra.explore_link / news_count | 탐색 화면 링크 · 관련 뉴스 수 |
| extra.geo / hours / filters | 요청 위치 {code, name} · 기간(시간) · 적용한 필터 {hours, category, active_only, sort} |
| extra.collected_at / source | 수집 시각(KST) · 데이터를 읽은 곳 — csv+data(CSV + 화면 데이터) · csv(증가율 · 카테고리 없음) · data(CSV 를 못 받아 화면 데이터만) |
채널 참고
- 수집 서버 자동 선택 —
server는 선택입니다. 비우면 허브가 지금 구글 트렌드 수집이 가능한 서버를 골라 배정합니다(없으면 409no_trends_server). 서버 · 막힘 상태는GET /trends-servers로 봅니다. - 위치는 코드(
KR·KR-11·US·US-CA·JP)나 이름(미국·서울특별시)으로 넣습니다 — 125개국, 그중 43개국은 시/도까지. 전 세계는 없습니다(WORLD·전 세계등은 422). 이름 해석은 수집 PC 의 목록으로 합니다 — 나라와 시/도에 같은 이름이 있으면 나라(조지아), 모르는 이름이면 그 요청은failed([invalid_payload] …, 재시도 없음) — 코드로 다시 요청하세요. - 카테고리는 실시간 인기 전용 ID 입니다(0 = 모든 카테고리 · 17 = 스포츠 …, 12 는 없음) — 탐색 카테고리 ID 와 다릅니다.
limit은 0~1000(0 = 그 조건의 화면 목록 전체, 보통 50~300개), 범위 밖이면 422. - 수집 PC 의 Chrome 이 실시간 인기 화면에서 위치 · 기간 · 카테고리 · 트렌드 상태 · 정렬을 고른 뒤 [내보내기 → CSV 다운로드]로 그 조건의 전체 목록을 받습니다(약 10~30초). 증가율 · 카테고리 · 정확한 검색량은 화면이 이미 받은 목록 데이터로 덧붙입니다(
extra.source). - 구글이 막을 때 — 보안 확인(캡차) · 쿠키 동의 화면이면
failed(재시도 없음), 그 서버는 사람이 처리할 때까지 409account_blocked(막힌 종류·시각은GET /trends-servers의blocked_kind·blocked_since). 구글이 목록 요청을 잠시 거절(429)하는 것은 막힘이 아닙니다 — 수집 PC 가 25~45초(다음엔 1~2분) 쉬었다가 처음부터 다시 하고(최대 2번), 그래도 안 되면failed로 돌아와 약 10분 뒤 자동으로 다시 시도합니다(요청당 3번까지). - 결과 크기는 트렌드당 약 1~3KB(300개면 약 0.5~1MB)입니다.
결과 수신(폴링·콜백) 방식은 비동기 & 콜백을 참고하세요.