Introduction

Interested in learning more about how the enterprise data formats map to the X API v2 format?

Check out our comparison guides:

Introduction

Enterprise

Posts are the basic atomic building block of all things X. All X APIs that return Posts provide that data encoded using JavaScript Object Notation (JSON). JSON is based on key-value pairs, with named attributes and associated values. Post objects retrieved from the API include a X User's "status update" but Retweets, replies, and quote Tweets are all also Post objects.  If a Post is related to another Post, as a Retweet, reply or quote Tweet, each will be identified or embedded into the Post object.  Even the simplest Post in the native X data format, will have nested JSON objects to represent the other attributes of a Post, such as the author, mentioned users, tagged place location, hashtags, cashtag symbols, media or URL links.  When working with X data, this is an important concept to understand. The format of the Post data you will receive from the X API depends on the type of Post received, the X API you are using, and the format settings.

Enterprise endpoints that return Post objects have been updated to provide the metadata needed to understand the Post's edit history. Learn more about these metadata on the "Edit Posts" fundamentals page.

In native X format, the JSON payload will include of ‘root-level’ attributes, and nested JSON objects (which are represented here with the {} notation):

      {
	"created_at": "Fri Feb 14 19:00:55 +0000 2020",
	"id_str": "1228393702244134912",
	"text": "What did the developer write in their Valentine’s card?\n  \nwhile(true) {\n    I = Love(You);  \n}",
	"entities": {
		"hashtags": [],
		"symbols": [],
		"user_mentions": [],
		"urls": []
	},
	"user": {
		"entities": {
			"url": {}
		}
	},
	"place": {}
}

Available data formats

Please note: It is highly recommended to use the Enriched Native format for enterprise data APIs. 

  • The Enriched Native format includes all new metadata since 2017, such as poll metadata, and additional metrics such as reply_count and quote_count.

  • Activity Streams format has not been updated with new metadata or enrichments since the character update in 2017.

Enterprise data APIs deliver data in two different formats.  The enterprise format closest to the standard v1.1 native format is Native Enriched.  The legacy enterprise data format is Activity Streams, orignially implimented and used by Gnip as a normalized format across X and other social media data providers at the time. While this format is still available, X has only invested new features and developments on the native enriched format since 2017.

The enriched native format is exactly how it sounds, it includes native X objects as well as additional enrichments avialable for enterprise data products such as URL unwinding metadata, profile geo, poll metadata and additional engagement metrics.  

 

Object comparison per data format 

Whatever your X use case, understanding what these JSON-encoded Post objects and attributes represent is critical to successfully finding your data signals of interest. To help in that effort, there are a set of pages dedicated to each object in each data format.

Reflecting the JSON hierarchy above, here are links to each of these objects:

Native Enriched Activity Streams
Link Post object Link Activity object
Link User object Link Actor object
Link Entities object Link X entities object
Link Extended entities object Link X extended entitites object
Link Geo object Link Location object
n/a Link Gnip object

 

Parsing best-practices

  • X JSON is encoded using UTF-8 characters.
  • Parsers should tolerate variance in the ordering of fields with ease. It should be assumed that Post JSON is served as an unordered hash of data.
  • Parsers should tolerate the addition of 'new' fields. 
  • JSON parsers must be tolerant of ‘missing’ fields, since not all fields appear in all contexts.
  • It is generally safe to consider a nulled field, an empty set, and the absence of a field as the same thing
 

Next Steps: