Skip to main content

​
쿼리 작성하기

쿼리 제한 사항! 사용 중인 액세스 레벨에 따라 쿼리에 제한이 적용됩니다.  종량제 고객의 경우 쿼리는 최대 512자, Enterprise 고객의 경우 최대 4,096자까지 작성할 수 있습니다. Enterprise 액세스를 사용 중이라면 담당 어카운트 매니저에게 문의해 주세요.  연산자 가용성 대부분의 연산자는 모든 개발자가 사용할 수 있지만, 일부 연산자는 Enterprise 액세스 승인을 받은 사용자에게만 제한되어 있습니다. 각 연산자가 어떤 액세스 레벨에서 사용 가능한지는 다음 레이블을 사용해 연산자 목록 테이블에 표시되어 있습니다:
  • Core operators: 모든 Project에서 사용 가능
  • Advanced operators: Enterprise 액세스가 있는 Project에서 사용 가능   

​
연산자 유형: 단독 사용 가능 및 접속사 필수

단독 연산자(standalone operators) 는 단독으로도 사용할 수 있고, (접속사가 필요한 연산자를 포함해) 다른 어떤 연산자와도 함께 사용할 수 있습니다. 예를 들어, 다음 쿼리는 단독 연산자인 #hashtag 연산자를 사용하기 때문에 동작합니다: #xapiv2 접속사 필수(conjunction-required) 연산자는 쿼리에서 단독으로 사용할 수 없으며, 쿼리에 최소 한 개의 단독 연산자가 포함된 경우에만 사용할 수 있습니다. 이러한 연산자를 단독으로 사용하면 범위가 지나치게 넓어져, 매우 많은 수의 포스트와 일치하게 되기 때문입니다. 예를 들어, 다음 쿼리들은 접속사 필수 연산자만 포함하고 있으므로 지원되지 않습니다: has:media has:links OR is:retweet 여기에 “X data”와 같은 단독 연산자를 추가하면, 쿼리가 올바르게 동작합니다.  “X data” has:mentions (has:media OR has:links)

​
불리언 연산자와 그룹화

단일 쿼리 안에 여러 연산자를 함께 사용하려면, 다음과 같은 도구를 사용할 수 있습니다: 부정에 대한 참고 사항 연산자 -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의 매칭 동작은 포스트 개수(Post counts)와는 다르게 동작합니다. filtered stream 규칙을 구성할 때, 강세와 발음 구별 기호가 포함된 키워드와 해시태그는 동일하게 강세와 발음 구별 기호가 포함된 용어에만 일치하며, 일반 문자를 사용하는 용어와는 일치하지 않는다는 점을 알아두십시오.  예를 들어, filtered stream 규칙에 키워드 Diacrítica 또는 해시태그 #cumpleaños 가 포함된 경우, 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
Quote Tweet 매칭 동작 Post 개수용 endpoint를 사용할 때, 연산자는 인용된 원본 Post의 콘텐츠에는 매칭되지 않고, Quote Tweet에 포함된 콘텐츠에는 매칭됩니다. 다만, filtered stream은 인용된 원본 Post의 콘텐츠와 Quote Tweet의 콘텐츠 둘 다에 매칭된다는 점에 유의하세요.   쿼리를 점진적으로 구축하기 쿼리를 자주, 그리고 일찍 테스트하기 처음부터 “올바른” 결과를 반환하는 쿼리를 만드는 경우는 드뭅니다. X에는 처음에는 명확하지 않을 수 있는 내용이 매우 많으며, 위에서 설명한 쿼리 문법이 여러분이 원하는 쿼리와 바로 맞지 않을 수 있습니다. 쿼리를 작성해 나갈 때, Search Post endpoint 중 하나를 사용해 주기적으로 테스트하여 쿼리에 매칭되는 포스트가 여러분의 사용 사례와 관련 있는지 확인하는 것이 중요합니다. 이 섹션에서는 다음 쿼리로 시작한 후, 테스트 중에 얻는 결과에 따라 이를 조정해 보겠습니다.  happy OR happiness 결과를 활용해 쿼리 범위 좁히기 Search Posts로 쿼리를 테스트할 때, 반환된 포스트에 여러분이 기대하고 원하는 데이터가 포함되어 있는지 살펴보아야 합니다. 넓은 쿼리와 더 큰 포스트 상위 집합으로 시작하면, 결과를 검토한 뒤 원치 않는 결과를 필터링하도록 쿼리를 좁혀 나갈 수 있습니다.   예시 쿼리를 테스트해 보니 다양한 언어의 포스트가 반환되는 것을 확인했습니다. 이 경우, 영어로 된 포스트만 받고 싶으므로 lang: 연산자를 추가해 보겠습니다. (happy OR happiness) lang:en 테스트 결과, 생일을 축하하는 포스트가 많이 포함되어 있었기 때문에 -birthday를 부정 키워드 연산자로 추가하겠습니다. 또한 원본 Post만 받기를 원하므로, 부정 연산자 -is:retweet도 추가했습니다. (happy OR happiness) lang:en -birthday -is:retweet 필요한 경우 포함 범위 조정하기 Search Posts를 통해 기대하는 데이터를 받지 못했고 실제로는 반환되어야 할 기존 포스트가 있다는 것을 알고 있다면, 원하는 데이터를 걸러내고 있을 수 있는 연산자를 제거하여 쿼리 범위를 넓혀야 할 수 있습니다.  우리 예시의 경우, 찾고자 하는 감정을 표현하는 다른 포스트가 개인 타임라인에 있었지만 테스트 결과에는 포함되지 않았음을 확인했습니다. 더 넓은 범위를 확보하기 위해 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  쿼리를 충분히 테스트하고 반복 개선을 마쳤다면, 이제 이 쿼리를 Post 개수용 endpoint에 함께 전송하여 전체 Post payload가 아니라 포스트 수량만을 수신하기 시작할 수 있습니다.

​
요청에 쿼리 추가하기

요청에 쿼리를 추가하려면 query 파라미터를 사용해야 합니다. 다른 모든 쿼리 파라미터와 마찬가지로, 작성한 쿼리는 반드시 HTTP로 인코딩해야 합니다. 아래는 cURL 명령을 사용했을 때의 예시입니다. 이 명령을 사용하려면 $BEARER_TOKEN을(를) 자신의 Bearer 토큰으로 바꾸어야 합니다:

​
쿼리 예시

자연재해 추적 다음 쿼리는 2017년에 휴스턴을 강타한 허리케인 Harvey에 대해 이야기하는 기상 기관과 관측소에서 게시한 원본 포스트에 매칭되었습니다. 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 인코딩, query 매개변수, 그리고 최근 포스트 수 URI가 적용된 쿼리의 예시입니다: https://api.x.com/2/tweets/counts/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 인코딩, query 매개변수, 그리고 최근 포스트 수 URI가 적용된 쿼리의 예시입니다: https://api.x.com/2/tweets/counts/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/counts/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%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 특정 게시물 주석과 관련된 포스트 찾기 이 규칙은 고양이가 아닌 반려동물 이미지를 포함하고, 게시물에서 식별된 언어가 일본어인 원본 게시물만 필터링하기 위해 만들어졌습니다. 이를 위해 Post annotation 기능을 활용하는 context: 연산자를 사용했습니다. 먼저 Post lookup 엔드포인트와 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 인코딩, query 매개변수, 그리고 최근 포스트 수 URI가 적용된 쿼리의 예시입니다: https://api.x.com/2/tweets/counts/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja

​
연산자