Documentation Index
Fetch the complete documentation index at: https://generaltranslation.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Standard v1.1과 X API v2 비교
- 유사점
- OAuth 1.0a 사용자 컨텍스트 및 OAuth 2.0 App-only
- 게시물 수정 내역과 메타데이터 지원
- 차이점
-
엔드포인트 URL
-
App 및 Project 요구 사항
-
응답 데이터 형식
-
요청 파라미터
-
새로운 쿼리 연산자
-
AND / OR 연산자 우선순위
OAuth 1.0a User Context와 OAuth 2.0 App-Only 인증
v1.1 search/posts와 X API v2 recent search 엔드포인트는 OAuth 1.0a User Context와 OAuth 2.0 App-Only를 모두 지원합니다.
따라서 이전에 표준 v1.1 search 엔드포인트를 사용하고 있었다면 X API v2 버전으로 마이그레이션하더라도 동일한 인증 방식을 계속 사용할 수 있습니다.
사용 중인 인증 라이브러리/패키지에 따라 다르지만, App-Only 인증이 가장 쉽게 시작할 수 있는 방법인 경우가 많으며, 간단한 요청 헤더 설정만으로 사용할 수 있습니다. App 액세스 토큰을 생성하는 방법은 이 OAuth 2.0 App-Only 가이드를 참고하세요.
X API v2 엔드포인트를 사용해 비공개 또는 광고 지표를 조회하려면 OAuth 1.0a User Context를 사용해야 하며, 지표를 조회하려는 게시물을 작성한 사용자에 해당하는 사용자 액세스 토큰을 전달해야 합니다.
게시물 편집 기록 및 메타데이터 지원
두 버전 모두 편집 이력을 설명하는 메타데이터를 제공합니다. 자세한 내용은 search API 참조 문서와 게시물 편집 기본 사항 페이지를 참고하세요.
엔드포인트 URL
-
Standard v1.1 엔드포인트:
-
X API v2 엔드포인트:
App 및 Project 요구 사항
X API v2 엔드포인트는 요청을 인증할 때 developer App과 연결된 Project의 자격 증명을 사용해야 합니다. 모든 X API v1.1 엔드포인트는 Project와 연결되지 않은 App 또는 Project와 연결된 App의 자격 증명을 모두 사용할 수 있습니다.
응답 데이터 형식
Standard v1.1과 X API v2 엔드포인트 버전 간의 가장 큰 차이점 중 하나는 페이로드에서 어떤 필드를 반환할지 선택하는 방식입니다.
Standard 엔드포인트의 경우, 기본적으로 많은 응답 필드를 받게 되며, 이후 파라미터를 사용해 페이로드에 어떤 필드 또는 필드 집합을 반환할지 지정할 수 있습니다.
X API v2 버전은 기본적으로 Post id와 text 필드만 제공합니다. 추가 필드나 객체를 요청하려면 fields 및 expansions 파라미터를 사용해야 합니다. 이러한 엔드포인트에서 요청한 모든 게시물 필드는 기본 Post 객체에 포함되어 반환됩니다. 확장된 user, media, poll, place 객체 및 필드는 응답 내 includes 객체에 포함되어 반환됩니다. 그런 다음 Post와 확장 객체 양쪽에 있는 ID를 매칭하여, 확장된 객체를 Post 객체와 다시 연결할 수 있습니다.
이러한 새 파라미터에 대해서는 각 가이드에서 더 자세히 읽어 보시거나, fields 및 expansions 사용 방법에 대한 가이드를 참고하시기를 권장합니다.
또한 Standard v1.1 필드를 v2의 새로운 필드로 매핑하는 데 도움이 되는 데이터 형식 마이그레이션 가이드도 제공합니다. 이 가이드는 특정 필드를 반환하기 위해 v2 요청에 함께 전달해야 하는 expansions 및 fields 파라미터를 구체적으로 안내합니다.
특정 필드를 요청하는 방식의 변경 외에도, X API v2는 API가 반환하는 객체(예: Post 및 user 객체)에 대해 새로운 JSON 디자인을 도입합니다.
- JSON 루트 레벨에서, Standard 엔드포인트는 Post 객체를 statuses 배열로 반환하는 반면, X API v2는 data 배열로 반환합니다.
- Retweeted 및 Quoted “statuses”를 참조하는 대신, X API v2 JSON은 Retweeted 및 Quoted Tweets를 참조합니다. contributors 및 user.translator_type 같은 많은 레거시 및 사용 중단 필드는 제거되고 있습니다.
- Post 객체의 favorites와 user 객체의 favourites를 모두 사용하는 대신, X API v2는 like라는 용어만 사용합니다.
- X는 값이 없는 JSON 값(예: null)은 페이로드에 기록하지 않는 규칙을 채택하고 있습니다. Post 및 user 속성은 null이 아닌 값을 가진 경우에만 포함됩니다.
또한 Post 객체에 다음을 포함한 새로운 필드 집합을 도입했습니다:
다음 Standard v1.1 요청 파라미터에는 X API v2에서의 대응 항목이 있습니다:
| Standard search v1.1 | Search Posts v2 |
|---|
| q | query |
| start_time (YYYY-MM-DDTHH:mm:ssZ) |
| until (YYYY-MM-DD) | end_time (YYYY-MM-DDTHH:mm:ssZ) |
| since_id | since_id |
| max_id | until_id |
| count | max_results |
| Response provides search_metadata.next_results | next_token |
| Standard v1.1 parameter | Details |
|---|
| geocode | Search Posts는 위치 기반 쿼리를 위한 geo 연산자를 지원합니다. |
| locale | Standard search에서는 쿼리의 언어를 지정하기 위해 사용되었으나, 완전히 구현되지는 않았습니다. |
| lang | Search Posts 엔드포인트는 관심 있는 언어와 일치시키기 위한 lang 쿼리 연산자를 제공합니다. |
| include_entities | 게시물 엔티티는 항상 포함됩니다. |
| result_type | Search Posts 엔드포인트는 참여 수준과 관계없이 일치하는 모든 포스트를 반환합니다. |
| extended | X API v2는 최대 280자까지의 게시물을 기본으로 지원하도록 처음부터 설계되었습니다. v2에는 ‘extended’ 게시물이라는 개념이 없습니다. |
- Conversation IDs - X에서 대화가 전개됨에 따라, 대화에 포함된 게시물을 표시하기 위한 conversation ID가 제공됩니다. 대화에 속한 모든 게시물의 conversation_id 값은 대화를 시작한 게시물의 Post ID로 설정됩니다.
- X Annotations 는 게시물에 대한 문맥 정보를 제공하며, 엔티티 및 컨텍스트 주석을 포함합니다. 엔티티는 사람, 장소, 상품, 조직으로 구성됩니다. 컨텍스트는 노출된 엔티티가 속한 도메인 또는 주제입니다. 예를 들어, 게시물에 언급된 사람은 운동선수, 배우, 정치인인지 여부를 나타내는 컨텍스트를 가질 수 있습니다.
-
context: 관심 있는 컨텍스트로 주석이 달린 포스트와 일치합니다.
-
entity: 관심 있는 엔티티로 주석이 달린 포스트와 일치합니다.
검색 쿼리를 구성할 때 기본적인 구성 요소는 OR 및 AND 논리 그룹을 사용하는 것입니다. 표준 검색 API는 AND보다 OR을 먼저 적용하는 반면, Search Posts 엔드포인트(프리미엄 및 엔터프라이즈 버전 포함)는 OR보다 AND를 먼저 적용합니다. 이러한 차이는 두 API 간에 쿼리를 변환할 때 매우 중요합니다.
예를 들어 표준 검색에서 ‘storm’ 키워드를 포함하면서 ‘colorado’라는 단어 또는 #COwx 해시태그가 언급된 포스트를 찾고 싶다면, 다음과 같은 검색 쿼리를 사용할 수 있습니다:
storm #COwx OR colorado
Search Posts의 연산자 우선순위에서는 AND가 OR보다 먼저 적용됩니다. 따라서 위의 쿼리는 다음과 같습니다:
(storm #COwx) OR colorado
그러나 위 규칙은 포스트에 ‘storm’이나 #COwx 해시태그가 언급되었는지와 관계없이 ‘Colorado’가 언급된 모든 포스트와 일치하게 됩니다. 또한 ‘storm’ 키워드와 #COwx 해시태그가 모두 언급된 포스트도 일치합니다.
쿼리가 원래 의도한 대로 동작하도록 하려면 OR 절을 함께 묶어야 합니다. 원래 표준 쿼리를 Search Posts에 맞게 변환하면 다음과 같습니다:
storm (#COwx OR colorado)
이 두 규칙은 매우 다른 매칭 동작을 보입니다. 2019년 10월 한 달 동안, 원래 규칙은 1,175,000개 이상의 포스트와 일치하는 반면, 올바르게 변환된 규칙은 약 5,600개의 포스트와만 일치합니다. AND와 OR의 차이를 반드시 유의하고, 필요한 곳에는 괄호를 사용하십시오.
다음 섹션에서는 표준 v1.1 엔드포인트와 이에 상응하는 v2 엔드포인트에 대한 cURL 요청을 보여줍니다.
요청은 OAuth 2.0 App-Only를 사용해 수행됩니다. 다음 cURL 요청을 실행하려면 Authorization 헤더의 ACCESS_TOKEN을 앱 액세스 토큰으로 교체해야 합니다. v2 엔드포인트의 경우, 앱 액세스 토큰은 Project 내의 developer App에 속해야 합니다.
v1.1 엔드포인트에서 반환되는 응답 페이로드는 v2 엔드포인트에서 반환되는 응답 페이로드와 다릅니다. v2에서는 기본 필드뿐만 아니라 fields 및 expansions 매개변수로 요청한 기타 필드도 응답에 포함됩니다. 이러한 매개변수를 사용해 반환받을 필드 집합을 다르게 지정할 수 있습니다.
표준 v1.1 GET search/tweets → v2 GET tweets/search/recent
curl --request GET \
--url 'https://api.x.com/1.1/search/tweets.json?q=from%3AXDevelopers%20-is%3Aretweet&count=100' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
