메인 콘텐츠로 건너뛰기
expansions를 사용하면 개발자는 페이로드에서 참조된 객체를 확장할 수 있습니다. 확장 가능한 객체는 ID로 참조됩니다. 예를 들어, 게시물 조회 페이로드에 반환되는 referenced_tweets.id 및 author_id 필드는 완전한 객체로 확장될 수 있습니다. 특정 게시물을 작성한 사용자와 관련된 필드, 또는 해당 게시물에 포함된 미디어, 설문조사, 장소와 관련된 필드를 요청하려면 요청에 관련 expansion 쿼리 매개변수를 전달해야 하며, 그러면 응답에서 해당 데이터를 받을 수 있습니다. 현재 게시물, 사용자, 목록, Space, 다이렉트 메시지 이벤트 객체를 반환하는 v2 엔드포인트는 모두 expansions를 지원합니다(아래 예시 참조). 요청에 expansion을 포함하면 동일한 응답 내에 해당 확장된 객체의 기본 필드가 함께 포함됩니다. 이는 별도의 요청 없이 하나의 응답에서 추가 데이터를 반환하는 데 도움이 됩니다. 확장된 객체와 관련된 추가 필드를 요청하려면, 해당 확장 객체와 연관된 필드 매개변수와 함께 응답에서 받고자 하는 필드의 쉼표로 구분된 목록을 포함할 수 있습니다. 참고로 필드는 쿼리에서 요청한 순서와 동일한 순서로 항상 반환되지 않을 수 있습니다. 아래 게시물 페이로드에는 확장 가능한 보조 객체에 대한 참조 ID가 포함되어 있습니다. 여기에는 게시물을 작성한 사용자의 author_id, 참조된 게시물의 id, 미디어 첨부에 대한 media_key가 포함됩니다. 
{
    "data": {
        "attachments": {
            "media_keys": ["16_1211797899316740096"]
        },
        "author_id": "2244994945",
        "id": "1212092628029698048",
        "referenced_tweets": [
            {
                "type": "replied_to",
                "id": "1212092627178287104"
            }
        ],
        "text": "우리는 API의 최고의 미래 버전이 여러분과 함께 만들어질 것이라고 믿습니다. X 플랫폼을 기반으로 개발하시는 모든 분들과 함께하는 또 다른 멋진 한 해를 기원합니다. 새해에도 여러분과 계속 협력하기를 기대합니다. https://t.co/yvxdK6aOo2"
    }
}

​
게시물 페이로드에서 사용 가능한 expansions

ExpansionDescription
author_id해당 게시물의 작성자를 나타내는 사용자 객체를 반환합니다
referenced_tweets.id이 게시물이 참조하는 게시물 객체를 반환합니다(리포스트, 인용, 또는 답글)
edit_history_tweet_ids게시물의 편집 이력에 포함된 게시물 객체를 반환합니다
in_reply_to_user_id이 게시물이 답글인 대상 게시물의 작성자를 나타내는 사용자 객체를 반환합니다
attachments.media_keys게시물에 포함된 이미지, 동영상, GIF를 나타내는 미디어 객체를 반환합니다
attachments.poll_ids게시물에 포함된 투표의 메타데이터를 담은 투표 객체를 반환합니다
geo.place_id게시물에 태그된 위치의 메타데이터를 담은 장소 객체를 반환합니다
entities.mentions.username게시물에서 멘션된 사용자를 나타내는 사용자 객체를 반환합니다
referenced_tweets.id.author_id참조된 게시물의 작성자를 나타내는 사용자 객체를 반환합니다

​
사용자 페이로드에서 사용 가능한 확장

확장설명
pinned_tweet_id사용자의 프로필 상단에 고정된 게시물을 나타내는 게시물 객체를 반환합니다

​
다이렉트 메시지 이벤트 페이로드에서 사용할 수 있는 expansions

ExpansionDescription
attachments.media_keys다이렉트 메시지에 첨부된 Media 객체를 반환합니다
referenced_tweets.id다이렉트 메시지에서 참조된 게시물(Post) 객체를 반환합니다
sender_id다이렉트 메시지 작성자이자 대화에 참여자를 초대한 사용자를 나타내는 User 객체를 반환합니다
participant_ids대화에 참여했거나 떠난 참여자를 나타내는 User 객체를 반환합니다

​
Spaces 페이로드에서 사용 가능한 expansions

Expansion설명
invited_user_ids초대된 계정을 나타내는 User 객체를 반환합니다
speaker_idsSpace에서 발언한 계정을 나타내는 User 객체를 반환합니다
creator_idSpace를 생성한 계정을 나타내는 User 객체를 반환합니다
host_ids호스트로 지정된 계정을 나타내는 User 객체를 반환합니다
topics_ids생성자가 설정한 토픽 설명을 반환합니다

​
목록 페이로드에서 사용 가능한 확장

확장 항목설명
owner_id목록을 생성하고 관리하는 계정을 나타내는 User 객체를 반환합니다

​
미디어 객체 확장

다음 요청에서는 기본 게시물 필드와 함께 포함되도록 geo.place_id 확장을 요청합니다. 샘플 요청 
{`curl 'https://api.x.com/2/tweets/:ID?expansions=geo.place_id' --header 'Authorization: Bearer $ACCESS_TOKEN'`}
예시 응답 
{`{
  "data": {
      "geo": {
          "place_id": "01a9a39529b27f36"
      },
      "id": "ID",
      "text": "Test"
  },
  "includes": {
      "places": [
          {
              "full_name": "Manhattan, NY",
              "id": "01a9a39529b27f36"
          }
      ]
  }
}`}

​
투표 객체 확장

다음 요청에서는 기본 게시물 필드와 함께 포함되도록 attachments.poll_ids expansions 파라미터를 요청합니다: 샘플 요청 샘플 응답 
{`{
  "data": {
      "attachments": {
          "poll_ids": ["1199786642468413448"]
      },
      "id": "1199786642791452673",
      "text": "C#"
  },
  "includes": {
      "polls": [
          {
              "id": "1199786642468413448",
              "options": [
                  {
                      "position": 1,
                      "label": ""C Sharp"",
                      "votes": 795
                  },
                  {
                      "position": 2,
                      "label": ""C Hashtag"",
                      "votes": 156
                  }
              ]
          }
      ]
  }
}`}

​
Place 객체 확장하기

다음 요청에서는 기본 게시물 필드와 함께 포함되도록 geo.place_id expansions를 요청합니다: 예시 요청 예시 응답 
{`{
  "data": {
      "geo": {
          "place_id": "01a9a39529b27f36"
      },
      "id": "ID",
      "text": "Test"
  },
  "includes": {
      "places": [
          {
              "full_name": "Manhattan, NY",
              "id": "01a9a39529b27f36"
          }
      ]
  }
}`}