Skip to content

Method: Specifying fields and expansions

Jump to bottom
Matthew R. DeVerna edited this page Aug 30, 2021 · 4 revisions

V2 API only returns limited information by default. To fetch more, you will need to specify the fields and expansions parameters in the request. osometweet contains corresponding classes to handle them. Following are some examples to show you how to this works.

Case 1: I don't need extra fields or expansions

If the default response is sufficient, just ignore the fields and expansions parameters and use OSoMeTweet as introduced in other examples. You can find what's returned by default in the official documents.

Case 2: Just give me everything

If you need everything, follow the example below.

First, you need to initialize the OsomeTweet object like before

import osometweet

# Initialize the OsomeTweet object
bearer_token = "YOUR_TWITTER_BEARER_TOKEN"
oauth2 = osometweet.OAuth2(bearer_token=bearer_token)
ot = osometweet.OsomeTweet(oauth2)

Then, just

# make request
ot.tweet_lookup('1348419350370398209', everything=True)

everything=True works for all osometweet endpoints.

Get all from a specific field

You can also retrieve all elements from specific object fields. The available object fields are:

  • UserFields
  • TweetFields
  • MediaFields
  • PlaceFields
  • PollFields

Now you can

import osometweet
import osometweet.fields as o_fields
bearer_token = "YOUR_TWITTER_BEARER_TOKEN"
oauth2 = osometweet.OAuth2(bearer_token=bearer_token)
ot = osometweet.OsomeTweet(oauth2)
all_user_fields = o_fields.UserFields(everything=True)
response = ot.user_lookup_ids('12', fields=all_user_fields)

NOTE:

  • In the above example, expansions are excluded merely for simplicity's sake, these can be included as well.
  • The same procedure can be repeated for all ObjectFields in the bullet list above (i.e., TweetFields, MediaFields, etc.).
  • If you follow the above procedure, it would not include all TweetField objects in your returned data. Only the object field parameters you pass into the query will be returned in the data (and only if they are present in the data).

Case 3: I need to specify exactly what I need

OSoMeTweet provides the flexibility to specify exactly what the API should return.

Let us use the tweet_lookup endpoint as an example.

Suppose we are interested in a tweet with the unique tweet ID number, 1212092628029698048.

In addition to the default tweet data, we also want to know:

  1. When it was created (captured in the created_at field)
  2. How popular it was (captured in the public_metrics field with information like retweet counts, etc.)
  3. The author of the tweet (so we will need to expand the author_id field)
  4. When the author created their account (so we also need to request the created_at field as a user field)

To retrieve all of this information, we simply specify these specific tweet and user fields in our query.

First, initialize and specify the tweet fields object

import osometweet.fields as o_fields

# Initialize the fields object
tweet_fields = o_fields.TweetFields()

# Specify the tweet fields you need
tweet_fields.fields = ['public_metrics', 'created_at']

Then initialize and specify the user fields object

# Initialize the user fields object
user_fields = o_fields.UserFields()

# Specify the fields you need
user_fields.fields = ['created_at']

Let's initialize and specify the expansion object

import osometweet.expansions as o_expansions

# Initialize the expansion object
expansions = o_expansions.TweetExpansions()

# Specify the expansions you need
expansions.expansions = ["author_id"]

Finally, we can make the request

# make request
ot.tweet_lookup(
    tids = ['1212092628029698048'],
    fields = tweet_fields+user_fields,
    expansions=expansions
)

More on fields

Twitter supports fields for user, tweet, media, poll, and place. You can use UserFields, TweetFields, MediaFields, PollFields, and PlaceFields classes to handle them, respectively. They only contain the default fields if not specified otherwise.

You can see what optional fields are available by

import osometweet.fields as o_fields

tweet_fields = o_fields.TweetFields()
print(tweet_fields.optional_fields)

You can specify the fields by

tweet_fields.fields = ['public_metrics', 'created_at']

After specifying the fields, you can check the status by

print(tweet_fields.fields)

You can add different fields objects up to get an object that contains all the information, and pass it to the API endpoints

import osometweet.fields as o_fields

tweet_fields = o_fields.TweetFields()
tweet_fields.fields = ['public_metrics', 'created_at']

user_fields = o_fields.UserFields()
user_fields.fields = ['created_at']

sum_of_fields = tweet_fields + user_fields
# OR
sum_of_fields = sum([tweet_fields, user_fields])

which will create the below (print(sum_of_fields) to see) which can be passed directly to any of the methods fields arguments.

{'tweet.fields': 'created_at,public_metrics', 'user.fields': 'created_at'}

NOTE:

  • For user endpoints, only tweet fields and user fields are supported; passing other fields such as media fields will cause an error
  • Tweet endpoints accept all fields

More about expansions

Twitter allows expansions for user payload and tweet payload. You can use UserExpansions and TweetExpansions to handle them. They contain all available fields if not specified otherwise.

You can see what expansions are available by

import osometweet.expansions as o_expansions

expansions = o_expansions.UserExpansions()
# OR
# expansions = o_expansions.TweetExpansions()
print(expansions.avail_expansions)

You can specify the expansions by

expansions.expansions = ["author_id"]

Note

  • You can only pass UserExpansions objects to user endpoints and TweetExpansions objects to tweet endpoints; the fields don't have this restriction
  • If you expand author_id, then there is no need to include it in the fields
Clone this wiki locally