x/
search-communities

키워드로 X 커뮤니티를 검색하고, 일치하는 커뮤니티마다 이름, 링크, 배너 이미지, 멤버 수, 민감한 콘텐츠 표시를 검색어당 최대 500개까지 반환합니다.

X Communities Search API

키워드 입력
커뮤니티별 멤버 수
민감한 콘텐츠 표시
결과당 0.7 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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 사용 방법

키워드로 검색하고 일치하는 커뮤니티를 페이지 단위로 읽습니다.

  1. {"query": "bitcoin", "results_limit": 20}을 /v1/x/search-communities로 POST합니다.
  2. status가 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링합니다.
  3. 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 값과 함께 저장하세요.

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 — 커뮤니티 멤버를 소개글과 팔로워 수가 담긴 프로필로 내보냅니다.

다른 플랫폼 둘러보기

X 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

X Communities Search API — 자주 묻는 질문

X Communities Search API는 키워드와 일치하는 X 커뮤니티를 찾는 프로그래밍 인터페이스입니다. 커뮤니티마다 id, url, 이름, 배너 이미지, 멤버 수, 민감한 콘텐츠 표시를 반환합니다.

query 값에 키워드를 넣어 보내세요(예: bitcoin). 일치하는 커뮤니티가 이름, 링크, 멤버 수와 함께 반환되며, X에서 바로 열거나 다른 커뮤니티 엔드포인트에 넘길 수 있습니다.

네, 직접 작성한 코드에서 가능합니다. 모든 결과에 metrics.members_count 값이 들어 있으므로, 먼저 결과를 모은 뒤 정렬하거나 최소 규모 조건을 적용하세요.

최대 500개입니다. results_limit 값은 10부터 500까지 10의 배수를 받고 기본값은 20이며, 결과는 next_cursor로 페이지 단위로 읽습니다.

X가 커뮤니티를 민감한 콘텐츠가 포함된 곳으로 지정하면 true, 그렇지 않으면 false입니다.

아니요. 검색 결과에는 이름, 배너, 멤버 수, 민감한 콘텐츠 표시가 담깁니다. 소개, 규칙, 가입 정책이 필요하면 url 값을 X Community API에 넘기세요.

일치하는 커뮤니티가 없다는 뜻입니다. 작업은 빈 결과로 성공 처리되며 요금은 청구되지 않습니다.