From a51a097c13b31a5ce290749b280455cb93f970cb Mon Sep 17 00:00:00 2001 From: Harmon Date: Sun, 11 Apr 2021 15:19:48 -0500 Subject: [PATCH] Document API.geo_search Automatically use docstring for documentation Improve method order --- docs/api.rst | 2 ++ tweepy/api.py | 70 +++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 62 insertions(+), 10 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 729b743..4c72ccd 100644 --- 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 2153c4f..e8b8285 100644 --- 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 -- 2.25.1