Add API.search_30_day and API.search_full_archive

diff --git a/docs/api.rst b/docs/api.rst
index 6c9e9c0bc4b6e3e180511264108f4d8391094f81..e5c283c5f0f86d8f5b539c50f8bc16cfa3611066 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -713,8 +713,8 @@ Saved Searches Methods
    :rtype: :class:`SavedSearch` object
 
 
-Help Methods
-------------
+Search Methods
+--------------
 
 .. method:: API.search(q, [geocode], [lang], [locale], [result_type], \
                        [count], [until], [since_id], [max_id], \
@@ -768,6 +768,101 @@ Help Methods
    :rtype: :class:`SearchResults` object
 
 
+.. method:: API.search_30_day(environment_name, query, [tag], [fromDate], \
+                              [toDate], [maxResults], [next])
+
+   Premium search that provides Tweets posted within the last 30 days.
+
+   :param environment_name: The (case-sensitive) label associated with your
+      search developer environment, as displayed at
+      https://developer.twitter.com/en/account/environments.
+   :param query: The equivalent of one premium rule/filter, with up to 1,024
+      characters (256 with Sandbox dev environments).
+      This parameter should include ALL portions of the rule/filter, including
+      all operators, and portions of the rule should not be separated into
+      other parameters of the query.
+   :param tag: Tags can be used to segregate rules and their matching data into
+      different logical groups. If a rule tag is provided, the rule tag is
+      included in the 'matching_rules' attribute.
+      It is recommended to assign rule-specific UUIDs to rule tags and maintain
+      desired mappings on the client side.
+   :param fromDate: The oldest UTC timestamp (from most recent 30 days) from
+      which the Tweets will be provided. Timestamp is in minute granularity and
+      is inclusive (i.e. 12:00 includes the 00 minute).
+      Specified: Using only the fromDate with no toDate parameter will deliver
+      results for the query going back in time from now( ) until the fromDate.
+      Not Specified: If a fromDate is not specified, the API will deliver all
+      of the results for 30 days prior to now( ) or the toDate (if specified).
+      If neither the fromDate or toDate parameter is used, the API will deliver
+      all results for the most recent 30 days, starting at the time of the
+      request, going backwards.
+   :param toDate: The latest, most recent UTC timestamp to which the Tweets
+      will be provided. Timestamp is in minute granularity and is not inclusive
+      (i.e. 11:59 does not include the 59th minute of the hour).
+      Specified: Using only the toDate with no fromDate parameter will deliver
+      the most recent 30 days of data prior to the toDate.
+      Not Specified: If a toDate is not specified, the API will deliver all of
+      the results from now( ) for the query going back in time to the fromDate.
+      If neither the fromDate or toDate parameter is used, the API will deliver
+      all results for the entire 30-day index, starting at the time of the
+      request, going backwards.
+   :param maxResults: The maximum number of search results to be returned by a
+      request. A number between 10 and the system limit (currently 500, 100 for
+      Sandbox environments). By default, a request response will return 100
+      results.
+   :param next: This parameter is used to get the next 'page' of results. The
+      value used with the parameter is pulled directly from the response
+      provided by the API, and should not be modified.
+
+
+.. method:: API.search_full_archive(environment_name, query, [tag], \
+                                    [fromDate], [toDate], [maxResults], [next])
+
+   Premium search that provides Tweets from as early as 2006, starting with the
+   first Tweet posted in March 2006.
+
+   :param environment_name: The (case-sensitive) label associated with your
+      search developer environment, as displayed at
+      https://developer.twitter.com/en/account/environments.
+   :param query: The equivalent of one premium rule/filter, with up to 1,024
+      characters (256 with Sandbox dev environments).
+      This parameter should include ALL portions of the rule/filter, including
+      all operators, and portions of the rule should not be separated into
+      other parameters of the query.
+   :param tag: Tags can be used to segregate rules and their matching data into
+      different logical groups. If a rule tag is provided, the rule tag is
+      included in the 'matching_rules' attribute.
+      It is recommended to assign rule-specific UUIDs to rule tags and maintain
+      desired mappings on the client side.
+   :param fromDate: The oldest UTC timestamp (from most recent 30 days) from
+      which the Tweets will be provided. Timestamp is in minute granularity and
+      is inclusive (i.e. 12:00 includes the 00 minute).
+      Specified: Using only the fromDate with no toDate parameter will deliver
+      results for the query going back in time from now( ) until the fromDate.
+      Not Specified: If a fromDate is not specified, the API will deliver all
+      of the results for 30 days prior to now( ) or the toDate (if specified).
+      If neither the fromDate or toDate parameter is used, the API will deliver
+      all results for the most recent 30 days, starting at the time of the
+      request, going backwards.
+   :param toDate: The latest, most recent UTC timestamp to which the Tweets
+      will be provided. Timestamp is in minute granularity and is not inclusive
+      (i.e. 11:59 does not include the 59th minute of the hour).
+      Specified: Using only the toDate with no fromDate parameter will deliver
+      the most recent 30 days of data prior to the toDate.
+      Not Specified: If a toDate is not specified, the API will deliver all of
+      the results from now( ) for the query going back in time to the fromDate.
+      If neither the fromDate or toDate parameter is used, the API will deliver
+      all results for the entire 30-day index, starting at the time of the
+      request, going backwards.
+   :param maxResults: The maximum number of search results to be returned by a
+      request. A number between 10 and the system limit (currently 500, 100 for
+      Sandbox environments). By default, a request response will return 100
+      results.
+   :param next: This parameter is used to get the next 'page' of results. The
+      value used with the parameter is pulled directly from the response
+      provided by the API, and should not be modified.
+
+
 List Methods
 ------------
 

diff --git a/tweepy/api.py b/tweepy/api.py
index c8551a3b6fbea0a699d244fca132415bff2ea56e..eb442e1f18344f9f46909c6cf3b1f91e3ce3b191 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -1279,6 +1279,34 @@ class API(object):
                            'max_id', 'until', 'result_type', 'count',
                            'include_entities']
         )
+    
+    def search_30_day(self, environment_name, *args, **kwargs):
+        """ :reference: https://developer.twitter.com/en/docs/tweets/search/api-reference/premium-search
+            :allowed_param: 'query', 'tag', 'fromDate', 'toDate', 'maxResults',
+                            'next'
+        """
+        return bind_api(
+            api=self,
+            path='/tweets/search/30day/{}.json'.format(environment_name),
+            payload_type='status', payload_list=True,
+            allowed_param=['query', 'tag', 'fromDate', 'toDate', 'maxResults',
+                           'next'],
+            require_auth=True
+        )(*args, **kwargs)
+    
+    def search_full_archive(self, environment_name, *args, **kwargs):
+        """ :reference: https://developer.twitter.com/en/docs/tweets/search/api-reference/premium-search
+            :allowed_param: 'query', 'tag', 'fromDate', 'toDate', 'maxResults',
+                            'next'
+        """
+        return bind_api(
+            api=self,
+            path='/tweets/search/fullarchive/{}.json'.format(environment_name),
+            payload_type='status', payload_list=True,
+            allowed_param=['query', 'tag', 'fromDate', 'toDate', 'maxResults',
+                           'next'],
+            require_auth=True
+        )(*args, **kwargs)
 
     @property
     def reverse_geocode(self):

diff --git a/tweepy/models.py b/tweepy/models.py
index 7c33d8f52453d2d4c8f54d0fac35493af18da013..5cea45299f0f8ec597e7669dba91ee3c0250d571 100644 (file)
--- a/tweepy/models.py
+++ b/tweepy/models.py
@@ -61,14 +61,18 @@ class Model(object):
         """
         results = ResultSet()
 
-        # Handle map parameter for statuses/lookup
-        if isinstance(json_list, dict) and 'id' in json_list:
-            for _id, obj in json_list['id'].items():
-                if obj:
-                    results.append(cls.parse(api, obj))
-                else:
-                    results.append(cls.parse(api, {'id': int(_id)}))
-            return results
+        if isinstance(json_list, dict):
+            # Handle map parameter for statuses/lookup
+            if 'id' in json_list:
+                for _id, obj in json_list['id'].items():
+                    if obj:
+                        results.append(cls.parse(api, obj))
+                    else:
+                        results.append(cls.parse(api, {'id': int(_id)}))
+                return results
+            # Handle premium search
+            if 'results' in json_list:
+                json_list = json_list['results']
 
         for obj in json_list:
             if obj: