데이터 인리치먼트: 엔터프라이즈

소개

Enterprise Enterprise 보강 정보는 일부 데이터 API의 응답 페이로드에 추가로 포함되는 메타데이터입니다. 유료 구독 플랜에서만 제공됩니다. 아래 표는 각 보강 정보에 대한 간략한 설명을 제공합니다.

보강 정보:	설명:
Expanded and Enhanced URLs	게시물 본문에 포함된 단축 URL(예: bitly)을 자동으로 원래 URL로 확장하고, 목적지 페이지의 HTML 제목(title) 및 설명(description) 메타데이터를 제공합니다.
Matching rules object	수신된 포스트에 어떤 규칙이 매칭되었는지 나타냅니다. 이 객체는 응답 객체에서 규칙 태그와 규칙 ID를 반환합니다.
Poll metadata	게시물에 설문이 존재하는지 여부를 기록하고, 설문 선택지 리스트를 포함하며, 설문의 기간과 만료 시간을 모두 포함합니다.
Profile geo	가능한 경우 [경도, 위도] 좌표를 포함한 파생 사용자 프로필 위치 데이터와 관련 장소 메타데이터를 제공합니다.

확장 및 향상된 URL

확장 및 향상된 URL 인리치먼트 기능은 게시물 본문에 포함된 단축 URL을 자동으로 확장하고, 확장된 최종 URL을 페이로드 내 메타데이터로 포함합니다. 또한 이 인리치먼트는 대상 페이지의 title 및 description 에서 가져온 HTML 페이지 메타데이터도 제공합니다. 중요 사항:

단축 링크를 실제 최종 URL로 해석하기 위해, 시스템은 제공된 URL로 HTTP HEAD 요청을 보내고 최종 URL에 도달할 때까지 모든 리디렉션을 따라갑니다. 이렇게 얻어진 최종 URL만(페이지의 실제 콘텐츠는 아님)이 응답 페이로드에 포함됩니다.
URL 인리치먼트는 실시간 스트림에 약 5~10초의 지연 시간을 유발합니다.
Full Archive Search API로 수행된 요청의 경우, 확장된 URL 인리치먼트 데이터는 최대 13개월 이내에 게시된 포스트에 대해서만 제공됩니다.
URL 인리치먼트는 게시물에 포함된 게시물 링크(인용 Tweet 포함), Moments 링크, 프로필 링크에는 제공되지 않습니다.

게시물 페이로드

확장 및 향상된 URL 보강 기능은 게시물 페이로드의 entities 객체 안, 구체적으로는 entitites.urls.unwound 객체에 포함되어 있습니다. 여기에는 다음과 같은 메타데이터 필드가 제공됩니다:

확장된 URL - unwound.url
확장된 HTTP 상태 - unwound.status
확장된 URL HTML 제목 - 300자 제한 - unwound.title
확장된 URL HTML 설명 - 1000자 제한 - unwound.description

다음은 URL 보강 기능이 포함된 entities 객체의 예시입니다:

"entities": {
    "hashtags": [

    ],
    "urls": [
      {
        "url": "https:\/\/t.co\/HkTkwFq8UT",
        "expanded_url": "http:\/\/bit.ly\/2wYTb9y",
        "display_url": "bit.ly\/2wYTb9y",
        "unwound": {
          "url": "https:\/\/www.forbes.com\/sites\/laurencebradford\/2016\/12\/08\/11-websites-to-learn-to-code-for-free-in-2017\/",
          "status": 200,
          "title": "11 Websites To Learn To Code For Free In 2017",
          "description": "It\u2019s totally possible to learn to code for free...but what are the best resources to achieve that? Here are 11 websites where you can get started."
        },
        "indices": [
          10,
          33
        ]
      }
    ],
    "user_mentions": [

    ],
    "symbols": [

    ]
  },

**다음은 추가 정보가 보강되지 않은 게시물 링크를 포함하는 entities 객체의 예시입니다. **

"entities": {
  "urls": [{
    "url": "https://t.co/SywNbZdDmb",
    "expanded_url": "https://x.com/XDevelopers/status/1050118621198921728",
    "display_url": "x.com/XDevelopers/s…",
     "indices": [
        142,
        165
     ]
   }
  ]
}

필터링 연산자

다음 연산자는 URL 메타데이터의 관련 필드에서 필터링을 수행하고 토큰 단위로 일치 여부를 검사합니다: url:

예: “url:tennis”
단어 tennis를 포함하는 모든 Expanded URL에서 토큰 단위로 일치 검색을 수행합니다.
“url:npr.org”과 같이 사용하여 특정 웹사이트의 링크를 포함하거나 제외하는 필터로도 사용할 수 있습니다.

url_title:

예: “url_title:tennis”
단어 tennis를 포함하는 모든 Expanded URL의 HTML title에서 토큰 단위로 일치 검색을 수행합니다.
payload에 포함된 HTML title 데이터에서 일치 항목을 찾으며, 이 데이터는 최대 300자로 제한됩니다.

url_description:

예: “url_description:tennis”
단어 tennis를 포함하는 모든 Expanded URL의 HTML description에서 토큰 단위로 일치 검색을 수행합니다.
payload에 포함된 HTML description에서 일치 항목을 찾으며, 이 데이터는 최대 1000자로 제한됩니다.

HTTP Status Codes

확장된 URL 엔리치먼트는 풀려고 시도하는 최종 URL에 대한 HTTP 상태 코드도 제공합니다. 일반적인 경우에는 200 값이 됩니다. 기타 400번대 값은 URL을 해석하는 데 문제가 있음을 나타냅니다. URL을 풀려고 시도할 때는 다양한 상태 코드가 반환될 수 있습니다. URL을 푸는 과정에서 리디렉션이 발생하면, 다음 중 하나가 발생할 때까지 계속 따라갑니다.

200번대 코드에 도달한 경우(성공)
리디렉션이 아닌 코드에 도달한 경우(실패)
최종 URL을 합리적인 시간 안에 해석할 수 없어 타임아웃이 발생한 경우(408 - timeout 반환)
어떤 종류의 예외가 발생한 경우

예외가 발생한 경우, 다음과 같이 사유와 반환 상태 코드 간 매핑을 사용합니다.

Reason	Status Code Returned
SSL Exceptions	403 (Forbidden, 금지됨)
Unwinding not allowed by URL	405
Socket Timeout	408 (Timeout, 시간 초과)
Unknown Host Exception	404 (Not Found, 찾을 수 없음)
Unsupported Operation	404 (Not Found, 찾을 수 없음)
Connect Exception	404 (Not Found, 찾을 수 없음)
Illegal Argument	400 (Bad Request, 잘못된 요청)
Everything else	400 (Bad Request, 잘못된 요청)

매칭 규칙

matching rules enrichment는 수신된 게시물과 일치한 규칙(들)이 무엇인지 나타내는 메타데이터 객체입니다. 주로 PowerTrack 스트림에서 사용됩니다. 매칭은 규칙에 포함된 용어(term)에 대한 정확 일치 방식으로 수행되며, 구두점이 있는 경우와 없는 경우 모두 activity의 콘텐츠를 스캔합니다. 매칭은 대소문자를 구분하지 않습니다. 콘텐츠에 규칙에 정의된 모든 용어가 포함되어 있는 것으로 확인되면, 일치를 발생시킨 규칙을 나타내는 루트 수준의 matching_rules 객체가 존재하게 됩니다. PowerTrack PowerTrack(실시간, Replay, Historical)을 통해 전달되는 게시물에는 다음과 같이 matching_rules 객체가 포함됩니다:

"matching_rules": [{
        "tag": null,
        "id": 907728589029646336,
        "id_str": "907728589029646336"
    }]

PowerTrack에서 matching_rules 객체는 주어진 결과에 매칭된 모든 규칙을 반영합니다. 즉, 하나의 게시물에 둘 이상의 규칙이 매칭되더라도 그 게시물은 한 번만 전달되지만, matching_rules 요소에는 매칭된 모든 규칙이 포함됩니다.

투표 메타데이터

투표 메타데이터는 모든 제품(Realtime 및 Historical API)에서 강화된 네이티브 형식의 페이로드로 제공되는 무료 보강 정보입니다. 이 메타데이터는 게시물에 투표가 포함되어 있음을 나타내고, 투표 선택지 목록을 포함하며, 투표 진행 기간과 만료 시각을 모두 포함합니다. 이 보강 정보를 사용하면 투표의 존재를 쉽게 파악할 수 있고, 표시용 투표 게시물을 올바르게 렌더링할 수 있습니다.

중요한 사항:

모든 엔터프라이즈 API(PowerTrack, Replay, Search, Historical PowerTrack)에서 사용 가능합니다.
- 참고: Replay 및 Historical PowerTrack의 경우, 이 메타데이터는 02/22/17에 처음 제공되었습니다.
투표 정보나 투표 결과는 포함하지 않습니다.
현재 필터/연산자를 지원하지 않습니다.
enriched native format에서만 제공됩니다.
- enriched native format은 Console을 통해 언제든지 변경할 수 있는 사용자 제어 설정입니다: Select a Product (PowerTrack, Replay, Search) > Settings 탭 > Output Format (Leave data in its original format)

게시물 페이로드

투표 게시물에는 페이로드의 “entities.polls” 객체에 다음 메타데이터가 포함됩니다:

위치(1–4)와 선택지 텍스트를 포함하는 최대 네 개의 선택지가 들어 있는 “options” 배열
투표 종료 일시
투표 지속 시간

자세한 내용은 아래의 샘플 페이로드를 참고하세요.

샘플 페이로드

아래는 추가된 투표 메타데이터가 표시된 확장된 네이티브 형식 페이로드의 일부입니다.

"entities":{
          "hashtags":[],
          "urls":[],
          "user_mentions":[],
          "symbols":[],
          "polls":[
             {
                "options":[
                   {
                      "position":1,
                      "text":"The better answer"
                   },
                   {
                      "position":2,
                      "text":"The best answer"
                   }
                ],
                "end_datetime":"Sat Feb 04 15:33:11 +0000 2017",
                "duration_minutes":1440
             }
          ]
       },

프로필 위치

소개

많은 X 사용자 프로필에는 사용자가 제공한 공개 위치 정보가 포함되어 있습니다. 이 데이터는 user.location 필드에서 일반 문자열 값으로 반환됩니다(User object data dictionary 참고). Profile Geo 보강은 가능한 경우 위치 문자열을 지오코딩하고 정규화하여 user.location 값과 관련된 구조화된 지오데이터를 추가합니다. 위도/경도 좌표와 관련 장소 메타데이터는 둘 다 엔터프라이즈 API 제품에서 게시물 페이로드의 일부로 포함된 경우에만 user.derived.locations에 추가됩니다. 이 데이터는 향상된 네이티브 포맷을 사용할 때 제공되며, PowerTrack 규칙을 조합해 필터링할 수 있습니다.

참고: Profile Geo 보강을 생성하는 데 사용되는 일부 보조 지리 데이터는 GeoNames.org에서 제공되며, X는 이를 Creative Commons Attribution 3.0 License에 따라 사용합니다.

Profile Geo 데이터는 X의 PowerTrack, Replay, Volume Stream, Search, Historical PowerTrack API에 포함됩니다.

프로필 Geo 데이터

Enriched native field name	Example value	Description
user.derived.locations.country	United States	게시물을 생성한 사용자의 국가입니다.
user.derived.locations.country_code	US	게시물을 생성한 사용자의 국가에 해당하는 두 글자의 ISO-3166 국가 코드입니다.
user.derived.locations.locality	Birmingham	게시물을 생성한 사용자의 지역(일반적으로 도시)입니다.
user.derived.locations.region	Alabama	게시물을 생성한 사용자의 지역(일반적으로 주/도)입니다.
user.derived.locations.sub_region	Jefferson County	게시물을 생성한 사용자의 하위 지역(일반적으로 카운티)입니다.
user.derived.locations.full_name	Birmingham, Alabama, United States	게시물을 생성한 사용자의 위치 전체 이름(하위 지역 제외)입니다.
User.derived.locations.geo	아래 참조	게시물을 생성한 사용자의 가장 세밀한 위치에 해당하는 좌표(위도/경도 값)를 포함하는 배열입니다.

Historical PowerTrack, Search 및 PowerTrack API에서는 프로필 Geo 데이터를 기반으로 한 필터링을 지원합니다. 프로필 Geo 데이터를 기준으로 필터링할 때 사용할 수 있는 연산자에 대한 자세한 내용은 해당 제품 문서를 참조하십시오.

예시 페이로드

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "United States",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "Alabama",
                    "sub_region": "Jefferson County",
                    "full_name": "Birmingham, Alabama, United States",
                    "geo": {
                        "coordinates": \[
                            -86.80249,
                            33.52066
                        \],
                        "type": "point"
                    }
                }
            \]
        }
    }
}

제한 사항

Profile Geo 보강 기능은 프로필 위치 문자열에 설명된 지리적 장소 중에서 최적의 후보를 파악하려고 시도합니다. 여러 개의 유사한 이름을 가진 장소가 있거나 이름이 모호한 등 여러 요인으로 인해 결과가 모든 경우에 정확하지 않을 수 있습니다.
사용자의 프로필 위치 필드(actor.location)에 값이 제공되지 않은 경우 분류를 시도하지 않습니다.
정밀도 수준(Precision Level): Profile Geo 보강 기능으로 국가 또는 지역 수준에서만 신뢰할 수 있는 결과를 얻을 수 있는 경우, subRegion 및 locality와 같은 더 낮은 수준의 지리 정보는 페이로드에서 생략됩니다.
Profile Geo 보강 기능은 보강 결과의 정밀도 수준에 해당하는 위도/경도 좌표(단일 포인트)를 제공합니다. 이 좌표는 보강된 위치 결과의 지리적 중심을 나타냅니다. 예를 들어 정밀도 수준이 국가 레벨인 경우, 해당 좌표는 그 국가의 지리적 중심으로 설정됩니다.
주소 속성(locality/region/country/country code)에 대해 제공되는 PowerTrack 연산자는 다양한 규칙 조합이 가능하도록 의도적으로 매우 세분화되어 있습니다. 이름을 공유하는 특정 위치를 타겟팅하려는 경우 주소 규칙을 조합하는 것을 고려하세요. 예를 들어, 다음과 같이 하면 “San Francisco, Philippines”에 대한 매칭을 피할 수 있습니다: profile_locality:“San Francisco” profile_region:California 개별 Profile Geo 필드를 타겟팅하는 규칙을 작성할 때, 세분화 수준이 높아질수록 볼 수 있는 결과가 제한된다는 점을 염두에 두세요. 어떤 경우에는 특정 도시의 데이터를 보려 할 때, 해당 도시와 상당 부분이 겹치는 지역이 있는 경우 지역 규칙에만 의존하고자 할 수 있습니다. 예를 들어, 스위스 취리히 시의 경우 profile_region:“Zurich” 규칙을 사용하면 주변 지역을 포함해 효과적으로 타겟팅할 수 있습니다.
네이티브 Geo 게시물과 함께 사용: Profile Geo 보강 기능은 페이로드에 포함된 native geo 값과는 다른, 게시물에 대한 대체 유형의 지리 정보를 제공합니다. 이 두 가지 유형의 지리 정보는 (사용 가능한 지리 데이터에 기반해) 특정 영역과 관련된 가능한 모든 게시물을 포착하기 위해 함께 결합해 사용할 수 있지만, 개념적으로 동일한 것은 아닙니다.

개요

포스트

사용자

다이렉트 메시지

좋아요

리스트

Spaces

커뮤니티

커뮤니티 노트

트렌드

뉴스

미디어

X 활동

사용량

스트림 연결

규정 준수

Enterprise v2

좋아요 스트림

GNIP 2.0

데이터 인리치먼트: 엔터프라이즈

소개

확장 및 향상된 URL

게시물 페이로드

필터링 연산자

HTTP Status Codes

매칭 규칙

투표 메타데이터

중요한 사항:

게시물 페이로드

샘플 페이로드

프로필 위치

소개

프로필 Geo 데이터

예시 페이로드

제한 사항

개요

포스트

사용자

다이렉트 메시지

좋아요

리스트

Spaces

커뮤니티

커뮤니티 노트

트렌드

뉴스

미디어

X 활동

사용량

스트림 연결

규정 준수

Enterprise v2

좋아요 스트림

GNIP 2.0

​소개

​확장 및 향상된 URL

​게시물 페이로드

​필터링 연산자

​HTTP Status Codes

​매칭 규칙

​투표 메타데이터

중요한 사항:

​게시물 페이로드

​샘플 페이로드

​프로필 위치

​소개

​프로필 Geo 데이터

​예시 페이로드

​제한 사항

소개

확장 및 향상된 URL

게시물 페이로드

필터링 연산자

HTTP Status Codes

매칭 규칙

투표 메타데이터

게시물 페이로드

샘플 페이로드

프로필 위치

소개

프로필 Geo 데이터

예시 페이로드

제한 사항