diff --git a/gdeltdoc/filters.py b/gdeltdoc/filters.py index 31bb7ea..3211c0a 100644 --- a/gdeltdoc/filters.py +++ b/gdeltdoc/filters.py @@ -5,6 +5,7 @@ Filter = Union[List[str], str] VALID_TIMESPAN_UNITS = ["min", "h", "hours", "d", "days", "w", "weeks", "m", "months"] +VALID_SORT_TYPES = ["DateDesc", "DateAsc", "ToneDesc", "ToneAsc", "HybridRel"] def near(n: int, *args) -> str: @@ -97,6 +98,7 @@ def __init__( theme: Optional[Filter] = None, tone: Optional[Filter] = None, tone_absolute: Optional[Filter] = None, + sort: Optional[str] = None, ) -> None: """ Construct filters for the GDELT API. @@ -172,6 +174,14 @@ def __init__( tone_absolute The same as `tone` but ignores the positive/negative sign and lets you simply search for high emotion or low emotion articles, regardless of whether they were happy or sad in tone + + sort + Controls the order of results. Must be one of: + - "DateDesc", or "DateAsc" - Sorts results by publication date + - "ToneDesc" or "ToneAsc" - Sorts results by tone + - "HybridRel" - Default relevance sorting mode for content published after September 16, 2018. + Uses a combination of textual relevance and outlet "popularity". + Not available for image searches. """ self.query_params: List[str] = [] self._valid_countries: List[str] = [] @@ -236,6 +246,11 @@ def __init__( self.query_params.append(f"&maxrecords={str(num_records)}") + if sort: + self._validate_sort_type(sort) + self.query_params.append(f"&sort={sort}") + + @property def query_string(self) -> str: return "".join(self.query_params) @@ -359,3 +374,23 @@ def _validate_timespan(timespan: str) -> None: raise ValueError( f"Timespan {timespan} is invalid. Period must be at least 60 minutes" ) + + @staticmethod + def _validate_sort_type(sort: str) -> None: + """ + Validate that the supplied sort type is one of the supported options. + Raises a `ValueError` if the sort type is not recognized. + + Params + ------ + sort + The sort type to be checked + + Returns + ------- + None + """ + if sort not in VALID_SORT_TYPES: + raise ValueError( + f"Sort type {sort} is invalid. Must be one of {', '.join(VALID_SORT_TYPES)}" + )