Document API.geo_search

Automatically use docstring for documentation
Improve method order

diff --git a/docs/api.rst b/docs/api.rst
index 729b743fbfb2f22328096cc9eb66f2b67da08581..4c72ccde289cc34f070ab39172dd4b897fb7152d 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -253,6 +253,8 @@ Get places near a location
 
 .. automethod:: API.reverse_geocode
 
+.. automethod:: API.geo_search
+
 
 Account Methods
 ---------------

diff --git a/tweepy/api.py b/tweepy/api.py
index 2153c4fe93ce104d1a53e9a51cf96506c895bb48..e8b8285a9284ac4d0a5acda06fc73fe51695e787 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -2709,6 +2709,66 @@ class API:
             ), lat=lat, long=long, **kwargs
         )
 
+    @payload('place', list=True)
+    def geo_search(self, **kwargs):
+        """geo_search(*, lat, long, query, ip, granularity, max_results)
+
+        Search for places that can be attached to a Tweet via
+        :func:`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 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
+        :func:`API.update_status`.
+
+        This is the recommended method to use find places that can be attached
+        to :func:`API.update_status`. Unlike :func:`API.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.
+
+        :param 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.
+        :param 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.
+        :param query: Free-form text to match against while executing a
+            geo-based query, best suited for finding nearby locations by name.
+        :param ip: An IP address. Used when attempting to fix geolocation based
+                   off of the user's IP address.
+        :param 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``.
+        :param 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.
+
+        :rtype: list of :class:`Place` objects
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/geo/places-near-location/api-reference/get-geo-search
+        """
+        return self.request(
+            'GET', 'geo/search', endpoint_parameters=(
+                'lat', 'long', 'query', 'ip', 'granularity', 'max_results'
+            ), **kwargs
+        )
+
     @payload('json')
     def rate_limit_status(self, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status
@@ -2741,16 +2801,6 @@ class API:
             ), query=query, **kwargs
         )
 
-    @payload('place', list=True)
-    def geo_search(self, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/geo/places-near-location/api-reference/get-geo-search
-        """
-        return self.request(
-            'GET', 'geo/search', endpoint_parameters=(
-                'lat', 'long', 'query', 'ip', 'granularity', 'max_results'
-            ), **kwargs
-        )
-
     @payload('json')
     def supported_languages(self, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/developer-utilities/supported-languages/api-reference/get-help-languages