X Communities Search
X 커뮤니티는 X에서 사람들이 가입하는 주제별 그룹으로, 검색 목록에서는 커뮤니티마다 이름, 배너 이미지, 멤버 수, 민감한 콘텐츠로 지정됐는지 여부가 표시됩니다. 이 목록을 키워드로 검색하면 어떤 주제가 어디서 논의되는지, 어느 그룹이 가장 큰지, 어느 그룹에 성인용 또는 민감한 콘텐츠 표시가 붙어 있는지 열어 보기 전에 알 수 있습니다.
X Communities Search API 주요 기능
- 키워드 하나로 일치하는 모든 커뮤니티query 값에 bitcoin 같은 단어나 문구를 넣으면, X가 해당 검색어에 보여 주는 커뮤니티가 하나씩 행으로 반환됩니다.
- 이름과 배너name과 cover_url 값이 커뮤니티의 제목과 배너 이미지를 제공하므로, 목록에서 알아보거나 자체 화면에 표시하기에 충분합니다.
- 규모 판단을 위한 멤버 수metrics.members_count 값이 가입자 수를 알려 주므로, 검색 결과에서 바로 작은 그룹과 수만 명 규모 커뮤니티를 구분할 수 있습니다.
- 민감한 콘텐츠 표시is_nsfw 값은 X에서 커뮤니티가 민감한 콘텐츠로 지정된 경우 true이므로, 성인용 공간이 보고서나 사용자에게 닿기 전에 처리할 수 있습니다.
- 변하지 않는 ID와 링크각 행에는 숫자형 커뮤니티 id와 https://x.com/i/communities/<id> 형식의 url 값이 있으며, 검색마다 같은 값이 유지되어 자체 데이터의 키로 쓸 수 있습니다.
X Communities Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | X 커뮤니티를 검색할 키워드입니다(예: bitcoin). |
results_limit | 선택 | 반환할 커뮤니티 수로, 10부터 500까지 10의 배수를 받습니다. 기본값은 20입니다. |
X Communities Search API 사용 방법
키워드로 검색하고 일치하는 커뮤니티를 페이지 단위로 읽습니다.
- {"query": "bitcoin", "results_limit": 20}을 /v1/x/search-communities로 POST합니다.
- status가 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링합니다.
- results.items에서 일치하는 커뮤니티를 읽고, has_more가 true인 동안 results.next_cursor로 다음 페이지를 요청합니다.
curl -X POST "https://api.socq.ai/v1/x/search-communities" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"bitcoin","results_limit":20}'
# Each result's url can go straight into X Community Members, X Community Moderators or X Community Posts.X Communities Search API 추천 활용 사례
- X에서 주제가 모이는 곳 파악: 시장이나 취미의 주요 용어를 검색하고 커뮤니티 이름, 링크, 멤버 수를 모아 관련 대화가 어디에 모이는지 확인합니다.
- 분야에서 가장 큰 커뮤니티 추리기: 결과를 metrics.members_count 기준으로 정렬해 후원, 게시, 심층 조사를 할 만큼 규모가 큰 몇 곳을 고릅니다.
- 브랜드 세이프한 커뮤니티 목록 유지: 커뮤니티 목록을 클라이언트와 공유하거나 제품에 노출하기 전에 is_nsfw 값이 true인 행을 모두 제외합니다.
- 멤버·모더레이터 내보내기로 연결: 추린 커뮤니티의 url 값을 X Community Members나 X Community Moderators에 넘겨, 그룹 목록에서 그 안의 사람들로 넘어갑니다.
X Communities Search API 활용 팁
- bitcoin과 btc처럼 비슷한 검색어를 함께 실행하고 결과를 id로 합치세요. 커뮤니티 하나가 여러 키워드에 걸릴 수 있습니다.
- 커뮤니티 성장 추이를 보려면 같은 검색어를 정기적으로 실행하고, id마다 metrics.members_count 값을 collected_at 값과 함께 저장하세요.
관련 API
X Communities Search API 외에 X의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Twitter Search API — 검색식으로 공개 게시물을 찾으며, 최신순 또는 인기순 정렬과 결과 수 제한을 지정할 수 있습니다.
- X Trends API — 알고 있는 숫자형 WOEID의 현재 공개 X 트렌드 스냅샷을 수집하며, 출처 순위, 검색어, 설명, 위치 맥락을 포함합니다.
- Twitter User Search API — 키워드로 공개 X 계정을 찾습니다.
- X Community API — 커뮤니티 링크에서 소개, 멤버 수, 규칙, 가입 정책을 가져옵니다.
- X Community Posts API — 커뮤니티에 공유된 공개 게시물을 텍스트, 작성자, 상호작용 수와 함께 가져옵니다.
- X Community Members API — 커뮤니티 멤버를 소개글과 팔로워 수가 담긴 프로필로 내보냅니다.
- Twitter Tweet Scraper API
- Twitter Profile Scraper API
- Twitter User Tweets Scraper 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 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 Moderators API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API