api.rst 28.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
.. _api_reference:

.. include:: parameters.rst

API Reference
=============

This page contains some basic documentation for the Tweepy module.


:mod:`tweepy.api` --- Twitter API wrapper
=========================================

14
.. class:: API([auth_handler=None], [host='api.twitter.com'], [search_host='search.twitter.com'], [cache=None], [api_root='/1'], [search_root=''], [retry_count=0], [retry_delay=0], [retry_errors=None], [timeout=60], [parser=ModelParser], [compression=False], [wait_on_rate_limit=False], [wait_on_rate_limit_notify=False], [proxy=None])
15 16 17 18 19 20 21 22 23 24 25 26 27

   This class provides a wrapper for the API as provided by
   Twitter. The functions provided in this class are listed below.

   :param auth_handler: authentication handler to be used
   :param host: general API host
   :param search_host: search API host
   :param cache: cache backend to use
   :param api_root: general API path root
   :param search_root: search API path root
   :param retry_count: default number of retries to attempt when error occurs
   :param retry_delay: number of seconds to wait between retries
   :param retry_errors: which HTTP status codes to retry
28 29 30 31 32 33
   :param timeout: The maximum amount of time to wait for a response from Twitter
   :param parser: The object to use for parsing the response from Twitter
   :param compression: Whether or not to use GZIP compression for requests
   :param wait_on_rate_limit: Whether or not to automatically wait for rate limits to replenish
   :param wait_on_rate_limit_notify: Whether or not to print a notification when Tweepy is waiting for rate limits to replenish
   :param proxy: The full url to an HTTPS proxy to use for connecting to Twitter.
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49

Timeline methods
----------------

.. method:: API.home_timeline([since_id], [max_id], [count], [page])

   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.

   :param since_id: |since_id|
   :param max_id: |max_id|
   :param count: |count|
   :param page: |page|
   :rtype: list of :class:`Status` objects

50
.. method:: API.statuses_lookup(id_, [include_entities], [trim_user], [map_])
Aaron Hill's avatar
Aaron Hill committed
51 52 53 54

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

55
   :param id_: A list of Tweet IDs to lookup, up to 100
Aaron Hill's avatar
Aaron Hill committed
56 57
   :param include_entities: A boolean indicating whether or not to include [entities](https://dev.twitter.com/docs/entities) in the returned tweets. Defaults to False.
   :param trim_user: A boolean indicating if user IDs should be provided, instead of full user information. Defaults to False.
58
   :param map_: A boolean indicating whether or not to include tweets that cannot be shown, but with a value of None. Defaults to False.
Aaron Hill's avatar
Aaron Hill committed
59
   :rtype: list of :class:`Status` objects
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88


.. method:: API.user_timeline([id/user_id/screen_name], [since_id], [max_id], [count], [page])

   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.

   :param id: |uid|
   :param user_id: |user_id|
   :param screen_name: |screen_name|
   :param since_id: |since_id|
   :param max_id: |max_id|
   :param count: |count|
   :param page: |page|
   :rtype: list of :class:`Status` objects


.. method:: API.retweets_of_me([since_id], [max_id], [count], [page])

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

   :param since_id: |since_id|
   :param max_id: |max_id|
   :param count: |count|
   :param page: |page|
   :rtype: list of :class:`Status` objects

89 90
.. method:: API.mentions_timeline([since_id], [max_id], [count])

91
   Returns the 20 most recent mentions, including retweets.
92 93 94 95 96

   :param since_id: |since_id|
   :param max_id: |max_id|
   :param count: |count|
   :rtype: list of :class:`Status` objects
97 98 99 100 101 102 103 104 105 106 107 108

Status methods
--------------

.. method:: API.get_status(id)

   Returns a single status specified by the ID parameter.

   :param id: |sid|
   :rtype: :class:`Status` object


109
.. method:: API.update_status(status, [in_reply_to_status_id], [auto_populate_reply_metadata], [lat], [long], [source], [place_id])
110 111 112 113 114 115

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

   :param status: The text of your status update.
   :param in_reply_to_status_id: The ID of an existing status that the update is in reply to.
116
   :param auto_populate_reply_metadata: Whether to automatically include the @mentions in the status metadata.
117 118 119
   :param lat: The location's latitude that this tweet refers to.
   :param long: The location's longitude that this tweet refers to.
   :param source: Source of the update. Only supported by Identi.ca. Twitter ignores this parameter.
Aaron Hill's avatar
Aaron Hill committed
120
   :param place_id: Twitter ID of location which is listed in the Tweet if geolocation is enabled for the user.
121 122 123
   :rtype: :class:`Status` object


124
.. method:: API.update_with_media(filename, [status], [in_reply_to_status_id], [auto_populate_reply_metadata], [lat], [long], [source], [place_id], [file])
Aaron Hill's avatar
Aaron Hill committed
125

126
   *Deprecated*: Use :func:`API.media_upload` instead. Update the authenticated user's status. Statuses that are duplicates
Aaron Hill's avatar
Aaron Hill committed
127 128 129 130 131
   or too long will be silently ignored.

   :param filename: The filename of the image to upload. This will automatically be opened unless `file` is specified
   :param status: The text of your status update.
   :param in_reply_to_status_id: The ID of an existing status that the update is in reply to.
132
   :param auto_populate_reply_metadata: Whether to automatically include the @mentions in the status metadata.
Aaron Hill's avatar
Aaron Hill committed
133 134 135 136 137 138 139 140
   :param lat: The location's latitude that this tweet refers to.
   :param long: The location's longitude that this tweet refers to.
   :param source: Source of the update. Only supported by Identi.ca. Twitter ignores this parameter.
   :param place_id: Twitter ID of location which is listed in the Tweet if geolocation is enabled for the user.
   :param 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
   :rtype: :class:`Status` object


141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
.. method:: API.destroy_status(id)

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

   :param id: |sid|
   :rtype: :class:`Status` object


.. method:: API.retweet(id)

   Retweets a tweet. Requires the id of the tweet you are retweeting.

   :param id: |sid|
   :rtype: :class:`Status` object


.. method:: API.retweets(id[,count])

   Returns up to 100 of the first retweets of the given tweet.

   :param id: |sid|
   :param count: Specifies the number of retweets to retrieve.
   :rtype: list of :class:`Status` objects


User methods
------------

.. method:: API.get_user(id/user_id/screen_name)

   Returns information about the specified user.

   :param id: |uid|
   :param user_id: |user_id|
   :param screen_name: |screen_name|
   :rtype: :class:`User` object


.. method:: API.me()

   Returns the authenticated user's information.

   :rtype: :class:`User` object


187
.. method::API.friends([id/user_id/screen_name], [cursor], [skip_status], [include_user_entities])
188 189 190 191 192 193 194

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

   :param id: |uid|
   :param user_id: |user_id|
   :param screen_name: |screen_name|
   :param cursor: |cursor|
195 196
   :param skip_status: |skip_status|
   :param include_user_entities: |include_user_entities|
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228
   :rtype: list of :class:`User` objects


.. method:: API.followers([id/screen_name/user_id], [cursor])

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

   :param id: |uid|
   :param user_id: |user_id|
   :param screen_name: |screen_name|
   :param cursor: |cursor|
   :rtype: list of :class:`User` objects

.. method:: API.search_users(q, [per_page], [page])

   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.

   :param q: The query to run against people search.
   :param per_page: Specifies the number of statuses to retrieve. May not be greater than 20.
   :param page: |page|
   :rtype: list of :class:`User` objects


Direct Message Methods
----------------------

229
.. method:: API.direct_messages([since_id], [max_id], [count], [page], [full_text])
230 231 232 233 234 235 236

   Returns direct messages sent to the authenticating user.

   :param since_id: |since_id|
   :param max_id: |max_id|
   :param count: |count|
   :param page: |page|
237
   :param full_text: |full_text|
238 239 240
   :rtype: list of :class:`DirectMessage` objects


241 242 243 244 245 246 247 248 249 250
.. method:: API.get_direct_message([id], [full_text])

   Returns a specific direct message.

   :param id: |id|
   :param full_text: |full_text|
   :rtype: :class:`DirectMessage` object


.. method:: API.sent_direct_messages([since_id], [max_id], [count], [page], [full_text])
251 252 253 254 255 256 257

   Returns direct messages sent by the authenticating user.

   :param since_id: |since_id|
   :param max_id: |max_id|
   :param count: |count|
   :param page: |page|
258
   :param full_text: |full_text|
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549
   :rtype: list of :class:`DirectMessage` objects


.. method:: API.send_direct_message(user/screen_name/user_id, text)

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

   :param user: The ID or screen name of the recipient user.
   :param screen_name: screen name of the recipient user
   :param user_id: user id of the recipient user
   :rtype: :class:`DirectMessage` object


.. method:: API.destroy_direct_message(id)

   Destroy a direct message. Authenticating user must be the recipient of
   the direct message.

   :param id: The ID of the direct message to destroy.
   :rtype: :class:`DirectMessage` object


Friendship Methods
------------------

.. method:: API.create_friendship(id/screen_name/user_id[,follow])

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

   :param id: |uid|
   :param screen_name: |screen_name|
   :param user_id: |user_id|
   :param follow: Enable notifications for the target user in addition to becoming friends.
   :rtype: :class:`User` object


.. method:: API.destroy_friendship(id/screen_name/user_id)

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

   :param id: |uid|
   :param screen_name: |screen_name|
   :param user_id: |user_id|
   :rtype: :class:`User` object


.. method:: API.show_friendship(source_id/source_screen_name, target_id/target_screen_name)

   Returns detailed information about the relationship between two users.

   :param source_id: The user_id of the subject user.
   :param source_screen_name: The screen_name of the subject user.
   :param target_id: The user_id of the target user.
   :param target_screen_name: The screen_name of the target user.
   :rtype: :class:`Friendship` object


.. method:: API.friends_ids(id/screen_name/user_id[,cursor])

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

   :param id: |uid|
   :param screen_name: |screen_name|
   :param user_id: |user_id|
   :param cursor: |cursor|
   :rtype: list of Integers


.. method:: API.followers_ids(id/screen_name/user_id)

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

   :param id: |uid|
   :param screen_name: |screen_name|
   :param user_id: |user_id|
   :param cursor: |cursor|
   :rtype: list of Integers


Account Methods
---------------

.. method:: API.verify_credentials()

   Verify the supplied user credentials are valid.

   :rtype: :class:`User` object if credentials are valid, otherwise False


.. method:: API.rate_limit_status()

   Returns the remaining number of API requests available to the
   requesting user before the API limit is reached for the current
   hour. Calls to rate_limit_status do not count against the rate
   limit. If authentication credentials are provided, the rate limit
   status for the authenticating user is returned. Otherwise, the rate
   limit status for the requester's IP address is returned.

   :rtype: :class:`JSON` object


.. method:: API.set_delivery_device(device)

   Sets which device Twitter delivers updates to for the authenticating
   user. Sending "none" as the device parameter will disable SMS updates.

   :param device: Must be one of: sms, none
   :rtype: :class:`User` object


.. method:: API.update_profile_colors([profile_background_color], [profile_text_color], [profile_link_color], [profile_sidebar_fill_color], [profile_sidebar_border_color])

   Sets one or more hex values that control the color scheme of the
   authenticating user's profile page on twitter.com.

   :param profile_background_color:
   :param profile_text_color:
   :param profile_link_color:
   :param profile_sidebar_fill_color:
   :param profile_sidebar_border_color:
   :rtype: :class:`User` object


.. method:: API.update_profile_image(filename)

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

   :param filename: local path to image file to upload. Not a remote URL!
   :rtype: :class:`User` object


.. method:: API.update_profile_background_image(filename)

   Update authenticating user's background image. Valid formats: GIF,
   JPG, or PNG

   :param filename: local path to image file to upload. Not a remote URL!
   :rtype: :class:`User` object


.. method:: API.update_profile([name], [url], [location], [description])

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

   :param name: Maximum of 20 characters
   :param url: Maximum of 100 characters. Will be prepended with "http://" if not present
   :param location: Maximum of 30 characters
   :param description: Maximum of 160 characters
   :rtype: :class:`User` object


Favorite Methods
----------------

.. method:: API.favorites([id], [page])

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

   :param id: The ID or screen name of the user to request favorites
   :param page: |page|
   :rtype: list of :class:`Status` objects


.. method:: API.create_favorite(id)

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

   :param id: |sid|
   :rtype: :class:`Status` object


.. method:: API.destroy_favorite(id)

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

   :param id: |sid|
   :rtype: :class:`Status` object


Block Methods
-------------

.. method:: API.create_block(id/screen_name/user_id)

   Blocks the user specified in the ID parameter as the authenticating
   user. Destroys a friendship to the blocked user if it exists.

   :param id: |uid|
   :param screen_name: |screen_name|
   :param user_id: |user_id|
   :rtype: :class:`User` object


.. method:: API.destroy_block(id/screen_name/user_id)

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

   :param id: |uid|
   :param screen_name: |screen_name|
   :param user_id: |user_id|
   :rtype: :class:`User` object


.. method:: API.blocks([page])

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

   :param page: |page|
   :rtype: list of :class:`User` objects


.. method:: API.blocks_ids()

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

   :rtype: list of Integers


Spam Reporting Methods
----------------------

.. method:: API.report_spam([id/user_id/screen_name])

   The user specified in the id is blocked by the authenticated user and
   reported as a spammer.

   :param id: |uid|
   :param screen_name: |screen_name|
   :param user_id: |user_id|
   :rtype: :class:`User` object


Saved Searches Methods
----------------------

.. method:: API.saved_searches()

   Returns the authenticated user's saved search queries.

   :rtype: list of :class:`SavedSearch` objects


.. method:: API.get_saved_search(id)

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

   :param id: The id of the saved search to be retrieved.
   :rtype: :class:`SavedSearch` object


.. method:: API.create_saved_search(query)

   Creates a saved search for the authenticated user.

   :param query: The query of the search the user would like to save.
   :rtype: :class:`SavedSearch` object


.. method:: 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.

   :param id: The id of the saved search to be deleted.
   :rtype: :class:`SavedSearch` object


Help Methods
------------

.. method:: API.search(q[,lang],[locale],[rpp],[page],[since_id],[geocode],[show_user])

   Returns tweets that match a specified query.

   :param q: the search query string
   :param lang: Restricts tweets to the given language, given by an ISO 639-1 code.
   :param locale: Specify the language of the query you are sending. This is intended for language-specific clients and the default should work in the majority of cases.
   :param rpp: The number of tweets to return per page, up to a max of 100.
   :param page: The page number (starting at 1) to return, up to a max of roughly 1500 results (based on rpp * page.
rother's avatar
rother committed
550
   :param since_id: |since_id|
551 552
   :param 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 "latitide,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.
   :param show_user: When true, prepends "<user>:" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is false.
553
   :rtype: list of :class:`SearchResults` objects
554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716


List Methods
------------

.. method:: API.create_list(name, [mode], [description])

   Creates a new list for the authenticated user. Accounts are limited to
   20 lists.

   :param name: The name of the new list.
   :param mode: |list_mode|
   :param description: The description of the list you are creating.
   :rtype: :class:`List` object


.. method:: API.destroy_list(slug)

   Deletes the specified list. Must be owned by the authenticated user.

   :param slug: |slug|
   :rtype: :class:`List` object


.. method:: API.update_list(slug, [name], [mode], [description])

   Updates the specified list. Note: this current throws a 500. Twitter
   is looking into the issue.

   :param slug: |slug|
   :param name: What you'd like to change the lists name to.
   :param mode: |list_mode|
   :param description: What you'd like to change the list description to.
   :rtype: :class:`List` object


.. method:: API.lists([cursor])

   List the lists of the specified user. Private lists will be included
   if the authenticated users is the same as the user who's lists are
   being returned.

   :param cursor: |cursor|
   :rtype: list of :class:`List` objects


.. method:: API.lists_memberships([cursor])

   List the lists the specified user has been added to.

   :param cursor: |cursor|
   :rtype: list of :class:`List` objects


.. method:: API.lists_subscriptions([cursor])

   List the lists the specified user follows.

   :param cursor: |cursor|
   :rtype: list of :class:`List` objects


.. method:: API.list_timeline(owner, slug, [since_id], [max_id], [per_page], [page])

   Show tweet timeline for members of the specified list.

   :param owner: |list_owner|
   :param slug: |slug|
   :param since_id: |since_id|
   :param max_id: |max_id|
   :param per_page: Number of results per a page
   :param page: |page|
   :rtype: list of :class:`Status` objects


.. method:: API.get_list(owner, slug)

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

   :param owner: |list_owner|
   :param slug: |slug|
   :rtype: :class:`List` object


.. method:: API.add_list_member(slug, 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 having 500 members.

   :param slug: |slug|
   :param id: the ID of the user to add as a member
   :rtype: :class:`List` object


.. method:: API.remove_list_member(slug, id)

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

   :param slug: |slug|
   :param id: the ID of the user to remove as a member
   :rtype: :class:`List` object


.. method:: API.list_members(owner, slug, cursor)

   Returns the members of the specified list.

   :param owner: |list_owner|
   :param slug: |slug|
   :param cursor: |cursor|
   :rtype: list of :class:`User` objects


.. method:: API.is_list_member(owner, slug, id)

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

   :param owner: |list_owner|
   :param slug: |slug|
   :param id: the ID of the user to check
   :rtype: :class:`User` object if user is a member of list, otherwise False.


.. method:: API.subscribe_list(owner, slug)

   Make the authenticated user follow the specified list.

   :param owner: |list_owner|
   :param slug: |slug|
   :rtype: :class:`List` object


.. method:: API.unsubscribe_list(owner, slug)

   Unsubscribes the authenticated user form the specified list.

   :param owner: |list_owner|
   :param slug: |slug|
   :rtype: :class:`List` object


.. method:: API.list_subscribers(owner, slug, [cursor])

   Returns the subscribers of the specified list.

   :param owner: |list_owner|
   :param slug: |slug|
   :param cursor: |cursor|
   :rtype: list of :class:`User` objects


.. method:: API.is_subscribed_list(owner, slug, id)

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

   :param owner: |list_owner|
   :param slug: |slug|
   :param id: the ID of the user to check
   :rtype: :class:`User` object if user is subscribed to the list, otherwise False.


717
Trends Methods
718 719
--------------------

720
.. method:: API.trends_available()
721

722
   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.
723

724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748
   :rtype: :class:`JSON` object


.. method:: API.trends_place(id, [exclude])

   Returns the top 10 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.

   :param 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.
   :param exclude: Setting this equal to hashtags will remove all hashtags from the trends list.
   :rtype: :class:`JSON` object

.. method:: API.trends_closest(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.

   :param 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.
   :param 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.
749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790
   :rtype: :class:`JSON` object


Geo Methods
-----------

.. method:: API.reverse_geocode([lat], [long], [accuracy], [granularity], [max_results])

   Given a latitude and longitude, looks for places (cities and
   neighbourhoods) whose IDs can be specified in a call to
   :func:`update_status` to appear as the name of the location. This
   call provides a detailed response about the location in question;
   the :func:`nearby_places` function should be preferred for getting
   a list of places nearby without great detail.

   :param lat: The location's latitude.
   :param long: The location's longitude.
   :param 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
   :param granularity: Assumed to be `neighborhood' by default; can also be `city'.
   :param max_results: A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to.

.. method:: API.reverse_geocode([lat], [long], [ip], [accuracy], [granularity], [max_results])

   Given a latitude and longitude, looks for nearby places (cities and
   neighbourhoods) whose IDs can be specified in a call to
   :func:`update_status` to appear as the name of the location. This
   call provides a detailed response about the location in question;
   the :func:`nearby_places` function should be preferred for getting
   a list of places nearby without great detail.

   :param lat: The location's latitude.
   :param long: The location's longitude.
   :param ip: The location's IP address. Twitter will attempt to geolocate using the IP address.
   :param 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
   :param granularity: Assumed to be `neighborhood' by default; can also be `city'.
   :param max_results: A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to.

.. method:: API.geo_id(id)

   Given *id* of a place, provide more details about that place.

   :param id: Valid Twitter ID of a location.
obskyr's avatar
obskyr committed
791

792 793 794 795 796 797 798 799 800

Utility methods
---------------

.. method:: API.configuration()

   Returns the current configuration used by Twitter including twitter.com slugs which are not usernames, maximum photo resolutions, and t.co shortened URL length.
   It is recommended applications request this endpoint when they are loaded, but no more than once a day.

801 802 803 804 805 806 807 808 809
Media methods
-------------

.. method:: API.media_upload()

   Uploads images to twitter and returns a `media_id`.

   :param media: The raw binary file content being uploaded. Cannot be used with `media_data`.
   :param media_data: The base64-encoded file content being uploaded. Cannot be used with `media`.
Chris Johnston's avatar
Chris Johnston committed
810
   :param additional_owners: A comma-separated list of user IDs to set as additional owners allowed to use the returned `media_id` in Tweets or Cards. Up to 100 additional owners may be specified.
811

obskyr's avatar
obskyr committed
812 813 814 815 816 817 818 819
:mod:`tweepy.error` --- Exceptions
==================================

The exceptions are available in the ``tweepy`` module directly,
which means ``tweepy.error`` itself does not need to be imported. For
example, ``tweepy.error.TweepError`` is available as ``tweepy.TweepError``.

.. exception:: TweepError
820

obskyr's avatar
obskyr committed
821
   The main exception Tweepy uses. Is raised for a number of things.
822

obskyr's avatar
obskyr committed
823 824 825
   When a ``TweepError`` is raised due to an error Twitter responded with,
   the error code (`as described in the API documentation
   <https://dev.twitter.com/overview/api/response-codes>`_) can be accessed
fefzero's avatar
fefzero committed
826
   at ``TweepError.response.text``. Note, however, that ``TweepError``\ s
obskyr's avatar
obskyr committed
827 828 829 830
   also may be raised with other things as message (for example plain
   error reason strings).

.. exception:: RateLimitError
831

obskyr's avatar
obskyr committed
832 833
   Is raised when an API method fails due to hitting Twitter's rate
   limit. Makes for easy handling of the rate limit specifically.
834

obskyr's avatar
obskyr committed
835 836
   Inherits from :exc:`TweepError`, so ``except TweepError`` will
   catch a ``RateLimitError`` too.