쿼리 작성

연산자를 사용해 검색 쿼리를 작성하는 방법을 알아봅니다

검색 엔드포인트는 GET 요청으로 단일 쿼리를 받아 해당 쿼리와 일치하는 과거 포스트 집합을 반환합니다. 쿼리는 다양한 포스트 속성에 매칭되는 연산자들로 구성됩니다.

---

​

쿼리 제한

사용 중인 액세스 수준에 따라 쿼리 길이에 다음과 같은 제한이 적용됩니다:

액세스 수준	최근 검색	전체 아카이브 검색
셀프 서비스	512자	1,024자
엔터프라이즈	4,096자	4,096자

---

​

연산자 사용 가능 여부

대부분의 연산자는 모든 개발자가 사용할 수 있지만, 일부는 특정 액세스 수준에서만 사용할 수 있습니다.

• 핵심 연산자: 모든 Project에서 사용할 수 있습니다.
• 고급 연산자: 특정 액세스 수준이 부여된 Project에서만 사용할 수 있습니다.

사용 가능 여부에 대한 자세한 내용은 전체 연산자 목록을 참고하세요.

---

​

연산자 유형: 단독 사용 가능 및 결합 필요

단독 연산자는 단독으로도 사용할 수 있고, (결합이 필요한 연산자를 포함해) 다른 어떤 연산자와도 함께 사용할 수 있습니다.

예를 들어, 이 쿼리는 #hashtag가 단독 연산자이기 때문에 유효합니다.

#xapiv2

연접 필수 연산자는 쿼리에서 단독으로 사용할 수 없으며, 하나 이상의 단독 사용 가능 연산자가 포함될 때에만 사용할 수 있습니다. 이는 이러한 연산자만 사용할 경우, 포스트가 지나치게 많이 매칭되기 때문입니다.

예를 들어, 다음 쿼리들은 연접 필수 연산자만 포함하고 있으므로 지원되지 않습니다:

has:media

has:links OR is:retweet

"X data"와 같은 구문을 단독 연산자로 추가하면 쿼리가 올바르게 동작합니다.

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

---

​

불리언 연산자와 그룹화

여러 연산자를 다음 도구를 사용해 함께 연결할 수 있습니다:

Operator	Description	Example
AND (space)	포스트는 두 조건을 모두 만족해야 합니다	snow day #NoSchool은 “snow” AND “day” AND #NoSchool을 모두 포함하는 포스트와 일치합니다
OR	포스트는 두 조건 중 하나 이상을 만족하면 됩니다	grumpy OR cat OR #meme은 “grumpy” OR “cat” OR #meme 중 하나를 포함하는 포스트와 일치합니다
NOT (dash)	이 조건과 일치하는 포스트를 제외합니다	cat #meme -grumpy는 “cat”과 #meme은 포함하지만 “grumpy”는 포함하지 않는 포스트와 일치합니다
Grouping (parentheses)	연산자들을 괄호로 묶어 그룹화합니다	(grumpy cat) OR (#meme has:images)는 두 그룹 중 하나와 일치합니다

부정에 대한 참고 사항

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

---

​

연산 순서

AND와 OR를 함께 사용할 때:

1. AND 논리로 연결된 연산자가 먼저 평가됩니다
2. 그다음 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)

---

​

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

발음 구별 기호(Diacritics): 악센트나 발음 구별 기호가 포함된 검색어는 해당 기호가 있는 포스트와 없는 포스트 모두에 일치합니다. 예를 들어, 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과 원본 게시물의 내용 모두와 일치합니다.

---

​

구체성과 효율성

단일 키워드나 해시태그와 같은 광범위한 연산자만 사용하는 것은 권장되지 않습니다. 방대한 양의 포스트와 일치하여 사용 한도를 빠르게 소진하게 됩니다.

효과적인 쿼리를 구성하기 위한 팁:

1. 처음에는 구체적으로 시작한 뒤, 점차 범위를 넓히세요 — 관련성이 높은 결과를 반환하는 타깃 쿼리를 만드세요
2. 여러 연산자를 사용하세요 — 연산자를 조합해 결과를 좁히세요
3. 문자 수를 주의하세요 — 전체 쿼리 문자열이 제한에 포함됩니다

예시 발전 단계:

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

# 개선됨 - 언어 필터 및 제외 조건 추가
(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단계: 트렌드에 맞게 조정

휴일 포스트가 결과에 나타납니다. 제외하세요:

(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

​

게시물 주석 활용

context: 연산자를 사용하여 반려동물(고양이 제외)에 대한 일본어 포스트 중 이미지가 포함된 포스트를 찾습니다:

먼저 게시물 조회를 사용하고 tweet.fields=context_annotations를 지정하여 domain.entity ID를 확인합니다:

• 고양이: domain 66, entity 852262932607926273
• 반려동물: domain 65, entity 852262932607926273

쿼리:

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

---

​

도구

쿼리 빌더 도구

인터랙티브하게 쿼리를 작성하고 테스트해 보세요

---

​

다음 단계

연산자 참조

모든 사용 가능한 연산자 목록

검색 빠른 시작

첫 검색 요청 보내기

연동 가이드

전체 연동 문서