Twitter Search
X 검색 결과는 검색어에 맞춰 선별된 공개 게시물로, 일치하는 게시물마다 언어, 작성자, 미디어, 엔티티, 대화 맥락, 공개된 참여 수치가 담겨 있습니다. 모든 레코드에 검색어를 함께 보관하면 주기적인 주제 스캔, 출시 반응 청취, 결과 세트 비교를 감사하기 쉬워집니다.
Twitter Search API 주요 기능
- 검색식 하나로 탐색비어 있지 않은 키워드나 검색식을 제출하면, 일치하는 공개 X 게시물을 구조화된 레코드로 변환합니다.
- 두 가지 조사 모드를 위한 정렬latest로 최근 일치 게시물을 따라가거나 top으로 주목도 높은 게시물을 살펴볼 수 있으며, 기본값은 latest입니다.
- 실용적인 검색 결과 상한20개 단위로 20~2,000개의 결과를 요청해 검색 수집의 최대 깊이를 정할 수 있습니다.
- 검색어를 유지하는 일치 결과텍스트, 작성자, 참여 수치, 미디어, 엔티티, 타임스탬프, 관계 필드를 extra.search_query 및 collected_at과 함께 제공합니다.
Twitter Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 일치하는 공개 게시물을 찾는 데 사용하는, 비어 있지 않은 키워드 또는 X 게시물 검색식으로, 필수 값입니다. |
results_limit | 선택 | 요청할 결과 수 상한으로, 선택 값입니다. 기본값은 20이며 20부터 2,000까지 20의 배수를 받습니다. |
sort_by | 선택 | 선택 사항인 정렬로, 최근 일치 게시물은 latest, 주목도 높은 게시물은 top입니다. 기본값은 latest입니다. |
Twitter Search API 사용 방법
구체적인 조사 질문을 검색식으로 정리하고, 그에 맞는 정렬을 선택한 뒤, 검색어를 결과 게시물과 함께 보존합니다.
- 찾으려는 X 게시물에 맞춰 비어 있지 않은 검색식을 하나 작성합니다.
- latest 또는 top을 선택하고, results_limit은 20부터 2,000까지 20 단위로 정합니다.
- /v1/x/search로 요청을 POST한 뒤, 완료될 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 저장하고, has_more가 false가 될 때까지 next_cursor를 따라갑니다.
curl -X POST "https://api.socq.ai/v1/x/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"artificial intelligence","results_limit":40,"sort_by":"latest"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueTwitter Search API 추천 활용 사례
- 특정 출시에 대한 반응 청취: 제품, 릴리스, 컨퍼런스, 캠페인 문구를 검색하고 일치하는 게시물을 게시 시각과 수집 시각으로 정리합니다.
- 브랜드·제품 멘션 추적: 특정 이름이나 문구에 대해 작성자, 텍스트, 공개된 참여 수치, 해시태그, 멘션, 미디어를 한데 모읍니다.
- 떠오르는 주제 파악: 같은 조사식으로 latest 결과는 새 게시물을 따라가는 데, top 결과는 주목도 높은 콘텐츠를 살펴보는 데 사용합니다.
- 주기적 검색어 데이터셋 유지: 일치 결과마다 extra.search_query를 저장하고, 버전을 붙인 검색식을 다시 실행해 이전에 없던 게시물 ID만 추가합니다.
Twitter Search API 활용 팁
- 구체적인 검색식으로 시작해 일치 결과를 확인하고, 범위가 너무 좁을 때만 표현을 넓히세요.
- 시의성이 중요한 모니터링에는 latest를, 시간순보다 주목도 높은 게시물이 중요할 때는 top을 선택하세요.
- results_limit은 20의 배수로 설정하고, 결과 수를 보장하는 값이 아니라 상한으로 해석하세요.
- 검색어의 표현이 바뀔 때마다 버전을 붙여, 주기적으로 수집한 결과 세트를 서로 비교할 수 있게 하세요.
- 게시물 id 기준으로 중복을 제거하되, 탐색 맥락을 위해 extra.search_query와 collected_at은 유지하세요.
관련 API
Twitter Search API 외에 X의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Twitter Tweet Scraper API — x.com 또는 twitter.com 게시물 URL에서 공개 게시물 텍스트, 작성자, 참여도, 미디어, 해시태그, 멘션, 대화 관계를 가져옵니다.
- Twitter Profile Scraper API — 사용자 이름으로 공개 계정 정보, 소개글, 프로필 이미지, 커버 이미지, 계정 상태, 공개된 오디언스 통계를 가져옵니다.
- X Post Replies API — X 게시물 URL에서 공개 답글을 수집하며, 정렬 방식을 선택할 수 있고 답글 텍스트, 작성자, 공개된 참여도, 미디어, 상위 게시물 맥락을 포함합니다.
- X Trends API — 알고 있는 숫자형 WOEID의 현재 공개 X 트렌드 스냅샷을 수집하며, 출처 순위, 검색어, 설명, 위치 맥락을 포함합니다.
- Twitter User Search API — 키워드로 공개 X 계정을 찾습니다.
- X Communities Search API — 키워드로 커뮤니티를 찾고, 멤버 수와 멤버·게시물 엔드포인트에 바로 쓸 수 있는 링크를 반환합니다.
- Twitter User Tweets Scraper API
- X Followers List API
- X Following List API
- X Post Quotes 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