API

class tweepy.API(auth=None, *, cache=None, host='api.twitter.com', parser=None, proxy=None, retry_count=0, retry_delay=0, retry_errors=None, timeout=60, upload_host='upload.twitter.com', user_agent=None, wait_on_rate_limit=False)

Twitter API v1.1 Interface

Changed in version 4.11: Added support for include_ext_edit_control endpoint/method parameter

Changed in version 4.14: Removed search_30_day and search_full_archive methods, as the Premium v1.1 API has been deprecated

Parameters
  • auth – The authentication handler to be used

  • cache – The cache to query if a GET method is used

  • host – The general REST API host server URL

  • parser – The Parser instance to use for parsing the response from Twitter; defaults to an instance of ModelParser

  • proxy – The full url to an HTTPS proxy to use for connecting to Twitter

  • retry_count – Number of retries to attempt when an error occurs

  • retry_delay – Number of seconds to wait between retries

  • retry_errors – Which HTTP status codes to retry

  • timeout – The maximum amount of time to wait for a response from Twitter

  • upload_host – The URL of the upload server

  • wait_on_rate_limit – Whether or not to automatically wait for rate limits to replenish

Raises

TypeError – If the given parser is not a Parser instance

References

https://developer.twitter.com/en/docs/api-reference-index

Twitter API v1.1 Endpoint

API Method

Tweets

Get Tweet timelines

GET statuses/home_timeline

API.home_timeline()

GET statuses/mentions_timeline

API.mentions_timeline()

GET statuses/user_timeline

API.user_timeline()

Post, retrieve, and engage with Tweets

GET favorites/list

API.get_favorites()

GET statuses/lookup

API.lookup_statuses()

GET statuses/oembed

API.get_oembed()

GET statuses/retweeters/ids

API.get_retweeter_ids()

GET statuses/retweets/:id

API.get_retweets()

GET statuses/retweets_of_me

API.get_retweets_of_me()

GET statuses/show/:id

API.get_status()

POST favorites/create

API.create_favorite()

POST favorites/destroy

API.destroy_favorite()

POST statuses/destroy/:id

API.destroy_status()

POST statuses/retweet/:id

API.retweet()

POST statuses/unretweet/:id

API.unretweet()

POST statuses/update

API.update_status()

POST statuses/update_with_media

API.update_status_with_media()

Search Tweets

GET search/tweets

API.search_tweets()

Accounts and users

Create and manage lists

GET lists/list

API.get_lists()

GET lists/members

API.get_list_members()

GET lists/members/show

API.get_list_member()

GET lists/memberships

API.get_list_memberships()

GET lists/ownerships

API.get_list_ownerships()

GET lists/show

API.get_list()

GET lists/statuses

API.list_timeline()

GET lists/subscribers

API.get_list_subscribers()

GET lists/subscribers/show

API.get_list_subscriber()

GET lists/subscriptions

API.get_list_subscriptions()

POST lists/create

API.create_list()

POST lists/destroy

API.destroy_list()

POST lists/members/create

API.add_list_member()

POST lists/members/create_all

API.add_list_members()

POST lists/members/destroy

API.remove_list_member()

POST lists/members/destroy_all

API.remove_list_members()

POST lists/subscribers/create

API.subscribe_list()

POST lists/subscribers/destroy

API.unsubscribe_list()

POST lists/update

API.update_list()

Follow, search, and get users

GET followers/ids

API.get_follower_ids()

GET followers/list

API.get_followers()

GET friends/ids

API.get_friend_ids()

GET friends/list

API.get_friends()

GET friendships/incoming

API.incoming_friendships()

GET friendships/lookup

API.lookup_friendships()

GET friendships/no_retweets/ids

API.no_retweets_friendships()

GET friendships/outgoing

API.outgoing_friendships()

GET friendships/show

API.get_friendship()

GET users/lookup

API.lookup_users()

GET users/search

API.search_users()

GET users/show

API.get_user()

POST friendships/create

API.create_friendship()

POST friendships/destroy

API.destroy_friendship()

POST friendships/update

API.update_friendship()

Manage account settings and profile

GET account/settings

API.get_settings()

GET account/verify_credentials

API.verify_credentials()

GET saved_searches/list

API.get_saved_searches()

GET saved_searches/show/:id

API.get_saved_search()

GET users/profile_banner

API.get_profile_banner()

POST account/remove_profile_banner

API.remove_profile_banner()

POST account/settings

API.set_settings()

POST account/update_profile

API.update_profile()

POST account/update_profile_banner

API.update_profile_banner()

POST account/update_profile_image

API.update_profile_image()

POST saved_searches/create

API.create_saved_search()

POST saved_searches/destroy/:id

API.destroy_saved_search()

Mute, block, and report users

GET blocks/ids

API.get_blocked_ids()

GET blocks/list

API.get_blocks()

GET mutes/users/ids

API.get_muted_ids()

GET mutes/users/list

API.get_mutes()

POST blocks/create

API.create_block()

POST blocks/destroy

API.destroy_block()

POST mutes/users/create

API.create_mute()

POST mutes/users/destroy

API.destroy_mute()

POST users/report_spam

API.report_spam()

Direct Messages

Sending and receiving events

DELETE direct_messages/events/destroy

API.delete_direct_message()

GET direct_messages/events/list

API.get_direct_messages()

GET direct_messages/events/show

API.get_direct_message()

POST direct_messages/events/new

API.send_direct_message()

Typing indicator and read receipts

POST direct_messages/indicate_typing

API.indicate_direct_message_typing()

POST direct_messages/mark_read

API.mark_direct_message_read()

Media

Upload media

GET media/upload

API.get_media_upload_status()

POST media/metadata/create

API.create_media_metadata()

API.media_upload()

POST media/upload

API.simple_upload()

API.chunked_upload()

POST media/upload (APPEND)

API.chunked_upload_append()

POST media/upload (FINALIZE)

API.chunked_upload_finalize()

POST media/upload (INIT)

API.chunked_upload_init()

Trends

Get locations with trending topics

GET trends/available

API.available_trends()

GET trends/closest

API.closest_trends()

Get trends near a location

GET trends/place

API.get_place_trends()

Geo

Get information about a place

GET geo/id/:place_id

API.geo_id()

Get places near a location

GET geo/reverse_geocode

API.reverse_geocode()

GET geo/search

API.search_geo()

Developer utilities

Get Twitter supported languages

GET help/languages

API.supported_languages()

Get app rate limit status

GET application/rate_limit_status

API.rate_limit_status()

Tweets

Get Tweet timelines

API.home_timeline(*, count, since_id, max_id, trim_user, exclude_replies, include_entities)

Returns the 20 most recent statuses, including retweets, posted by the authenticating user and that user’s friends. This is the equivalent of /timeline/home on the Web.

Parameters
  • count – The number of results to try and retrieve per page.

  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.

  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

  • exclude_replies – This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count Tweets — this is because the count parameter retrieves that many Tweets before filtering out retweets and replies.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-home_timeline

API.mentions_timeline(*, count, since_id, max_id, trim_user, include_entities)

Returns the 20 most recent mentions, including retweets.

Parameters
  • count – The number of results to try and retrieve per page.

  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.

  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-mentions_timeline

API.user_timeline(*, user_id, screen_name, since_id, count, max_id, trim_user, exclude_replies, include_rts)

Returns the 20 most recent statuses posted from the authenticating user or the user specified. It’s also possible to request another user’s timeline via the id parameter.

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.

  • count – The number of results to try and retrieve per page.

  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

  • exclude_replies – This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count Tweets — this is because the count parameter retrieves that many Tweets before filtering out retweets and replies.

  • include_rts – When set to false, the timeline will strip any native retweets (though they will still count toward both the maximal length of the timeline and the slice selected by the count parameter). Note: If you’re using the trim_user parameter in conjunction with include_rts, the retweets will still contain a full user object.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-user_timeline

Post, retrieve, and engage with Tweets

API.get_favorites(*, user_id, screen_name, count, since_id, max_id, include_entities)

Returns the favorite statuses for the authenticating user or user specified by the ID parameter.

Changed in version 4.0: Renamed from API.favorites

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • count – The number of results to try and retrieve per page.

  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.

  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-favorites-list

API.lookup_statuses(id, *, include_entities, trim_user, map, include_ext_alt_text, include_card_uri)

Returns full Tweet objects for up to 100 Tweets per request, specified by the id parameter.

Changed in version 4.0: Renamed from API.statuses_lookup

Parameters
  • id – A list of Tweet IDs to lookup, up to 100

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

  • map – A boolean indicating whether or not to include Tweets that cannot be shown. Defaults to False.

  • include_ext_alt_text – If alt text has been added to any attached media entities, this parameter will return an ext_alt_text value in the top-level key for the media entity.

  • include_card_uri – A boolean indicating if the retrieved Tweet should include a card_uri attribute when there is an ads card attached to the Tweet and when that card was attached using the card_uri value.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-lookup

API.get_oembed(url, *, maxwidth, hide_media, hide_thread, omit_script, align, related, lang, theme, link_color, widget_type, dnt)

Returns a single Tweet, specified by either a Tweet web URL or the Tweet ID, in an oEmbed-compatible format. The returned HTML snippet will be automatically recognized as an Embedded Tweet when Twitter’s widget JavaScript is included on the page.

The oEmbed endpoint allows customization of the final appearance of an Embedded Tweet by setting the corresponding properties in HTML markup to be interpreted by Twitter’s JavaScript bundled with the HTML response by default. The format of the returned markup may change over time as Twitter adds new features or adjusts its Tweet representation.

The Tweet fallback markup is meant to be cached on your servers for up to the suggested cache lifetime specified in the cache_age.

Parameters
  • url – The URL of the Tweet to be embedded

  • maxwidth – The maximum width of a rendered Tweet in whole pixels. A supplied value under or over the allowed range will be returned as the minimum or maximum supported width respectively; the reset width value will be reflected in the returned width property. Note that Twitter does not support the oEmbed maxheight parameter. Tweets are fundamentally text, and are therefore of unpredictable height that cannot be scaled like an image or video. Relatedly, the oEmbed response will not provide a value for height. Implementations that need consistent heights for Tweets should refer to the hide_thread and hide_media parameters below.

  • hide_media – When set to true, "t", or 1, links in a Tweet are not expanded to photo, video, or link previews.

  • hide_thread – When set to true, "t", or 1, a collapsed version of the previous Tweet in a conversation thread will not be displayed when the requested Tweet is in reply to another Tweet.

  • omit_script – When set to true, "t", or 1, the <script> responsible for loading widgets.js will not be returned. Your webpages should include their own reference to widgets.js for use across all Twitter widgets including Embedded Tweets.

  • align – Specifies whether the embedded Tweet should be floated left, right, or center in the page relative to the parent element.

  • related – A comma-separated list of Twitter usernames related to your content. This value will be forwarded to Tweet action intents if a viewer chooses to reply, like, or retweet the embedded Tweet.

  • lang – Request returned HTML and a rendered Tweet in the specified Twitter language supported by embedded Tweets.

  • theme – When set to dark, the Tweet is displayed with light text over a dark background.

  • link_color – Adjust the color of Tweet text links with a hexadecimal color value.

  • widget_type – Set to video to return a Twitter Video embed for the given Tweet.

  • dnt – When set to true, the Tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.

Returns

JSON

Return type

dict

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-oembed

API.get_retweeter_ids(id, *, count, cursor, stringify_ids)

Returns up to 100 user IDs belonging to users who have retweeted the Tweet specified by the id parameter.

Changed in version 4.0: Renamed from API.retweeters

Parameters
  • id – The numerical ID of the status.

  • count – The number of results to try and retrieve per page.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • stringify_ids – Have IDs returned as strings instead

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids

API.get_retweets(id, *, count, trim_user)

Returns up to 100 of the first Retweets of the given Tweet.

Changed in version 4.0: Renamed from API.retweets

Parameters
  • id – The numerical ID of the status.

  • count – The number of results to try and retrieve per page.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets-id

API.get_retweets_of_me(*, count, since_id, max_id, trim_user, include_entities, include_user_entities)

Returns the 20 most recent Tweets of the authenticated user that have been retweeted by others.

Changed in version 4.0: Renamed from API.retweets_of_me

Parameters
  • count – The number of results to try and retrieve per page.

  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.

  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • include_user_entities – The user object entities node will not be included when set to false. Defaults to true.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-retweets_of_me

API.get_status(id, *, trim_user, include_my_retweet, include_entities, include_ext_alt_text, include_card_uri)

Returns a single status specified by the ID parameter.

Parameters
  • id – The numerical ID of the status.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

  • include_my_retweet – A boolean indicating if any Tweets returned that have been retweeted by the authenticating user should include an additional current_user_retweet node, containing the ID of the source status for the retweet.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • include_ext_alt_text – If alt text has been added to any attached media entities, this parameter will return an ext_alt_text value in the top-level key for the media entity.

  • include_card_uri – A boolean indicating if the retrieved Tweet should include a card_uri attribute when there is an ads card attached to the Tweet and when that card was attached using the card_uri value.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-show-id

API.create_favorite(id, *, include_entities)

Favorites the status specified in the id parameter as the authenticating user.

Parameters
  • id – The numerical ID of the status.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-create

API.destroy_favorite(id, *, include_entities)

Un-favorites the status specified in the id parameter as the authenticating user.

Parameters
  • id – The numerical ID of the status.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-favorites-destroy

API.destroy_status(id, *, trim_user)

Destroy the status specified by the id parameter. The authenticated user must be the author of the status to destroy.

Parameters
  • id – The numerical ID of the status.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-destroy-id

API.retweet(id, *, trim_user)

Retweets a Tweet. Requires the ID of the Tweet you are retweeting.

Parameters
  • id – The numerical ID of the status.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-retweet-id

API.unretweet(id, *, trim_user)

Untweets a retweeted status. Requires the ID of the retweet to unretweet.

Parameters
  • id – The numerical ID of the status.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-unretweet-id

API.update_status(status, *, in_reply_to_status_id, auto_populate_reply_metadata, exclude_reply_user_ids, attachment_url, media_ids, possibly_sensitive, lat, long, place_id, display_coordinates, trim_user, card_uri)

Updates the authenticating user’s current status, also known as Tweeting.

For each update attempt, the update text is compared with the authenticating user’s recent Tweets. Any attempt that would result in duplication will be blocked, resulting in a 403 error. A user cannot submit the same status twice in a row.

While not rate limited by the API, a user is limited in the number of Tweets they can create at a time. If the number of updates posted by the user reaches the current allowed limit this method will return an HTTP 403 error.

Parameters
  • status – The text of your status update.

  • in_reply_to_status_id – The ID of an existing status that the update is in reply to. Note: This parameter will be ignored unless the author of the Tweet this parameter references is mentioned within the status text. Therefore, you must include @username, where username is the author of the referenced Tweet, within the update.

  • auto_populate_reply_metadata – If set to true and used with in_reply_to_status_id, leading @mentions will be looked up from the original Tweet, and added to the new Tweet from there. This wil append @mentions into the metadata of an extended Tweet as a reply chain grows, until the limit on @mentions is reached. In cases where the original Tweet has been deleted, the reply will fail.

  • exclude_reply_user_ids – When used with auto_populate_reply_metadata, a comma-separated list of user ids which will be removed from the server-generated @mentions prefix on an extended Tweet. Note that the leading @mention cannot be removed as it would break the in-reply-to-status-id semantics. Attempting to remove it will be silently ignored.

  • attachment_url – In order for a URL to not be counted in the status body of an extended Tweet, provide a URL as a Tweet attachment. This URL must be a Tweet permalink, or Direct Message deep link. Arbitrary, non-Twitter URLs must remain in the status text. URLs passed to the attachment_url parameter not matching either a Tweet permalink or Direct Message deep link will fail at Tweet creation and cause an exception.

  • media_ids – A list of media_ids to associate with the Tweet. You may include up to 4 photos or 1 animated GIF or 1 video in a Tweet.

  • possibly_sensitive – If you upload Tweet media that might be considered sensitive content such as nudity, or medical procedures, you must set this value to true.

  • lat – The latitude of the location this Tweet refers to. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there is no corresponding long parameter.

  • long – The longitude of the location this Tweet refers to. The valid ranges for longitude are -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there no corresponding lat parameter.

  • place_id – A place in the world.

  • display_coordinates – Whether or not to put a pin on the exact coordinates a Tweet has been sent from.

  • trim_user – A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False.

  • card_uri – Associate an ads card with the Tweet using the card_uri value from any ads card response.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-update

API.update_status_with_media(status, filename, *, file, possibly_sensitive, in_reply_to_status_id, lat, long, place_id, display_coordinates)

Update the authenticated user’s status. Statuses that are duplicates or too long will be silently ignored.

Changed in version 4.0: Renamed from API.update_with_media

Parameters
  • status – The text of your status update.

  • filename – The filename of the image to upload. This will automatically be opened unless file is specified.

  • file – A file object, which will be used instead of opening filename. filename is still required, for MIME type detection and to use as a form field in the POST data.

  • possibly_sensitive – Set to true for content which may not be suitable for every audience.

  • in_reply_to_status_id – The ID of an existing status that the update is in reply to.

  • lat – The location’s latitude that this tweet refers to.

  • long – The location’s longitude that this tweet refers to.

  • place_id – Twitter ID of location which is listed in the Tweet if geolocation is enabled for the user.

  • display_coordinates – Whether or not to put a pin on the exact coordinates a Tweet has been sent from.

Returns

Return type

Status

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-update_with_media

Search Tweets

API.search_tweets(q, *, geocode, lang, locale, result_type, count, until, since_id, max_id, include_entities)

Returns a collection of relevant Tweets matching a specified query.

Please note that Twitter’s search service and, by extension, the Search API is not meant to be an exhaustive source of Tweets. Not all Tweets will be indexed or made available via the search interface.

Note

Twitter’s standard search API only “searches against a sampling of recent Tweets published in the past 7 days.”

If you’re specifying an ID range beyond the past 7 days or there are no results from the past 7 days, then no results will be returned.

See Twitter’s documentation on the standard search API for more information.

Note

In API v1.1, the response format of the Search API has been improved to return Tweet objects more similar to the objects you’ll find across the REST API and platform. However, perspectival attributes (fields that pertain to the perspective of the authenticating user) are not currently supported on this endpoint. 12

Changed in version 4.0: Renamed from API.search

Parameters
  • q – The search query string of 500 characters maximum, including operators. Queries may additionally be limited by complexity.

  • geocode – Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by “latitude,longitude,radius”, where radius units must be specified as either “mi” (miles) or “km” (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly. A maximum of 1,000 distinct “sub-regions” will be considered when using the radius modifier.

  • lang – Restricts tweets to the given language, given by an ISO 639-1 code. Language detection is best-effort.

  • locale – Specify the language of the query you are sending (only ja is currently effective). This is intended for language-specific consumers and the default should work in the majority of cases.

  • result_type

    Specifies what type of search results you would prefer to receive. The current default is “mixed.” Valid values include:

    • mixed : include both popular and real time results in the response

    • recent : return only the most recent results in the response

    • popular : return only the most popular results in the response

  • count – The number of results to try and retrieve per page.

  • until – Returns tweets created before the given date. Date should be formatted as YYYY-MM-DD. Keep in mind that the search index has a 7-day limit. In other words, no tweets will be found for a date older than one week.

  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occurred since the since_id, the since_id will be forced to the oldest ID available.

  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

SearchResults

References

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/search/api-reference/get-search-tweets

Accounts and users

Create and manage lists

API.get_lists(*, user_id, screen_name, reverse)

Returns all lists the authenticating or specified user subscribes to, including their own. The user is specified using the user_id or screen_name parameters. If no user is given, the authenticating user is used.

A maximum of 100 results will be returned by this call. Subscribed lists are returned first, followed by owned lists. This means that if a user subscribes to 90 lists and owns 20 lists, this method returns 90 subscriptions and 10 owned lists. The reverse method returns owned lists first, so with reverse=true, 20 owned lists and 80 subscriptions would be returned.

Changed in version 4.0: Renamed from API.lists_all

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • reverse – A boolean indicating if you would like owned lists to be returned first. See description above for information on how this parameter works.

Returns

Return type

List[List]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-list

API.get_list_members(*, list_id, slug, owner_screen_name, owner_id, count, cursor, include_entities, skip_status)

Returns the members of the specified list.

Changed in version 4.0: Renamed from API.list_members

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

  • count – The number of results to try and retrieve per page.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members

API.get_list_member(*, list_id, slug, user_id, screen_name, owner_screen_name, owner_id, include_entities, skip_status)

Check if the specified user is a member of the specified list.

Changed in version 4.0: Renamed from API.show_list_member

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Raises

NotFound – The user is not a member of the list.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-members-show

API.get_list_memberships(*, user_id, screen_name, count, cursor, filter_to_owned_lists)

Returns the lists the specified user has been added to. If user_id or screen_name are not provided, the memberships for the authenticating user are returned.

Changed in version 4.0: Renamed from API.lists_memberships

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • count – The number of results to try and retrieve per page.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • filter_to_owned_lists – A boolean indicating whether to return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.

Returns

Return type

List[List]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships

API.get_list_ownerships(*, user_id, screen_name, count, cursor)

Returns the lists owned by the specified user. Private lists will only be shown if the authenticated user is also the owner of the lists. If user_id and screen_name are not provided, the ownerships for the authenticating user are returned.

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • count – The number of results to try and retrieve per page.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns

Return type

List[List]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships

API.get_list(*, list_id, slug, owner_screen_name, owner_id)

Returns the specified list. Private lists will only be shown if the authenticated user owns the specified list.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-show

API.list_timeline(*, list_id, slug, owner_screen_name, owner_id, since_id, max_id, count, include_entities, include_rts)

Returns a timeline of Tweets authored by members of the specified list. Retweets are included by default. Use the include_rts=false parameter to omit retweets.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

  • since_id – Returns only statuses with an ID greater than (that is, more recent than) the specified ID.

  • max_id – Returns only statuses with an ID less than (that is, older than) or equal to the specified ID.

  • count – The number of results to try and retrieve per page.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • include_rts – A boolean indicating whether the list timeline will contain native retweets (if they exist) in addition to the standard stream of Tweets. The output format of retweeted Tweets is identical to the representation you see in home_timeline.

Returns

Return type

List[Status]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses

API.get_list_subscribers(*, list_id, slug, owner_screen_name, owner_id, count, cursor, include_entities, skip_status)

Returns the subscribers of the specified list. Private list subscribers will only be shown if the authenticated user owns the specified list.

Changed in version 4.0: Renamed from API.list_subscribers

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

  • count – The number of results to try and retrieve per page.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers

API.get_list_subscriber(*, owner_screen_name, owner_id, list_id, slug, user_id, screen_name, include_entities, skip_status)

Check if the specified user is a subscriber of the specified list.

Changed in version 4.0: Renamed from API.show_list_subscriber

Parameters
  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Raises

NotFound – The user is not a subscriber of the list.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers-show

API.get_list_subscriptions(*, user_id, screen_name, count, cursor)

Obtain a collection of the lists the specified user is subscribed to, 20 lists per page by default. Does not include the user’s own lists.

Changed in version 4.0: Renamed from API.lists_subscriptions

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • count – The number of results to try and retrieve per page.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns

Return type

List[List]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/get-lists-subscriptions

API.create_list(name, *, mode, description)

Creates a new list for the authenticated user. Note that you can create up to 1000 lists per account.

Parameters
  • name – The name of the new list.

  • mode – Whether your list is public or private. Values can be public or private. Lists are public by default if no mode is specified.

  • description – The description of the list you are creating.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-create

API.destroy_list(*, owner_screen_name, owner_id, list_id, slug)

Deletes the specified list. The authenticated user must own the list to be able to destroy it.

Parameters
  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy

API.add_list_member(*, list_id, slug, user_id, screen_name, owner_screen_name, owner_id)

Add a member to a list. The authenticated user must own the list to be able to add members to it. Lists are limited to 5,000 members.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create

API.add_list_members(*, list_id, slug, user_id, screen_name, owner_screen_name, owner_id)

Add up to 100 members to a list. The authenticated user must own the list to be able to add members to it. Lists are limited to 5,000 members.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • user_id – A comma separated list of user IDs, up to 100 are allowed in a single request

  • screen_name – A comma separated list of screen names, up to 100 are allowed in a single request

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create_all

API.remove_list_member(*, list_id, slug, user_id, screen_name, owner_screen_name, owner_id)

Removes the specified member from the list. The authenticated user must be the list’s owner to remove members from the list.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy

API.remove_list_members(*, list_id, slug, user_id, screen_name, owner_screen_name, owner_id)

Remove up to 100 members from a list. The authenticated user must own the list to be able to remove members from it. Lists are limited to 5,000 members.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • user_id – A comma separated list of user IDs, up to 100 are allowed in a single request

  • screen_name – A comma separated list of screen names, up to 100 are allowed in a single request

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy_all

API.subscribe_list(*, owner_screen_name, owner_id, list_id, slug)

Subscribes the authenticated user to the specified list.

Parameters
  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-create

API.unsubscribe_list(*, list_id, slug, owner_screen_name, owner_id)

Unsubscribes the authenticated user from the specified list.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-destroy

API.update_list(*, list_id, slug, name, mode, description, owner_screen_name, owner_id)

Updates the specified list. The authenticated user must own the list to be able to update it.

Parameters
  • list_id – The numerical id of the list.

  • slug – You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you’ll also have to specify the list owner using the owner_id or owner_screen_name parameters.

  • name – The name for the list.

  • mode – Whether your list is public or private. Values can be public or private. Lists are public by default if no mode is specified.

  • description – The description to give the list.

  • owner_screen_name – The screen name of the user who owns the list being requested by a slug.

  • owner_id – The user ID of the user who owns the list being requested by a slug.

Returns

Return type

List

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/create-manage-lists/api-reference/post-lists-update

Follow, search, and get users

API.get_follower_ids(*, user_id, screen_name, cursor, stringify_ids, count)

Returns an array containing the IDs of users following the specified user.

Changed in version 4.0: Renamed from API.followers_ids

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • stringify_ids – Have IDs returned as strings instead

  • count – The number of results to try and retrieve per page.

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids

API.get_followers(*, user_id, screen_name, cursor, count, skip_status, include_user_entities)

Returns a user’s followers ordered in which they were added. If no user is specified by id/screen name, it defaults to the authenticated user.

Changed in version 4.0: Renamed from API.followers

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • count – The number of results to try and retrieve per page.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

  • include_user_entities – The user object entities node will not be included when set to false. Defaults to true.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-list

API.get_friend_ids(*, user_id, screen_name, cursor, stringify_ids, count)

Returns an array containing the IDs of users being followed by the specified user.

Changed in version 4.0: Renamed from API.friends_ids

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • stringify_ids – Have IDs returned as strings instead

  • count – The number of results to try and retrieve per page.

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids

API.get_friends(*, user_id, screen_name, cursor, count, skip_status, include_user_entities)

Returns a user’s friends ordered in which they were added 100 at a time. If no user is specified it defaults to the authenticated user.

Changed in version 4.0: Renamed from API.friends

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • count – The number of results to try and retrieve per page.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

  • include_user_entities – The user object entities node will not be included when set to false. Defaults to true.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friends-list

API.incoming_friendships(*, cursor, stringify_ids)

Returns a collection of numeric IDs for every user who has a pending request to follow the authenticating user.

Changed in version 4.0: Renamed from API.friendships_incoming

Parameters
  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • stringify_ids – Have IDs returned as strings instead

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friendships-incoming

API.lookup_friendships(*, screen_name, user_id)

Returns the relationships of the authenticated user to the list of up to 100 screen_name or user_id provided.

Parameters
  • screen_name – A list of screen names, up to 100 are allowed in a single request.

  • user_id – A list of user IDs, up to 100 are allowed in a single request.

Returns

Return type

List[Relationship]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup

API.no_retweets_friendships(*, stringify_ids)

Returns a collection of user_ids that the currently authenticated user does not want to receive retweets from.

Parameters

stringify_ids – Have IDs returned as strings instead

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friendships-no_retweets-ids

API.outgoing_friendships(*, cursor, stringify_ids)

Returns a collection of numeric IDs for every protected user for whom the authenticating user has a pending follow request.

Changed in version 4.0: Renamed from API.friendships_outgoing

Parameters
  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • stringify_ids – Have IDs returned as strings instead

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friendships-outgoing

API.get_friendship(*, source_id, source_screen_name, target_id, target_screen_name)

Returns detailed information about the relationship between two users.

Changed in version 4.0: Renamed from API.show_friendship

Parameters
  • source_id – The user_id of the subject user.

  • source_screen_name – The screen_name of the subject user.

  • target_id – The user_id of the target user.

  • target_screen_name – The screen_name of the target user.

Returns

Return type

Friendship

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friendships-show

API.lookup_users(*, screen_name, user_id, include_entities, tweet_mode)

Returns fully-hydrated user objects for up to 100 users per request.

There are a few things to note when using this method.

  • You must be following a protected user to be able to see their most recent status update. If you don’t follow a protected user their status will be removed.

  • The order of user IDs or screen names may not match the order of users in the returned array.

  • If a requested user is unknown, suspended, or deleted, then that user will not be returned in the results list.

  • If none of your lookup criteria can be satisfied by returning a user object, a HTTP 404 will be thrown.

Parameters
  • screen_name – A list of screen names, up to 100 are allowed in a single request.

  • user_id – A list of user IDs, up to 100 are allowed in a single request.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • tweet_mode – Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup

API.search_users(q, *, page, count, include_entities)

Run a search for users similar to Find People button on Twitter.com; the same results returned by people search on Twitter.com will be returned by using this API (about being listed in the People Search). It is only possible to retrieve the first 1000 matches from this API.

Parameters
  • q – The query to run against people search.

  • page – Specifies the page of results to retrieve. Note: there are pagination limits.

  • count – The number of results to try and retrieve per page.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-search

API.get_user(*, user_id, screen_name, include_entities)

Returns information about the specified user.

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-show

API.create_friendship(*, screen_name, user_id, follow)

Create a new friendship with the specified user (aka follow).

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • follow – Enable notifications for the target user in addition to becoming friends.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create

API.destroy_friendship(*, screen_name, user_id)

Destroy a friendship with the specified user (aka unfollow).

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy

API.update_friendship(*, screen_name, user_id, device, retweets)

Turn on/off Retweets and device notifications from the specified user.

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • device – Turn on/off device notifications from the target user.

  • retweets – Turn on/off Retweets from the target user.

Returns

Return type

Friendship

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/post-friendships-update

Manage account settings and profile

API.get_settings()

Returns settings (including current trend, geo and sleep time information) for the authenticating user.

Returns

JSON

Return type

dict

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-settings

API.verify_credentials(*, include_entities, skip_status, include_email)

Verify the supplied user credentials are valid.

Parameters
  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

  • include_email – When set to true email will be returned in the user objects as a string.

Raises

Unauthorized – Authentication unsuccessful

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials

API.get_saved_searches()

Returns the authenticated user’s saved search queries.

Changed in version 4.0: Renamed from API.saved_searches

Returns

Return type

List[SavedSearch]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-list

Retrieve the data for a saved search owned by the authenticating user specified by the given ID.

Parameters

id – The ID of the saved search to be retrieved.

Returns

Return type

SavedSearch

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-show-id

API.get_profile_banner(*, user_id, screen_name)

Returns a map of the available size variations of the specified user’s profile banner. If the user has not uploaded a profile banner, a HTTP 404 will be served instead.

The profile banner data available at each size variant’s URL is in PNG format.

Parameters
  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

Returns

JSON

Return type

dict

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-users-profile_banner

API.remove_profile_banner()

Removes the uploaded profile banner for the authenticating user.

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-account-remove_profile_banner

API.set_settings(*, sleep_time_enabled, start_sleep_time, end_sleep_time, time_zone, trend_location_woeid, lang)

Updates the authenticating user’s settings.

Parameters
  • sleep_time_enabled – When set to true, t or 1 , will enable sleep time for the user. Sleep time is the time when push or SMS notifications should not be sent to the user.

  • start_sleep_time – The hour that sleep time should begin if it is enabled. The value for this parameter should be provided in ISO 8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user’s time_zone setting.

  • end_sleep_time – The hour that sleep time should end if it is enabled. The value for this parameter should be provided in ISO 8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user’s time_zone setting.

  • time_zone – The timezone dates and times should be displayed in for the user. The timezone must be one of the Rails TimeZone names.

  • trend_location_woeid – The Yahoo! Where On Earth ID to use as the user’s default trend location. Global information is available by using 1 as the WOEID.

  • lang – The language which Twitter should render in for this user. The language must be specified by the appropriate two letter ISO 639-1 representation.

Returns

JSON

Return type

dict

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-account-settings

API.update_profile(*, name, url, location, description, profile_link_color, include_entities, skip_status)

Sets values that users are able to set under the “Account” tab of their settings page.

Parameters
  • name – Full name associated with the profile.

  • url – URL associated with the profile. Will be prepended with http:// if not present

  • location – The city or country describing where the user of the account is located. The contents are not normalized or geocoded in any way.

  • description – A description of the user owning the account.

  • profile_link_color – Sets a hex value that controls the color scheme of links used on the authenticating user’s profile page on twitter.com. This must be a valid hexadecimal value, and may be either three or six characters (ex: F00 or FF0000).

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile

API.update_profile_banner(filename, *, file, width, height, offset_left, offset_top)

Uploads a profile banner on behalf of the authenticating user.

Parameters
  • filename – The filename of the image to upload. This will automatically be opened unless file is specified.

  • file – A file object, which will be used instead of opening filename. filename is still required, for MIME type detection and to use as a form field in the POST data.

  • width – The width of the preferred section of the image being uploaded in pixels. Use with height, offset_left, and offset_top to select the desired region of the image to use.

  • height – The height of the preferred section of the image being uploaded in pixels. Use with width, offset_left, and offset_top to select the desired region of the image to use.

  • offset_left – The number of pixels by which to offset the uploaded image from the left. Use with height, width, and offset_top to select the desired region of the image to use.

  • offset_top – The number of pixels by which to offset the uploaded image from the top. Use with height, width, and offset_left to select the desired region of the image to use.

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_banner

API.update_profile_image(filename, *, file, include_entities, skip_status)

Update the authenticating user’s profile image. Valid formats: GIF, JPG, or PNG

Parameters
  • filename – The filename of the image to upload. This will automatically be opened unless file is specified.

  • file – A file object, which will be used instead of opening filename. filename is still required, for MIME type detection and to use as a form field in the POST data.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image

Creates a saved search for the authenticated user.

Parameters

query – The query of the search the user would like to save.

Returns

Return type

SavedSearch

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-create

Destroys a saved search for the authenticated user. The search specified by ID must be owned by the authenticating user.

Parameters

id – The ID of the saved search to be deleted.

Returns

Return type

SavedSearch

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-destroy-id

Mute, block, and report users

API.get_blocked_ids(*, stringify_ids, cursor)

Returns an array of numeric user IDs the authenticating user is blocking.

Changed in version 4.0: Renamed from API.blocks_ids

Parameters
  • stringify_ids – Have IDs returned as strings instead

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids

API.get_blocks(*, include_entities, skip_status, cursor)

Returns an array of user objects that the authenticating user is blocking.

Changed in version 4.0: Renamed from API.blocks

Parameters
  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-blocks-list

API.get_muted_ids(*, stringify_ids, cursor)

Returns an array of numeric user IDs the authenticating user has muted.

Changed in version 4.0: Renamed from API.mutes_ids

Parameters
  • stringify_ids – Have IDs returned as strings instead

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns

Return type

List[int]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids

API.get_mutes(*, cursor, include_entities, skip_status)

Returns an array of user objects the authenticating user has muted.

Changed in version 4.0: Renamed from API.mutes

Parameters
  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Returns

Return type

List[User]

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list

API.create_block(*, screen_name, user_id, include_entities, skip_status)

Blocks the specified user from following the authenticating user. In addition the blocked user will not show in the authenticating users mentions or timeline (unless retweeted by another user). If a follow or friend relationship exists it is destroyed.

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create

API.destroy_block(*, screen_name, user_id, include_entities, skip_status)

Un-blocks the user specified in the ID parameter for the authenticating user.

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • include_entities – The entities node will not be included when set to false. Defaults to true.

  • skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-blocks-destroy

API.create_mute(*, screen_name, user_id)

Mutes the user specified in the ID parameter for the authenticating user.

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create

API.destroy_mute(*, screen_name, user_id)

Un-mutes the user specified in the ID parameter for the authenticating user.

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy

API.report_spam(*, screen_name, user_id, perform_block)

Report the specified user as a spam account to Twitter.

Parameters
  • screen_name – Specifies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID.

  • user_id – Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name.

  • perform_block – A boolean indicating if the reported account should be blocked. Defaults to True.

Returns

Return type

User

References

https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-users-report_spam

Direct Messages

Sending and receiving events

API.delete_direct_message(id)

Deletes the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message. Direct Messages are only removed from the interface of the user context provided. Other members of the conversation can still access the Direct Messages.

Changed in version 4.0: Renamed from API.destroy_direct_message

Parameters

id – The ID of the Direct Message that should be deleted.

References

https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/delete-message-event

API.get_direct_messages(*, count, cursor)

Returns all Direct Message events (both sent and received) within the last 30 days. Sorted in reverse-chronological order.

Changed in version 4.0: Renamed from API.list_direct_messages

Parameters
  • count – The number of results to try and retrieve per page.

  • cursor – Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body’s next_cursor and previous_cursor attributes to page back and forth in the list.

Returns

Return type

List[DirectMessage]

References

https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/list-events

API.get_direct_message(id)

Returns a specific direct message.

Parameters

id – The ID of the Direct Message event that should be returned.

Returns

Return type

DirectMessage

References

https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/get-event

API.send_direct_message(recipient_id, text, *, quick_reply_options, attachment_type, attachment_media_id, ctas)

Sends a new direct message to the specified user from the authenticating user.

Parameters
  • recipient_id – The ID of the user who should receive the direct message.

  • text – The text of your Direct Message. Max length of 10,000 characters.

  • quick_reply_options – Array of Options objects (20 max).

  • attachment_type – The attachment type. Can be media or location.

  • attachment_media_id – A media id to associate with the message. A Direct Message may only reference a single media_id.

  • ctas – Array of 1-3 call-to-action (CTA) button objects

Returns

Return type

DirectMessage

References

https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/new-event

Typing indicator and read receipts

API.indicate_direct_message_typing(recipient_id)

Displays a visual typing indicator in the recipient’s Direct Message conversation view with the sender. Each request triggers a typing indicator animation with a duration of ~3 seconds.

New in version 4.9.

Parameters

recipient_id – The user ID of the user to receive the typing indicator.

References

https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/typing-indicator-and-read-receipts/api-reference/new-typing-indicator

API.mark_direct_message_read(last_read_event_id, recipient_id)

Marks a message as read in the recipient’s Direct Message conversation view with the sender.

New in version 4.9.

Parameters
  • last_read_event_id – The message ID of the most recent message to be marked read. All messages before it will be marked read as well.

  • recipient_id – The user ID of the user the message is from.

References

https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/typing-indicator-and-read-receipts/api-reference/new-read-receipt

Media

Upload media

API.get_media_upload_status(media_id)

Check on the progress of a chunked media upload. If the upload has succeeded, it’s safe to create a Tweet with this media_id.

Parameters

media_id – The ID of the media to check.

Returns

Return type

Media

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/get-media-upload-status

API.create_media_metadata(media_id, alt_text)

This endpoint can be used to provide additional information about the uploaded media_id. This feature is currently only supported for images and GIFs. Call this endpoint to attach additional metadata such as image alt text.

Parameters
  • media_id – The ID of the media to add alt text to.

  • alt_text – The alt text to add to the image.

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/post-media-metadata-create

API.media_upload(filename, *, file, chunked, media_category, additional_owners)

Use this to upload media to Twitter. This calls either simple_upload() or chunked_upload(). Chunked media upload is automatically used for videos. If chunked is set or the media is a video, wait_for_async_finalize can be specified as a keyword argument to be passed to chunked_upload().

Parameters
  • filename – The filename of the image to upload. This will automatically be opened unless file is specified.

  • file – A file object, which will be used instead of opening filename. filename is still required, for MIME type detection and to use as a form field in the POST data.

  • chunked – Whether or not to use chunked media upload. Videos use chunked upload regardless of this parameter. Defaults to False.

  • media_category – The category that represents how the media will be used. This field is required when using the media with the Ads API.

  • additional_owners – A list of user IDs to set as additional owners allowed to use the returned media_id in Tweet or Cards. Up to 100 additional owners may be specified.

Returns

Return type

Media

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/overview

API.simple_upload(filename, *, file, media_category, additional_owners)

Use this endpoint to upload media to Twitter. This does not use the chunked upload endpoints.

Parameters
  • filename – The filename of the image to upload. This will automatically be opened unless file is specified.

  • file – A file object, which will be used instead of opening filename. filename is still required, for MIME type detection and to use as a form field in the POST data.

  • media_category – The category that represents how the media will be used. This field is required when using the media with the Ads API.

  • additional_owners – A list of user IDs to set as additional owners allowed to use the returned media_id in Tweet or Cards. Up to 100 additional owners may be specified.

Returns

Return type

Media

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/post-media-upload

API.chunked_upload(filename, *, file, file_type, wait_for_async_finalize, media_category, additional_owners)

Use this to upload media to Twitter. This uses the chunked upload endpoints and calls chunked_upload_init(), chunked_upload_append(), and chunked_upload_finalize(). If wait_for_async_finalize is set, this calls get_media_upload_status() as well.

Parameters
  • filename – The filename of the image to upload. This will automatically be opened unless file is specified.

  • file – A file object, which will be used instead of opening filename. filename is still required, for MIME type detection and to use as a form field in the POST data.

  • file_type – The MIME type of the media being uploaded.

  • wait_for_async_finalize – Whether to wait for Twitter’s API to finish processing the media. Defaults to True.

  • media_category – The category that represents how the media will be used. This field is required when using the media with the Ads API.

  • additional_owners – A list of user IDs to set as additional owners allowed to use the returned media_id in Tweet or Cards. Up to 100 additional owners may be specified.

Returns

Return type

Media

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/uploading-media/chunked-media-upload

API.chunked_upload_append(media_id, media, segment_index)

Use this endpoint to upload a chunk (consecutive byte range) of the media file.

Parameters
  • media_id – The media_id returned from the initialization.

  • media – The raw binary file content being uploaded. It must be <= 5 MB.

  • segment_index – An ordered index of file chunk. It must be between 0-999 inclusive. The first segment has index 0, second segment has index 1, and so on.

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/post-media-upload-append

API.chunked_upload_finalize(media_id)

Use this endpoint after the entire media file is uploaded via appending. If (and only if) the response contains a processing_info field, it may also be necessary to check its status and wait for it to return success before proceeding to Tweet creation.

Parameters

media_id – The media_id returned from the initialization.

Returns

Return type

Media

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/post-media-upload-finalize

API.chunked_upload_init(total_bytes, media_type, *, media_category, additional_owners)

Use this endpoint to initiate a chunked file upload session.

Parameters
  • total_bytes – The size of the media being uploaded in bytes.

  • media_type – The MIME type of the media being uploaded.

  • media_category – The category that represents how the media will be used. This field is required when using the media with the Ads API.

  • additional_owners – A list of user IDs to set as additional owners allowed to use the returned media_id in Tweet or Cards. Up to 100 additional owners may be specified.

Returns

Return type

Media

References

https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/post-media-upload-init

Geo

Get information about a place

API.geo_id(place_id)

Given place_id, provide more details about that place.

Parameters

place_id – Valid Twitter ID of a location.

Returns

Return type

Place

References

https://developer.twitter.com/en/docs/twitter-api/v1/geo/place-information/api-reference/get-geo-id-place_id

Get places near a location

API.reverse_geocode(lat, long, *, accuracy, granularity, max_results)

Given a latitude and a longitude, searches for up to 20 places that can be used as a place_id when updating a status.

This request is an informative call and will deliver generalized results about geography.

Parameters
  • lat – The location’s latitude.

  • long – The location’s longitude.

  • accuracy – Specify the “region” in which to search, such as a number (then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet). If this is not passed in, then it is assumed to be 0m

  • granularity – Assumed to be neighborhood by default; can also be city.

  • max_results – A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to.

Returns

Return type

List[Place]

References

https://developer.twitter.com/en/docs/twitter-api/v1/geo/places-near-location/api-reference/get-geo-reverse_geocode

API.search_geo(*, lat, long, query, ip, granularity, max_results)

Search for places that can be attached to a Tweet via update_status(). Given a latitude and a longitude pair, an IP address, or a name, this request will return a list of all the valid places that can be used as the place_id when updating a status.

Conceptually, a query can be made from the user’s location, retrieve a list of places, have the user validate the location they are at, and then send the ID of this location with a call to update_status().

This is the recommended method to use find places that can be attached to update_status(). Unlike reverse_geocode() which provides raw data access, this endpoint can potentially re-order places with regards to the user who is authenticated. This approach is also preferred for interactive place matching with the user.

Some parameters in this method are only required based on the existence of other parameters. For instance, lat is required if long is provided, and vice-versa.

Changed in version 4.0: Renamed from API.geo_search

Parameters
  • lat – The latitude to search around. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding long parameter.

  • long – The longitude to search around. The valid ranges for longitude are -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is turned off, or if there not a corresponding lat parameter.

  • query – Free-form text to match against while executing a geo-based query, best suited for finding nearby locations by name.

  • ip – An IP address. Used when attempting to fix geolocation based off of the user’s IP address.

  • granularity

    This is the minimal granularity of place types to return and must be one of: neighborhood, city, admin or country. If no granularity is provided for the request neighborhood is assumed.

    Setting this to city, for example, will find places which have a type of city, admin or country.

  • max_results – A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many “nearby” results to return. Ideally, only pass in the number of places you intend to display to the user here.

Returns

Return type

List[Place]

References

https://developer.twitter.com/en/docs/twitter-api/v1/geo/places-near-location/api-reference/get-geo-search

Developer utilities

Get Twitter supported languages

API.supported_languages()

Returns the list of languages supported by Twitter along with the language code supported by Twitter.

The language code may be formatted as ISO 639-1 alpha-2 (en), ISO 639-3 alpha-3 (msa), or ISO 639-1 alpha-2 combined with an ISO 3166-1 alpha-2 localization (zh-tw).

Returns

JSON

Return type

dict

References

https://developer.twitter.com/en/docs/twitter-api/v1/developer-utilities/supported-languages/api-reference/get-help-languages

Get app rate limit status

API.rate_limit_status(*, resources)

Returns the current rate limits for methods belonging to the specified resource families. When using application-only auth, this method’s response indicates the application-only auth rate limiting context.

Parameters

resources – A comma-separated list of resource families you want to know the current rate limit disposition for.

Returns

JSON

Return type

dict

References

https://developer.twitter.com/en/docs/twitter-api/v1/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status

Footnotes

1

https://web.archive.org/web/20170829051949/https://dev.twitter.com/rest/reference/get/search/tweets

2

https://twittercommunity.com/t/favorited-reports-as-false-even-if-status-is-already-favorited-by-the-user/11145