x/
trends

하나 이상의 숫자 WOEID에 대한 현재 공개 X 트렌드를 수집하며, 원본 순위, 검색어, 설명, 위치 정보, 수집 시각을 제공합니다.

X Trends API

WOEID 스냅샷
원본 순위
위치 정보
결과당 0.5 크레딧
준비됨
README

SocQ 작성 · 업데이트

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로 시작해 위치별 상한을 정하고, 반환된 레코드는 수집 시점의 스냅샷으로 다룹니다.

  1. 알고 있는 WOEID를 숫자 문자열로 하나 이상 입력합니다. 이 엔드포인트는 지명을 WOEID로 변환하지 않습니다.
  2. results_limit은 20부터 2,000 사이의 정수로 정하거나, WOEID당 기본값 100을 그대로 사용합니다.
  3. /v1/x/trends로 요청을 POST한 뒤, 작업이 성공할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. 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 true

X Trends API 추천 활용 사례

  • 알고 있는 시장의 주제 파악: 모니터링 시스템이 이미 관리하는 위치 식별자에 대응하는 현재 트렌드 이름, 순위, 설명을 수집합니다.
  • 반복 관찰 스냅샷 구축: 같은 WOEID를 직접 정한 일정으로 실행하고, 이후 변화 분석을 위해 모든 결과에 collected_at을 함께 저장합니다.
  • 주제 검토 대기열 만들기: 반환된 이름, 검색어, 순위, 설명으로 공개 주제의 우선순위를 정해 분석가의 검토나 후속 탐색 워크플로에 넘깁니다.

X Trends API 활용 팁

  • 작업을 제출하기 전에 숫자 WOEID를 준비하세요. 지명이나 자유 형식의 위치 텍스트는 사용할 수 없습니다.
  • 기본으로 제공되는 1은 백엔드에 게시된 요청 예시를 따른 값이므로, 의도한 범위에 맞는 식별자로 바꿔 사용하세요.
  • 현재 트렌드 집합이 요청한 수보다 적은 행을 포함할 수 있으므로, results_limit은 WOEID별 상한으로 취급하세요.
  • 같은 이름의 트렌드는 한 작업 안에서 중복이 제거될 수 있으므로, 트렌드와 위치의 대응을 모두 보존해야 한다면 겹치는 위치는 별도의 작업으로 실행하세요.
  • 관측 시각으로는 collected_at을 사용하세요. 원본이 트렌드 생성 타임스탬프를 제공하지 않으므로 created_at은 null입니다.
  • 작업 결과의 커서는 이미 저장된 레코드를 넘겨 볼 뿐이며, 제공처에 트렌드의 다음 페이지를 요청하지 않습니다.

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 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

X Trends API — 자주 묻는 질문

X Trends API는 숫자 WOEID별로 현재 공개 X 트렌드 스냅샷을 수집하는 프로그래밍 인터페이스입니다.

알고 있는 위치 식별자를 숫자 문자열로 하나 이상 제출합니다. 이 엔드포인트는 도시나 국가 이름을 WOEID로 바꿔 주지 않습니다.

기본값은 100이고 20부터 2,000까지의 정수를 받으며, WOEID마다 따로 적용됩니다. 원본이 요청한 상한보다 적은 현재 트렌드를 제공할 수도 있습니다.

레코드에는 id와 text로 쓰이는 트렌드 이름, 있는 경우 상위 제공처의 순위, collected_at이 담기고, 확인 가능하면 WOEID, 검색어, 설명이 extra 필드에 들어갑니다.

아니요. 요청한 WOEID별 현재 스냅샷만 반환합니다. 이력이 필요하면 자체 시스템에서 반복 실행을 예약하고 저장해 만드세요.

저장된 레코드는 한 작업 안에서 정규화된 트렌드 이름 기준으로 중복이 제거됩니다. 같은 이름이 제출한 여러 위치에 나타나면, 먼저 저장된 레코드에는 extra.woeid 값이 하나만 남을 수 있습니다.

정상적으로 저장된 정규화 트렌드 하나당 0.5 SocQ 크레딧이 차감됩니다. 예상 금액은 제출한 모든 WOEID에 results_limit을 적용해 계산하며, 사용하지 않은 선차감 크레딧은 작업 정산 후 환불됩니다.