Expansion

Expansion을 사용하면 단일 API 응답에 관련 객체를 포함할 수 있습니다. 여러 요청을 하지 않고 한 번의 호출로 게시물과 그 작성자, 미디어 또는 참조된 게시물을 가져옵니다.

Expansion 작동 방식

expansion을 요청하면 API는 응답의 includes 섹션에 전체 객체를 포함합니다:

curl "https://api.x.com/2/tweets/1234567890?expansions=author_id" \
  -H "Authorization: Bearer $TOKEN"

응답:

Example response

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "author_id": "2244994945"
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers"
    }]
  }
}

data의 author_id가 includes의 user 객체에 연결됩니다.

Post expansion

Expansion	반환 값	사용 사례
`author_id`	User 객체	게시물 작성자 세부 정보 가져오기
`referenced_tweets.id`	Post 객체	인용/답글 대상 게시물 가져오기
`referenced_tweets.id.author_id`	User 객체	참조된 게시물의 작성자 가져오기
`in_reply_to_user_id`	User 객체	답글이 달린 사용자 가져오기
`attachments.media_keys`	Media 객체	이미지, 동영상, GIF 가져오기
`attachments.poll_ids`	Poll 객체	투표 옵션과 표수 가져오기
`geo.place_id`	Place 객체	위치 세부 정보 가져오기
`entities.mentions.username`	User 객체	언급된 사용자 가져오기
`edit_history_tweet_ids`	Post 객체	편집된 게시물의 이전 버전 가져오기

User expansion

Expansion	반환 값	사용 사례
`pinned_tweet_id`	Post 객체	사용자의 고정 게시물 가져오기

Space expansion

Expansion	반환 값	사용 사례
`creator_id`	User 객체	Space 생성자 가져오기
`host_ids`	User 객체	Space 호스트 가져오기
`speaker_ids`	User 객체	Space 발언자 가져오기
`invited_user_ids`	User 객체	초대된 사용자 가져오기

DM expansion

Expansion	반환 값	사용 사례
`sender_id`	User 객체	메시지 발신자 가져오기
`participant_ids`	User 객체	대화 참가자 가져오기
`attachments.media_keys`	Media 객체	첨부된 미디어 가져오기
`referenced_tweets.id`	Post 객체	참조된 게시물 가져오기

List expansion

Expansion	반환 값	사용 사례
`owner_id`	User 객체	리스트 소유자 가져오기

Field와 결합

Expansion은 각 객체의 기본 field를 반환합니다. 추가 field를 가져오려면 expansion을 field 파라미터와 결합하세요:

curl "https://api.x.com/2/tweets/1234567890?\
expansions=author_id,attachments.media_keys&\
user.fields=description,public_metrics&\
media.fields=url,alt_text" \
  -H "Authorization: Bearer $TOKEN"

응답:

Example response

{
  "data": {
    "id": "1234567890",
    "text": "Check out this image!",
    "author_id": "2244994945",
    "attachments": {
      "media_keys": ["3_1234567890"]
    }
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers",
      "description": "The voice of the X Developer Platform",
      "public_metrics": {
        "followers_count": 570842
      }
    }],
    "media": [{
      "media_key": "3_1234567890",
      "type": "photo",
      "url": "https://pbs.twimg.com/media/example.jpg",
      "alt_text": "Example image"
    }]
  }
}

여러 expansion

쉼표로 구분된 목록으로 여러 expansion을 요청합니다:

expansions=author_id,referenced_tweets.id,attachments.media_keys

일반적인 패턴

전체 게시물 컨텍스트
대화 스레드
고정 게시물이 있는 사용자

작성자, 미디어, 참조된 게시물이 포함된 게시물 가져오기:

expansions=author_id,attachments.media_keys,referenced_tweets.id
tweet.fields=created_at,public_metrics,conversation_id
user.fields=username,name,profile_image_url
media.fields=url,preview_image_url,type

답글과 그 작성자를 함께 가져오기:

expansions=author_id,in_reply_to_user_id,referenced_tweets.id
tweet.fields=conversation_id,in_reply_to_user_id,created_at
user.fields=username,name

사용자 프로필과 고정 게시물을 함께 가져오기:

expansions=pinned_tweet_id
user.fields=description,public_metrics,verified
tweet.fields=created_at,public_metrics

data와 includes 연결

includes의 객체는 위치 정보를 포함하지 않습니다. ID를 사용하여 연결하세요:

# Python example
response = api_call()
post = response["data"]
users = {u["id"]: u for u in response["includes"]["users"]}

# Get the author
author = users.get(post["author_id"])
print(f"{author['name']} said: {post['text']}")

// JavaScript example
const { data: post, includes } = response;
const users = Object.fromEntries(
  includes.users.map(u => [u.id, u])
);

const author = users[post.author_id];
console.log(`${author.name} said: ${post.text}`);

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Expansion

Expansion 작동 방식

Post expansion

User expansion

Space expansion

DM expansion

List expansion

Field와 결합

여러 expansion

일반적인 패턴

data와 includes 연결

다음 단계

Fields

Data Dictionary

​Expansion 작동 방식

​Post expansion

​User expansion

​Space expansion

​DM expansion

​List expansion

​Field와 결합

​여러 expansion

​일반적인 패턴

​data와 includes 연결

​다음 단계

Fields

Data Dictionary

Expansion 작동 방식

Post expansion

User expansion

Space expansion

DM expansion

List expansion

Field와 결합

여러 expansion

일반적인 패턴

data와 includes 연결

다음 단계