쿼리 작성

search 엔드포인트는 GET 요청과 함께 단일 쿼리를 받고, 쿼리에 매칭되는 과거 게시물 집합을 반환합니다. 쿼리는 다양한 게시물 속성에 매칭되는 연산자로 구성됩니다.

쿼리 제한 사항

쿼리는 사용 중인 access level에 따라 제한됩니다:

Access level	Recent search	Full-archive search
Self-serve	512자	1,024자
Enterprise	4,096자	4,096자

연산자 사용 가능 여부

대부분의 연산자는 모든 개발자가 사용할 수 있지만, 일부는 특정 access level 전용입니다:

Core operators: 모든 Project 사용 시 이용 가능
Advanced operators: 특정 access level이 있는 Project 사용 시 이용 가능

가용성 상세는 전체 연산자 목록을 참고하세요.

연산자 유형: standalone 및 conjunction-required

Standalone 연산자는 단독으로 사용하거나, conjunction이 필요한 연산자를 포함한 다른 연산자들과 함께 사용할 수 있습니다. 예를 들어, #hashtag는 standalone 연산자이므로 다음 쿼리가 정상 동작합니다:

#xapiv2

Conjunction-required 연산자는 쿼리에서 단독으로 사용할 수 없으며, 최소 하나 이상의 standalone 연산자가 포함되어야만 사용할 수 있습니다. 이는 이러한 연산자를 단독으로 사용할 경우 매우 많은 양의 게시물이 매칭되기 때문입니다. 예를 들어, 다음 쿼리들은 conjunction-required 연산자만 포함하고 있으므로 지원되지 않습니다:

has:media

has:links OR is:retweet

여기에 "X data"와 같은 standalone 연산자를 추가하면 쿼리가 정상 동작합니다:

"X data" has:mentions (has:media OR has:links)

Boolean 연산자와 그룹화

다음 도구를 사용해 여러 연산자를 조합할 수 있습니다:

Operator	Description	Example
AND (공백)	두 조건을 모두 매칭해야 함	`snow day #NoSchool`은 “snow” AND “day” AND #NoSchool을 포함한 게시물에 매칭
OR	두 조건 중 하나라도 매칭	`grumpy OR cat OR #meme`은 “grumpy” OR “cat” OR #meme을 포함한 게시물에 매칭
NOT (대시)	이 조건에 매칭되는 게시물 제외	`cat #meme -grumpy`는 “cat”과 #meme을 포함하지만 “grumpy”는 포함하지 않는 게시물에 매칭
그룹화 (괄호)	연산자를 하나로 묶음	`(grumpy cat) OR (#meme has:images)`는 두 그룹 중 하나에 매칭

부정 관련 참고 사항

-is:nullcast 연산자는 반드시 부정된 형태로만 사용해야 합니다
부정된 연산자는 단독으로 사용할 수 없습니다
그룹화된 연산자를 부정하지 마세요. skiing -(snow OR day OR noschool) 대신 skiing -snow -day -noschool을 사용하세요

연산 우선순위

AND와 OR를 함께 사용할 때:

AND 로직으로 연결된 연산자가 먼저 결합됩니다
그 다음 OR 로직으로 연결된 연산자가 적용됩니다

예시:

Query	Evaluated as
`apple OR iphone ipad`	`apple OR (iphone ipad)`
`ipad iphone OR android`	`(iphone ipad) OR android`

모호함을 없애려면 괄호를 사용하세요:

(apple OR iphone) ipad

iphone (ipad OR android)

구두점, 발음 구별 부호, 대소문자 구분

발음 구별 부호: 악센트나 발음 구별 부호가 포함된 검색 쿼리는 악센트가 있는 게시물과 없는 게시물 모두에 매칭됩니다. 예를 들어 Diacrítica는 _Diacrítica_와 _Diacritica_에 모두 매칭됩니다. 대소문자 구분: 모든 연산자는 대소문자를 구분하지 않습니다. cat 쿼리는 cat, CAT, _Cat_에 모두 매칭됩니다.

Filtered stream은 다르게 동작합니다filtered stream 규칙을 작성할 때, 악센트가 포함된 키워드는 악센트가 있는 게시물에만 매칭됩니다. 예를 들어 Diacrítica는 _Diacrítica_에만 매칭되고 _Diacritica_에는 매칭되지 않습니다.

Quote Tweet 매칭

Search Posts를 사용할 때, 연산자는 Quote Tweet의 콘텐츠에 매칭되지만 인용된 원본 게시물의 콘텐츠에는 매칭되지 않습니다.

Filtered stream은 다르게 동작합니다—Quote Tweet과 원본 게시물의 콘텐츠 모두에 매칭됩니다.

구체성 및 효율성

단일 키워드나 해시태그와 같은 광범위한 연산자를 사용하는 것은 권장되지 않습니다—엄청난 양의 게시물이 매칭되어 사용량 한도를 빠르게 소진하게 됩니다.

효과적인 쿼리 작성을 위한 팁:

구체적으로 시작한 뒤 확장하기 — 관련성 있는 결과를 반환하는 타깃형 쿼리를 만드세요
여러 연산자 사용하기 — 연산자를 조합해 결과 범위를 좁히세요
문자 수 확인하기 — 쿼리 문자열 전체가 제한에 포함됩니다

예시 진행:

# Too broad - 200,000+ Posts per day
happy

# Better - adds language filter and exclusions
(happy OR happiness) lang:en -birthday -is:retweet

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet

반복적으로 쿼리 다듬기

1단계: 기본 쿼리로 시작

happy OR happiness

2단계: 결과를 기반으로 테스트 및 범위 좁히기

여러 언어의 게시물이 있었습니다. 언어 필터를 추가합니다:

(happy OR happiness) lang:en

생일 인사가 반환됩니다. 이를 제외하고 리트윗도 제외합니다:

(happy OR happiness) lang:en -birthday -is:retweet

3단계: 커버리지 확장

더 많은 감정을 포착하고 싶습니다. 관련 키워드를 추가합니다:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet

4단계: 트렌드에 맞춰 조정

Holiday 게시물이 등장합니다. 이를 제외합니다:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

요청에 쿼리 추가하기

query 파라미터를 사용하고 쿼리를 HTTP 인코딩하세요:

curl "https://api.x.com/2/tweets/search/recent?\
query=cat%20has%3Amedia%20-grumpy&\
tweet.fields=created_at&\
max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

쿼리 예시

자연재해 추적

허리케인 Harvey에 대한 기상 기관의 게시물에 매칭: 쿼리:

has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet

전체 요청 URL:

https://api.x.com/2/tweets/search/recent?query=has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1)%20-is%3Aretweet

#nowplaying에 대한 감성 분석

긍정 감성:

#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing

부정 감성:

#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible

Post annotations 사용

context: 연산자를 사용해 이미지가 있는 일본어 게시물 중 반려동물 관련(고양이 제외)을 찾기: 먼저 tweet.fields=context_annotations와 함께 Post lookup을 사용해 domain.entity ID를 확인합니다:

Cats: domain 66, entity 852262932607926273
Pets: domain 65, entity 852262932607926273

쿼리:

context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja

Getting Started

Products

Fundamentals

Partners & Customers

Resources

쿼리 제한 사항

연산자 사용 가능 여부

연산자 유형: standalone 및 conjunction-required

Boolean 연산자와 그룹화

연산 우선순위

구두점, 발음 구별 부호, 대소문자 구분

Quote Tweet 매칭

구체성 및 효율성

반복적으로 쿼리 다듬기

1단계: 기본 쿼리로 시작

2단계: 결과를 기반으로 테스트 및 범위 좁히기

3단계: 커버리지 확장

4단계: 트렌드에 맞춰 조정

요청에 쿼리 추가하기

쿼리 예시

자연재해 추적

#nowplaying에 대한 감성 분석

Post annotations 사용

도구

Query Builder Tool

다음 단계

연산자 레퍼런스

Search 퀵스타트

통합 가이드

​쿼리 제한 사항

​연산자 사용 가능 여부

​연산자 유형: standalone 및 conjunction-required

​Boolean 연산자와 그룹화

​연산 우선순위

​구두점, 발음 구별 부호, 대소문자 구분

​Quote Tweet 매칭

​구체성 및 효율성

​반복적으로 쿼리 다듬기

​1단계: 기본 쿼리로 시작

​2단계: 결과를 기반으로 테스트 및 범위 좁히기

​3단계: 커버리지 확장

​4단계: 트렌드에 맞춰 조정

​요청에 쿼리 추가하기

​쿼리 예시

​자연재해 추적

​#nowplaying에 대한 감성 분석

​Post annotations 사용

​도구

Query Builder Tool

​다음 단계

연산자 레퍼런스

Search 퀵스타트

통합 가이드

쿼리 제한 사항

연산자 사용 가능 여부

연산자 유형: standalone 및 conjunction-required

Boolean 연산자와 그룹화

연산 우선순위

구두점, 발음 구별 부호, 대소문자 구분

Quote Tweet 매칭

구체성 및 효율성

반복적으로 쿼리 다듬기

1단계: 기본 쿼리로 시작

2단계: 결과를 기반으로 테스트 및 범위 좁히기

3단계: 커버리지 확장

4단계: 트렌드에 맞춰 조정

요청에 쿼리 추가하기

쿼리 예시

자연재해 추적

#nowplaying에 대한 감성 분석

Post annotations 사용

도구

다음 단계