쿼리 빌드

​

게시물 검색을 위한 쿼리 빌드

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

​

목차

• 쿼리 빌드
• 쿼리 제한사항
• 연산자 지원 여부
• 연산자 유형: 단독 사용 vs. 결합 필요
• 불리언 연산자와 그룹화
• 연산 순서
• 구두점, 발음 구별 부호, 대소문자 구분
• 특이성 및 효율성
• 인용 트윗 매칭 동작
• 쿼리의 점진적 빌드
• 요청에 쿼리 추가하기
• 쿼리 예시
• 연산자 목록

​

쿼리 작성하기

​

쿼리 제한

사용 중인 액세스 레벨에 따라 쿼리에 제한이 적용됩니다.

Basic 또는 Pro 액세스의 경우 최근 검색 엔드포인트에서 쿼리 길이는 최대 512자입니다.

Pro 액세스의 경우 전체 아카이브 검색 엔드포인트에서 쿼리 길이는 최대 1,024자입니다. 

​

연산자 사용 가능 여부

대부분의 연산자는 모든 개발자가 사용할 수 있지만, 특정 액세스 수준에만 제공되는 연산자도 있습니다. 각 연산자가 어떤 액세스 수준에서 사용 가능한지는 다음 레이블을 사용해 연산자 목록 표에 표시합니다.

• 핵심 연산자: 어떤 Project에서도 사용 가능.
• 고급 연산자: 특정 액세스 수준이 있는 Project에서 사용 가능.

​

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

단독 연산자는 혼자서도, 또는 다른 모든 연산자(결합이 필요한 연산자 포함)와 함께도 사용할 수 있습니다.

예를 들어, 다음 쿼리는 단독 연산자인 #hashtag 연산자를 사용하므로 작동합니다:

#xapiv2

결합 필요 연산자는 쿼리에서 단독으로 사용할 수 없습니다. 쿼리에 최소 한 개의 단독 연산자가 포함되어 있을 때만 사용할 수 있습니다. 이는 이러한 연산자를 단독으로 사용하면 조건이 지나치게 포괄적이 되어 매우 많은 양의 게시물과 일치하게 되기 때문입니다.

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

has:media

has:links OR is:retweet

"X data"와 같은 단독 연산자를 추가하면 해당 쿼리는 정상적으로 작동합니다.

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

​

불리언 연산자와 그룹화

단일 쿼리에서 여러 연산자를 연결해 사용하려면 다음 도구를 활용할 수 있습니다:

AND 로직	연속된 연산자 사이에 공백이 있으면 불리언 “AND” 로직이 적용되어, 두 조건이 모두 충족될 때만 게시물이 매칭됩니다. 예를 들어 snow day #NoSchool은 snow와 day라는 용어와 해시태그 #NoSchool이 포함된 게시물과 매칭됩니다.
OR 로직	연속된 연산자 사이에 OR이 있으면 OR 로직이 적용되어, 둘 중 하나의 조건만 충족해도 게시물이 매칭됩니다. 예를 들어 grumpy OR cat OR #meme을 지정하면 grumpy 또는 cat이라는 용어, 혹은 해시태그 #meme이 포함된 모든 게시물과 매칭됩니다.
NOT 로직, 부정	키워드(또는 임의의 연산자) 앞에 대시(-)를 붙이면 이를 부정(NOT)합니다. 예를 들어 cat #meme -grumpy는 해시태그 #meme과 용어 cat이 포함된 게시물 중에서, 용어 grumpy가 포함되지 않은 게시물에만 매칭됩니다. 자주 쓰이는 쿼리 절로 -is:retweet이 있으며, 이는 리트윗에는 매칭되지 않아 원본 게시물, 인용 트윗, 답글에만 매칭됩니다. 모든 연산자는 부정할 수 있지만, 부정된 연산자만 단독으로 사용할 수는 없습니다.
그룹화	괄호를 사용하여 연산자를 함께 그룹화할 수 있습니다. 예를 들어 (grumpy cat) OR (#meme has:images)는 grumpy와 cat이라는 용어가 포함된 게시물이거나, 이미지가 있고 해시태그 #meme이 포함된 게시물을 반환합니다. AND가 먼저 적용되고, 그 다음에 OR이 적용된다는 점에 유의하세요.

부정에 대한 참고 사항

연산자 -is:nullcast는 항상 부정 형태로 사용해야 합니다.

부정된 연산자는 단독으로 사용할 수 없습니다.

괄호로 묶인 연산자 집합 전체를 한꺼번에 부정하지 마세요. 대신 각 개별 연산자를 부정하세요. 예를 들어 skiing -(snow OR day OR noschool)을 사용하는 대신 skiing -snow -day -noschool을 사용하는 것을 권장합니다. 

​

연산 순서

AND와 OR 기능을 함께 사용할 때는 다음 연산 순서에 따라 쿼리가 평가됩니다.

1. AND 논리로 연결된 연산자가 먼저 결합됩니다.
2. 그다음 OR 논리로 연결된 연산자가 적용됩니다.

예를 들어:

• 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 또는 해시태그 #cumpleaños로 쿼리하면, 틸데가 있는 í나 에녜가 있는 형태인 Diacrítica, _#cumpleaños_뿐만 아니라, 틸데나 에녜가 없는 Diacritica, _#cumpleanos_와도 일치합니다.

악센트나 발음 구별 부호가 있는 문자는 일반 문자와 동일하게 처리되며, 단어 경계로 간주되지 않습니다. 예를 들어, 키워드 cumpleaños로 쿼리하면 단어 _cumpleaños_를 포함하는 항목과만 일치하며, cumplea, cumplean, _os_를 포함하는 항목과는 일치하지 않습니다.

모든 연산자는 대소문자를 구분하지 않고 평가됩니다. 예를 들어, 쿼리 cat은 다음 모든 형태를 포함한 게시물과 일치합니다: cat, CAT, Cat.

filtered stream의 매칭 동작은 Search Posts와 다릅니다. building a filtered stream rule 시, 악센트와 발음 구별 부호가 포함된 키워드와 해시태그는 동일한 부호가 포함된 용어에만 일치하며, 일반 문자만 사용하는 용어에는 일치하지 않는다는 점을 유의하세요.

예를 들어, 키워드 Diacrítica 또는 해시태그 #cumpleaños를 포함하는 filtered stream 규칙은 Diacrítica 및 _#cumpleaños_에만 일치하며, 틸데나 에녜가 없는 Diacritica 또는 _#cumpleanos_에는 일치하지 않습니다.

​

구체성과 효율성

쿼리를 작성하기 시작할 때 염두에 둘 몇 가지가 있습니다.

• 단일 키워드나 #hashtag처럼 범위가 넓은 독립 연산자만으로 쿼리를 구성하는 것은 일반적으로 권장되지 않습니다. 방대한 양의 게시물과 일치할 가능성이 높기 때문입니다. 더 탄탄한 쿼리를 작성하면 더 구체적인 일치 게시물 집합을 얻을 수 있고, 가치 있는 인사이트를 찾기 위해 살펴봐야 하는 페이로드의 잡음도 줄일 수 있습니다.
  • 예를 들어, 쿼리가 키워드 happy 하나뿐이라면 하루에 200,000~300,000개의 게시물을 받게 될 가능성이 큽니다.
  • 조건 연산자를 더 추가하면 검색 결과 범위가 좁아집니다. 예: (happy OR happiness) place_country:GB -birthday -is:retweet
• 효율적인 쿼리를 작성하면 쿼리 길이의 문자 제한을 준수하는 데에도 도움이 됩니다. 문자 수에는 공백과 연산자를 포함한 전체 쿼리 문자열이 모두 포함됩니다.
  • 예를 들어, 다음 쿼리의 길이는 59자입니다: (happy OR happiness) place_country:GB -birthday -is:retweet

​

인용 트윗 일치 동작

Search Posts 엔드포인트를 사용할 때 연산자는 인용된 원본 게시물의 콘텐츠에는 일치하지 않지만, 인용 트윗에 포함된 콘텐츠에는 일치합니다.

다만, filtered stream은 인용된 원본 게시물의 콘텐츠와 인용 트윗의 콘텐츠 모두에 대해 일치한다는 점에 유의하세요.

​

반복적으로 쿼리 구성하기

쿼리는 일찍, 그리고 자주 테스트하세요

처음부터 “정확한” 결과를 반환하는 쿼리를 만드는 일은 드뭅니다. X에는 처음에는 눈에 띄지 않을 수 있는 요소가 매우 많고, 위에서 설명한 쿼리 구문을 원하는 검색에 정확히 맞추기도 어렵습니다. 쿼리를 작성할 때는 주기적으로 테스트하는 것이 중요합니다.

이 섹션에서는 다음 쿼리로 시작한 뒤, 테스트에서 얻은 결과를 바탕으로 조정해 보겠습니다: 

happy OR happiness

결과를 활용해 쿼리를 좁히기

쿼리를 테스트할 때는 반환된 게시물을 훑어보며 기대한 데이터가 포함되어 있는지 확인해야 합니다. 넓은 범위의 쿼리와 더 큰 게시물 매칭 집합으로 시작하면 결과를 검토한 뒤 원치 않는 결과를 걸러내도록 쿼리를 좁혀갈 수 있습니다.  

예시 쿼리를 테스트해 보니 다양한 언어의 게시물이 포함되어 있었습니다. 이 경우 영어 게시물만 받도록 lang: 연산자를 추가합니다:

(happy OR happiness) lang:en

테스트 결과 생일 축하와 관련된 게시물이 다수 포함되어 있어, 부정 키워드 연산자로 -birthday를 추가합니다. 또한 원본 게시물만 받기 위해 부정 연산자 -is:retweet도 추가합니다:

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

필요한 경우 포함 범위 조정

예상한 데이터가 오지 않고, 반환되어야 할 기존 게시물이 있다는 것을 알고 있다면, 원하는 데이터를 걸러내는 연산자를 제거해 쿼리 범위를 넓여야 할 수 있습니다.

예시에서 우리가 찾는 감정을 표현한 다른 게시물들이 개인 타임라인에 있었지만, 테스트 결과에는 포함되지 않았음을 확인했습니다. 더 넓은 범위를 포괄하기 위해 키워드 excited와 elated를 추가하겠습니다.

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

기간 내 유행/급증 패턴에 맞춰 조정하기

X에서는 트렌드가 빠르게 나타났다가 사라집니다. 쿼리 관리는 능동적으로 수행해야 합니다. 쿼리를 오래 사용할 계획이라면, 수집 중인 데이터를 주기적으로 점검해 조정이 필요한지 확인하는 것을 권장합니다.

예시에서 “happy holidays”를 기원하는 게시물이 수집되기 시작한 것을 확인했습니다. 이러한 게시물을 결과에서 제외하려 하므로 부정 키워드 -holidays를 추가하겠습니다.

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

​

요청에 쿼리 추가하기

요청에 쿼리를 추가하려면 query 매개변수를 사용해야 합니다. 다른 쿼리 매개변수와 마찬가지로, 작성한 쿼리를 HTTP로 인코딩했는지 확인해야 합니다.

다음은 cURL 명령을 사용한 예시로, tweet.fields와 max_results 매개변수도 포함되어 있습니다. 이 명령을 사용하려면 $BEARER_TOKEN을 본인의 베어러 토큰으로 교체하세요:

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"

​

쿼리 예제

​

자연재해 추적

다음 쿼리는 2017년 휴스턴을 강타한 허리케인 하비를 다루는 기상 기관과 관측소의 원본 게시물에 매칭되었습니다.

HTTP 인코딩을 적용하지 않은 쿼리는 다음과 같습니다:

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

HTTP 인코딩, 쿼리 매개변수, 최근 검색 URI를 포함한 쿼리는 다음과 같습니다:

https://api.x.com/2/tweets/search/recent?query=-is%3Aretweet%20has%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)

​

대화의 감성 검토

다음 규칙은 해시태그 _#nowplaying_을 중심으로 전개되는 대화의 감성을 더 잘 파악하는 데 사용할 수 있으며, 범위는 북미 지역에서 게시된 게시물로만 제한됩니다.

다음은 두 가지 서로 다른 쿼리(긍정용과 부정용)가 HTTP 인코딩 없이 표시되는 예시입니다:

#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

다음은 HTTP 인코딩, 쿼리 매개변수, 그리고 최근 검색 URI를 포함했을 때의 쿼리 예시입니다:

https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing

https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible

​

특정 게시물 주석과 관련된 게시물 찾기

이 규칙은 게시물의 언어가 일본어로 식별된 경우, 고양이를 제외한 반려동물 이미지를 포함한 원본 게시물을 검색하도록 설계되었습니다. 이를 위해 게시물 주석 기능을 활용하는 context: 연산자를 사용했습니다. 먼저 게시물 조회 엔드포인트와 tweet.fields=context_annotations 필드 매개변수를 사용하여 쿼리에 적용할 domain.entity ID를 식별했습니다:

• 고양이와 관련된 게시물은 domain 66(Interests and Hobbies 카테고리)과 entity 852262932607926273(Cats)을 반환합니다.
• 반려동물과 관련된 게시물은 domain 65(Interests and Hobbies Vertical)과 entity 852262932607926273(Pets)을 반환합니다.

HTTP 인코딩 없이 쿼리는 다음과 같습니다:

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

HTTP 인코딩, 쿼리 매개변수, 최신 검색 URI를 포함한 쿼리는 다음과 같습니다:

https://api.x.com/2/tweets/search/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja

추가 안내가 필요하면 쿼리 빌더 도구를 사용해 보세요. 

​

연산자

참고: 일부 연산자는 다른 이름(별칭)을 사용할 수 있습니다.

| 연산자 | 유형 | 설명 | | :---------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | --------------- | ------------------------------ | ----------- | --------------- | ----------------------------------- | -------------- | ------------- | --------------------------------------- | -------------------- | ------------ | -------------------------------- | ------------ | --------------- | -------------------------------- | ----------- | ----------- | ---------------------------------- | -------------------------- | ------------- | ------------------------------ | --------------- | ------------ | -------------------------------- | --------------- | ------------- | ----------------------------- | ---------------- | ------------ | ------------------------------ | ------------- | ---------------- | ---------------------------------------------- | -------------- | -------------- | ------------------------------ | ------------- | ------------- | ---------------------------------- | ----------- | ------------- | ------------------------------ | ------------ | --------------------------- | ------------------------------- | --------- | ------------ | ---------------------------------- | ------------- | ------------- | ------------------------------- | ---------------- | | keyword | 단독 | 게시물 본문에서 키워드를 일치시킵니다. 이는 토큰화 일치로, 키워드 문자열이 게시물 본문의 토큰화된 텍스트와 비교됩니다. 토큰화는 문장 부호, 기호, 유니코드 기본 평면 구분 문자를 기준으로 단어를 분할합니다.

예를 들어, 텍스트 “I like coca-cola”가 포함된 게시물은 다음 토큰으로 분할됩니다: I, like, coca, cola. 그런 다음 이러한 토큰이 쿼리에 사용한 키워드 문자열과 비교됩니다. 문장 부호(예: coca-cola), 기호, 또는 구분 문자가 포함된 문자열과 일치시키려면 키워드를 큰따옴표로 감싸야 합니다.

예시: pepsi OR cola OR "coca cola" | | emoji | 단독 | 게시물 본문에서 이모지를 일치시킵니다. 키워드와 마찬가지로 이모지도 토큰화 일치이며, 사용한 이모지가 게시물 본문의 토큰화된 텍스트와 비교됩니다.

이모지에 변형이 있는 경우, 쿼리에 추가하려면 큰따옴표로 감싸야 합니다.

예시: (😃 OR 😡) 😬 | | "exact phrase match" | 단독 | 게시물 본문에서 정확한 구절을 일치시킵니다.

예시: ("X API" OR #v2) -"recent search" | | # | 단독 | 게시물에 인식된 해시태그가 포함된 경우를 일치시킵니다(해시태그가 게시물 내에서 인식된 엔터티인 경우).

이 연산자는 토큰화 일치가 아닌 정확 일치를 수행하므로, 규칙 #thanku는 정확히 #thanku 해시태그가 있는 게시물과는 일치하지만 #thankunext 해시태그가 있는 게시물과는 일치하지 않습니다.

예시: #thankunext #fanart OR @arianagrande | | @ | 단독 | 지정한 사용자명을 언급한 게시물을 일치시킵니다(사용자명이 @ 문자를 포함하는 인식된 엔터티인 경우).

예시: (@XDevelopers OR @API) -@X | | $ | 단독 | 지정된 ‘캐시태그’(토큰의 첫 문자가 $인 경우)가 포함된 게시물을 일치시킵니다.<br /><br />캐시태그 연산자는 본문에서 캐시태그를 추출하려고 시도하는 대신, X의 ‘symbols’ 엔터티 추출에 의존해 캐시태그를 일치시킵니다.<br /><br />예시: `$twtr OR @XDevelopers -fb` | | `from:` | 단독 | 특정 사용자가 작성한 게시물을 일치시킵니다.<br />값은 사용자명(@ 문자는 제외) 또는 사용자의 숫자형 사용자 ID일 수 있습니다.<br /><br />`from:` 연산자당 하나의 사용자명/ID만 전달할 수 있습니다.<br /><br />예시: `from:XDevelopers OR from:API -from:X` | | `to:` | 단독 | 특정 사용자에게 보낸 답글인 게시물을 일치시킵니다.<br />값은 사용자명(@ 문자는 제외) 또는 사용자의 숫자형 사용자 ID일 수 있습니다.<br /><br />`to:` 연산자당 하나의 사용자명/ID만 전달할 수 있습니다.<br /><br />예시: `to:XDevelopers OR to:API -to:X` | | `url:` | 단독 | 게시물의 유효한 형식의 URL에 대해 토큰화 일치를 수행합니다.<br /><br />이 연산자는 `url` 또는 `expanded_url` 필드의 내용을 기준으로 일치합니다. 예를 들어, “You should check out X Developer Labs: https://t.co/c0A36SWil4”를 포함하는 게시물(단축 URL이 https://developer.twitter.com 으로 리디렉트됨)은 다음 두 규칙 모두와 일치합니다:<br /><br />`from:XDevelopers url:"https://developer.twitter.com"` (이는 `entities.urls.expanded_url`의 내용과 일치하기 때문)<br /><br />`from:XDevelopers url:"https://t.co"` (이는 `entities.urls.url`의 내용과 일치하기 때문)<br /><br />문장 부호나 특수 문자가 포함된 토큰과 구절은 큰따옴표로 감싸야 합니다(예: `url:"/developer"`). 마찬가지로 특정 프로토콜과 일치시키려면 큰따옴표로 감싸세요(예: `url:"https://developer.twitter.com"`). | | `retweets_of:` | 단독 | 지정한 사용자의 리트윗인 게시물을 일치시킵니다. 값은 사용자명(@ 문자는 제외) 또는 사용자의 숫자형 사용자 ID일 수 있습니다.<br /><br />`retweets_of:` 연산자당 하나의 사용자명/ID만 전달할 수 있습니다.<br /><br />예시: `retweets_of:twitterdev OR retweets_of:twitterapi` | | `in_reply_to_tweet_id:` | 단독 | *사용 가능한 별칭:* `in_reply_to_status_id:`<br />지정한 게시물에 대한 답글을 일치시킵니다.<br /><br />예시: `in_reply_to_tweet_id:1539382664746020864` | | `retweets_of_tweet_id:` | 단독 | *사용 가능한 별칭:* `retweets_of_status_id:`<br />지정한 게시물의 명시적(또는 네이티브) 리트윗을 일치시킵니다. 사용해야 하는 게시물 ID는 리트윗이 아닌 원본 게시물의 ID여야 합니다.<br /><br />예시: `retweets_of_tweet_id:1539382664746020864` | | `quotes_of_tweet_id:` | 단독 | *사용 가능한 별칭:* `quotes_of_status_id:`<br />지정한 게시물의 인용 트윗을 일치시킵니다. 사용해야 하는 게시물 ID는 인용 트윗이 아닌 원본 게시물의 ID여야 합니다.<br /><br />예시: `quotes_of_tweet_id:1539382664746020864` | | `context:` | 단독 | 특정 도메인 id/엔터티 id 쌍을 가진 게시물을 일치시킵니다. 이 연산자에 대해 자세히 알아보려면 [annotations](/ko/x-api/fundamentals/post-annotations) 페이지를 방문하세요.<br /><br />`context:` 연산자당 하나의 도메인/엔터티만 전달할 수 있습니다.<br /><br />`context:domain_id.entity_id`<br /><br />또한 OR 연산자를 사용해 여러 도메인/엔터티를 결합할 수 있습니다:<br /><br />`(context:47.1139229372198469633 OR context:11.1088514520308342784)`<br /><br />예시:<br />`context:10.799022225751871488` (`domain_id.entity_id`는 해당 도메인-엔터티 쌍과 일치하는 게시물을 반환) | | `entity:` | 단독 | 특정 엔터티 문자열 값을 가진 게시물을 일치시킵니다. 이 연산자에 대해 자세히 알아보려면 [annotations](/ko/x-api/fundamentals/post-annotations) 페이지를 방문하세요.<br />**참고**: 이는 최근 검색에서만 사용할 수 있습니다.<br /><br />`entity:` 연산자는 하나만 전달할 수 있습니다.<br /><br />`entity:"string declaration of entity/place"`<br /><br />예시: `entity:"Michael Jordan" OR entity:"Barcelona"` | | `conversation_id:` | 단독 | 동일한 대화 ID를 공유하는 게시물을 일치시킵니다. 대화 ID는 대화를 시작한 게시물의 게시물 ID로 설정됩니다. 게시물에 대한 답글이 게시될 때(답글에 대한 답글 포함) `conversation_id`가 해당 JSON 페이로드에 추가됩니다.<br /><br />`conversation_id:` 연산자당 하나의 대화 ID만 전달할 수 있습니다.<br /><br />예시: `conversation_id:1334987486343299072 (from:XDevelopers OR from:api)` | | `list:` | Standalone | **신규** 지정된 리스트의 구성원인 사용자가 게시한 게시물과 일치합니다.<br /><br />예를 들어 @XDevelopers와 @api가 리스트 123의 구성원이고 쿼리에 `list:123`을 포함한 경우, 응답에는 해당 계정이 게시한 게시물만 포함됩니다. [List lookup](/ko/x-api/lists/list-lookup/introduction) 엔드포인트를 사용하여 리스트 ID를 확인할 수 있습니다.<br /><br />주의: 쿼리당 `list:` 연산자는 하나만 사용할 수 있으며, 각 `list:` 연산자에는 하나의 리스트만 지정할 수 있습니다.<br /><br />예시: `list:123` | | `place:` | Standalone | 지정된 위치 또는 X place ID로 태그된 게시물과 일치합니다. 여러 단어로 된 장소 이름(“New York City”, “Palo Alto”)은 따옴표로 감싸야 합니다.<br /><br />각 `place:` 연산자에는 하나의 장소만 전달할 수 있습니다.<br /><br />참고: X place ID를 얻는 방법은 [GET geo/search](https://developer.x.com/content/developer-twitter/en/docs/geo/places-near-location/api-reference/get-geo-search) Standard v1.1 엔드포인트를 참조하세요.<br /><br />참고: 이 연산자는 리트윗에는 일치하지 않습니다. 리트윗의 장소 정보는 원본 게시물에 연결되기 때문입니다. 또한 인용 트윗의 원본 게시물에 연결된 장소에도 일치하지 않습니다.<br /><br />예시: `place:"new york city" OR place:seattle OR place:fd70c22040963ac7` | | `place_country:` | Standalone | 태그된 장소/위치에 연결된 국가 코드가 지정된 ISO 알파-2 문자 코드와 일치하는 게시물과 일치합니다.<br /><br />유효한 ISO 코드 목록은 [Wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)에서 확인할 수 있습니다.<br /><br />각 `place_country:` 연산자에는 하나의 ISO 코드만 전달할 수 있습니다.<br /><br />참고: 이 연산자는 리트윗에는 일치하지 않습니다. 리트윗의 장소 정보는 원본 게시물에 연결되기 때문입니다. 또한 인용 트윗의 원본 게시물에 연결된 장소에도 일치하지 않습니다.<br /><br />예시: `place_country:US OR place_country:MX OR place_country:CA` | | `point_radius:` | Standalone | 해당되는 경우 게시물의 `place.geo.coordinates` 객체와, X에서는 장소 지오 폴리곤에 대해 일치시키며, 장소 폴리곤이 정의된 영역에 완전히 포함될 때 일치합니다.<br /><br />`point_radius:[longitude latitude radius]`<br /><br />- 지원되는 반지름 단위는 마일(mi)과 킬로미터(km)입니다<br />- 반지름은 25mi 미만이어야 합니다<br />- 경도는 ±180 범위입니다<br />- 위도는 ±90 범위입니다<br />- 모든 좌표는 소수점 각도(십진 도)입니다<br />- 규칙 인수는 대괄호로 감싸고 공백으로 구분합니다<br /><br />각 `point_radius:` 연산자에는 하나의 지오 폴리곤만 전달할 수 있습니다.<br /><br />참고: 이 연산자는 리트윗에는 일치하지 않습니다. 리트윗의 장소 정보는 원본 게시물에 연결되기 때문입니다. 또한 인용 트윗의 원본 게시물에 연결된 장소에도 일치하지 않습니다.<br /><br />예시: `point_radius:[2.355128 48.861118 16km] OR point_radius:[-41.287336 174.761070 20mi]` | | `bounding_box:` | Standalone | *사용 가능한 별칭:* `geo_bounding_box:`<br />해당되는 경우 게시물의 place.geo.coordinates 객체와, X에서는 장소 지오 폴리곤에 대해 일치시키며, 장소 폴리곤이 정의된 영역에 완전히 포함될 때 일치합니다.<br /><br />`bounding_box:[west_long south_lat east_long north_lat]`<br /><br />- `west_long south_lat`는 경계 상자의 남서쪽 모서리를 나타내며, `west_long`은 그 지점의 경도이고 `south_lat`은 위도입니다.<br />- `east_long north_lat`는 경계 상자의 북동쪽 모서리를 나타내며, `east_long`은 그 지점의 경도이고 `north_lat`은 위도입니다.<br />- 경계 상자의 너비와 높이는 25mi 미만이어야 합니다<br />- 경도는 ±180 범위입니다<br />- 위도는 ±90 범위입니다<br />- 모든 좌표는 소수점 각도(십진 도)입니다.<br />- 규칙 인수는 대괄호로 감싸고 공백으로 구분합니다.<br /><br />각 `bounding_box:` 연산자에는 하나의 지오 폴리곤만 전달할 수 있습니다.<br /><br />참고: 이 연산자는 리트윗에는 일치하지 않습니다. 리트윗의 장소 정보는 원본 게시물에 연결되기 때문입니다. 또한 인용 트윗의 원본 게시물에 연결된 장소에도 일치하지 않습니다.<br /><br />예시: `bounding_box:[-105.301758 39.964069 -105.178505 40.09455]` | | `is:retweet` | Conjunction required | 지정된 규칙의 나머지 조건과도 일치하는 리트윗과 매칭합니다. 이 연산자는 진짜 리트윗(예: 리트윗 버튼으로 생성된 것)만 찾습니다. 인용 트윗은 이 연산자에 일치하지 않습니다.<br /><br />예시: `data @XDevelopers -is:retweet` | | `is:reply` | Conjunction required | 규칙과 일치하는 명시적 답글만 전달합니다. 또한 부정하여 쿼리와 일치하는 답글을 전달에서 제외할 수 있습니다.<br /><br />참고: 이 연산자는 필터드 스트림 엔드포인트에서도 사용할 수 있습니다. 필터드 스트림에서 사용하면 원본 게시물에 대한 답글, 인용 트윗의 답글, 리트윗의 답글에 일치합니다.<br /><br />예시: `from:XDevelopers is:reply` | | `is:quote` | Conjunction required | 모든 인용 트윗(댓글이 포함된 게시물)을 반환합니다.<br /><br />예시: `"sentiment analysis" is:quote` | | `is:verified` | Conjunction required | 작성자가 X에서 인증된 게시물만 전달합니다.<br /><br />예시: `#nowplaying is:verified` | | `-is:nullcast` | Conjunction required | ads.twitter.com에서 프로모션 전용으로 생성되어 `"source":"Twitter for Advertisers (legacy)"` 또는 `"source":"Twitter for Advertisers"` 값을 가진 게시물을 제거합니다.<br />이 연산자는 반드시 부정형으로 사용해야 합니다.<br /><br />Nullcast된 게시물에 대한 자세한 내용은 [Post availability](https://developer.x.com/content/developer-twitter/en/docs/twitter-api/v1/tweets/post-and-engage/guides/tweet-availability) 페이지를 참조하세요.<br /><br />예시: `"mobile games" -is:nullcast` | | `has:hashtags` | Conjunction required | 하나 이상의 해시태그를 포함하는 게시물과 일치합니다.<br /><br />예시: `from:XDevelopers -has:hashtags` | | `has:cashtags` | Conjunction required | 캐시태그 기호(앞에 ‘’ 문자가 붙은 형태, 예: $tag)를 포함하는 게시물과 일치합니다.

예시: #stonks has:cashtags | | has:links | Conjunction required | 본문에 링크와 미디어가 포함된 게시물과 일치합니다.

예시: from:XDevelopers announcement has:links | | has:mentions | Conjunction required | 다른 X 사용자를 멘션한 게시물과 일치합니다.

예시: #nowplaying has:mentions | | has:media | Conjunction required | 사용 가능한 별칭: has:media_link
사진, GIF, 동영상 등 X에서 판별한 미디어 객체를 포함하는 게시물과 일치합니다. Periscope로 생성된 미디어나 다른 미디어 호스팅 사이트로의 링크가 있는 게시물에는 일치하지 않습니다.

예시: (kittens OR puppies) has:media | | has:images | Conjunction required | 이미지에 대한 인식된 URL을 포함하는 게시물과 일치합니다.

예시: #meme has:images | | has:video_link | Conjunction required | 사용 가능한 별칭: has:videos
X에 직접 업로드된 네이티브 X 동영상을 포함하는 게시물과 일치합니다. Periscope로 생성된 동영상이나 다른 동영상 호스팅 사이트로의 링크가 있는 게시물에는 일치하지 않습니다.

예시: #icebucketchallenge has:video_link | | has:geo | 연결사 필요 | X 사용자가 제공한, 게시물에 특화된 지리 정보가 있는 게시물과 일치합니다. 이는 표시 이름, 지오 폴리곤 및 기타 필드를 포함한 X 장소 형태의 위치이거나, 드문 경우 위도–경도 좌표일 수 있습니다.

참고: 장소(게시물 지오)를 기준으로 일치시키는 연산자는 원본 게시물만 포함합니다. 리트윗에는 장소 데이터가 없습니다.

예: recommend #paris has:geo -bakery | | lang: | 연결사 필요 | X에서 특정 언어로 분류된 게시물과 일치합니다(게시물이 분류된 경우에 한함). 현재 각 게시물은 하나의 언어로만 분류되므로 여러 언어를 AND로 결합하면 결과가 나오지 않습니다.

lang: 연산자당 단 하나의 BCP 47 언어 식별자만 전달할 수 있습니다.

참고: 언어 분류가 불가능한 경우 제공되는 결과는 ‘und’(정의되지 않음)입니다.

예: recommend #paris lang:en

아래 목록은 현재 지원되는 언어와 해당 BCP 47 언어 식별자를 나타냅니다:

Amharic: am | German: de | Malayalam: ml | Slovak: sk
Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl
Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb
Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es
Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv
Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl
Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta
Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te
Croatian: hr | Icelandic: is | Persian: fa | Thai: th
Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo
Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW
Danish: da | Japanese: ja | Romanian: ro | Turkish: tr
Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk
English: en | Khmer: km | Serbian: sr | Urdu: ur
Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug
Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi
French: fr | Latvian: lv | Sinhala: si | Welsh: cy
Georgian: ka | Lithuanian: lt |