X Trends
X 트렌드는 숫자 WOEID에서 확인할 수 있는 공개 주제를 위치 기준으로 담은 스냅샷으로, 원본 이름, 순위, 검색어, 설명, 수집 시각이 함께 보관됩니다. 이 구조는 지역별 주제 탐색과 반복 관찰을 지원하며, 각 레코드가 과거 트렌드 이력이 아니라 수집 시점의 상태임을 분명히 보여 줍니다.
X Trends API 주요 기능
- 위치 기준 수집알고 있는 숫자 WOEID를 하나 이상 지정해 현재 공개 트렌드를 요청하며, 원래의 식별자는 extra.woeid에 보존합니다.
- 원본 순위 보존상위 제공처의 순위가 있으면 SocQ가 계산한 점수로 바꾸지 않고 그대로 metrics.rank에 유지합니다.
- 활용도 높은 트렌드 맥락트렌드 이름과 함께, 제공되는 경우 상위 제공처의 검색어와 설명을 받습니다.
- 위치별 독립 상한제출한 WOEID마다 results_limit을 따로 적용하며, 각 위치에서 현재 확인 가능한 트렌드 집합을 한 번씩 수집합니다.
X Trends API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
woeids | 필수 | 알고 있는 X 위치 식별자의 배열로, 하나 이상이 필요한 필수 값입니다. 각 식별자는 비어 있지 않은 숫자 문자열이어야 합니다. |
results_limit | 선택 | WOEID마다 따로 적용되는 선택 사항인 정수 상한입니다. 기본값은 100이며 20부터 2,000까지의 값을 받습니다. |
X Trends API 사용 방법
이미 알고 있는 숫자 WOEID로 시작해 위치별 상한을 정하고, 반환된 레코드는 수집 시점의 스냅샷으로 다룹니다.
- 알고 있는 WOEID를 숫자 문자열로 하나 이상 입력합니다. 이 엔드포인트는 지명을 WOEID로 변환하지 않습니다.
- results_limit은 20부터 2,000 사이의 정수로 정하거나, WOEID당 기본값 100을 그대로 사용합니다.
- /v1/x/trends로 요청을 POST한 뒤, 작업이 성공할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고, has_more가 true인 동안 작업 결과의 next_cursor를 따라갑니다.
curl -X POST "https://api.socq.ai/v1/x/trends" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"woeids":["1"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueX Trends API 추천 활용 사례
- 알고 있는 시장의 주제 파악: 모니터링 시스템이 이미 관리하는 위치 식별자에 대응하는 현재 트렌드 이름, 순위, 설명을 수집합니다.
- 반복 관찰 스냅샷 구축: 같은 WOEID를 직접 정한 일정으로 실행하고, 이후 변화 분석을 위해 모든 결과에 collected_at을 함께 저장합니다.
- 주제 검토 대기열 만들기: 반환된 이름, 검색어, 순위, 설명으로 공개 주제의 우선순위를 정해 분석가의 검토나 후속 탐색 워크플로에 넘깁니다.
X Trends API 활용 팁
- 작업을 제출하기 전에 숫자 WOEID를 준비하세요. 지명이나 자유 형식의 위치 텍스트는 사용할 수 없습니다.
- 기본으로 제공되는 1은 백엔드에 게시된 요청 예시를 따른 값이므로, 의도한 범위에 맞는 식별자로 바꿔 사용하세요.
- 현재 트렌드 집합이 요청한 수보다 적은 행을 포함할 수 있으므로, results_limit은 WOEID별 상한으로 취급하세요.
- 같은 이름의 트렌드는 한 작업 안에서 중복이 제거될 수 있으므로, 트렌드와 위치의 대응을 모두 보존해야 한다면 겹치는 위치는 별도의 작업으로 실행하세요.
- 관측 시각으로는 collected_at을 사용하세요. 원본이 트렌드 생성 타임스탬프를 제공하지 않으므로 created_at은 null입니다.
- 작업 결과의 커서는 이미 저장된 레코드를 넘겨 볼 뿐이며, 제공처에 트렌드의 다음 페이지를 요청하지 않습니다.
관련 API
X Trends API 외에 X의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Twitter Tweet Scraper API — x.com 또는 twitter.com 게시물 URL에서 공개 게시물 텍스트, 작성자, 참여도, 미디어, 해시태그, 멘션, 대화 관계를 가져옵니다.
- Twitter Profile Scraper API — 사용자 이름으로 공개 계정 정보, 소개글, 프로필 이미지, 커버 이미지, 계정 상태, 공개된 오디언스 통계를 가져옵니다.
- Twitter User Tweets Scraper API — 사용자 이름으로 최근 공개 게시물, 작성자, 미디어, 해시태그, 멘션, 참여도를 수집하며 답글은 제외합니다.
- Twitter Search API — 검색식으로 공개 게시물을 찾으며, 최신순 또는 인기순 정렬과 결과 수 제한을 지정할 수 있습니다.
- Twitter User Search API — 키워드로 공개 X 계정을 찾습니다.
- X Communities Search API — 키워드로 커뮤니티를 찾고, 멤버 수와 멤버·게시물 엔드포인트에 바로 쓸 수 있는 링크를 반환합니다.
- X Followers List API
- X Following List API
- X Post Quotes API
- X Post Replies API
- X Post Retweeters API
- Twitter Mentions API
- X Community API
- X Community Posts API
- X Thread Context API
- X Account Location API
- X Verified Followers API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API