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
- Parameters
auth – 用来做身份认证
cache – 查询是否使用了GET方法的缓存
host – REST API 服务主机URL
parser – 用于解析来自Twitter的响应的解析器实例；默认为ModelParser的实例
proxy – 用于连接到Twitter的HTTPS代理url
retry_count – 发生错误时的重试次数
retry_delay – 重试之间等待的秒数
retry_errors – 要重试的HTTP状态代码
timeout – 最大等待Twitter响应时间
upload_host – 上传服务的url
wait_on_rate_limit – 是否开启自动速率限制
- Raises
TypeError – If the given parser is not a Parser instance
References
Twitter API v1.1 Endpoint |
|
|---|---|
Tweets
Get Tweet timelines
- API.home_timeline(*, count, since_id, max_id, trim_user, exclude_replies, include_entities)
返回用户发布的最多20条最新推文（包括转推）。这相当于web上的主页/日程表。
- Parameters
count – 每页返回的结果数。
since_id – 只返回tweet_id大于指定id（即比指定tweet_id 近）的推文，推文越早发表tweet_id越小。
max_id – 只返回tweet_id小于（即早于）或等于指定tweet_id的推文。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
exclude_replies – 此参数将阻止回复出现在返回的结果中。 将
exclude_replies与count参数一起使用将意味着您将收到最多 count 个推文——这是因为 count 参数会在过滤掉转发和回复之前检索那么多推文。include_entities – 设置为false时，将不包括entities节点。默认为true。
- Return type
References
- API.mentions_timeline(*, count, since_id, max_id, trim_user, include_entities)
返回最近的 20 次提及，包括转发。
- Parameters
count – 每页返回的结果数。
since_id – 只返回tweet_id大于指定id（即比指定tweet_id 近）的推文，推文越早发表tweet_id越小。
max_id – 只返回tweet_id小于（即早于）或等于指定tweet_id的推文。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
include_entities – 设置为false时，将不包括entities节点。默认为true。
- Return type
References
- API.user_timeline(*, user_id, screen_name, since_id, count, max_id, trim_user, exclude_replies, include_rts)
返回验证用户或指定用户发布的 20 个最新推文。 也可以通过 id 参数请求另一个用户的时间线。
- Parameters
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
since_id – 只返回tweet_id大于指定id（即比指定tweet_id 近）的推文，推文越早发表tweet_id越小。
count – 每页返回的结果数。
max_id – 只返回tweet_id小于（即早于）或等于指定tweet_id的推文。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
exclude_replies – 此参数将阻止回复出现在返回的结果中。 将
exclude_replies与count参数一起使用将意味着您将收到最多 count 个推文——这是因为 count 参数会在过滤掉转发和回复之前检索那么多推文。include_rts – 当设置为
false时，返回将剔除当前用户的转推（尽管它们仍将计入返回的总数和由 count 参数选择的切片）。 注意：如果您将 trim_user 参数与 include_rts 结合使用，则转推仍将包含完整的用户对象。
- Return type
References
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 – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
count – 每页返回的结果数。
since_id – 只返回tweet_id大于指定id（即比指定tweet_id 近）的推文，推文越早发表tweet_id越小。
max_id – 只返回tweet_id小于（即早于）或等于指定tweet_id的推文。
include_entities – 设置为false时，将不包括entities节点。默认为true。
- Return type
References
- 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
idparameter.Changed in version 4.0: Renamed from
API.statuses_lookup- Parameters
id – A list of Tweet IDs to lookup, up to 100
include_entities – 设置为false时，将不包括entities节点。默认为true。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
map – 一个布尔值，表示是否返回无法展示的推文。默认为False。
include_ext_alt_text – 如果已将alt text添加到任何连接的媒体实体，此参数将在媒体实体的 top-level 键中返回 ext_alt_text 属性。
include_card_uri – 一个布尔值，表示搜索到的推文是否应包含 card_uri 属性，当有广告卡链接到推文时，搜索到的推文是否应包含 card_uri 属性。
- Return type
References
- 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
widthproperty. Note that Twitter does not support the oEmbedmaxheightparameter. 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 forheight. Implementations that need consistent heights for Tweets should refer to thehide_threadandhide_mediaparameters below.hide_media – When set to
true,"t", or1, links in a Tweet are not expanded to photo, video, or link previews.hide_thread – When set to
true,"t", or1, 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", or1, the<script>responsible for loadingwidgets.jswill not be returned. Your webpages should include their own reference towidgets.jsfor 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
videoto 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
References
- API.get_retweeter_ids(id, *, count, cursor, stringify_ids)
返回转发某推文的最多100个用户
ID。Changed in version 4.0: Renamed from
API.retweeters- Parameters
id – 推文ID。
count – 每页返回的结果数。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。stringify_ids – 将ID作为字符串返回。
- Return type
References
- 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 – 推文ID。
count – 每页返回的结果数。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
- Return type
References
- 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 – 每页返回的结果数。
since_id – 只返回tweet_id大于指定id（即比指定tweet_id 近）的推文，推文越早发表tweet_id越小。
max_id – 只返回tweet_id小于（即早于）或等于指定tweet_id的推文。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
include_entities – 设置为false时，将不包括entities节点。默认为true。
include_user_entities – 设置为 false 时将不包含用户对象实体节点。 默认为true。
- Return type
References
- 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 – 推文ID。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
include_my_retweet – 一个布尔值，表示返回的当前用户转发的推文是否应包含一个额外的 current_user_retweet 节点，current_user_retweet 中包含转发的源推文ID。
include_entities – 设置为false时，将不包括entities节点。默认为true。
include_ext_alt_text – 如果已将alt text添加到任何连接的媒体实体，此参数将在媒体实体的 top-level 键中返回 ext_alt_text 属性。
include_card_uri – 一个布尔值，表示搜索到的推文是否应包含 card_uri 属性，当有广告卡链接到推文时，搜索到的推文是否应包含 card_uri 属性。
- Return type
References
- API.create_favorite(id, *, include_entities)
Favorites the status specified in the
idparameter as the authenticating user.- Parameters
id – 推文ID。
include_entities – 设置为false时，将不包括entities节点。默认为true。
- Return type
References
- API.destroy_favorite(id, *, include_entities)
Un-favorites the status specified in the
idparameter as the authenticating user.- Parameters
id – 推文ID。
include_entities – 设置为false时，将不包括entities节点。默认为true。
- Return type
References
- API.destroy_status(id, *, trim_user)
Destroy the status specified by the
idparameter. The authenticated user must be the author of the status to destroy.- Parameters
id – 推文ID。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
- Return type
References
- API.retweet(id, *, trim_user)
Retweets a Tweet. Requires the ID of the Tweet you are retweeting.
- Parameters
id – 推文ID。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
- Return type
References
- API.unretweet(id, *, trim_user)
Untweets a retweeted status. Requires the ID of the retweet to unretweet.
- Parameters
id – 推文ID。
trim_user – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
- Return type
References
- 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 – 一个布尔值，指示是否应提供用户ID，而不是完整的用户对象。默认为False。
card_uri – Associate an ads card with the Tweet using the card_uri value from any ads card response.
- Return type
References
- 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.
Deprecated since version 3.7.0: Use
API.media_upload()instead.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
fileis specified.file – A file object, which will be used instead of opening
filename.filenameis 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.
- Return type
References
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 – 每页返回的结果数。
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 – 只返回tweet_id大于指定id（即比指定tweet_id 近）的推文，推文越早发表tweet_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 – 只返回tweet_id小于（即早于）或等于指定tweet_id的推文。
include_entities – 设置为false时，将不包括entities节点。默认为true。
- 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_idorscreen_nameparameters. 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
reversemethod returns owned lists first, so withreverse=true, 20 owned lists and 80 subscriptions would be returned.Changed in version 4.0: Renamed from
API.lists_all- Parameters
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
reverse – A boolean indicating if you would like owned lists to be returned first. See description above for information on how this parameter works.
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
count – 每页返回的结果数。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。include_entities – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
include_entities – 设置为false时，将不包括entities节点。默认为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.
- Return type
References
- 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_idorscreen_nameare not provided, the memberships for the authenticating user are returned.Changed in version 4.0: Renamed from
API.lists_memberships- Parameters
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
count – 每页返回的结果数。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。filter_to_owned_lists – A boolean indicating whether to return just lists the authenticating user owns, and the user represented by
user_idorscreen_nameis a member of.
- Return type
References
- 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_idandscreen_nameare not provided, the ownerships for the authenticating user are returned.- Parameters
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
count – 每页返回的结果数。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
- Return type
References
- 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=falseparameter to omit retweets.- Parameters
list_id – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
since_id – 只返回tweet_id大于指定id（即比指定tweet_id 近）的推文，推文越早发表tweet_id越小。
max_id – 只返回tweet_id小于（即早于）或等于指定tweet_id的推文。
count – 每页返回的结果数。
include_entities – 设置为false时，将不包括entities节点。默认为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.
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
count – 每页返回的结果数。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。include_entities – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
- Return type
References
- 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 – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
list_id – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
include_entities – 设置为false时，将不包括entities节点。默认为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.
- Return type
References
- 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 – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
count – 每页返回的结果数。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。
- Return type
References
- 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.
- Return type
References
- 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 – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
list_id – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
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 – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
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 – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
- Return type
References
- API.subscribe_list(*, owner_screen_name, owner_id, list_id, slug)
Subscribes the authenticated user to the specified list.
- Parameters
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
list_id – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
- Return type
References
- API.unsubscribe_list(*, list_id, slug, owner_screen_name, owner_id)
Unsubscribes the authenticated user from the specified list.
- Parameters
list_id – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
owner_screen_name – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
- Return type
References
- 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 – 列表的 ID。
slug – 您可以通过列表的slug而不是数字id来识别列表。如果您决定这样做，请注意，您还必须使用 owner_id 或 owner_screen_name 参数指定列表所有者。
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 – 拥有 slug 请求列表用户的昵称。
owner_id – 拥有 slug 请求列表用户的 ID。
- Return type
References
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 – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。stringify_ids – 将ID作为字符串返回。
count – 每页返回的结果数。
- Return type
References
- 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 – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。count – 每页返回的结果数。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
include_user_entities – 设置为 false 时将不包含用户对象实体节点。 默认为true。
- Return type
References
- 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 – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。stringify_ids – 将ID作为字符串返回。
count – 每页返回的结果数。
- Return type
References
- 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 – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。count – 每页返回的结果数。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
include_user_entities – 设置为 false 时将不包含用户对象实体节点。 默认为true。
- Return type
References
- 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 – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。stringify_ids – 将ID作为字符串返回。
- Return type
References
- 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.
- Return type
References
- API.no_retweets_friendships(*, stringify_ids)
Returns a collection of user_ids that the currently authenticated user does not want to receive retweets from.
References
- 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 – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。stringify_ids – 将ID作为字符串返回。
- Return type
References
- 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.
- Return type
References
- 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 – 设置为false时，将不包括entities节点。默认为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.
- Return type
References
- 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 – 每页返回的结果数。
include_entities – 设置为false时，将不包括entities节点。默认为true。
- Return type
References
- API.get_user(*, user_id, screen_name, include_entities)
Returns information about the specified user.
- Parameters
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
include_entities – 设置为false时，将不包括entities节点。默认为true。
- Return type
References
- API.create_friendship(*, screen_name, user_id, follow)
Create a new friendship with the specified user (aka follow).
- Parameters
screen_name – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
follow – Enable notifications for the target user in addition to becoming friends.
- Return type
References
- API.destroy_friendship(*, screen_name, user_id)
Destroy a friendship with the specified user (aka unfollow).
- Parameters
screen_name – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
- Return type
References
- API.update_friendship(*, screen_name, user_id, device, retweets)
Turn on/off Retweets and device notifications from the specified user.
- Parameters
screen_name – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
device – Turn on/off device notifications from the target user.
retweets – Turn on/off Retweets from the target user.
- Return type
References
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
References
- API.verify_credentials(*, include_entities, skip_status, include_email)
Verify the supplied user credentials are valid.
- Parameters
include_entities – 设置为false时，将不包括entities节点。默认为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
- Return type
References
- API.get_saved_searches()
Returns the authenticated user’s saved search queries.
Changed in version 4.0: Renamed from
API.saved_searches- Return type
References
- API.get_saved_search(id)
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.
- Return type
References
- 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 – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
screen_name – 指定用户的昵称。
- Returns
JSON
- Return type
References
- API.remove_profile_banner()
Removes the uploaded profile banner for the authenticating user.
References
- 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,tor1, 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_zonesetting.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_zonesetting.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
References
- 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 presentlocation – 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 – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
- Return type
References
- 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
fileis specified.file – A file object, which will be used instead of opening
filename.filenameis 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, andoffset_topto 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, andoffset_topto 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, andoffset_topto 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, andoffset_leftto select the desired region of the image to use.
References
- 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
fileis specified.file – A file object, which will be used instead of opening
filename.filenameis still required, for MIME type detection and to use as a form field in the POST data.include_entities – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
- Return type
References
- API.create_saved_search(query)
Creates a saved search for the authenticated user.
- Parameters
query – The query of the search the user would like to save.
- Return type
References
- API.destroy_saved_search(id)
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.
- Return type
References
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 – 将ID作为字符串返回。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。
- Return type
References
- 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 – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。
- Return type
References
- 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 – 将ID作为字符串返回。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。
- Return type
References
- 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 – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。include_entities – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
- Return type
References
- 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 – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
include_entities – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
- Return type
References
- 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 – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
include_entities – 设置为false时，将不包括entities节点。默认为true。
skip_status – A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false.
- Return type
References
- API.create_mute(*, screen_name, user_id)
Mutes the user specified in the ID parameter for the authenticating user.
- Parameters
screen_name – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
- Return type
References
- API.destroy_mute(*, screen_name, user_id)
Un-mutes the user specified in the ID parameter for the authenticating user.
- Parameters
screen_name – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
- Return type
References
- API.report_spam(*, screen_name, user_id, perform_block)
Report the specified user as a spam account to Twitter.
- Parameters
screen_name – 指定用户的昵称。
user_id – 指定用户的ID。当用户ID也是昵称时，有助于消除歧义。
perform_block – A boolean indicating if the reported account should be blocked. Defaults to True.
- Return type
References
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
- 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 – 每页返回的结果数。
cursor – 返回分页。 值为 -1 开始分页。 当值为上次请求返回的
next_cursor或previous_cursor时，可以上下翻页。
- Return type
References
- API.get_direct_message(id)
Returns a specific direct message.
- Parameters
id – The ID of the Direct Message event that should be returned.
- Return type
References
- 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
- Return type
References
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
- 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
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.
- Return type
References
- 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
- API.media_upload(filename, *, file, chunked, media_category, additional_owners)
Use this to upload media to Twitter. This calls either
API.simple_upload()orAPI.chunked_upload(). Chunked media upload is automatically used for videos. Ifchunkedis set or the media is a video,wait_for_async_finalizecan be specified as a keyword argument to be passed toAPI.chunked_upload().- Parameters
filename – The filename of the image to upload. This will automatically be opened unless
fileis specified.file – A file object, which will be used instead of opening
filename.filenameis 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_idin Tweet or Cards. Up to 100 additional owners may be specified.
- Return type
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
fileis specified.file – A file object, which will be used instead of opening
filename.filenameis 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_idin Tweet or Cards. Up to 100 additional owners may be specified.
- Return type
References
- 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
API.chunked_upload_init(),API.chunked_upload_append(), andAPI.chunked_upload_finalize(). Ifwait_for_async_finalizeis set, this callsAPI.get_media_upload_status()as well.- Parameters
filename – The filename of the image to upload. This will automatically be opened unless
fileis specified.file – A file object, which will be used instead of opening
filename.filenameis 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_idin Tweet or Cards. Up to 100 additional owners may be specified.
- Return type
References
- 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_idreturned 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
- 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_idreturned from the initialization.- Return type
References
- 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_idin Tweet or Cards. Up to 100 additional owners may be specified.
- Return type
References
Trends
Get locations with trending topics
- API.available_trends()
Returns the locations that Twitter has trending topic information for. The response is an array of “locations” that encode the location’s WOEID (a Yahoo! Where On Earth ID) and some other human-readable information such as a canonical name and country the location belongs in.
Changed in version 4.0: Renamed from
API.trends_available- Returns
JSON
- Return type
References
- API.closest_trends(lat, long)
Returns the locations that Twitter has trending topic information for, closest to a specified location.
The response is an array of “locations” that encode the location’s WOEID and some other human-readable information such as a canonical name and country the location belongs in.
A WOEID is a Yahoo! Where On Earth ID.
Changed in version 4.0: Renamed from
API.trends_closest- Parameters
lat – If provided with a long parameter the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (West is negative, East is positive) inclusive.
long – If provided with a lat parameter the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (West is negative, East is positive) inclusive.
- Returns
JSON
- Return type
References
Get trends near a location
- API.get_place_trends(id *, exclude)
Returns the top 50 trending topics for a specific WOEID, if trending information is available for it.
The response is an array of “trend” objects that encode the name of the trending topic, the query parameter that can be used to search for the topic on Twitter Search, and the Twitter Search URL.
This information is cached for 5 minutes. Requesting more frequently than that will not return any more data, and will count against your rate limit usage.
The tweet_volume for the last 24 hours is also returned for many trends if this is available.
Changed in version 4.0: Renamed from
API.trends_place- Parameters
id – The Yahoo! Where On Earth ID of the location to return trending information for. Global information is available by using 1 as the WOEID.
exclude – Setting this equal to hashtags will remove all hashtags from the trends list.
- Returns
JSON
- Return type
References
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.
- Return type
References
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_idwhen 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
neighborhoodby default; can also becity.max_results – A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to.
- Return type
References
- API.search_geo(*, lat, long, query, ip, granularity, max_results)
Search for places that can be attached to a Tweet via
API.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 theplace_idwhen 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
API.update_status().This is the recommended method to use find places that can be attached to
API.update_status(). UnlikeAPI.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,
latis required iflongis 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
longparameter.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_enabledis turned off, or if there not a correspondinglatparameter.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,adminorcountry. If no granularity is provided for the requestneighborhoodis assumed.Setting this to
city, for example, will find places which have a type ofcity,adminorcountry.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.
- Return type
References
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
References
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
References
Footnotes