검색 API: 엔터프라이즈

참고:

포스트 검색과 포스트 개수의 새로운 버전을 X API v2로 출시했습니다. X API v2에서 새로워진 점을 검토해 보시기를 권장합니다. 

이 엔드포인트들은 포스트 수정 메타데이터를 포함하도록 업데이트되었습니다. 이러한 메타데이터에 대한 자세한 내용은 “포스트 수정” 기본 사항 페이지에서 확인할 수 있습니다. 

​

Overview

Enterprise

Enterprise API는 관리형 액세스 레벨에서만 사용할 수 있습니다. 이 API를 사용하려면 먼저 엔터프라이즈 영업팀과 함께 계정을 개설해야 합니다. 자세한 내용은 여기를 참조하세요.

모든 X API 검색 게시물 제품은 여기에서 확인할 수 있습니다.

엔터프라이즈 검색 API에는 두 가지 유형이 있습니다:

1. 30-Day Search API는 이전 30일 동안의 데이터를 제공합니다.
2. Full-Archive Search API는 2006년 3월 첫 번째 게시물까지 거슬러 올라가는 X 데이터 전체 코퍼스에 대한 완전하고 즉각적인 액세스를 제공합니다.

이들 RESTful API는 요청당 최대 2,048자의 단일 쿼리를 지원합니다. 쿼리는 PowerTrack 규칙 구문으로 작성됩니다. 자세한 내용은 규칙 및 필터링을 참조하세요. 사용자는 분 단위까지의 시간 범위를 지정할 수 있습니다. 다만 응답은 사용자가 지정한 maxResults 값 또는 31일 중 더 작은 값으로 제한되며, 다음 결과 세트를 페이지네이션하기 위한 next 토큰을 포함합니다. 시간 매개변수가 지정되지 않은 경우, API는 가장 최근 30일 동안의 일치하는 데이터를 반환합니다.

엔터프라이즈 검색 API는 분 단위 정밀도로 게시물 아카이브에 대한 저지연, 원본 보존(full-fidelity)의 쿼리 기반 액세스를 제공합니다. 게시물 데이터는 쿼리와 일치하는 가장 최신 게시물부터 시작하여 역시간순으로 제공됩니다. 게시물은 게시된 후 약 30초가 지나면 Search API를 통해 조회할 수 있습니다.

이 검색 엔드포인트는 수정된 게시물 메타데이터를 제공합니다. 2022년 9월 29일 이후에 생성된 포스트에 대한 모든 객체에는, 해당 게시물이 한 번도 수정되지 않았더라도, 게시물 수정 메타데이터가 포함됩니다. 게시물이 수정될 때마다 새로운 게시물 ID가 생성됩니다. 게시물의 수정 이력은 원래 ID부터 시작하는 게시물 ID 배열에 기록됩니다.

이 엔드포인트는 항상 가장 최근 수정본과 모든 수정 이력을 함께 반환합니다. 30분 편집 가능 시간이 지난 후에 수집된 게시물은 최종 버전을 나타냅니다. Edit Post 메타데이터에 대해 자세히 알아보려면 Edit Posts 기본 사항 페이지를 확인하세요.

요청에는 각 API 응답에서 반환할 포스트의 최대 개수를 지정하는 maxResults 매개변수가 포함됩니다. 쿼리와 연관된 포스트가 응답당 이 최대 결과 수보다 많을 경우, 응답에 next 토큰이 포함됩니다. 이러한 next 토큰은 이후 요청에서 사용되어 쿼리와 연관된 전체 포스트 집합을 페이지네이션하는 데 사용됩니다.

이 엔터프라이즈 검색 API는 사용자가 자신의 쿼리와 관련된 데이터 볼륨을 요청할 수 있는 counts 엔드포인트를 제공합니다. 

​

요청 type

Enterprise Search API는 두 가지 요청 type을 지원합니다.

​

Search requests (data)

엔터프라이즈 검색 API에 대한 검색 요청을 사용하면, 지정한 기간에 대해 응답당 최대 500개의 결과를 조회할 수 있으며, 추가 데이터를 위해 페이지네이션을 수행할 수 있습니다. maxResults 매개변수를 사용하면, (사용자가 필요에 따라 더 많은 결과를 요청할 수 있도록) 화면 표시용 사용 사례에 맞게 더 작은 페이지 크기를 지정하거나, 대량 데이터 수집을 위해 더 큰 페이지 크기(최대 500)를 지정할 수 있습니다. 데이터는 최신 순(내림차순)으로 제공되며, 전송 시점 기준으로 컴플라이언스가 보장됩니다.

​

Counts requests (Post count)

Counts 요청은 지정한 기간 동안 특정 쿼리와 일치하는 활동이 몇 번 발생했는지를 나타내는 과거 활동 카운트를 조회할 수 있는 기능을 제공합니다. 응답은 본질적으로 일, 시간, 또는 분 단위(기본 버킷은 hour)로 구간화된 카운트 히스토그램을 제공합니다. 카운트 결과는 게시물이 게시된 후 상당히 오랜 시점(7일 이상)에 발생하는 컴플라이언스 이벤트(예: 포스트 삭제)를 항상 반영하지는 않는다는 점에 유의해야 합니다. 따라서 동일한 쿼리에 대한 데이터 요청의 메트릭과 카운트 메트릭이 항상 일치하지 않을 수 있습니다.

청구 참고: 데이터 및 카운트 엔드포인트에 대해 수행되는 각 요청 – 페이지네이션 요청을 포함하여 – 은 청구 대상 요청으로 계산됩니다. 따라서 하나의 쿼리에 여러 페이지의 결과가 있는 경우, X개의 결과 페이지를 페이지네이션하면 청구 시 X개의 요청으로 간주됩니다.

​

사용 가능한 연산자

Enterprise 검색 API는 최대 2,048자 길이의 규칙을 지원합니다. Enterprise 검색 API에서 지원하는 연산자는 아래 목록을 참고하세요. 자세한 설명은 여기를 참조하세요. 

게시물 내용 기준 일치:	관심 계정 기준 일치:	게시물 속성:	지리 공간 연산자:
* keyword * “quoted phrase” * “keyword1 keyword2”~N * # * @ * $ * url: * lang:	* from: * to: * retweets_of:	* is:retweet * has:mentions * has:hashtags * has:media * has:videos * has:images * has:links * has:symbols * is:verified * -is:nullcast (부정 전용 연산자)	* bounding_box:[west_long south_lat east_long north_lat] * point_radius:[lon lat radius] * has:geo * place: * place_country: * has:profile_geo * profile_country: * profile_region: * profile_locality:

참고: 연산자를 중첩해서(내포하여) 사용하지 마십시오. "#cats"는 검색 API에서 cats로 해석됩니다.   lang: 연산자와 모든 is: 및 has: 연산자는 단독 연산자로 사용할 수 없으며, 반드시 다른 절과 함께 결합해서 사용해야 합니다(예: @XDevelopers has:links).    

검색 API는 토크나이징/매칭 동작 특성으로 인해 제한된 연산자 세트를 사용합니다. Enterprise 실시간 및 배치형 과거 데이터 API는 추가 연산자를 제공합니다. 자세한 내용은 여기를 참조하세요.

자세한 내용은 연산자 시작하기 가이드를 참조하세요.

​

데이터 가용성 / 중요 날짜

Full-Archive 검색 API를 사용할 때는 X 플랫폼이 2006년부터 계속 발전해 왔다는 점을 염두에 두어야 합니다. 새로운 기능이 추가될 때마다 기본 JSON 객체에도 새로운 메타데이터가 추가되었습니다. 따라서 검색 연산자가 매칭에 사용하는 게시물 속성이 언제 추가되었는지를 이해하는 것이 중요합니다. 아래는 주요 메타데이터 그룹이 처음 ‘생성’된 보다 기초적인 날짜들입니다. 게시물 속성이 처음 도입된 시점에 대해 더 알아보려면 이 가이드를 참고하세요.

• 첫 게시물: 3/21/2006
• 첫 네이티브 Retweet: 11/6/2009
• 첫 위치 태그 게시물: 11/19/2009
• 필터링을 위해 URL이 처음 인덱싱된 날짜: 8/27/2011
• 향상된 URL 확장 메타데이터(웹사이트 제목 및 설명): 12/1/2014
• 프로필 Geo 보강 메타데이터 및 필터링: 2/17/2015

​

데이터 업데이트와 가변성

enterprise search API에서는 게시물 내 일부 데이터가 가변적입니다. 즉, 최초 보관 이후에 업데이트되거나 변경될 수 있습니다.

이 가변 데이터는 두 가지 범주로 나뉩니다:

• 사용자 객체 메타데이터:
  • 사용자의 @handle (숫자 ID는 절대 변경되지 않음)
  • 자기소개(Bio) 설명
  • 수치: 게시물 수(statuses), 팔로워 수, 팔로잉 수(friends), 즐겨찾기 수, 리스트 수
  • 프로필 위치
  • 시간대, 언어 등 기타 세부정보
• 게시물 통계 - 즉, 사용자 행동으로 인해 플랫폼에서 변경될 수 있는 모든 항목(아래 예시 참조):
  • 즐겨찾기 수
  • 리트윗 수

대부분의 경우, search API는 게시물 생성 시점이 아니라 쿼리 시점(query-time) 기준으로 플랫폼에 존재하는 데이터를 반환합니다. 그러나 select 연산자(예: from, to, @, is:verified)를 사용하는 쿼리의 경우에는 그렇지 않을 수 있습니다. 데이터는 인덱스에서 정기적으로 업데이트되며, 가장 최근 기간에 대해서는 더 높은 빈도로 업데이트됩니다. 그 결과, 일부 경우에는 반환된 데이터가 X.com에 표시되는 현재 데이터와 정확히 일치하지 않을 수 있으나, 마지막으로 인덱싱되었을 당시의 데이터와는 일치합니다.

이러한 불일치 문제는 연산자가 가변 데이터에 적용되는 쿼리에만 해당된다는 점에 유의하십시오. 한 가지 예는 사용자 이름(username)으로 필터링하는 경우이며, 가장 좋은 우회 방법은 이러한 쿼리에서 @handle 대신 사용자 숫자 ID를 사용하는 것입니다.

​

단일 스레드 vs. 멀티 스레드 요청

각 고객에는 본인의 search 엔드포인트에 대해 정의된 rate limit이 있습니다. Full-Archive search의 기본 분당 rate limit은 분당 120개의 요청으로, 초당 평균 2개의 쿼리(QPS)에 해당합니다. 이 평균 QPS는 이론적으로 매초 API에 2개의 요청을 보낼 수 있음을 의미합니다. 제품의 페이지네이션 기능을 고려하면, 1년 기간의 쿼리에 해당 기간 전체에 걸쳐 균등하게 분포된 백만 개의 포스트가 연관되어 있는 경우, 모든 데이터를 수신하기 위해서는 2,000개가 넘는 요청이 필요합니다 (maxResults가 500이라고 가정). 응답당 2초가 걸린다고 가정하면, 단일 스레드를 통해 직렬/순차적으로 모든 데이터를 가져오는 데 4,000초(또는 1시간을 약간 넘는 시간)가 소요됩니다(이전 응답의 “next” 토큰을 사용해 초당 1개의 요청을 보내는 방식). 나쁘지 않습니다!

이제 데이터를 수신하기 위해 12개의 병렬 스레드를 사용하는 상황을 고려해 보겠습니다. 백만 개의 포스트가 1년 기간 전체에 균등하게 분포되어 있다고 가정하면, 요청을 12개의 병렬 스레드(멀티 스레드)로 나누어 단일 “작업”에 대해 초당 rate limit을 더 많이 활용할 수 있습니다. 다시 말해, 관심 있는 각 월(month)마다 하나의 스레드를 실행함으로써 데이터를 12배 더 빠르게(또는 약 6분 내에) 가져올 수 있습니다.

이 멀티 스레드 예시는 counts 엔드포인트에도 동일하게 적용됩니다. 예를 들어, 2년 기간에 대한 게시물 카운트를 얻고자 한다면, 단일 스레드 요청을 사용하여 한 번에 31일 단위로 카운트를 페이지네이션할 수 있습니다. 응답당 2초가 걸린다고 가정하면, 전체 카운트 세트를 조회하기 위해 24개의 API 요청을 수행하는 데 약 48초가 소요됩니다. 그러나 동시에 여러 개의 1개월 단위 요청을 보내는 옵션도 있습니다. 초당 12개의 요청을 보내는 경우, 전체 카운트 세트를 약 2초 만에 가져올 수 있습니다.

​

재시도 로직

엔터프라이즈 검색 API에서 503 오류가 발생하는 경우, 일시적인 오류일 가능성이 높으며, 짧은 시간 후에 요청을 다시 시도하면 해결될 수 있습니다.

요청이 연속해서 4번 실패했고, 각 실패 사이에 최소 10분을 기다렸다면, 다음 단계를 수행해 문제를 해결하십시오:

• 요청이 포함하는 시간 범위를 줄인 후 다시 시도합니다. 실패할 경우 최소 6시간 단위의 시간 창이 될 때까지 반복합니다.
• 많은 수의 용어를 OR 조건으로 결합하고 있다면, 이를 개별 규칙으로 나눈 뒤 각 규칙을 개별적으로 다시 시도합니다.
• 규칙에서 많은 수의 제외 조건을 사용하고 있다면, 규칙에서 부정된 용어의 수를 줄이고 다시 시도합니다.

​

빠른 시작

​

엔터프라이즈 Search Posts: 30-Day API 시작하기

엔터프라이즈 Search Posts: 30-Day API는 최근 30일 이내에 게시된 포스트를 제공합니다. 포스트는 요청에서 지정한 쿼리를 기반으로 매칭되어 반환됩니다. 쿼리는 반환받을 포스트에 어떤 내용이 포함되어야 하는지를 정의하는 규칙입니다. 이 튜토리얼에서는 X 계정 @XDevelopers에서 영어로 작성된 포스트를 검색해 보겠습니다.

반환받는 포스트는 전체 포스트 페이로드를 제공하는 data 형식이거나, 매칭된 포스트의 개수 데이터를 제공하는 counts 형식일 수 있습니다. 이 튜토리얼에서는 cURL을 사용하여 data 및 counts 엔드포인트에 요청을 보낼 것입니다.

다음이 필요합니다:

• [엔터프라이즈 계정]https://developer.x.com/en/products/x-api/enterprise
• 사용자 이름, 비밀번호, 계정 이름
• console.gnip.com에 표시되는 검색 엔드포인트와 연결된 레이블

​

데이터 엔드포인트에 액세스하기

데이터 엔드포인트는 일치한 포스트 각각에 대한 전체 게시물 페이로드를 제공합니다. 우리는 from: 및 lang: 연산자를 사용하여 @XDevelopers 계정에서 작성된 영어 포스트를 찾겠습니다. 더 많은 연산자를 보려면 여기를 클릭하세요.

cURL

cURL은 URL 문법을 사용해 파일을 가져오거나 전송하는 명령줄 도구입니다.

아래 항목을 수정한 뒤, 이어지는 cURL 요청을 복사해 명령줄에 붙여넣으세요:

• Username <USERNAME> 예: [e-mail]

• Account name <ACCOUNT-NAME> 예: john-doe

• Label <LABEL> 예: prod

• fromDate and toDate 예: "fromDate":"201811010000", "toDate":"201811122359"

요청을 전송하면 비밀번호 입력을 요청하는 프롬프트가 표시됩니다.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/30day/accounts/<ACCOUNT-NAME>/<LABEL>.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>"}'

cURL 예시

_이것은 예시용 cURL 요청입니다. 그대로 실행하면 동작하지 않습니다._

curl -X POST [e-mail] "https://gnip-api.x.com/search/30day/accounts/john-doe/prod.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"201811100000","toDate":"201812012359"}'

​

데이터 엔드포인트 응답 페이로드

API 요청에 대한 응답으로 반환되는 페이로드는 아래와 같이 JSON 형식으로 제공됩니다.

{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"Tagboard, Twitter 및 TEGNA의 협업이 가능하게 하는 혁신적인 크라우드소싱은 지역에 밀접하게 관련된 대화를 이끌어내고 있습니…",
			"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter 웹 클라이언트<\/a>",
			"truncated": false,
			"in_reply_to_status_id": null,
			"in_reply_to_status_id_str": null,
			"in_reply_to_user_id": null,
			"in_reply_to_user_id_str": null,
			"in_reply_to_screen_name": null,
			"user": {
				"id": 2244994945,
				"id_str": "2244994945",
				"name": "Twitter Dev",
				"screen_name": "TwitterDev",
				"location": "Internet",
				"url": "https:\/\/developer.x.com\/",
				"description": "Twitter 플랫폼의 뉴스, 업데이트 및 이벤트에 대한 공식 채널입니다. 기술적인 도움이 필요하신가요? https:\/\/devcommunity.com\/ 를 방문하세요 ⌨️ #TapIntoTwitter",
				"translator_type": "null",
				"protected": false,
				"verified": true,
				"followers_count": 503828,
				"friends_count": 1477,
				"listed_count": 1437,
				"favourites_count": 2199,
				"statuses_count": 3380,
				"created_at": "Sat Dec 14 04:35:55 +0000 2013",
				"utc_offset": null,
				"time_zone": null,
				"geo_enabled": true,
				"lang": "en",
				"contributors_enabled": false,
				"is_translator": false,
				"profile_background_color": "null",
				"profile_background_image_url": "null",
				"profile_background_image_url_https": "null",
				"profile_background_tile": null,
				"profile_link_color": "null",
				"profile_sidebar_border_color": "null",
				"profile_sidebar_fill_color": "null",
				"profile_text_color": "null",
				"profile_use_background_image": null,
				"profile_image_url": "null",
				"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg",
				"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817",
				"default_profile": false,
				"default_profile_image": false,
				"following": null,
				"follow_request_sent": null,
				"notifications": null
			},
			"geo": null,
			"coordinates": null,
			"place": null,
			"contributors": null,
			"retweeted_status": {
				"created_at": "Tue Oct 30 21:30:25 +0000 2018",
				"id": 1057384253116289025,
				"id_str": "1057384253116289025",
				"text": "\"Tagboard, Twitter 및 TEGNA의 협업이 가능하게 하는 혁신적인 크라우드소싱은 지역에 밀접하게 관련된 대화를 이끌어내고 있습니… https:\/\/t.co\/w46U5TRTzQ",
				"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter 웹 클라이언트<\/a>",
				"truncated": true,
				"in_reply_to_status_id": null,
				"in_reply_to_status_id_str": null,
				"in_reply_to_user_id": null,
				"in_reply_to_user_id_str": null,
				"in_reply_to_screen_name": null,
				"user": {
					"id": 175187944,
					"id_str": "175187944",
					"name": "Tyler Singletary",
					"screen_name": "harmophone",
					"location": "San Francisco, CA",
					"url": "http:\/\/medium.com\/@harmophone",
					"description": "SVP Product at @Tagboard. Did some Data, biz, and product @Klout & for @LithiumTech; @BBI board member; @Insightpool advisor. World's worst whiteboarder.",
					"translator_type": "null",
					"protected": false,
					"verified": false,
					"followers_count": 1982,
					"friends_count": 1877,
					"listed_count": 245,
					"favourites_count": 23743,
					"statuses_count": 12708,
					"created_at": "Thu Aug 05 22:59:29 +0000 2010",
					"utc_offset": null,
					"time_zone": null,
					"geo_enabled": false,
					"lang": "en",
					"contributors_enabled": false,
					"is_translator": false,
					"profile_background_color": "null",
					"profile_background_image_url": "null",
					"profile_background_image_url_https": "null",
					"profile_background_tile": null,
					"profile_link_color": "null",
					"profile_sidebar_border_color": "null",
					"profile_sidebar_fill_color": "null",
					"profile_text_color": "null",
					"profile_use_background_image": null,
					"profile_image_url": "null",
					"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg",
					"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841",
					"default_profile": false,
					"default_profile_image": false,
					"following": null,
					"follow_request_sent": null,
					"notifications": null
				},
				"geo": null,
				"coordinates": null,
				"place": null,
				"contributors": null,
				"is_quote_status": false,
				"extended_tweet": {
					"full_text": "\"Tagboard, Twitter 및 TEGNA의 협업이 가능하게 하는 혁신적인 크라우드소싱은 지역에 밀접하게 관련된 대화를 실시간으로 이끌어내고, 토론 중에 유권자들이 질문을 할 수 있도록 해 주고 있습니다.\"  -- @adamostrow, @TEGNA\nLearn More: https:\/\/t.co\/ivAFtanfje",
					"display_text_range": [
						0,
						259
					],
					"entities": {
						"hashtags": [],
						"urls": [
							{
								"url": "https:\/\/t.co\/ivAFtanfje",
								"expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
								"display_url": "blog.tagboard.com\/twitter-and-ta…",
								"unwound": {
									"url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
									"status": 200,
									"title": "Twitter와 Tagboard, Tagboard를 활용해 최고의 선거 콘텐츠를 뉴스 매체에 제공하기 위해 협업…",
									"description": "작성자: Tyler Singletary, Tagboard 제품 총괄"
								},
								"indices": [
									236,
									259
								]
							}
						],
						"user_mentions": [
							{
								"screen_name": "adamostrow",
								"name": "Adam Ostrow",
								"id": 5695942,
								"id_str": "5695942",
								"indices": [
									204,
									215
								]
							},
							{
								"screen_name": "TEGNA",
								"name": "TEGNA",
								"id": 34123003,
								"id_str": "34123003",
								"indices": [
									217,
									223
								]
							}
						],
						"symbols": []
					}
				},
				"quote_count": 0,
				"reply_count": 1,
				"retweet_count": 6,
				"favorite_count": 19,
				"entities": {
					"hashtags": [],
					"urls": [
						{
							"url": "https:\/\/t.co\/w46U5TRTzQ",
							"expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025",
							"display_url": "twitter.com\/i\/web\/status\/1…",
							"indices": [
								117,
								140
							]
						}
					],
					"user_mentions": [],
					"symbols": []
				},
				"favorited": false,
				"retweeted": false,
				"possibly_sensitive": false,
				"filter_level": "low",
				"lang": "en"
			},
			"is_quote_status": false,
			"quote_count": 0,
			"reply_count": 0,
			"retweet_count": 0,
			"favorite_count": 0,
			"entities": {
				"hashtags": [],
				"urls": [],
				"user_mentions": [
					{
						"screen_name": "harmophone",
						"name": "Tyler Singletary",
						"id": 175187944,
						"id_str": "175187944",
						"indices": [
							3,
							14
						]
					}
				],
				"symbols": []
			},
			"favorited": false,
			"retweeted": false,
			"filter_level": "low",
			"lang": "en",
			"matching_rules": [
				{
					"tag": null
				}
			]
		}
	],
	"requestParameters": {
		"maxResults": 100,
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

​

counts 엔드포인트에 액세스하기

counts 엔드포인트를 사용하여 @XDevelopers 계정에서 영어로 작성된 게시물 수를 day 단위로 그룹화해 조회하겠습니다.

cURL

cURL은 URL 문법을 사용하여 파일을 가져오거나 전송하는 명령줄 도구입니다.

다음을 변경한 후 아래 cURL 요청을 명령줄에 복사해 넣으세요:

• Username <USERNAME> 예: [e-mail]

• Account name <ACCOUNT-NAME> 예: john-doe

• Label <LABEL> 예: prod

• fromDate 및 toDate 예: "fromDate":"201811010000", "toDate":"201811122359"

요청을 전송하면 비밀번호 입력을 요구하는 메시지가 표시됩니다.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/30day/accounts/<ACCOUNT-NAME>/<LABEL>/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>","bucket":"day"}'

cURL 예시

이것은 예시용 cURL 요청입니다. 그대로 실행해도 동작하지 않습니다.

curl -X POST [e-mail] "https://gnip-api.x.com/search/30day/accounts/john-doe/prod/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"201811100000","toDate":"201812012359","bucket":"day"}'

​

Counts endpoint response payload

API 요청에 대한 응답 페이로드는 아래와 같이 JSON 형식으로 표시됩니다.

{
	"results": [
		{
			"timePeriod": "201811010000",
			"count": 0
		},
		{
			"timePeriod": "201811020000",
			"count": 1
		},
		{
			"timePeriod": "201811030000",
			"count": 0
		},
		{
			"timePeriod": "201811040000",
			"count": 0
		},
		{
			"timePeriod": "201811050000",
			"count": 0
		}
	],
	"totalCount": 1,
	"requestParameters": {
		"bucket": "day",
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

잘하셨습니다! 이제 enterprise Search Posts: 30-Day API에 성공적으로 액세스했습니다.

참고 문서

• 게시물 객체 소개
• 검색 연산자
• 게시물 객체와 페이로드

​

enterprise Search Posts: Full-Archive API 시작하기

enterprise Search Posts: Full-Archive API는 2006년에 처음 작성된 포스트부터 지금까지의 포스트에 대한 액세스를 제공합니다. 포스트는 요청에서 지정한 쿼리를 기준으로 매칭되어 반환됩니다. 쿼리는 반환받을 포스트에 어떤 내용이 포함되어야 하는지 정의하는 규칙입니다. 이 튜토리얼에서는 영어로 작성된 X 계정 @XDevelopers에서 생성된 포스트를 검색합니다.

응답으로 받는 포스트는 전체 포스트 페이로드를 제공하는 data 형식이거나, 매칭된 포스트의 개수를 수치로 제공하는 counts 형식일 수 있습니다. 이 튜토리얼에서는 cURL을 사용해 data 및 counts 엔드포인트에 요청을 보냅니다.

다음 항목이 필요합니다:

• [엔터프라이즈 계정]https://developer.x.com/en/products/x-api/enterprise
• 사용자 이름, 비밀번호, 계정 이름
• console.gnip.com에 표시되는 검색 엔드포인트에 연결된 레이블

​

데이터 엔드포인트에 액세스하기

데이터 엔드포인트는 일치하는 포스트에 대한 전체 게시물 페이로드를 제공합니다. from: 및 lang: 연산자를 사용하여 @XDevelopers 계정에서 작성된 영어 포스트를 찾겠습니다. 추가 연산자에 대해서는 여기를 클릭하세요.

• cURL
• cURL 예시

cURL

cURL은 URL 구문을 사용하여 파일을 가져오거나 전송하는 명령줄 도구입니다.

다음 cURL 요청을 명령줄에 복사한 뒤, 아래 항목을 변경하여 사용하세요:

• Username <USERNAME> 예: [e-mail]

• Account name <ACCOUNT-NAME> 예: john-doe

• Label <LABEL> 예: prod

• fromDate 및 toDate 예: "fromDate":"201802010000", "toDate":"201802282359"

요청을 전송한 후 비밀번호 입력을 요청받습니다.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/fullarchive/accounts/<ACCOUNT-NAME>/<LABEL>.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>"}'

cURL 예시

이는 예시용 cURL 요청입니다. 그대로 실행하면 동작하지 않습니다.

curl -X POST [e-mail] "https://gnip-api.x.com/search/fullarchive/accounts/john-doe/prod.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"201802010000","toDate":"201802282359"}'

데이터 엔드포인트 응답 페이로드

API 요청에 대한 응답 페이로드는 아래와 같이 JSON 형식으로 반환됩니다.

{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"Tagboard, Twitter 및 TEGNA 간의 혁신적인 크라우드소싱 협업을 통해 지역적으로 관련성 높은 대화를 이끌어내고 있습니…",
			"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter 웹 클라이언트<\/a>",
			"truncated": false,
			"in_reply_to_status_id": null,
			"in_reply_to_status_id_str": null,
			"in_reply_to_user_id": null,
			"in_reply_to_user_id_str": null,
			"in_reply_to_screen_name": null,
			"user": {
				"id": 2244994945,
				"id_str": "2244994945",
				"name": "Twitter Dev",
				"screen_name": "TwitterDev",
				"location": "Internet",
				"url": "https:\/\/developer.x.com\/",
				"description": "Twitter 플랫폼 뉴스, 업데이트 및 이벤트에 대한 공식 채널입니다. 기술적인 도움이 필요하신가요? https:\/\/devcommunity.com\/를 방문하세요. ⌨️ #TapIntoTwitter",
				"translator_type": "null",
				"protected": false,
				"verified": true,
				"followers_count": 503828,
				"friends_count": 1477,
				"listed_count": 1437,
				"favourites_count": 2199,
				"statuses_count": 3380,
				"created_at": "Sat Dec 14 04:35:55 +0000 2013",
				"utc_offset": null,
				"time_zone": null,
				"geo_enabled": true,
				"lang": "en",
				"contributors_enabled": false,
				"is_translator": false,
				"profile_background_color": "null",
				"profile_background_image_url": "null",
				"profile_background_image_url_https": "null",
				"profile_background_tile": null,
				"profile_link_color": "null",
				"profile_sidebar_border_color": "null",
				"profile_sidebar_fill_color": "null",
				"profile_text_color": "null",
				"profile_use_background_image": null,
				"profile_image_url": "null",
				"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg",
				"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817",
				"default_profile": false,
				"default_profile_image": false,
				"following": null,
				"follow_request_sent": null,
				"notifications": null
			},
			"geo": null,
			"coordinates": null,
			"place": null,
			"contributors": null,
			"retweeted_status": {
				"created_at": "Tue Oct 30 21:30:25 +0000 2018",
				"id": 1057384253116289025,
				"id_str": "1057384253116289025",
				"text": "\"Tagboard, Twitter 및 TEGNA 간의 혁신적인 크라우드소싱 협업을 통해 지역적으로 관련성 높은 대화를 이끌어내고 있습니… https:\/\/t.co\/w46U5TRTzQ",
				"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter 웹 클라이언트<\/a>",
				"truncated": true,
				"in_reply_to_status_id": null,
				"in_reply_to_status_id_str": null,
				"in_reply_to_user_id": null,
				"in_reply_to_user_id_str": null,
				"in_reply_to_screen_name": null,
				"user": {
					"id": 175187944,
					"id_str": "175187944",
					"name": "Tyler Singletary",
					"screen_name": "harmophone",
					"location": "San Francisco, CA",
					"url": "http:\/\/medium.com\/@harmophone",
					"description": "@Tagboard의 제품 총괄 부사장(SVP Product). @Klout 및 @LithiumTech에서 데이터, 비즈니스, 제품 관련 업무를 담당했습니다. @BBI 이사회 멤버이자 @Insightpool 자문위원. 세계 최악의 화이트보드 사용자.",
					"translator_type": "null",
					"protected": false,
					"verified": false,
					"followers_count": 1982,
					"friends_count": 1877,
					"listed_count": 245,
					"favourites_count": 23743,
					"statuses_count": 12708,
					"created_at": "Thu Aug 05 22:59:29 +0000 2010",
					"utc_offset": null,
					"time_zone": null,
					"geo_enabled": false,
					"lang": "en",
					"contributors_enabled": false,
					"is_translator": false,
					"profile_background_color": "null",
					"profile_background_image_url": "null",
					"profile_background_image_url_https": "null",
					"profile_background_tile": null,
					"profile_link_color": "null",
					"profile_sidebar_border_color": "null",
					"profile_sidebar_fill_color": "null",
					"profile_text_color": "null",
					"profile_use_background_image": null,
					"profile_image_url": "null",
					"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg",
					"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841",
					"default_profile": false,
					"default_profile_image": false,
					"following": null,
					"follow_request_sent": null,
					"notifications": null
				},
				"geo": null,
				"coordinates": null,
				"place": null,
				"contributors": null,
				"is_quote_status": false,
				"extended_tweet": {
					"full_text": "\"Tagboard, Twitter 및 TEGNA 간의 혁신적인 크라우드소싱 협업을 통해 지역적으로 관련성 높은 대화를 실시간으로 이끌어내고, 토론 중 유권자들이 질문을 할 수 있도록 돕고 있습니다.”  -- @adamostrow, @TEGNA\n자세히 알아보기: https:\/\/t.co\/ivAFtanfje",
					"display_text_range": [
						0,
						259
					],
					"entities": {
						"hashtags": [],
						"urls": [
							{
								"url": "https:\/\/t.co\/ivAFtanfje",
								"expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
								"display_url": "blog.tagboard.com\/twitter-and-ta…",
								"unwound": {
									"url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
									"status": 200,
									"title": "Twitter와 Tagboard, Tagboard를 활용해 최고의 선거 콘텐츠를 뉴스 매체에 제공하기 위해 협업…",
									"description": "Tagboard 제품 총괄 책임자(Head of Product) Tyler Singletary 작성"
								},
								"indices": [
									236,
									259
								]
							}
						],
						"user_mentions": [
							{
								"screen_name": "adamostrow",
								"name": "Adam Ostrow",
								"id": 5695942,
								"id_str": "5695942",
								"indices": [
									204,
									215
								]
							},
							{
								"screen_name": "TEGNA",
								"name": "TEGNA",
								"id": 34123003,
								"id_str": "34123003",
								"indices": [
									217,
									223
								]
							}
						],
						"symbols": []
					}
				},
				"quote_count": 0,
				"reply_count": 1,
				"retweet_count": 6,
				"favorite_count": 19,
				"entities": {
					"hashtags": [],
					"urls": [
						{
							"url": "https:\/\/t.co\/w46U5TRTzQ",
							"expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025",
							"display_url": "twitter.com\/i\/web\/status\/1…",
							"indices": [
								117,
								140
							]
						}
					],
					"user_mentions": [],
					"symbols": []
				},
				"favorited": false,
				"retweeted": false,
				"possibly_sensitive": false,
				"filter_level": "low",
				"lang": "en"
			},
			"is_quote_status": false,
			"quote_count": 0,
			"reply_count": 0,
			"retweet_count": 0,
			"favorite_count": 0,
			"entities": {
				"hashtags": [],
				"urls": [],
				"user_mentions": [
					{
						"screen_name": "harmophone",
						"name": "Tyler Singletary",
						"id": 175187944,
						"id_str": "175187944",
						"indices": [
							3,
							14
						]
					}
				],
				"symbols": []
			},
			"favorited": false,
			"retweeted": false,
			"filter_level": "low",
			"lang": "en",
			"matching_rules": [
				{
					"tag": null
				}
			]
		}
	],
	"requestParameters": {
		"maxResults": 100,
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

​

counts 엔드포인트 사용하기

counts 엔드포인트를 사용하면 day 단위로 그룹화된, @XDevelopers 계정에서 영어로 작성된 포스트 개수를 조회할 수 있습니다.

cURL

cURL은 URL 구문을 사용하여 파일을 가져오거나 전송하는 명령줄 도구입니다.

다음 항목을 수정한 뒤 아래 cURL 요청을 명령줄에서 복사해 실행합니다:

• Username <USERNAME> 예: [e-mail]

• Account name <ACCOUNT-NAME> 예: john-doe

• Label <LABEL> 예: prod

• fromDate 및 toDate 예: "fromDate":"201802010000", "toDate":"201802282359"

요청을 전송한 후 비밀번호 입력을 요청받습니다.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/fullarchive/accounts/<ACCOUNT-NAME>/<LABEL>/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>","bucket":"day"}'

cURL 예제

_이 cURL 요청은 예시입니다. 그대로 실행해도 동작하지 않습니다._

curl -X POST [e-mail] "https://gnip-api.x.com/search/fullarchive/accounts/john-doe/prod/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"201802010000","toDate":"201802282359","bucket":"day"}'

​

Counts 엔드포인트 응답 페이로드

API 요청에 대한 응답 페이로드는 아래와 같이 JSON 형식으로 반환됩니다.

{
	"results": [
		{
			"timePeriod": "201811010000",
			"count": 0
		},
		{
			"timePeriod": "201811020000",
			"count": 1
		},
		{
			"timePeriod": "201811030000",
			"count": 0
		},
		{
			"timePeriod": "201811040000",
			"count": 0
		},
		{
			"timePeriod": "201811050000",
			"count": 0
		}
	],
	"totalCount": 1,
	"requestParameters": {
		"bucket": "day",
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

잘하셨습니다! 이제 enterprise Search Posts: Full-Archive API에 성공적으로 접근할 수 있게 되었습니다.

참고 문서

• 게시물 객체 소개
• 검색 연산자
• 게시물 객체와 페이로드

​

가이드

​

검색 쿼리 작성하기

​

엔터프라이즈 연산자

아래는 X의 엔터프라이즈 검색 API에서 지원되는 모든 연산자 목록입니다.

• Enterprise 30일 검색 API
• Enterprise 전체 아카이브 검색 API

제품별로 사용 가능한 연산자를 나란히 비교하려면 여기를 참고하세요.

연산자	설명
keyword	게시물의 본문 또는 URL 내에서 토큰화된 키워드와 일치하는지를 검사합니다. 이는 토큰 단위 매치로, 키워드 문자열이 게시물 본문의 토큰화된 텍스트와 비교된다는 의미입니다. 토큰화는 구두점, 기호, separator 유니코드 기본 평면 문자들을 기준으로 수행됩니다. 예를 들어, 본문이 “I like coca-cola”인 게시물은 다음과 같은 토큰으로 분리됩니다: I, like, coca, cola. 그런 다음 이 토큰들이 규칙에 사용한 키워드 문자열과 비교됩니다. 구두점(예: coca-cola), 기호, 또는 separator 문자를 포함하는 문자열과 일치시키려면 아래에 설명된 것처럼 따옴표로 감싼 정확히 일치하는 매치(quoted exact match)를 사용해야 합니다. Note: Search API에서는 악센트가 있는 문자와 특수 문자가 표준 라틴 문자로 정규화되며, 이로 인해 외국어에서 의미가 바뀌거나 예기치 않은 결과가 반환될 수 있습니다: 예를 들어, “músic”은 “music”과 일치하며 그 반대도 마찬가지입니다. 예를 들어, 스페인어의 흔한 구절인 “Feliz Año Nuevo!”는 “Feliz Ano Nuevo”로 인덱싱되며, 이로 인해 해당 구절의 의미가 변경됩니다. Note: 이 연산자는 게시물 내의 URL과 풀어 쓴(unwound) URL 모두에 대해 매치됩니다.
emoji	게시물 본문에 포함된 이모지와 일치합니다. 이모지 일치는 토큰화 기반으로 수행되며, 사용한 이모지가 토큰화된 게시물 본문 텍스트와 비교된다는 의미입니다. 토큰화는 구두점, 기호/이모지, 구분자에 해당하는 유니코드 기본 평면 문자를 기준으로 이루어집니다. 예를 들어 텍스트가 “I like ”인 게시물은 다음과 같은 토큰으로 분리됩니다: I, like, . 그런 다음 이 토큰들을 규칙에 사용한 이모지와 비교합니다. 이모지에 변형(variant)이 있는 경우, 규칙에 추가할 때 반드시 따옴표(” “)를 사용해야 합니다.
”exact phrase match”	게시물 본문이나 URL 내에서 토큰화된 상태로 순서까지 동일한 구문과 일치시킵니다. 이는 토큰 단위로 일치 여부를 검사한다는 뜻으로, 키워드 문자열이 게시물 본문의 토큰화된 텍스트와 비교된다는 의미입니다. 토큰화는 구두점, 기호, 구분자에 해당하는 유니코드 기본 평면 문자들을 기준으로 수행됩니다. Note: 구두점은 토큰화되지 않으며 공백처럼 처리됩니다. 예를 들어, 따옴표로 감싼 “#hashtag”는 “hashtag”와는 일치하지만 #hashtag와는 일치하지 않습니다(실제 해시태그와 일치시키려면 따옴표 없이 hashtag # 연산자를 사용하십시오). 예를 들어, 따옴표로 감싼 “$cashtag”는 “cashtag”와는 일치하지만$cashtag와는 일치하지 않습니다(실제 캐시태그와 일치시키려면 따옴표 없이 cashtag $ 연산자를 사용하십시오). 예를 들어, “Love Snow”는 “#love #snow”와 일치합니다. 예를 들어, “#Love #Snow”는 “love snow”와 일치합니다. Note: 이 연산자는 게시물 내의 URL과 unwound URL 모두에서 일치 여부를 검사합니다.
”keyword1 keyword2”~N	일반적으로 근접 연산자(proximity operator)라고 하며, 키워드들이 서로 N 토큰보다 멀리 떨어져 있지 않은 게시물을 매칭합니다. 키워드의 순서가 반대인 경우에는 서로 N-2 토큰보다 멀리 떨어져 있을 수 없습니다. 따옴표 안에는 원하는 만큼의 키워드를 포함할 수 있습니다. N은 6을 초과할 수 없습니다. 이 연산자는 enterprise 검색 API에서만 사용할 수 있습니다.
from:	특정 사용자가 작성한 모든 게시물과 일치합니다. 값은 해당 사용자의 X 계정 숫자 ID 또는 사용자 이름(@ 문자는 제외)이어야 합니다. X 계정 숫자 ID를 조회하는 방법은 여기 또는 여기를 참조하세요.
to:	특정 사용자에게 달린 답글인 모든 게시물과 일치합니다. 값은 사용자의 숫자형 Account ID 또는 사용자 이름(@ 문자는 제외)이어야 합니다. 숫자형 X Account ID를 조회하는 방법은 HERE를 참고하세요.
url:	게시물의 확장된 URL에 대해 토큰화된(키워드/구문) 매칭을 수행합니다(url_contains와 유사). 구두점이나 특수 문자가 포함된 토큰과 구문은 큰따옴표로 감싸야 합니다. 예: url:“/developer”. 일반적으로는 권장되지 않지만, 특정 프로토콜에 대해 매칭하려는 경우에도 큰따옴표로 감싸십시오: url:“https://developer.x.com”. 참고: PowerTrack 또는 Historical PowerTrack을 사용할 때, 이 연산자는 인용 게시물(Quote Post)의 원본 게시물에 포함된 URL에도 매칭됩니다. 예를 들어, 규칙에 url:“developer.x.com”이 포함되어 있고 어떤 게시물이 해당 URL을 포함하고 있다면, 그 게시물을 인용한 모든 Quote Tweet도 결과에 포함됩니다. Search API를 사용할 때는 이렇게 동작하지 않습니다.
#	지정된 해시태그가 있는 모든 게시물을 반환합니다. 이 연산자는 토큰화 매치가 아닌 정확 일치(exact match)를 수행합니다. 즉, 규칙 “2016”은 해시태그가 정확히 “2016”인 게시물과는 일치하지만, 해시태그가 “2016election”인 게시물과는 일치하지 않습니다. 참고: 해시태그 연산자는 본문에서 직접 해시태그를 추출하는 것이 아니라, X의 엔터티 추출 기능에 의존해 해시태그를 매치합니다. X Entities JSON 속성에 대한 자세한 내용은 HERE를 참조하세요.
@	지정된 사용자 이름을 멘션한 모든 게시물과 일치합니다. to: 연산자는 @mention 연산자의 결과 중 일부만 반환합니다.
$	지정된 ‘캐시태그’를 포함하는 모든 게시물과 일치합니다(토큰의 첫 문자가 ‘$’인 경우). 캐시태그 연산자는 게시물 본문에서 직접 캐시태그를 추출하려고 시도하는 대신, 캐시태그를 매칭하기 위해 X의 ‘symbols’ 엔터티 추출 기능에 의존합니다. X Entities JSON 속성에 대한 자세한 내용은 여기를 참조하십시오. 이 연산자는 enterprise 검색 API에서만 사용할 수 있습니다.
retweets_of:	사용 가능한 별칭: retweets_of_user: 지정된 사용자의 리트윗인 포스트를 매칭합니다. 사용자 이름과 숫자형 X 계정 ID를 모두 사용할 수 있습니다(게시물 상태 ID 아님).숫자형 X 계정 ID를 조회하는 방법은 여기를 참고하세요.
lang:	X가 특정 언어로 분류한 게시물과 일치합니다(게시물이 분류된 경우에 한함). 각 게시물은 현재 하나의 언어로만 분류되므로, 여러 언어를 AND 논리 연산자로 함께 지정하면 아무 결과도 반환되지 않는다는 점에 유의해야 합니다. Note: 언어 분류를 할 수 없는 경우 제공되는 결과는 ‘und’(미정의)입니다. 아래 목록은 현재 지원되는 언어와 해당 BCP 47 언어 식별자를 나타냅니다.

암하라어: am	독일어: de	말라얄람어: ml	슬로바크어: sk
아랍어: ar	그리스어: el	디베히어: dv	슬로베니아어: sl
아르메니아어: hy	구자라트어: gu	마라티어: mr	소라니 쿠르드어: ckb
바스크어: eu	아이티 크리올어: ht	네팔어: ne	스페인어: es
벵골어: bn	히브리어: iw	노르웨이어: no	스웨덴어: sv
보스니아어: bs	힌디어: hi	오리야어: or	타갈로그어: tl
불가리아어: bg	로마자 표기 힌디어: hi-Latn	펀자브어: pa	타밀어: ta
미얀마어: my	헝가리어: hu	파슈토어: ps	텔루구어: te
크로아티아어: hr	아이슬란드어: is	페르시아어: fa	태국어: th
카탈루냐어: ca	인도네시아어: in	폴란드어: pl	티베트어: bo
체코어: cs	이탈리아어: it	포르투갈어: pt	중국어(번체): zh-TW
덴마크어: da	일본어: ja	루마니아어: ro	터키어: tr
네덜란드어: nl	칸나다어: kn	러시아어: ru	우크라이나어: uk
영어: en	크메르어: km	세르비아어: sr	우르두어: ur
에스토니아어: et	한국어: ko	중국어(간체): zh-CN	위구르어: ug
핀란드어: fi	라오어: lo	신드어: sd	베트남어: vi
프랑스어: fr	라트비아어: lv	싱할라어: si	웨일스어: cy
조지아어: ka	리투아니아어: lt

place:	지정된 위치 태그 또는 X place ID(예시 참조)가 포함된 포스트와 일치합니다. 여러 단어로 이루어진 place 이름(“New York City”, “Palo Alto”)은 따옴표로 감싸야 합니다. 참고: X place ID를 얻는 방법은 GET geo/search 공개 API 엔드포인트를 참고하세요. 참고: 이 연산자는 리트윗과는 일치하지 않습니다. 리트윗의 place 정보는 원본 게시물에 연결되어 있기 때문입니다. 또한 Quote Tweet의 원본 게시물에 연결된 place 정보와도 일치하지 않습니다.
place_country:	태그된 place에 연관된 국가 코드가 지정된 ISO 알파-2 문자 코드와 일치하는 포스트와 일치합니다. 유효한 ISO 코드는 여기에서 확인할 수 있습니다: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 참고: 이 연산자는 리트윗과는 일치하지 않습니다. 리트윗의 place 정보는 원본 게시물에 연결되어 있기 때문입니다. 또한 Quote Tweet의 원본 게시물에 연결된 place 정보와도 일치하지 않습니다.
point_radius:[lon lat radius]	게시물이 정확한 위치(x, y)를 포함하는 경우 해당 위치와, X에서는 정의된 영역 내에 “Place” 지오 폴리곤이 완전히 포함되어 있는 경우 해당 Place와 일치합니다. * 지원되는 반지름 단위는 마일(mi)과 킬로미터(km)입니다. * 반지름은 25mi 미만이어야 합니다. * 경도는 ±180 범위입니다. * 위도는 ±90 범위입니다. * 모든 좌표는 십진수 도(degree) 단위입니다. * 규칙 인수는 대괄호로 감싸고 공백으로 구분합니다. 참고: 이 연산자는 리트윗과는 일치하지 않습니다. 리트윗의 place 정보는 원본 게시물에 연결되어 있기 때문입니다. 또한 Quote Tweet의 원본 게시물에 연결된 place 정보와도 일치하지 않습니다.
bounding_box:[west_long south_lat east_long north_lat]	사용 가능한 별칭: geo_bounding_box: 게시물이 정확한 위치(long, lat)를 포함하는 경우 해당 위치와, X에서는 정의된 영역 내에 “Place” 지오 폴리곤이 완전히 포함되어 있는 경우 해당 Place와 일치합니다. * west_long 및 south_lat는 바운딩 박스의 남서 모서리를 나타내며, west_long은 그 지점의 경도, south_lat는 위도입니다. * east_long 및 north_lat는 바운딩 박스의 북동 모서리를 나타내며, east_long은 그 지점의 경도, north_lat는 위도입니다. * 바운딩 박스의 너비와 높이는 25mi 미만이어야 합니다. * 경도는 ±180 범위입니다. * 위도는 ±90 범위입니다. * 모든 좌표는 십진수 도(degree) 단위입니다. * 규칙 인수는 대괄호로 감싸고 공백으로 구분합니다. 참고: 이 연산자는 리트윗과는 일치하지 않습니다. 리트윗의 place 정보는 원본 게시물에 연결되어 있기 때문입니다. 또한 Quote Tweet의 원본 게시물에 연결된 place 정보와도 일치하지 않습니다.
profile_country:	Profile Geo enrichment의 “address” 객체에 있는 “countryCode” 필드 값과 정확히 일치합니다. ISO-3166-1-alpha-2 사양을 기반으로 한 정규화된 두 글자 국가 코드 집합을 사용합니다. 이 연산자는 간결성을 위해 “address” 객체의 “country” 필드용 연산자 대신 제공됩니다.
profile_region:	Profile Geo enrichment의 “address” 객체에 있는 “region” 필드와 일치합니다. 이는 전체 문자열에 대한 정확한 일치입니다. 백슬래시로 문자를 이스케이프할 필요가 없습니다. 예를 들어, 슬래시가 포함된 문자열을 매칭하려면 “one/two”를 사용하고, “one/two”는 사용하지 마세요. 공백이나 구두점이 포함된 부분 문자열을 매칭하려면 큰따옴표를 사용하세요.
profile_locality:	Profile Geo enrichment의 “address” 객체에 있는 “locality” 필드와 일치합니다. 이는 전체 문자열에 대한 정확한 일치입니다. 백슬래시로 문자를 이스케이프할 필요가 없습니다. 예를 들어, 슬래시가 포함된 문자열을 매칭하려면 “one/two”를 사용하고, “one/two”는 사용하지 마세요. 공백이나 구두점이 포함된 부분 문자열을 매칭하려면 큰따옴표를 사용하세요.

참고: 모든 is: 및 has: 연산자는 Search API에서 단독으로 사용할 수 없으며, 반드시 다른 절과 함께 사용해야 합니다.

예: @XDeevelopers has:links

has:geo	X에서 제공하는 게시물 전용 위치(geo) 데이터를 가진 포스트와 일치합니다. 이는 “geo” 위도‑경도 좌표이거나, 표시 이름, 지오 폴리곤 및 기타 필드가 포함된 X “Place” 형태의 “location” 값일 수 있습니다. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:를 포함하지 않는 다른 연산자와 함께 사용해야 합니다.
has:profile_geo	사용 가능한 별칭: has:derived_user_geo 어떤 Profile Geo 메타데이터든 포함된 포스트와 일치합니다. 실제 메타데이터 값은 어떤 것이든 상관없습니다. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:를 포함하지 않는 다른 연산자와 함께 사용해야 합니다.
has:links	이 연산자는 메시지 본문에 링크가 포함된 포스트와 일치하는 결과를 반환합니다. 참고: Search API를 사용할 때는 이 연산자를 is: 또는 has:가 포함되지 않은 다른 연산자와 함께 사용해야 합니다.
is:retweet	규칙과 일치하는 명시적인 리트윗만 전달합니다. 또한 이 연산자를 부정하여 규칙과 일치하는 리트윗을 전달 대상에서 제외하고, 원본 콘텐츠만 전달되도록 할 수 있습니다. 이 연산자는 X의 리트윗 기능을 사용한 실제 리트윗(true Retweet)만을 대상으로 합니다. X의 리트윗 기능을 사용하지 않는 인용 Tweet이나 수정된 Post는 이 연산자로 매치되지 않습니다. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:를 포함하지 않는 다른 연산자와 함께 사용해야 합니다.
is:reply	포스트가 다른 포스트에 대한 답글인지 여부를 기준으로 포스트를 필터링하는 연산자입니다. 규칙과 일치하는 명시적인 답글만 전달합니다. 또한 부정형으로 사용하여 규칙과 일치하는 답글을 전달 대상에서 제외할 수도 있습니다. 이 연산자는 유료 프리미엄 및 엔터프라이즈 검색에서만 사용할 수 있으며, Sandbox 개발 환경에서는 사용할 수 없습니다. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:가 포함되지 않은 다른 연산자와 함께 사용해야 합니다.
is:quote	Quote Tweet만 또는 다른 포스트를 참조하는 포스트만 전달하며, 이는 Post 페이로드의 “is_quote_status”:true 값으로 식별됩니다. 또한 부정을 사용해 Quote Tweet을 제외할 수도 있습니다. 참고: Search API를 사용할 때는 이 연산자를 is: 또는 has:를 포함하지 않는 다른 연산자와 함께 사용해야 합니다.
is:verified	작성자가 X에서 “verified”로 인증된 포스트만 전달합니다. 부정 형태로 사용하면 작성자가 verified로 인증된 포스트를 제외할 수도 있습니다. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:가 포함되지 않은 다른 연산자와 함께 사용해야 합니다.
has:mentions	다른 X 사용자를 언급한 포스트와 일치합니다. 참고: Search API를 사용할 때에는 이 연산자는 is: 또는 has:가 포함되지 않은 다른 연산자와 함께 사용해야 합니다.
has:hashtags	해시태그를 포함하는 포스트와 일치합니다. 참고: Search API를 사용할 때는 이 연산자를 is: 또는 has:를 포함하지 않는 다른 연산자들과 함께 반드시 사용해야 합니다.
has:media	사용 가능한 별칭: has:media_link X에서 분류한 미디어 URL을 포함하는 포스트와 일치합니다. 예를 들어, pic.x.com. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:를 포함하지 않는 다른 연산자와 함께 사용해야 합니다.
has:images	X에서 분류한 미디어 URL을 포함하는 포스트와 일치합니다. 예를 들어 pic.x.com. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:가 포함되지 않은 다른 연산자와 함께 사용해야 합니다.
has:videos	사용 가능한 별칭: has:video_link X에 직접 업로드된 네이티브 X 동영상이 포함된 포스트를 매칭합니다. Vine, Periscope에서 생성된 동영상이나 다른 동영상 호스팅 사이트로 연결되는 링크가 있는 포스트에는 매칭되지 않습니다. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:가 포함되지 않은 다른 연산자와 함께 사용해야 합니다.
has:symbols	앞에 ‘$’ 문자가 붙은 캐시태그 기호(예:$tag)가 포함된 포스트와 일치합니다. 이 연산자는 enterprise 검색 API에서만 사용할 수 있습니다. 참고: Search API를 사용할 때 이 연산자는 is: 또는 has:를 포함하지 않는 다른 연산자와 함께 사용해야 합니다.

​

제품 개요

엔터프라이즈 등급 Full-archive Search는 2015년 8월에 출시되었고, 프리미엄 등급 버전은 2018년 2월에 출시되었습니다. 이 검색 제품은 고객이 공개된 모든 게시물에 즉시 접근할 수 있도록 해줍니다. Full-archive Search를 사용하면 하나의 쿼리만 제출하고, 클래식한 RESTful 방식으로 응답을 받게 됩니다. Full-archive Search는 응답당 최대 500개의 포스트를 반환하는 페이지네이션을 구현하며, 프리미엄의 경우 분당 최대 60회(rpm), 엔터프라이즈의 경우 분당 120회의 레이트 리밋을 지원합니다. 이러한 특성 덕분에 Full-archive Search는 포스트를 빠르게, 그리고 동시 요청을 활용하여 대규모로 조회하는 데 사용할 수 있습니다.

디스크에 저장된 포스트 플랫 파일 집합을 기반으로 하는 Historical PowerTrack과 달리, Full-archive Search 포스트 아카이브는 온라인 데이터베이스와 매우 유사합니다. 모든 데이터베이스와 마찬가지로, 그 내용에 대해 쿼리를 수행할 수 있습니다. 또한 고성능 데이터 검색을 가능하게 하는 인덱스 를 활용합니다. Full-archive Search 엔드포인트에서는 쿼리 언어가 PowerTrack Operator로 구성되며, 각 Operator는 인덱싱된 포스트 JSON 속성에 대응합니다.

또한 Historical PowerTrack과 마찬가지로, 쿼리를 수행하는 시점에 맞춰 최신 상태로 유지되는 포스트 속성들도 있습니다. 예를 들어, 오늘 Search API를 사용하여 2010년에 게시된 포스트를 조회하는 경우, 사용자 프로필 설명, 계정의 ‘home’ 위치, 표시 이름, 그리고 좋아요 및 리트윗 개수에 대한 포스트 메트릭은 2010년 당시의 값이 아니라 오늘 기준으로 갱신된 값이 제공됩니다. 

​

메타데이터 타임라인

아래는 Full-archive search 엔드포인트 연산자(Operator)들이 언제부터 매칭되기 시작했는지에 대한 타임라인입니다. 일부 경우에는, X에서 특정 ‘커뮤니케이션 관행’이 널리 사용되기 훨씬 나중에 연산자 매칭이 시작되었습니다. 예를 들어, @Replies는 2006년에 사용자 관행으로 등장했지만, 2007년 초까지 ‘지원하는’ JSON을 가진 일급 객체 또는 _이벤트_가 되지는 않았습니다. 따라서 2006년의 @Replies를 매칭하려면 to: 및 in_reply_to_status_id: PowerTrack 연산자에 의존하기보다는 게시물 본문을 검사해야 합니다.

여기에 제공된 세부 정보는 Full-Archive Search(수백 번의 검색을 기반으로 한 결과)를 사용해 생성되었습니다. 이 타임라인은 100% 완전하거나 정확하지 않을 수 있습니다. 사용 사례에 근본적인 영향을 미치는 다른 필터링/메타데이터의 “시작일”을 확인하신 경우, 저희에게 알려주시기 바랍니다.

기반이 되는 검색 인덱스는 다시 빌드될 수 있다는 점에 유의하세요. 따라서 이 타임라인의 세부 사항은 변경될 수 있습니다.

​

2006

• 3월 26일 - lang:. 검색 인덱스를 생성하는 동안 게시물 메타데이터를 나중에 소급 채워 넣는(backfill) 예시입니다.
• 7월 13일 - has:mentions가 매칭되기 시작합니다.
• 10월 6일 - has:symbols. 주식 종목 기호를 논의할 때 사용하는 $cashtag(또는 symbol)은 2009년 초가 되어서야 흔해집니다. 그 전까지의 대부분의 사용은 아마도 속어 표기였을 것입니다(예:$slang).
• 10월 26일 - has:links가 매칭되기 시작합니다.
• 11월 23일 - has:hashtags가 매칭되기 시작합니다.

​

2007

• January 30 - 최초의 정식 @reply (in_reply_to_user_id) 도입, reply_to_status_id: 매칭이 시작됨.
• August 23 - 해시태그가 주제와 대화를 조직하는 일반적인 관행으로 등장. 일주일 뒤 첫 실질적 사용이 나타남.

​

2009

• 5월 15일 - is:retweet. 이 Operator는 공식 리트윗의 ‘베타’ 출시와 해당 “Via @” 패턴부터 매칭하기 시작합니다. 이 베타 기간 동안에는 Post 동사(verb)가 ‘post’이고, 원본 게시물은 페이로드에 포함되지 않습니다.
• 8월 13일 - 공식 리트윗의 최종 버전이 “RT @” 패턴, 동사(verb)를 ‘share’로 설정하고, 원본 게시물을 포함하는 ‘retweet_status’ 속성과 함께 출시됩니다(이로 인해 JSON 페이로드 크기가 대략 두 배가 됩니다).

​

2010

• 3월 6일 - has:geo, bounding_box: 및 point_radius: geo 연산자(Operator)가 매칭을 시작합니다.
• 8월 28일 - has:videos (2015년 2월까지 이 연산자는 youtube.com, vimeo.com, vivo.com 등 일부 동영상 호스팅 사이트 링크가 포함된 포스트와 매칭됩니다).

​

2011

• July 20 - has:media 및 has:images가 매칭되기 시작했습니다. 네이티브 사진 기능은 2010년 8월 9일 공식적으로 발표되었습니다.

​

2014

• 12월 3일경 - HTML 제목과 설명이 포함된 일부 향상된 URL 메타데이터가 페이로드에 포함되기 시작했습니다. 향상된 메타데이터는 2016년 5월에 보다 완전한 형태로 정착했습니다.

​

2015

• 2월 10일 - has:videos가 ‘네이티브’ X 동영상을 대상으로 동작합니다.
• 2월 17일 - has:profile_geo, profile_country:, profile_region:, profile_locality: Profile Geo 연산자를 사용할 수 있게 됩니다.
• 2월 17일 - place_country: 및 place: 게시물 위치(geo) 연산자를 사용할 수 있게 됩니다.

​

2016

• 5월 1일 - 강화된 URL 메타데이터가 더 폭넓게 제공되었으며, 공식적으로는 2016년 8월 Gnip 2.0 출시의 일부로 발표되었습니다. Search API에서는 이 메타데이터와 관련된 Operator가 제공되지 않습니다.

​

2017

• 2월 22일 - 투표 메타데이터가 보강된 네이티브(enriched native) 형식으로 제공됩니다. 이 메타데이터에 사용할 수 있는 Operator는 제공되지 않습니다.

​

2022

• September 27 - 이 날짜 이후에 생성된 모든 Post 객체에는 게시물 편집 메타데이터가 제공됩니다. Post 객체를 반환하는 모든 Enterprise 엔드포인트는 이 날짜부터 이 메타데이터를 제공하도록 업데이트되었습니다. 제공되는 편집 메타데이터에는 edit_history 및 edit_controls 객체가 포함됩니다. 이 메타데이터는 2022년 9월 27일 이전에 생성된 게시물에는 반환되지 않습니다. 현재 이 메타데이터와 일치하는 Enterprise Operators는 제공되지 않습니다. 게시물 편집 메타데이터에 대해 더 알아보려면 Edit Posts fundamentals 페이지를 확인하세요.

​

2022

• 9월 29일 - 이 날짜 이후에 생성된 모든 게시물 객체에는 편집된 게시물 메타데이터가 제공됩니다. 게시물 객체를 제공하는 모든 Enterprise 엔드포인트는 이 날짜부터 해당 메타데이터를 제공하도록 업데이트되었습니다. 제공되는 편집 메타데이터에는 edit_history 및 edit_controls 객체가 포함됩니다. 이 메타데이터는 2022년 9월 27일 이전에 생성된 포스트에 대해서는 반환되지 않습니다. 현재 이 메타데이터에 대응하는 Enterprise Operators는 제공되지 않습니다. 편집 게시물 메타데이터에 대해 더 알아보려면 Edit Posts fundamentals 페이지를 확인하세요.

​

필터링 팁

위에서 설명한 타임라인 정보를 종합해 보면, Search API 필터를 작성할 때 고려해야 할 세부 사항이 매우 많다는 것을 알 수 있습니다. 특히 다음 두 가지를 유의해야 합니다:

• 일부 메타데이터에는 ‘생성일(born-on)’이 있기 때문에 필터 결과에 위음성(false negative) 이 발생할 수 있습니다. 이런 검색에는 전체 또는 일부 검색 기간 동안 존재하지 않았던 메타데이터에 의존하는 Operator가 포함됩니다. 예를 들어 has:images Operator를 사용해 게시물을 검색하는 경우, 2011년 7월 이전 기간에 대해서는 일치하는 결과가 없습니다. 해당 Operator는 네이티브 사진(사용자가 X UI를 통해 게시물에 첨부한 사진)을 기준으로 매칭되기 때문입니다. 사진 공유 게시물에 대한 보다 완전한 데이터 세트를 얻으려면, 2011년 7월 이전 기간에는 일반적인 사진 호스팅 URL에 매칭되는 규칙 절을 필터에 포함해야 합니다.
• 일부 메타데이터는 게시물이 X에 게시된 이후 시점의 메타데이터로 다시 채워(backfill)졌습니다.

PowerTrack 쿼리를 작성할 때 일반적으로 중점적으로 보게 되는 속성 유형은 다음과 같습니다:

• X 프로필
• 원본 또는 공유 게시물
• 게시물 언어 분류
• 지리 정보가 참조된 게시물
• 공유된 링크 미디어

이 중 일부는 제품별로 다른 동작을 가지며, 나머지는 동일한 동작을 가집니다. 자세한 내용은 아래를 참조하세요.

​

X 프로필

Search API는 과거 포스트를 검색 시점 에 존재하는 그대로의 사용자 프로필 데이터와 함께 제공합니다. 2014년의 게시물을 요청하더라도, 해당 사용자의 프로필 메타데이터는 쿼리 시점의 상태를 반영합니다.

​

원본 게시물 및 리트윗

PowerTrack _is:retweet_ 연산자를 사용하면 리트윗을 포함할지 제외할지 선택할 수 있습니다. 이 연산자를 사용하는 사용자는 2009년 8월 이전 데이터에 대해 리트윗을 일치(또는 비일치)시키기 위한 두 가지 전략을 마련해야 합니다. 2009년 8월 이전에는 “@RT ” 패턴과 일치하는지 확인하기 위해, 정확한 구문 일치 방식으로 게시물 본문 자체를 검사해야 합니다(실제로 2009년 5월부터 8월 사이의 리트윗을 필터링하는 경우에는 “Via @” 패턴도 포함해야 합니다). 2009년 8월 이후 기간에는 _is:retweet_ 연산자를 사용할 수 있습니다.

​

게시물 언어 분류

게시물의 언어 분류를 기준으로 필터링할 때, X의 과거 제품들은 서로 상당히 다릅니다. Search 아카이브가 구축될 때, 모든 게시물에는 X 언어 분류가 소급 적용되었습니다. 따라서 lang: 연산자는 전체 게시물 아카이브에서 사용할 수 있습니다.

​

포스트의 지리 정보 지정(Geo-referencing)

포스트의 지리 정보를 지정하는 주요 방법은 세 가지입니다.

• 포스트 메시지 내 지리적 참조. 포스트 메시지에 포함된 지리적 참조에 매칭하는 방법입니다. 현지 지식에 의존해야 해서 가장 까다로운 방법이지만, 전체 포스트 아카이브에 대해 사용할 수 있는 옵션입니다. 샌프란시스코 지역을 대상으로 ‘golden gate’ 필터를 기반으로 2006년에 지리 정보가 지정된 매칭 예시는 여기에서 확인할 수 있습니다.

• 사용자가 지오태그한 포스트. Search API에서는 2010년 3월부터 일부 Geo 연산자를 사용해 포스트를 매칭할 수 있게 되었고, 2015년 2월에는 다른 연산자들이 추가되었습니다.

  • 2010년 3월 6일: has:geo, bounding_box: 및 point_radius:
  • 2015년 2월 17일: place_country: 및 place:

• 사용자가 설정한 계정 프로필 ‘home’ 위치. 프로필 Geo 연산자는 Historical PowerTrack과 Search API 모두에서 사용할 수 있습니다. Search API에서는 이 프로필 Geo 메타데이터를 2015년 2월부터 사용할 수 있습니다. 프로필 Geo 메타데이터가 제공되기 이전에 게시된 포스트의 경우, 정규화되지 않은 사용자 입력에 매칭하는 데 사용할 수 있는 bio_location: 연산자가 제공됩니다.

​

공유 링크와 미디어

2012년 3월에 확장 URL 엔리치먼트가 도입되었습니다. 그 이전까지는 게시물 페이로드에 사용자가 제공한 URL만 포함되었습니다. 따라서 사용자가 단축 URL을 포함한 경우, 관심 있는 (확장된) URL과 매칭하기가 어려울 수 있습니다. Search API에서는 이 메타데이터를 2012년 3월부터 사용할 수 있습니다.

2016년 7월에 향상된 URL 엔리치먼트가 도입되었습니다. 이 향상된 버전은 게시물 페이로드에 웹사이트의 HTML 제목과 설명을 제공하며, 이에 기반해 매칭할 수 있는 연산자(Operator)도 함께 제공합니다. 이러한 메타데이터는 2014년 12월부터 나타나기 시작합니다.

2016년 9월, X는 ‘네이티브 첨부 파일’을 도입하여, 뒤에 오는 공유 링크가 게시물 140자 제한에 포함되지 않도록 했습니다. 두 가지 URL 엔리치먼트는 이러한 공유 링크에도 계속 적용됩니다.

관련 Search 연산자들이 매칭되기 시작한 시점은 다음과 같습니다:

• 2006년 10월 26일 - has:links
• 2011년 7월 20일 - has:images 및 has:media
• 2011년 8월 - Expanded URLs enrichment를 사용하는 url:. 2006년 9월처럼 이른 시점에도 (url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube)는 twitter_entities 및 gnip 객체에 urls[] 메타데이터가 없음에도 불구하고 http://x.com/Adam/statuses/16602 와 매칭됩니다. “youtube.com”은 어떤 urls[] 메타데이터도 없이 url:youtube와 매칭되는 메시지 콘텐츠의 예입니다.
• 2015년 2월 10일 - 네이티브 비디오용 has:videos. 2010/08/28부터 2015/02/10 사이에는 이 연산자가 youtube.com, vimeo.com, vivo.com과 같은 일부 비디오 호스팅 사이트로의 링크가 포함된 포스트와 매칭됩니다.
• 2016년 5월 1일 - Enhanced URLs enrichment를 기반으로 하는 url_title: 및 url_description: 이 일반적으로 제공되기 시작했습니다. 첫 번째 Enhanced URL 메타데이터는 2014년 12월에 나타나기 시작했습니다.

​

자주 묻는 질문(FAQ)

​

Search Post API 관련 일반 질문

data 엔드포인트를 통해 받는 포스트 수가 counts 엔드포인트에서 집계된 포스트 수와 일치하지 않습니다. 왜 이런 일이 발생하나요?

counts 엔드포인트가 제공하는 결과와 data 엔드포인트가 제공하는 결과 사이에는 알려진 차이가 있습니다. 이는 counts 엔드포인트가 사전 컴플라이언스(pre-compliance) 단계의 결과를 제공하여 삭제된 게시물, 위치 정보 삭제(scrub geo) 등과 같은 요소를 반영하지 않는 반면, data 엔드포인트는 전달 시점에 컴플라이언스를 준수하며 모든 컴플라이언스 이벤트를 반영하기 때문에, 결과에 불일치가 발생할 수 있기 때문입니다.

내 쿼리와 일치해야 하는 게시물을 받지 못했습니다. 왜 그런가요?

이런 일이 발생했을 수 있는 몇 가지 가능한 이유가 있습니다. 예를 들면 다음과 같습니다.

1. 예상했던 게시물이 보호된 계정의 게시물인 경우
2. 데이터 엔드포인트가 모든 컴플라이언스 이벤트를 고려하기 때문입니다(즉, 삭제된 게시물, 삭제된 위치 정보 등은 응답에 포함되지 않습니다).

내 쿼리가 게시물과 일치했지만, 내가 NOT 조건으로 제외한 키워드도 포함되어 있습니다. 왜 이런 일이 발생하나요?

이는 프리미엄 규칙 및 필터링 기능을 잘못 사용했기 때문일 가능성이 큽니다. 여기의 문서를 검토하고, 규칙을 작성할 때 적용되는 제한 사항을 충분히 이해하고 있는지 확인하세요.

Search 게시물 API를 처음 사용할 때 활용할 수 있는 라이브러리가 있나요?

네, 다음과 같은 것들이 있습니다.

• Tweepy - 표준 Search/Posts 제품을 사용할 때 유용한 라이브러리입니다(Python)
• X API - 표준 Search Post API를 사용할 때 유용한 라이브러리입니다(Python)
• Search Posts Python 및 Search Posts Ruby - 엔터프라이즈용(및 v2!) Search Post API와 함께 사용할 수 있는 유용한 도구 두 가지입니다

우리가 직접 지원하는 모든 라이브러리는 xdevplatform GitHub 페이지에서 확인할 수 있습니다: https://github.com/xdevplatform.

도움이 될 수 있는 기타 타사 라이브러리도 있습니다. 다만 이들 중 일부는 프리미엄 및 엔터프라이즈 제품에서는 작동하지 않을 수 있다는 점에 유의해 주세요.

데이터 엔드포인트에 대한 요청에서 `maxResults`로 설정한 값보다 더 적은 수의 포스트를 받는 경우가 있을까요?

네. 데이터 엔드포인트는 지정한 maxResults 값 또는 30일 기간 단위로 페이지네이션됩니다.

예를 들어, 특정 30일 기간에 포스트가 800개 있는 경우 전체 결과를 가져오려면 두 번의 요청을 보내야 합니다. 요청당 반환될 수 있는 포스트의 최대 개수는 500개(maxResults)이기 때문입니다. 그리고 첫 번째 달에 포스트가 400개, 두 번째 달에 포스트가 100개 있는 경우에도 전체 결과를 가져오려면 두 번의 요청을 사용해야 합니다. 첫 번째 요청이 지정한 maxResults보다 적은 수의 포스트를 반환하더라도, 페이지네이션은 30일 기간이 지나면 이루어지기 때문입니다.

검색 결과 포스트는 어떤 순서로 반환되나요?

포스트는 최신순(내림차순)으로 반환됩니다. 예를 들어, 첫 페이지 결과에는 쿼리와 일치하는 가장 최신 포스트가 표시되며, 페이지네이션은 결과의 게시 날짜를 기준으로 처음 요청한 fromDate에 도달할 때까지 계속 진행됩니다.

Edit Posts 기능은 내 사용량과 과금에 어떤 영향을 미치나요?

청구 시에는 원본 게시물만 계산됩니다. 이후에 이루어진 편집은 모두 무시되며 전체 활동 집계에 반영되지 않습니다. 

Enterprise

Enterprise Search 게시물 API의 가격 및 요금제에 대해 더 자세히 알고 싶고, 이 오퍼링을 신청하고 싶습니다. 어떻게 하면 되나요?

당사의 엔터프라이즈 솔루션은 예측 가능한 가격으로 귀사의 비즈니스 요구에 맞게 맞춤 제공합니다. 자세한 내용 확인 및 신청은 여기를 참조해 주십시오.

내 사용 사례에 맞는 규칙 세트는 어떻게 만들 수 있나요?

• 엔터프라이즈 Search 게시물 API 문서는 여기를 참고하세요.
• 규칙 및 필터링에 대한 유용한 정보는 여기에서 확인할 수 있습니다.
• 데이터 엔드포인트 사용에 대한 유용한 정보는 여기에서 확인할 수 있습니다.
• 카운트 엔드포인트 사용에 대한 유용한 정보는 여기에서 확인할 수 있습니다.
• 사용 가능한 연산자 목록은 여기에서 확인할 수 있습니다.

이번 달 요청 한도/제한을 초과했는데 더 많은 데이터에 액세스해야 합니다. 어떻게 하면 되나요?

이와 관련된 도움을 받으시려면 X 담당 Account Manager에게 문의해 주세요.

​

오류 해결 가이드

코드 404 - Not Found

1. 각 엔드포인트에 올바른 매개변수를 사용하고 있는지 확인하세요 (예: buckets 필드는 data 엔드포인트가 아니라 counts 엔드포인트에서만 사용할 수 있습니다).
2. :product, :account_name, :label 필드가 올바른지 다시 한 번 확인하세요. GNIP 콘솔(엔터프라이즈 고객 전용)에서 :label 필드를 확인할 수 있습니다.

​

API 참조 문서

​

Enterprise search APIs

엔터프라이즈 검색 API에는 다음 두 가지가 있습니다.

• 30-Day Search API - 최근 30일 이내에 게시된 Tweet을 제공합니다.
• Full-Archive Search API - 2006년 3월에 게시된 첫 번째 Tweet부터 시작해, 2006년까지 거슬러 올라가는 Tweet을 제공합니다.

이 검색 API는 공통된 설계를 따르며, 아래 문서는 두 API 모두에 적용됩니다. 2022년 9월 29일부터 생성된 Tweet의 경우, Tweet 객체에는 편집 이력을 설명하는 Tweet 편집 메타데이터가 포함됩니다. 자세한 내용은 “Edit Tweets” 기본 사항 페이지를 참조하세요.

아래에서는 엔터프라이즈 검색 API를 연동할 때 필요한 중요한 세부 정보를 확인할 수 있습니다.

• Tweet 데이터 및 개수(count)를 요청하는 메서드
• 인증
• 페이지네이션
• API 요청 매개변수 및 요청 예시
• API 응답 JSON 페이로드 및 응답 예시
• HTTP 응답 코드

엔터프라이즈 API는 Tweet 아카이브에 대한 저지연, 원본 보존(full-fidelity)의 쿼리 기반 액세스를 제공합니다. 두 API의 유일한 차이점은 검색할 수 있는 기간으로, 최근 30일 또는 2006년부터입니다. 기간은 분 단위까지 지정할 수 있습니다. Tweet 데이터는 쿼리와 일치하는 가장 최근 Tweet부터 역순 시간 순으로 제공됩니다. Tweet은 게시된 후 약 30초가 지나면 검색 API에서 사용할 수 있습니다.

​

메서드

엔터프라이즈 검색의 기본 URI는 https://gnip-api.x.com/search/입니다.

메서드	설명
POST /search/:product/accounts/:account_name/:label	지정된 PowerTrack 규칙과 일치하는, 지난 30일 동안의 Tweet을 조회합니다.
POST /search/:product/accounts/:account_name/:label/counts	지정된 PowerTrack 규칙과 일치하는, 지난 30일 동안의 Tweet 개수를 조회합니다.

여기서:

• :product는 요청을 보내는 검색 endpoint를 나타내며, 30day 또는 fullarchive입니다.
• :account_name은 console.gnip.com에 표시되는 계정과 연결된 이름으로, 대소문자를 구분합니다.
• :label은 console.gnip.com에 표시되는 검색 endpoint와 연결된 레이블로, 대소문자를 구분합니다.

예를 들어, TwitterDev 계정이 레이블이 ‘prod’(production의 약어)인 30일 검색 product를 보유하고 있는 경우 검색 endpoint는 다음과 같습니다.

• 데이터 endpoint: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json
• 카운트 endpoint: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json

완전한 엔터프라이즈 검색 API endpoint는 https://console.gnip.com에서 확인할 수 있습니다.

아래에는 curl이라는 간단한 HTTP 유틸리티를 사용한 여러 요청 예시가 있습니다. 이 예시들은 :product, :account_name, :label이 포함된 URL을 사용합니다. 이 예시들을 사용할 때에는 반드시 URL을 자신의 정보로 업데이트해야 합니다.

​

인증

Enterprise search API에 대한 모든 요청에는 https://console.gnip.com 계정에 로그인할 때 사용하는 유효한 이메일 주소와 비밀번호 조합으로 구성한 HTTP _Basic Authentication_을 사용해야 합니다. 각 요청마다 이 인증 정보를 Authorization 헤더에 포함해 전달해야 합니다.

​

요청/응답 동작

fromDate 및 toDate 파라미터를 사용하면 API가 지원하는 어떤 기간이든 요청할 수 있습니다. 30-Day search API는 가장 최근 31일간의 Tweet을 제공합니다(‘30-Day’ API라고 부르지만, 사용자가 한 달 전체를 요청할 수 있도록 31일을 제공합니다). Full-Archive search API는 최초의 Tweet(2006년 3월 21일)까지 거슬러 올라가는 Tweet을 제공합니다. 다만 단일 응답에는 지정한 maxResults 값과 31일 중 더 작은 쪽까지만 포함됩니다. 매칭되는 데이터 양 또는 지정한 시간 범위가 maxResults 또는 31일을 초과하는 경우, 남은 지정 시간 범위를 페이지네이션하기 위해 사용해야 하는 next 토큰을 받게 됩니다.

예를 들어, Full-Archive search를 사용하여 2017년 1월 1일부터 2017년 6월 30일까지 쿼리에 매칭되는 모든 Tweet을 조회한다고 가정해 보겠습니다. 이때 요청에서 fromDate 및 toDate 파라미터를 사용해 해당 6개월 전체 기간을 지정합니다. search API는 첫 번째 Tweet ‘페이지’를 응답으로 반환하며, 이때 Tweet 개수는 maxResults 파라미터(기본값은 100)에 맞게 반환됩니다. 더 많은 Tweet이 존재하는 경우(대부분의 경우 더 많이 존재합니다), API는 다음 ‘페이지’의 데이터를 요청할 수 있도록 하는 next 토큰도 함께 제공합니다. 이 과정은 API가 더 이상 next 토큰을 반환하지 않을 때까지 반복됩니다. 자세한 내용은 다음 섹션을 참고하세요.

​

페이지네이션

데이터 요청과 count 요청을 모두 수행할 때는, 단일 응답으로 반환할 수 있는 것보다 더 많은 데이터가 있을 가능성이 큽니다. 그런 경우 응답에 next 토큰이 포함됩니다. next 토큰은 최상위 수준 JSON 속성으로 제공됩니다. next 토큰이 제공되는 경우에는 추가로 조회해야 할 데이터가 있다는 의미이므로, 계속해서 API 요청을 보내야 합니다.

참고: next 토큰의 동작은 데이터 요청과 count 요청에서 약간 다르며, 둘 다 아래에서 설명합니다. 예시 응답은 API 참조 문서 섹션에 제공되어 있습니다.

데이터 페이지네이션

데이터에 대한 요청은 단일 응답에 포함될 수 있는 양보다 더 많은 데이터를 반환하는 경우가 많습니다. 각 데이터 요청에는 요청마다 반환할 Tweet의 최대 개수를 설정하는 매개변수가 포함됩니다. 이 maxResults 매개변수의 기본값은 100이며, 10–500 범위 내에서 설정할 수 있습니다. 쿼리와 일치하는 Tweet 수가 요청에 사용한 maxResults 매개변수 값보다 많은 경우, 응답에는 루트 수준 JSON 속성으로 ‘next’ 토큰이 포함됩니다. 이 ‘next’ 토큰은 해당 쿼리에 대해 다음에 일치하는 Tweet 묶음(즉, 다음 ‘page’)을 가져오기 위한 후속 요청에서 사용됩니다. 쿼리에 대한 마지막 ‘page’에 도달해 더 이상 ‘next’ 토큰이 제공되지 않을 때까지 ‘next’ 토큰이 계속 반환됩니다.

다음 ‘page’의 데이터를 요청하려면, (사용했다면) query, toDate, fromDate 매개변수를 포함해 초기 쿼리와 완전히 동일한 쿼리를 보내야 하며, 이전 응답에서 받은 값을 설정한 ‘next’ 요청 매개변수도 포함해야 합니다. 이는 GET 또는 POST 요청 모두에서 사용할 수 있습니다. 단, GET 요청의 경우 ‘next’ 매개변수는 URL 인코딩되어야 합니다.

이전 쿼리에서 받은 ‘next’ 요소를 계속 전달하면, 쿼리가 대상으로 하는 기간 동안의 모든 Tweet을 받을 때까지 데이터를 가져올 수 있습니다. ‘next’ 요소가 포함되지 않은 응답을 받으면, 이는 마지막 페이지에 도달했으며 지정된 쿼리와 시간 범위에 대해 더 이상 사용할 수 있는 데이터가 없다는 의미입니다.

카운트 페이지네이션

counts endpoint는 쿼리와 연관된 Tweet 개수를 일 단위, 시간 단위, 또는 분 단위 기준으로 제공합니다. counts API endpoint는 최대 31일 분량의 카운트에 대해 타임스탬프가 포함된 카운트 배열을 반환합니다. 31일이 넘는 기간의 카운트를 요청하면 next 토큰이 제공됩니다. 데이터용 next 토큰과 마찬가지로, 원래 요청과 완전히 동일한 쿼리를 다시 수행해야 하며, 이전 응답에서 받은 값을 next 요청 매개변수로 함께 보내야 합니다.

31일을 초과하는 카운트를 요청하는 경우 외에도, next 토큰이 제공되는 또 다른 시나리오가 있습니다. 볼륨이 높은 쿼리의 경우, 카운트를 생성하는 데 걸리는 시간이 길어져 응답 타임아웃이 발생할 수 있습니다. 이 경우 31일 미만의 카운트를 받게 되지만, 전체 카운트 페이로드를 계속 요청할 수 있도록 next 토큰이 함께 제공됩니다. 중요: 타임아웃이 발생하면 항상 전체 “버킷”만 반환됩니다. 예를 들어 2.5일 분량의 데이터는 2일치 전체 “버킷”으로만 반환됩니다.

추가 참고 사항

• 검색 요청에서 fromDate 또는 toDate를 사용할 때는 지정한 시간 범위 안에 있는 결과만 받게 됩니다. 시간 범위 내에서 마지막 결과 세트에 도달하면 ‘next’ 토큰을 받지 못합니다.
• ‘next’ 요소는 10~500 사이의 어떤 maxResults 값과도 함께 사용할 수 있습니다(기본값은 100). maxResults는 각 응답에서 반환되는 Tweet 수를 결정하지만, 결국 모든 결과를 받는 것을 막지는 않습니다.
• ‘next’ 요소는 만료되지 않습니다. 동일한 ‘next’ 쿼리를 사용한 여러 요청은, 요청 시점과 관계없이 동일한 결과를 받게 됩니다.
• ‘next’ 매개변수를 사용해 결과를 페이지로 나누어 조회할 때, 쿼리 경계에서 중복 항목이 발생할 수 있습니다. 애플리케이션은 이러한 중복을 허용하도록 설계해야 합니다.

​

데이터 엔드포인트

POST /search/:product/:label

엔드포인트 패턴:

이 엔드포인트는 지정된 쿼리와 시간 범위에 대한 데이터를 반환합니다. 시간 범위를 지정하지 않으면, 시간 파라미터는 기본적으로 지난 30일로 설정됩니다. 참고: 아래에 설명된 파라미터를 URL에 인코딩하면, POST 대신 GET 요청을 사용해도 동일한 기능을 구현할 수 있습니다.

데이터 요청 매개변수

Parameters	Description	Required	Sample Value
query	최대 2,048자의 길이를 가진 하나의 PowerTrack 규칙에 해당합니다(긍정/부정 절의 개수에는 제한이 없음). 이 매개변수에는 모든 연산자를 포함한 PowerTrack 규칙의 모든 부분이 포함되어야 하며, 규칙의 일부를 쿼리의 다른 매개변수로 분리해서는 안 됩니다. 참고: 모든 PowerTrack 연산자가 지원되는 것은 아닙니다. 지원되는 연산자는 여기에 나열되어 있습니다.	Yes	(snow OR cold OR blizzard) weather
tag	태그는 규칙과 해당 규칙에 매칭되는 데이터를 서로 다른 논리적 그룹으로 분리하는 데 사용할 수 있습니다. 규칙 태그가 제공되면, 해당 규칙 태그는 matching_rules 속성에 포함됩니다. 규칙별 UUID를 규칙 태그에 할당하고, 원하는 매핑은 클라이언트 측에서 관리할 것을 권장합니다.	No	8HYG54ZGTU
fromDate	Tweet이 제공될 가장 이른 UTC 타임스탬프입니다(Full-Archive 검색의 경우 2006년 3월 21일까지 가능). 타임스탬프는 분 단위 정밀도를 가지며 포함 범위입니다(예: 12:00은 00분을 포함). 지정된 경우: toDate 매개변수 없이 fromDate만 사용하는 경우, now() 시점부터 과거로 거슬러 올라가면서 fromDate까지의 쿼리 결과를 제공합니다. 지정되지 않은 경우: fromDate가 지정되지 않으면, API는 now() 또는 toDate(지정된 경우)를 기준으로 그 이전 30일 동안의 모든 결과를 제공합니다. fromDate와 toDate 매개변수를 모두 사용하지 않으면, API는 요청 시점을 시작점으로 하여 과거로 거슬러 올라가며 가장 최근 30일 동안의 모든 결과를 제공합니다.	No	201207220000
toDate	Tweet이 제공될 가장 늦은, 최신 UTC 타임스탬프입니다. 타임스탬프는 분 단위 정밀도를 가지며 비포함 범위입니다(예: 11:59는 해당 시각의 59분을 포함하지 않음). 지정된 경우: fromDate 매개변수 없이 toDate만 사용하는 경우, toDate 이전의 가장 최근 30일간 데이터가 제공됩니다. 지정되지 않은 경우: toDate가 지정되지 않으면, API는 now() 시점부터 과거로 거슬러 올라가면서 fromDate까지의 모든 결과를 제공합니다. fromDate와 toDate 매개변수를 모두 사용하지 않으면, API는 요청 시점을 시작점으로 하여 과거로 거슬러 올라가며 전체 30일 인덱스에 대한 모든 결과를 제공합니다.	No	201208220000
maxResults	요청에서 반환할 검색 결과의 최대 개수입니다. 10과 시스템 제한값(현재 500) 사이의 숫자여야 합니다. 기본적으로 요청 응답은 100개의 결과를 반환합니다.	No	500
next	여기에 설명된 것처럼 다음 ‘페이지’의 결과를 가져오는 데 사용되는 매개변수입니다. 이 매개변수에 사용되는 값은 API가 제공하는 응답에서 직접 가져와야 하며, 수정해서는 안 됩니다.	No	NTcxODIyMDMyODMwMjU1MTA0

추가 세부사항

사용 가능 기간	30일: 최근 31일 전체 아카이브: 2006년 3월 21일 - 현재
쿼리 형식	PowerTrack 규칙 1개에 해당하며, 최대 2,048자까지 사용할 수 있습니다(긍정 및 부정 절(clause)의 개수에는 제한이 없습니다). 참고: 모든 PowerTrack 연산자가 지원되는 것은 아닙니다. 지원되는 연산자 목록은 Available operators를 참조하세요.
요청 한도	파트너는 분 단위와 초 단위 모두에서 요청 한도가 적용됩니다. 분당 요청 한도는 계약서에 명시된 대로 파트너별로 다릅니다. 그러나 이러한 분당 요청 한도는 한 번에 몰아서 사용하도록 설계된 것이 아닙니다. 분당 요청 한도와 관계없이, 모든 파트너는 데이터 및/또는 카운트에 대한 모든 요청을 합산했을 때 초당 최대 20개의 요청으로 제한됩니다.
규정 준수(Compliance)	Full-Archive Search API를 통해 제공되는 모든 데이터는 전송 시점에 규정을 준수하는 상태입니다.
실시간 가용성	데이터는 Twitter 플랫폼에서 생성된 후 30초 이내에 인덱스에 반영되어 사용할 수 있습니다.

데이터 요청 및 응답 예시

POST 요청 예시

• POST 요청의 매개변수는 아래와 같이 JSON 형식의 본문(body)을 통해 전송됩니다.
• 조회하려는 PowerTrack 규칙의 모든 구성 요소(예: 키워드, bounding_box:와 같은 기타 연산자)는 ‘query’ 매개변수에 포함해야 합니다.
• 규칙의 일부를 쿼리 URL의 개별 매개변수로 분리하지 마십시오.

다음은 초기 데이터 요청을 보내기 위한 POST(cURL 사용) 명령 예시입니다:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm"}'

API 데이터 응답에 ‘next’ 토큰이 포함된 경우, 아래는 제공된 토큰을 ‘next’ 파라미터에 설정하여 원래 요청을 다시 수행하는 후속 요청 예시입니다:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm",
    "next":"NTcxODIyMDMyODMwMjU1MTA0"}'

예시 GET 요청

• GET 요청의 요청 매개변수는 표준 URL 인코딩을 사용하여 URL에 인코딩됩니다.
• 조회하려는 PowerTrack 규칙의 모든 부분(예: 키워드, bounding_box:와 같은 기타 연산자)은 ‘query’ 매개변수에 넣어야 합니다.
• 쿼리 URL에서 규칙의 일부를 별도의 매개변수로 분리하지 마십시오.

다음은 초기 데이터 요청을 수행하기 위한 예시 GET (cURL 사용) 명령입니다:

    curl -u<username> "http://gnip-api.x.com/search/:product/accounts/:account_name/:label.json?query=from%3Atwitterdev&maxResults=500&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm"

예시 데이터 응답

2022년 9월 29일 이후에 생성된 Tweet의 경우, Tweet 객체에 편집 이력을 설명하는 Tweet 편집 메타데이터가 포함됩니다. 자세한 내용은 “Edit Tweets” 기본 설명 페이지를 참조하세요.

아래는 데이터 쿼리에 대한 예시 응답입니다. 이 예시는 사용 가능한 Tweet 수가 ‘maxResults’보다 많아서 이후 요청을 위해 ‘next’ 토큰이 제공된 상황을 가정합니다. 쿼리와 연관된 Tweet 수가 ‘maxResults’ 이하거나 그보다 적다면, 응답에 ‘next’ 토큰이 포함되지 않습니다. ‘next’ 요소의 값은 쿼리마다 변경되며 불투명한 문자열로 취급해야 합니다. 응답 본문에서 ‘next’ 요소는 다음과 같은 형태입니다:

{
    "results":
      [
            {--Tweet 1--},
            {--Tweet 2--},
            ...
            {--Tweet 500--}
      ],
    "next":"NTcxODIyMDMyODMwMjU1MTA0",
    "requestParameters":
      {
        "maxResults":500,
        "fromDate":"201101010000",
        "toDate":"201201010000"
      }
  }

후속 요청에 대한 응답은 다음과 비슷할 수 있습니다(새로운 Tweet과 변경된 ‘next’ 값에 주의하세요):

{
      "results":
      [
            {--Tweet 501--},
            {--Tweet 502--},
            ...
            {--Tweet 1000--}
      ],
      "next":"R2hCDbpBFR6eLXGwiRF1cQ",
      "requestParameters":
      {
        "maxResults":500,
        "fromDate":"201101010000",
        "toDate":"201201010000"
      }
  }

이전 쿼리에서 받은 ‘next’ 요소를, 해당 쿼리가 다루는 기간의 모든 Tweet을 받을 때까지 계속 전달할 수 있습니다. ‘next’ 요소가 포함되지 않은 응답을 받으면, 마지막 페이지에 도달했으며 지정한 기간에 대해 더 이상 추가 데이터가 없음을 의미합니다.

​

카운트 엔드포인트

/search/:stream/counts

엔드포인트 패턴:

/search/fullarchive/accounts/:account_name/:label/counts.json

이 엔드포인트는 지정된 쿼리에 대한 카운트(데이터 볼륨) 데이터를 반환합니다. 기간이 지정되지 않은 경우 시간 파라미터는 기본적으로 최근 30일로 설정됩니다. 데이터 볼륨은 일 단위, 시간 단위(기본값), 또는 분 단위 중 하나로 타임스탬프가 포함된 배열 형태로 반환됩니다.

참고: 아래에 설명된 파라미터를 URL에 인코딩하면 POST 대신 GET 요청을 사용해도 동일한 동작을 수행할 수 있습니다.

카운트 요청 매개변수

Parameters	Description	Required	Sample Value
query	최대 2,048자까지 허용되는 하나의 PowerTrack 규칙과 동일합니다(긍정 및 부정 절(clause)의 개수에는 제한이 없습니다). 이 매개변수에는 모든 연산자(operator)를 포함한 PowerTrack 규칙의 모든 부분이 포함되어야 하며, 규칙의 일부를 query의 다른 매개변수로 분리해서는 안 됩니다. 참고: 모든 PowerTrack 연산자가 지원되는 것은 아닙니다. 지원되는 연산자 목록은 Available operators를 참조하세요.	Yes	(snow OR cold OR blizzard) weather
fromDate	Tweet이 제공될 수 있는 가장 오래된 UTC 타임스탬프(2006년 3월 21일까지 거슬러 올라감)입니다. 타임스탬프는 분 단위 정밀도를 가지며, 포함 범위입니다(예: 12:00은 00분을 포함). 지정한 경우: toDate 매개변수 없이 fromDate만 사용하는 경우, API는 now()부터 fromDate까지 과거로 거슬러 올라가며 쿼리에 대한 카운트(데이터 볼륨)를 제공합니다. fromDate가 now()로부터 31일 이전보다 더 과거라면, 요청을 페이지로 넘기기 위한 next 토큰을 받게 됩니다. 지정하지 않은 경우: fromDate를 지정하지 않으면, API는 now() 또는(지정된 경우) toDate로부터 30일 이전까지의 카운트(데이터 볼륨)를 제공합니다. fromDate와 toDate 매개변수를 모두 사용하지 않는 경우, API는 요청 시점을 기준으로 과거로 30일간의 가장 최근 카운트(데이터 볼륨)를 제공합니다.	No	201207220000
toDate	Tweet이 제공될 수 있는 가장 최근(최신) UTC 타임스탬프입니다. 타임스탬프는 분 단위 정밀도를 가지며, 비포함 범위입니다(예: 11:59는 해당 시(hour)의 59분을 포함하지 않음). 지정한 경우: fromDate 매개변수 없이 toDate만 사용하는 경우, toDate로부터 30일 이전까지의 가장 최근 카운트(데이터 볼륨)를 제공합니다. 지정하지 않은 경우: toDate를 지정하지 않으면, API는 쿼리에 대해 fromDate까지 과거로 거슬러 올라가며 카운트(데이터 볼륨)를 제공합니다. fromDate가 now()로부터 31일 이전보다 더 과거라면, 요청을 페이지로 넘기기 위한 next 토큰을 받게 됩니다. fromDate와 toDate 매개변수를 모두 사용하지 않는 경우, API는 요청 시점을 기준으로 과거로 30일간의 가장 최근 카운트(데이터 볼륨)를 제공합니다.	No	201208220000
bucket	카운트 데이터가 제공될 시간 단위입니다. 카운트 데이터는 요청한 기간에 대해 하루, 한 시간 또는 1분 단위로 반환될 수 있습니다. 기본적으로는 시간(hour) 단위 카운트가 제공됩니다. 옵션: ‘day’, ‘hour’, ‘minute’	No	minute
next	이 매개변수는 여기에 설명된 대로 다음 ‘페이지’의 결과를 가져오는 데 사용됩니다. 이 매개변수에 사용하는 값은 API가 제공한 응답에서 직접 가져와야 하며, 수정해서는 안 됩니다.	No	NTcxODIyMDMyODMwMjU1MTA0

추가 세부 정보

사용 가능 기간	30-Day: 최근 31일 Full-Archive: 2006년 3월 21일 - 현재
쿼리 형식	최대 2,048자 길이의 PowerTrack 규칙 1개와 동일합니다. 참고: 모든 PowerTrack 연산자가 지원되는 것은 아닙니다. 지원되는 연산자 목록은 사용 가능한 연산자를 참고하세요.
요청 한도	파트너에게는 분 및 초 단위로 세분화된 요청 한도가 적용됩니다. 분당 요청 한도는 계약서에 명시된 대로 파트너별로 다릅니다. 그러나 이러한 분당 요청 한도는 단일 버스트로 모두 사용하도록 설계된 것이 아닙니다. 분당 요청 한도와 관계없이, 모든 파트너는 데이터 및/또는 카운트에 대한 모든 요청을 합산하여 초당 최대 20개 요청으로 제한됩니다.
카운트 정밀도	이 엔드포인트를 통해 제공되는 카운트는 실제로 발생한 Tweet 수를 반영하며, 이후의 컴플라이언스 이벤트(삭제, 지오 정보 삭제 등)는 반영하지 않습니다. 카운트에 포함된 일부 Tweet은 사용자의 컴플라이언스 조치로 인해 데이터 엔드포인트를 통해 제공되지 않을 수 있습니다.

카운트 요청 및 응답 예제

POST 요청 예시

• POST 요청의 요청 매개변수는 아래와 같이 JSON 형식의 요청 본문(body)으로 전송됩니다.
• 조회하려는 PowerTrack 규칙의 모든 요소(예: 키워드, bounding_box:와 같은 기타 연산자)는 ‘query’ 매개변수에 넣어야 합니다.
• 규칙의 일부를 쿼리 URL의 개별 매개변수로 분리하지 마십시오.

다음은 초기 counts 요청을 보내기 위한 POST(cURL 사용) 명령 예시입니다:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day"}'

API counts 응답에 ‘next’ 토큰이 포함되어 있다면, 아래와 같이 원래 요청에서 ‘next’ 매개변수에 제공된 토큰 값을 설정하여 보내는 후속 요청 예시는 다음과 같습니다:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day",
    "next":"YUcxO87yMDMyODMwMjU1MTA0"}'

GET 요청 예시

• GET 요청의 매개변수는 표준 URL 인코딩을 사용하여 URL에 인코딩됩니다
• 조회할 PowerTrack 규칙의 모든 부분(예: 키워드, bounding_box:와 같은 기타 연산자)은 모두 ‘query’ 매개변수에 포함해야 합니다
• 규칙의 일부를 쿼리 URL에서 분리하여 별도의 매개변수로 전달하지 마십시오

다음은 초기 counts 요청을 수행하기 위한 GET 요청(cURL 사용) 명령 예시입니다:

    curl -u<username> "http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json?query=TwitterDev&bucket=day&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm"

​

예시 counts 응답

아래는 counts(데이터 볼륨) 쿼리에 대한 예시 응답입니다. 이 예시 응답에는 ‘next’ 토큰이 포함되어 있는데, 이는 counts 요청의 조회 기간이 31일을 초과했거나, 제출된 쿼리와 관련된 데이터 볼륨이 충분히 커서 부분 응답만 반환되었음을 의미합니다.

‘next’ 요소의 값은 쿼리마다 달라지며, 내부 구조를 해석하지 않는 단순 문자열로 취급해야 합니다. 응답 본문에서 ‘next’ 요소는 다음과 같은 형태를 띱니다:

    {
      "results": [
        { "timePeriod": "201101010000", "count": 32 },
        { "timePeriod": "201101020000", "count": 45 },
        { "timePeriod": "201101030000", "count": 57 },
        { "timePeriod": "201101040000", "count": 123 },
        { "timePeriod": "201101050000", "count": 134 },
        { "timePeriod": "201101060000", "count": 120 },
        { "timePeriod": "201101070000", "count": 43 },
        { "timePeriod": "201101080000", "count": 65 },
        { "timePeriod": "201101090000", "count": 85 },
        { "timePeriod": "201101100000", "count": 32 },
        { "timePeriod": "201101110000", "count": 23 },
        { "timePeriod": "201101120000", "count": 85 },
        { "timePeriod": "201101130000", "count": 32 },
        { "timePeriod": "201101140000", "count": 95 },
        { "timePeriod": "201101150000", "count": 109 },
        { "timePeriod": "201101160000", "count": 34 },
        { "timePeriod": "201101170000", "count": 74 },
        { "timePeriod": "201101180000", "count": 24 },
        { "timePeriod": "201101190000", "count": 90 },
        { "timePeriod": "201101200000", "count": 85 },
        { "timePeriod": "201101210000", "count": 93 },
        { "timePeriod": "201101220000", "count": 48 },
        { "timePeriod": "201101230000", "count": 37 },
        { "timePeriod": "201101240000", "count": 54 },
        { "timePeriod": "201101250000", "count": 52 },
        { "timePeriod": "201101260000", "count": 84 },
        { "timePeriod": "201101270000", "count": 120 },
        { "timePeriod": "201101280000", "count": 34 },
        { "timePeriod": "201101290000", "count": 83 },
        { "timePeriod": "201101300000", "count": 23 },
        { "timePeriod": "201101310000", "count": 12 }
       ],
      "totalCount":2027,
      "next":"NTcxODIyMDMyODMwMjU1MTA0",
      "requestParameters":
        {
          "bucket":"day",
          "fromDate":"201101010000",
          "toDate":"201201010000"
        }
    }

후속 요청에 대한 응답은 다음과 같을 수 있습니다(새 counts 타임라인과 다른 ‘next’ 값에 유의하세요).

    {
      "results": [
        { "timePeriod": "201102010000", "count": 45 },
        { "timePeriod": "201102020000", "count": 76 },
         ....
        { "timePeriod": "201103030000", "count": 13 }
     ],
     "totalCount":3288,
     "next":"WE79fnakFanyMDMyODMwMjU1MTA0",
     "requestParameters":
        {
          "bucket":"day",
          "fromDate":"201101010000",
          "toDate":"201201010000"
        }
    }

이전 쿼리에서 받은 ‘next’ 요소를 계속 전달하여, 해당 쿼리 기간에 대한 모든 카운트를 받을 때까지 사용할 수 있습니다. ‘next’ 요소가 포함되지 않은 응답을 받으면 마지막 페이지에 도달했으며, 지정한 시간 범위 내에서 추가로 반환될 카운트가 없음을 의미합니다.

​

HTTP response codes

상태	텍스트	설명
200	OK	요청이 성공했습니다. JSON 응답은 다음과 비슷한 형식입니다.
400	Bad Request	일반적으로 이 응답은 요청에 잘못된 JSON이 포함되어 있거나 JSON 페이로드를 전혀 보내지 않은 경우에 발생합니다.
401	Unauthorized	잘못된 자격 증명으로 인해 HTTP 인증에 실패했습니다. console.gnip.com에 해당 자격 증명으로 로그인하여 요청에 올바르게 사용하고 있는지 확인하세요.
404	Not Found	요청이 전송된 URL에서 리소스를 찾을 수 없습니다. 잘못된 URL을 사용했을 가능성이 높습니다.
422	Unprocessable Entity	쿼리의 매개변수가 잘못된 경우 반환됩니다. 예: 잘못된 PowerTrack 규칙.
429	Unknown Code	사용 중인 앱이 연결 요청 한도를 초과했습니다. 이에 해당하는 JSON 메시지는 다음과 비슷한 형식입니다.
500	Internal Server Error	서버 측에서 오류가 발생했습니다. 지수적 백오프 패턴을 사용해 요청을 다시 시도하세요.
502	Proxy Error	서버 측에서 오류가 발생했습니다. 지수적 백오프 패턴을 사용해 요청을 다시 시도하세요.
503	Service Unavailable	서버 측에서 오류가 발생했습니다. 지수적 백오프 패턴을 사용해 요청을 다시 시도하세요.