From 30072e55f112e385b70722ab31224ffe2ca7c8ae Mon Sep 17 00:00:00 2001 From: Islem Maboud Date: Fri, 26 Sep 2025 15:51:53 +0100 Subject: [PATCH 1/3] feat: update to latest openapi spec --- .env | 1 + .gitignore | 2 - .openapi-generator/FILES | 13 +- README.md | 18 +- perigon/__init__.py | 15 +- perigon/api/__init__.py | 1 - perigon/api/v1_api.py | 1864 +++++++++++------ perigon/models/__init__.py | 14 +- perigon/models/article.py | 28 + perigon/models/article_search_filter.py | 13 + perigon/models/article_search_params.py | 23 +- perigon/models/company.py | 5 + perigon/models/error_response.py | 107 + perigon/models/news_cluster.py | 10 + perigon/models/person.py | 20 + perigon/models/place.py | 5 + perigon/models/scored_data_article.py | 5 + perigon/models/scored_data_wiki_data.py | 5 + perigon/models/source.py | 20 + perigon/models/source_holder.py | 5 + perigon/models/source_location.py | 5 + perigon/models/stat_result.py | 97 + perigon/models/story_history_record.py | 184 ++ perigon/models/story_history_result.py | 105 + perigon/models/summary_body.py | 19 +- perigon/models/topic_dto.py | 5 + .../models/wikidata_political_party_holder.py | 10 + perigon/models/wikidata_position_holder.py | 15 + perigon/models/wikipedia_search_params.py | 13 +- 29 files changed, 1936 insertions(+), 691 deletions(-) create mode 100644 .env create mode 100644 perigon/models/error_response.py create mode 100644 perigon/models/stat_result.py create mode 100644 perigon/models/story_history_record.py create mode 100644 perigon/models/story_history_result.py diff --git a/.env b/.env new file mode 100644 index 0000000..25536d4 --- /dev/null +++ b/.env @@ -0,0 +1 @@ +PERIGON_API_KEY="1354fd4c-91dc-43fc-86d5-fcd114bfdd09" \ No newline at end of file diff --git a/.gitignore b/.gitignore index 1b2eda4..43995bd 100644 --- a/.gitignore +++ b/.gitignore @@ -64,5 +64,3 @@ target/ #Ipython Notebook .ipynb_checkpoints - -.env \ No newline at end of file diff --git a/.openapi-generator/FILES b/.openapi-generator/FILES index cc20fbc..7247004 100644 --- a/.openapi-generator/FILES +++ b/.openapi-generator/FILES @@ -2,7 +2,6 @@ README.md perigon/__init__.py perigon/api/__init__.py -perigon/api/supplemental_endpoints_api.py perigon/api/v1_api.py perigon/api_client.py perigon/api_response.py @@ -13,10 +12,6 @@ perigon/models/article.py perigon/models/article_search_filter.py perigon/models/article_search_params.py perigon/models/articles_vector_search_result.py -perigon/models/auth_exception.py -perigon/models/auth_exception_cause.py -perigon/models/auth_exception_cause_stack_trace_inner.py -perigon/models/auth_exception_suppressed_inner.py perigon/models/category_holder.py perigon/models/category_with_score_holder.py perigon/models/company.py @@ -26,11 +21,10 @@ perigon/models/company_search_result.py perigon/models/coordinate.py perigon/models/coordinate_filter.py perigon/models/entity_holder.py +perigon/models/error_response.py perigon/models/event_type_holder.py perigon/models/id_name_holder.py -perigon/models/illegal_parameter_exception.py perigon/models/image_holder.py -perigon/models/internal_error_exception.py perigon/models/journalist.py perigon/models/journalist_search_result.py perigon/models/key_point.py @@ -40,7 +34,6 @@ perigon/models/location_count.py perigon/models/location_holder.py perigon/models/name_count.py perigon/models/news_cluster.py -perigon/models/not_found_exception.py perigon/models/people_search_result.py perigon/models/person.py perigon/models/person_count.py @@ -58,11 +51,13 @@ perigon/models/source_holder.py perigon/models/source_location.py perigon/models/source_search_result.py perigon/models/source_top_stat_holder.py +perigon/models/stat_result.py +perigon/models/story_history_record.py +perigon/models/story_history_result.py perigon/models/story_search_result.py perigon/models/summary_body.py perigon/models/summary_search_result.py perigon/models/symbol_holder.py -perigon/models/too_many_requests_exception.py perigon/models/topic_dto.py perigon/models/topic_holder.py perigon/models/topic_labels.py diff --git a/README.md b/README.md index d399dc0..05ca03d 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ articles, journalist = asyncio.run(fetch_data()) ### Articles – search and filter news (`/v1/all`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/overview](https://docs.perigon.io/docs/overview) ```python # Simple query @@ -127,7 +127,7 @@ articles = api.search_articles(source=["nytimes.com"]) ### Companies – fetch structured company data (`/v1/companies`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/company-data](https://docs.perigon.io/docs/company-data) ```python results = api.search_companies(name="Apple", size=5) @@ -135,7 +135,7 @@ results = api.search_companies(name="Apple", size=5) ### Journalists – search and detail look‑up (`/v1/journalists`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/journalist-data](https://docs.perigon.io/docs/journalist-data) ```python # Search for journalists @@ -147,7 +147,7 @@ journalist = api.get_journalist_by_id(id=results.journalists[0].id) ### Stories – discover related article clusters (`/v1/stories`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/stories-overview](https://docs.perigon.io/docs/stories-overview) ```python stories = api.search_stories(q="climate change", size=5) @@ -155,7 +155,7 @@ stories = api.search_stories(q="climate change", size=5) ### Vector search – semantic retrieval (`/v1/vector`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/vector-endpoint](https://docs.perigon.io/docs/vector-endpoint) ```python from perigon.models.article_search_params import ArticleSearchParams @@ -170,7 +170,7 @@ results = api.vector_search_articles( ### Summarizer – generate an instant summary (`/v1/summarizer`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/search-summarizer](https://docs.perigon.io/docs/search-summarizer) ```python from perigon.models.summary_body import SummaryBody @@ -186,7 +186,7 @@ print(summary) ### Topics – explore taxonomy (`/v1/topics`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/topics](https://docs.perigon.io/docs/topics) ```python topics = api.search_topics(size=10) @@ -194,7 +194,7 @@ topics = api.search_topics(size=10) ### Wikipedia – search and filter pages (`/v1/wikipedia`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/wikipedia](https://docs.perigon.io/docs/wikipedia) ```python # Search Wikipedia pages @@ -213,7 +213,7 @@ wikipedia_result = api.search_wikipedia( ### Wikipedia vector search – semantic retrieval (`/v1/vector/wikipedia`)
-**Docs →** +**Docs →** [https://docs.perigon.io/docs/vector-wikipedia](https://docs.perigon.io/docs/vector-wikipedia) ```python from perigon.models.wikipedia_search_params import WikipediaSearchParams diff --git a/perigon/__init__.py b/perigon/__init__.py index 7d1f7f1..8803948 100644 --- a/perigon/__init__.py +++ b/perigon/__init__.py @@ -18,7 +18,6 @@ __version__ = "1.0.0" # import apis into sdk package -from perigon.api.supplemental_endpoints_api import SupplementalEndpointsApi from perigon.api.v1_api import V1Api from perigon.api_client import ApiClient @@ -39,12 +38,6 @@ from perigon.models.article_search_filter import ArticleSearchFilter from perigon.models.article_search_params import ArticleSearchParams from perigon.models.articles_vector_search_result import ArticlesVectorSearchResult -from perigon.models.auth_exception import AuthException -from perigon.models.auth_exception_cause import AuthExceptionCause -from perigon.models.auth_exception_cause_stack_trace_inner import ( - AuthExceptionCauseStackTraceInner, -) -from perigon.models.auth_exception_suppressed_inner import AuthExceptionSuppressedInner from perigon.models.category_holder import CategoryHolder from perigon.models.category_with_score_holder import CategoryWithScoreHolder from perigon.models.company import Company @@ -54,11 +47,10 @@ from perigon.models.coordinate import Coordinate from perigon.models.coordinate_filter import CoordinateFilter from perigon.models.entity_holder import EntityHolder +from perigon.models.error_response import ErrorResponse from perigon.models.event_type_holder import EventTypeHolder from perigon.models.id_name_holder import IdNameHolder -from perigon.models.illegal_parameter_exception import IllegalParameterException from perigon.models.image_holder import ImageHolder -from perigon.models.internal_error_exception import InternalErrorException from perigon.models.journalist import Journalist from perigon.models.journalist_search_result import JournalistSearchResult from perigon.models.key_point import KeyPoint @@ -68,7 +60,6 @@ from perigon.models.location_holder import LocationHolder from perigon.models.name_count import NameCount from perigon.models.news_cluster import NewsCluster -from perigon.models.not_found_exception import NotFoundException from perigon.models.people_search_result import PeopleSearchResult from perigon.models.person import Person from perigon.models.person_count import PersonCount @@ -86,11 +77,13 @@ from perigon.models.source_location import SourceLocation from perigon.models.source_search_result import SourceSearchResult from perigon.models.source_top_stat_holder import SourceTopStatHolder +from perigon.models.stat_result import StatResult +from perigon.models.story_history_record import StoryHistoryRecord +from perigon.models.story_history_result import StoryHistoryResult from perigon.models.story_search_result import StorySearchResult from perigon.models.summary_body import SummaryBody from perigon.models.summary_search_result import SummarySearchResult from perigon.models.symbol_holder import SymbolHolder -from perigon.models.too_many_requests_exception import TooManyRequestsException from perigon.models.topic_dto import TopicDto from perigon.models.topic_holder import TopicHolder from perigon.models.topic_labels import TopicLabels diff --git a/perigon/api/__init__.py b/perigon/api/__init__.py index 358b5a3..ff6d0ad 100644 --- a/perigon/api/__init__.py +++ b/perigon/api/__init__.py @@ -1,5 +1,4 @@ # flake8: noqa # import apis into api package -from perigon.api.supplemental_endpoints_api import SupplementalEndpointsApi from perigon.api.v1_api import V1Api diff --git a/perigon/api/v1_api.py b/perigon/api/v1_api.py index 905ea99..b86e885 100644 --- a/perigon/api/v1_api.py +++ b/perigon/api/v1_api.py @@ -2,7 +2,14 @@ from enum import Enum from typing import Any, Dict, Iterable, List, Mapping, Optional, Union -from pydantic import Field, StrictBool, StrictFloat, StrictInt, StrictStr +from pydantic import ( + Field, + StrictBool, + StrictFloat, + StrictInt, + StrictStr, + field_validator, +) from typing_extensions import Annotated from perigon.api_client import ApiClient @@ -16,6 +23,8 @@ from perigon.models.query_search_result import QuerySearchResult from perigon.models.sort_by import SortBy from perigon.models.source_search_result import SourceSearchResult +from perigon.models.stat_result import StatResult +from perigon.models.story_history_result import StoryHistoryResult from perigon.models.story_search_result import StorySearchResult from perigon.models.summary_body import SummaryBody from perigon.models.summary_search_result import SummarySearchResult @@ -26,6 +35,8 @@ # Define API paths PATH_GET_JOURNALIST_BY_ID = "/v1/journalists/{id}" +PATH_GET_STORY_COUNTS = "/v1/stories/stats" +PATH_GET_STORY_HISTORY = "/v1/stories/history" PATH_SEARCH_ARTICLES = "/v1/articles/all" PATH_SEARCH_COMPANIES = "/v1/companies/all" PATH_SEARCH_JOURNALISTS = "/v1/journalists/all" @@ -135,6 +146,547 @@ async def get_journalist_by_id_async(self, id: str) -> Journalist: resp.raise_for_status() return Journalist.model_validate(resp.json()) + # ----------------- get_story_counts (sync) ----------------- # + def get_story_counts( + self, + split_by: str, + q: Optional[str] = None, + name: Optional[str] = None, + cluster_id: Optional[List[str]] = None, + exclude_cluster_id: Optional[List[str]] = None, + sort_by: Optional[SortBy] = None, + page: Optional[int] = None, + size: Optional[int] = None, + var_from: Optional[datetime] = None, + to: Optional[datetime] = None, + initialized_from: Optional[datetime] = None, + initialized_to: Optional[datetime] = None, + updated_from: Optional[datetime] = None, + updated_to: Optional[datetime] = None, + topic: Optional[List[str]] = None, + category: Optional[List[str]] = None, + taxonomy: Optional[List[str]] = None, + source: Optional[List[str]] = None, + source_group: Optional[List[str]] = None, + min_unique_sources: Optional[int] = None, + person_wikidata_id: Optional[List[str]] = None, + person_name: Optional[str] = None, + company_id: Optional[List[str]] = None, + company_name: Optional[str] = None, + company_domain: Optional[List[str]] = None, + company_symbol: Optional[List[str]] = None, + country: Optional[List[str]] = None, + state: Optional[List[str]] = None, + city: Optional[List[str]] = None, + area: Optional[List[str]] = None, + min_cluster_size: Optional[int] = None, + max_cluster_size: Optional[int] = None, + name_exists: Optional[bool] = None, + positive_sentiment_from: Optional[float] = None, + positive_sentiment_to: Optional[float] = None, + neutral_sentiment_from: Optional[float] = None, + neutral_sentiment_to: Optional[float] = None, + negative_sentiment_from: Optional[float] = None, + negative_sentiment_to: Optional[float] = None, + show_story_page_info: Optional[bool] = None, + show_num_results: Optional[bool] = None, + show_duplicates: Optional[bool] = None, + show_highlighting: Optional[bool] = None, + highlight_fragment_size: Optional[int] = None, + highlight_num_fragments: Optional[int] = None, + highlight_pre_tag: Optional[str] = None, + highlight_post_tag: Optional[str] = None, + highlight_q: Optional[str] = None, + expand_articles: Optional[bool] = None, + ) -> StatResult: + """ + Get statistics on story counts over time intervals. Supports filtering by various story attributes and grouping by different time intervals (hour, day, week, month). + + Args: + split_by (str): String. The value for 'splitBy' must be one of the following: HOUR, DAY, WEEK, MONTH, or NONE. (required) + Allowed values: 'HOUR', 'DAY', 'WEEK', 'MONTH', 'NONE' + q (Optional[str]): String. Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations. + cluster_id (Optional[List[str]]): String Array. Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter. + exclude_cluster_id (Optional[List[str]]): String Array. Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories. + sort_by (Optional[SortBy]): String. Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 + to (Optional[datetime]): Date. 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59 + initialized_from (Optional[datetime]): Date. Filter for stories created after this date. Alternative parameter for filtering by story creation date. + initialized_to (Optional[datetime]): Date. Filter for stories created before this date. Alternative parameter for filtering by story creation date. + updated_from (Optional[datetime]): Date. Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines. + updated_to (Optional[datetime]): Date. Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines. + topic (Optional[List[str]]): String Array. Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + category (Optional[List[str]]): String Array. Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter. + taxonomy (Optional[List[str]]): String Array. Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter. + min_unique_sources (Optional[int]): Integer. Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3. + person_wikidata_id (Optional[List[str]]): String Array. Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals. + person_name (Optional[str]): String. Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + company_id (Optional[List[str]]): String Array. Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint. + company_name (Optional[str]): String. Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field. + company_domain (Optional[List[str]]): String Array. Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint. + company_symbol (Optional[List[str]]): String Array. Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + city (Optional[List[str]]): String Array. Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + area (Optional[List[str]]): String Array. Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + min_cluster_size (Optional[int]): Integer. Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles. + max_cluster_size (Optional[int]): Integer. Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster. + name_exists (Optional[bool]): Boolean. Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + show_story_page_info (Optional[bool]): Boolean. + show_num_results (Optional[bool]): Boolean. Show total number of results. By default set to false, will cap result count at 10000. + show_duplicates (Optional[bool]): Boolean. Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown. + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + expand_articles (Optional[bool]): Boolean. Preview 5 articles from the cluster. + + Returns: + StatResult: The response + """ + # Get path template from class attribute + path = PATH_GET_STORY_COUNTS + + # --- build query dict on the fly --- + params: Dict[str, Any] = {} + if q is not None: + params["q"] = q + if name is not None: + params["name"] = name + if cluster_id is not None: + params["clusterId"] = cluster_id + if exclude_cluster_id is not None: + params["excludeClusterId"] = exclude_cluster_id + if sort_by is not None: + params["sortBy"] = sort_by + if page is not None: + params["page"] = page + if size is not None: + params["size"] = size + if var_from is not None: + params["from"] = var_from + if to is not None: + params["to"] = to + if initialized_from is not None: + params["initializedFrom"] = initialized_from + if initialized_to is not None: + params["initializedTo"] = initialized_to + if updated_from is not None: + params["updatedFrom"] = updated_from + if updated_to is not None: + params["updatedTo"] = updated_to + if topic is not None: + params["topic"] = topic + if category is not None: + params["category"] = category + if taxonomy is not None: + params["taxonomy"] = taxonomy + if source is not None: + params["source"] = source + if source_group is not None: + params["sourceGroup"] = source_group + if min_unique_sources is not None: + params["minUniqueSources"] = min_unique_sources + if person_wikidata_id is not None: + params["personWikidataId"] = person_wikidata_id + if person_name is not None: + params["personName"] = person_name + if company_id is not None: + params["companyId"] = company_id + if company_name is not None: + params["companyName"] = company_name + if company_domain is not None: + params["companyDomain"] = company_domain + if company_symbol is not None: + params["companySymbol"] = company_symbol + if country is not None: + params["country"] = country + if state is not None: + params["state"] = state + if city is not None: + params["city"] = city + if area is not None: + params["area"] = area + if min_cluster_size is not None: + params["minClusterSize"] = min_cluster_size + if max_cluster_size is not None: + params["maxClusterSize"] = max_cluster_size + if name_exists is not None: + params["nameExists"] = name_exists + if positive_sentiment_from is not None: + params["positiveSentimentFrom"] = positive_sentiment_from + if positive_sentiment_to is not None: + params["positiveSentimentTo"] = positive_sentiment_to + if neutral_sentiment_from is not None: + params["neutralSentimentFrom"] = neutral_sentiment_from + if neutral_sentiment_to is not None: + params["neutralSentimentTo"] = neutral_sentiment_to + if negative_sentiment_from is not None: + params["negativeSentimentFrom"] = negative_sentiment_from + if negative_sentiment_to is not None: + params["negativeSentimentTo"] = negative_sentiment_to + if show_story_page_info is not None: + params["showStoryPageInfo"] = show_story_page_info + if show_num_results is not None: + params["showNumResults"] = show_num_results + if show_duplicates is not None: + params["showDuplicates"] = show_duplicates + if show_highlighting is not None: + params["showHighlighting"] = show_highlighting + if highlight_fragment_size is not None: + params["highlightFragmentSize"] = highlight_fragment_size + if highlight_num_fragments is not None: + params["highlightNumFragments"] = highlight_num_fragments + if highlight_pre_tag is not None: + params["highlightPreTag"] = highlight_pre_tag + if highlight_post_tag is not None: + params["highlightPostTag"] = highlight_post_tag + if highlight_q is not None: + params["highlightQ"] = highlight_q + if expand_articles is not None: + params["expandArticles"] = expand_articles + if split_by is not None: + params["splitBy"] = split_by + params = _normalise_query(params) + + resp = self.api_client.request("GET", path, params=params) + resp.raise_for_status() + return StatResult.model_validate(resp.json()) + + # ----------------- get_story_counts (async) ----------------- # + async def get_story_counts_async( + self, + split_by: str, + q: Optional[str] = None, + name: Optional[str] = None, + cluster_id: Optional[List[str]] = None, + exclude_cluster_id: Optional[List[str]] = None, + sort_by: Optional[SortBy] = None, + page: Optional[int] = None, + size: Optional[int] = None, + var_from: Optional[datetime] = None, + to: Optional[datetime] = None, + initialized_from: Optional[datetime] = None, + initialized_to: Optional[datetime] = None, + updated_from: Optional[datetime] = None, + updated_to: Optional[datetime] = None, + topic: Optional[List[str]] = None, + category: Optional[List[str]] = None, + taxonomy: Optional[List[str]] = None, + source: Optional[List[str]] = None, + source_group: Optional[List[str]] = None, + min_unique_sources: Optional[int] = None, + person_wikidata_id: Optional[List[str]] = None, + person_name: Optional[str] = None, + company_id: Optional[List[str]] = None, + company_name: Optional[str] = None, + company_domain: Optional[List[str]] = None, + company_symbol: Optional[List[str]] = None, + country: Optional[List[str]] = None, + state: Optional[List[str]] = None, + city: Optional[List[str]] = None, + area: Optional[List[str]] = None, + min_cluster_size: Optional[int] = None, + max_cluster_size: Optional[int] = None, + name_exists: Optional[bool] = None, + positive_sentiment_from: Optional[float] = None, + positive_sentiment_to: Optional[float] = None, + neutral_sentiment_from: Optional[float] = None, + neutral_sentiment_to: Optional[float] = None, + negative_sentiment_from: Optional[float] = None, + negative_sentiment_to: Optional[float] = None, + show_story_page_info: Optional[bool] = None, + show_num_results: Optional[bool] = None, + show_duplicates: Optional[bool] = None, + show_highlighting: Optional[bool] = None, + highlight_fragment_size: Optional[int] = None, + highlight_num_fragments: Optional[int] = None, + highlight_pre_tag: Optional[str] = None, + highlight_post_tag: Optional[str] = None, + highlight_q: Optional[str] = None, + expand_articles: Optional[bool] = None, + ) -> StatResult: + """ + Async variant of get_story_counts. Get statistics on story counts over time intervals. Supports filtering by various story attributes and grouping by different time intervals (hour, day, week, month). + + Args: + split_by (str): String. The value for 'splitBy' must be one of the following: HOUR, DAY, WEEK, MONTH, or NONE. (required) + Allowed values: 'HOUR', 'DAY', 'WEEK', 'MONTH', 'NONE' + q (Optional[str]): String. Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations. + cluster_id (Optional[List[str]]): String Array. Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter. + exclude_cluster_id (Optional[List[str]]): String Array. Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories. + sort_by (Optional[SortBy]): String. Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 + to (Optional[datetime]): Date. 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59 + initialized_from (Optional[datetime]): Date. Filter for stories created after this date. Alternative parameter for filtering by story creation date. + initialized_to (Optional[datetime]): Date. Filter for stories created before this date. Alternative parameter for filtering by story creation date. + updated_from (Optional[datetime]): Date. Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines. + updated_to (Optional[datetime]): Date. Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines. + topic (Optional[List[str]]): String Array. Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + category (Optional[List[str]]): String Array. Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter. + taxonomy (Optional[List[str]]): String Array. Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter. + min_unique_sources (Optional[int]): Integer. Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3. + person_wikidata_id (Optional[List[str]]): String Array. Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals. + person_name (Optional[str]): String. Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + company_id (Optional[List[str]]): String Array. Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint. + company_name (Optional[str]): String. Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field. + company_domain (Optional[List[str]]): String Array. Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint. + company_symbol (Optional[List[str]]): String Array. Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + city (Optional[List[str]]): String Array. Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + area (Optional[List[str]]): String Array. Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + min_cluster_size (Optional[int]): Integer. Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles. + max_cluster_size (Optional[int]): Integer. Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster. + name_exists (Optional[bool]): Boolean. Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + show_story_page_info (Optional[bool]): Boolean. + show_num_results (Optional[bool]): Boolean. Show total number of results. By default set to false, will cap result count at 10000. + show_duplicates (Optional[bool]): Boolean. Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown. + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + expand_articles (Optional[bool]): Boolean. Preview 5 articles from the cluster. + + Returns: + StatResult: The response + """ + # Get path template from class attribute + path = PATH_GET_STORY_COUNTS + + params: Dict[str, Any] = {} + if q is not None: + params["q"] = q + if name is not None: + params["name"] = name + if cluster_id is not None: + params["clusterId"] = cluster_id + if exclude_cluster_id is not None: + params["excludeClusterId"] = exclude_cluster_id + if sort_by is not None: + params["sortBy"] = sort_by + if page is not None: + params["page"] = page + if size is not None: + params["size"] = size + if var_from is not None: + params["from"] = var_from + if to is not None: + params["to"] = to + if initialized_from is not None: + params["initializedFrom"] = initialized_from + if initialized_to is not None: + params["initializedTo"] = initialized_to + if updated_from is not None: + params["updatedFrom"] = updated_from + if updated_to is not None: + params["updatedTo"] = updated_to + if topic is not None: + params["topic"] = topic + if category is not None: + params["category"] = category + if taxonomy is not None: + params["taxonomy"] = taxonomy + if source is not None: + params["source"] = source + if source_group is not None: + params["sourceGroup"] = source_group + if min_unique_sources is not None: + params["minUniqueSources"] = min_unique_sources + if person_wikidata_id is not None: + params["personWikidataId"] = person_wikidata_id + if person_name is not None: + params["personName"] = person_name + if company_id is not None: + params["companyId"] = company_id + if company_name is not None: + params["companyName"] = company_name + if company_domain is not None: + params["companyDomain"] = company_domain + if company_symbol is not None: + params["companySymbol"] = company_symbol + if country is not None: + params["country"] = country + if state is not None: + params["state"] = state + if city is not None: + params["city"] = city + if area is not None: + params["area"] = area + if min_cluster_size is not None: + params["minClusterSize"] = min_cluster_size + if max_cluster_size is not None: + params["maxClusterSize"] = max_cluster_size + if name_exists is not None: + params["nameExists"] = name_exists + if positive_sentiment_from is not None: + params["positiveSentimentFrom"] = positive_sentiment_from + if positive_sentiment_to is not None: + params["positiveSentimentTo"] = positive_sentiment_to + if neutral_sentiment_from is not None: + params["neutralSentimentFrom"] = neutral_sentiment_from + if neutral_sentiment_to is not None: + params["neutralSentimentTo"] = neutral_sentiment_to + if negative_sentiment_from is not None: + params["negativeSentimentFrom"] = negative_sentiment_from + if negative_sentiment_to is not None: + params["negativeSentimentTo"] = negative_sentiment_to + if show_story_page_info is not None: + params["showStoryPageInfo"] = show_story_page_info + if show_num_results is not None: + params["showNumResults"] = show_num_results + if show_duplicates is not None: + params["showDuplicates"] = show_duplicates + if show_highlighting is not None: + params["showHighlighting"] = show_highlighting + if highlight_fragment_size is not None: + params["highlightFragmentSize"] = highlight_fragment_size + if highlight_num_fragments is not None: + params["highlightNumFragments"] = highlight_num_fragments + if highlight_pre_tag is not None: + params["highlightPreTag"] = highlight_pre_tag + if highlight_post_tag is not None: + params["highlightPostTag"] = highlight_post_tag + if highlight_q is not None: + params["highlightQ"] = highlight_q + if expand_articles is not None: + params["expandArticles"] = expand_articles + if split_by is not None: + params["splitBy"] = split_by + params = _normalise_query(params) + + resp = await self.api_client.request_async("GET", path, params=params) + resp.raise_for_status() + return StatResult.model_validate(resp.json()) + + # ----------------- get_story_history (sync) ----------------- # + def get_story_history( + self, + cluster_id: Optional[List[str]] = None, + var_from: Optional[datetime] = None, + to: Optional[datetime] = None, + sort_by: Optional[str] = None, + page: Optional[int] = None, + size: Optional[int] = None, + changelog_exists: Optional[bool] = None, + ) -> StoryHistoryResult: + """ + + Args: + cluster_id (Optional[List[str]]): String Array. Filter to specific story. Passing a cluster ID will filter results to only the content found within the cluster. + var_from (Optional[datetime]): Date. 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 + to (Optional[datetime]): Date. 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59. + sort_by (Optional[str]): String. Sort stories by count, creation date (createdAt), story refresh trigger date (triggeredAt). + Allowed values: 'createdAt', 'triggeredAt' + page (Optional[int]): Integer. Zero-based page number. From 0 to 10000. See the Pagination section for limitations. + size (Optional[int]): Integer. Number of stories results per page, from 0 to 100. + changelog_exists (Optional[bool]): Boolean. Filter to only include clusters that have a changelog or not. + + Returns: + StoryHistoryResult: The response + """ + # Get path template from class attribute + path = PATH_GET_STORY_HISTORY + + # --- build query dict on the fly --- + params: Dict[str, Any] = {} + if cluster_id is not None: + params["clusterId"] = cluster_id + if var_from is not None: + params["from"] = var_from + if to is not None: + params["to"] = to + if sort_by is not None: + params["sortBy"] = sort_by + if page is not None: + params["page"] = page + if size is not None: + params["size"] = size + if changelog_exists is not None: + params["changelogExists"] = changelog_exists + params = _normalise_query(params) + + resp = self.api_client.request("GET", path, params=params) + resp.raise_for_status() + return StoryHistoryResult.model_validate(resp.json()) + + # ----------------- get_story_history (async) ----------------- # + async def get_story_history_async( + self, + cluster_id: Optional[List[str]] = None, + var_from: Optional[datetime] = None, + to: Optional[datetime] = None, + sort_by: Optional[str] = None, + page: Optional[int] = None, + size: Optional[int] = None, + changelog_exists: Optional[bool] = None, + ) -> StoryHistoryResult: + """ + Async variant of get_story_history. + + Args: + cluster_id (Optional[List[str]]): String Array. Filter to specific story. Passing a cluster ID will filter results to only the content found within the cluster. + var_from (Optional[datetime]): Date. 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 + to (Optional[datetime]): Date. 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59. + sort_by (Optional[str]): String. Sort stories by count, creation date (createdAt), story refresh trigger date (triggeredAt). + Allowed values: 'createdAt', 'triggeredAt' + page (Optional[int]): Integer. Zero-based page number. From 0 to 10000. See the Pagination section for limitations. + size (Optional[int]): Integer. Number of stories results per page, from 0 to 100. + changelog_exists (Optional[bool]): Boolean. Filter to only include clusters that have a changelog or not. + + Returns: + StoryHistoryResult: The response + """ + # Get path template from class attribute + path = PATH_GET_STORY_HISTORY + + params: Dict[str, Any] = {} + if cluster_id is not None: + params["clusterId"] = cluster_id + if var_from is not None: + params["from"] = var_from + if to is not None: + params["to"] = to + if sort_by is not None: + params["sortBy"] = sort_by + if page is not None: + params["page"] = page + if size is not None: + params["size"] = size + if changelog_exists is not None: + params["changelogExists"] = changelog_exists + params = _normalise_query(params) + + resp = await self.api_client.request_async("GET", path, params=params) + resp.raise_for_status() + return StoryHistoryResult.model_validate(resp.json()) + # ----------------- search_articles (sync) ----------------- # def search_articles( self, @@ -142,6 +694,7 @@ def search_articles( title: Optional[str] = None, desc: Optional[str] = None, content: Optional[str] = None, + summary: Optional[str] = None, url: Optional[str] = None, article_id: Optional[List[str]] = None, cluster_id: Optional[List[str]] = None, @@ -159,6 +712,8 @@ def search_articles( source_group: Optional[List[str]] = None, exclude_source_group: Optional[List[str]] = None, exclude_source: Optional[List[str]] = None, + watchlist: Optional[List[str]] = None, + exclude_watchlist: Optional[List[str]] = None, paywall: Optional[bool] = None, byline: Optional[List[str]] = None, author: Optional[List[str]] = None, @@ -229,92 +784,95 @@ def search_articles( Search and filter all news articles available via the Perigon API. The result includes a list of individual articles that were matched to your specific criteria. Args: - q (Optional[str]): Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - title (Optional[str]): Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - desc (Optional[str]): Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. - content (Optional[str]): Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. - url (Optional[str]): Search within article URLs to find content from specific website sections or domains. Supports wildcards (* and ?) for partial URL matching. - article_id (Optional[List[str]]): Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. - cluster_id (Optional[List[str]]): Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. - sort_by (Optional[AllEndpointSortBy]): Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - var_from (Optional[datetime]): Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - to (Optional[datetime]): Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - add_date_from (Optional[datetime]): Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - add_date_to (Optional[datetime]): Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - refresh_date_from (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - refresh_date_to (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - medium (Optional[List[str]]): Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. - source (Optional[List[str]]): Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. - source_group (Optional[List[str]]): Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. - exclude_source_group (Optional[List[str]]): Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). - exclude_source (Optional[List[str]]): Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. - paywall (Optional[bool]): Filter to show only results where the source has a paywall (true) or does not have a paywall (false). - byline (Optional[List[str]]): Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. - author (Optional[List[str]]): Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. - exclude_author (Optional[List[str]]): Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. - journalist_id (Optional[List[str]]): Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. - exclude_journalist_id (Optional[List[str]]): Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. - language (Optional[List[str]]): Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. - exclude_language (Optional[List[str]]): Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. - search_translation (Optional[bool]): Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. - label (Optional[List[str]]): Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. - exclude_label (Optional[List[str]]): Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. - category (Optional[List[str]]): Filter by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized articles. Multiple values create an OR filter. - exclude_category (Optional[List[str]]): Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. - topic (Optional[List[str]]): Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. - exclude_topic (Optional[List[str]]): Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. - link_to (Optional[str]): Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. - show_reprints (Optional[bool]): Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. - reprint_group_id (Optional[str]): Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. - city (Optional[List[str]]): Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_city (Optional[List[str]]): A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. - area (Optional[List[str]]): Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. - state (Optional[List[str]]): Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_state (Optional[List[str]]): A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). - county (Optional[List[str]]): A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. - exclude_county (Optional[List[str]]): Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter - locations_country (Optional[List[str]]): Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. - country (Optional[List[str]]): Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. - exclude_locations_country (Optional[List[str]]): Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. - location (Optional[List[str]]): Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. - lat (Optional[float]): Latitude of the center point to search places - lon (Optional[float]): Longitude of the center point to search places - max_distance (Optional[float]): Maximum distance (in km) from starting point to search articles by tagged places - source_city (Optional[List[str]]): Find articles published by sources that are located within a given city. - source_county (Optional[List[str]]): Find articles published by sources that are located within a given county. - source_country (Optional[List[str]]): Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). - source_state (Optional[List[str]]): Find articles published by sources that are located within a given state. - source_lat (Optional[float]): Latitude of the center point to search articles created by local publications. - source_lon (Optional[float]): Latitude of the center point to search articles created by local publications. - source_max_distance (Optional[float]): Maximum distance from starting point to search articles created by local publications. - person_wikidata_id (Optional[List[str]]): Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. - exclude_person_wikidata_id (Optional[List[str]]): Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. - person_name (Optional[List[str]]): Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. - exclude_person_name (Optional[List[str]]): Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. - company_id (Optional[List[str]]): Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. - exclude_company_id (Optional[List[str]]): Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. - company_name (Optional[str]): Filter articles by company name mentions. Performs an exact match on company names. - company_domain (Optional[List[str]]): Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. - exclude_company_domain (Optional[List[str]]): Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. - company_symbol (Optional[List[str]]): Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. - exclude_company_symbol (Optional[List[str]]): A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. - show_num_results (Optional[bool]): Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. - positive_sentiment_from (Optional[float]): Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - positive_sentiment_to (Optional[float]): Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - neutral_sentiment_from (Optional[float]): Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - neutral_sentiment_to (Optional[float]): Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - negative_sentiment_from (Optional[float]): Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - negative_sentiment_to (Optional[float]): Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - taxonomy (Optional[List[str]]): Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) - prefix_taxonomy (Optional[str]): Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance - show_highlighting (Optional[bool]): When set to true, enables text highlighting in search results. - highlight_fragment_size (Optional[int]): Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. - highlight_num_fragments (Optional[int]): Controls the maximum number of highlighted fragments to return per field. - highlight_pre_tag (Optional[str]): Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. - highlight_post_tag (Optional[str]): Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. - highlight_q (Optional[str]): Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + q (Optional[str]): String. Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + title (Optional[str]): String. Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + desc (Optional[str]): String. Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + content (Optional[str]): String. Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. + summary (Optional[str]): String. Search within article summary fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + url (Optional[str]): String. Search query on the url field. Semantic similar to q parameter. E.g. could be used for querying certain website sections, e.g. source=cnn.com&url=travel. + article_id (Optional[List[str]]): String Array. Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. + cluster_id (Optional[List[str]]): String Array. Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. + sort_by (Optional[AllEndpointSortBy]): String. Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + to (Optional[datetime]): Date. Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + add_date_from (Optional[datetime]): Date. Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + add_date_to (Optional[datetime]): Date. Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + refresh_date_from (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + refresh_date_to (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + medium (Optional[List[str]]): String Array. Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. + exclude_source_group (Optional[List[str]]): String Array. Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). + exclude_source (Optional[List[str]]): String Array. Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. + watchlist (Optional[List[str]]): String Array. Filter articles using watchlists of people and companies. Multiple values create an OR filter to include articles mentioning any entity from the specified watchlists. + exclude_watchlist (Optional[List[str]]): String Array. Exclude articles mentioning entities from specified watchlists. Multiple values create an AND-exclude filter, removing content mentioning any entity from the specified watchlists. + paywall (Optional[bool]): Boolean. Filter to show only results where the source has a paywall (true) or does not have a paywall (false). + byline (Optional[List[str]]): String Array. Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. + author (Optional[List[str]]): String Array. Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. + exclude_author (Optional[List[str]]): String Array. Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. + journalist_id (Optional[List[str]]): String Array. Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. + exclude_journalist_id (Optional[List[str]]): String Array. Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. + language (Optional[List[str]]): String Array. Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. + exclude_language (Optional[List[str]]): String Array. Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. + search_translation (Optional[bool]): Boolean. Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. + label (Optional[List[str]]): String Array. Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. + exclude_label (Optional[List[str]]): String Array. Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. + category (Optional[List[str]]): String Array. Filter by categories. Categories are general themes that the article is about. Examples of categories: Tech, Politics, etc. If multiple parameters are passed, they will be applied as OR operations. Use 'none' to search uncategorized articles. + exclude_category (Optional[List[str]]): String Array. Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. + topic (Optional[List[str]]): String Array. Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + exclude_topic (Optional[List[str]]): String Array. Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. + link_to (Optional[str]): String. Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. + show_reprints (Optional[bool]): Boolean. Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. + reprint_group_id (Optional[str]): String. Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. + city (Optional[List[str]]): String Array. Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_city (Optional[List[str]]): String Array. A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. + area (Optional[List[str]]): String Array. Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_state (Optional[List[str]]): String Array. A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). + county (Optional[List[str]]): String Array. A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. + exclude_county (Optional[List[str]]): String Array. Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter + locations_country (Optional[List[str]]): String Array. Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + exclude_locations_country (Optional[List[str]]): String Array. Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. + location (Optional[List[str]]): String Array. Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. + lat (Optional[float]): Float. Latitude of the center point to search places + lon (Optional[float]): Float. Longitude of the center point to search places + max_distance (Optional[float]): Float. Maximum distance (in km) from starting point to search articles by tagged places + source_city (Optional[List[str]]): String Array. Find articles published by sources that are located within a given city. + source_county (Optional[List[str]]): String Array. Find articles published by sources that are located within a given county. + source_country (Optional[List[str]]): String Array. Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). + source_state (Optional[List[str]]): String Array. Find articles published by sources that are located within a given state. + source_lat (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_lon (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_max_distance (Optional[float]): Float. Maximum distance from starting point to search articles created by local publications. + person_wikidata_id (Optional[List[str]]): String Array. Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. + exclude_person_wikidata_id (Optional[List[str]]): String Array. Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. + person_name (Optional[List[str]]): String Array. Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + exclude_person_name (Optional[List[str]]): String Array. Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. + company_id (Optional[List[str]]): String Array. Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. + exclude_company_id (Optional[List[str]]): String Array. Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. + company_name (Optional[str]): String. Filter articles by company name mentions. Performs an exact match on company names. + company_domain (Optional[List[str]]): String Array. Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. + exclude_company_domain (Optional[List[str]]): String Array. Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. + company_symbol (Optional[List[str]]): String Array. Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. + exclude_company_symbol (Optional[List[str]]): String Array. A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. + show_num_results (Optional[bool]): Boolean. Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + taxonomy (Optional[List[str]]): String Array. Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) + prefix_taxonomy (Optional[str]): String. Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. Returns: QuerySearchResult: The response @@ -332,6 +890,8 @@ def search_articles( params["desc"] = desc if content is not None: params["content"] = content + if summary is not None: + params["summary"] = summary if url is not None: params["url"] = url if article_id is not None: @@ -366,6 +926,10 @@ def search_articles( params["excludeSourceGroup"] = exclude_source_group if exclude_source is not None: params["excludeSource"] = exclude_source + if watchlist is not None: + params["watchlist"] = watchlist + if exclude_watchlist is not None: + params["excludeWatchlist"] = exclude_watchlist if paywall is not None: params["paywall"] = paywall if byline is not None: @@ -509,6 +1073,7 @@ async def search_articles_async( title: Optional[str] = None, desc: Optional[str] = None, content: Optional[str] = None, + summary: Optional[str] = None, url: Optional[str] = None, article_id: Optional[List[str]] = None, cluster_id: Optional[List[str]] = None, @@ -526,6 +1091,8 @@ async def search_articles_async( source_group: Optional[List[str]] = None, exclude_source_group: Optional[List[str]] = None, exclude_source: Optional[List[str]] = None, + watchlist: Optional[List[str]] = None, + exclude_watchlist: Optional[List[str]] = None, paywall: Optional[bool] = None, byline: Optional[List[str]] = None, author: Optional[List[str]] = None, @@ -596,92 +1163,95 @@ async def search_articles_async( Async variant of search_articles. Search and filter all news articles available via the Perigon API. The result includes a list of individual articles that were matched to your specific criteria. Args: - q (Optional[str]): Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - title (Optional[str]): Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - desc (Optional[str]): Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. - content (Optional[str]): Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. - url (Optional[str]): Search within article URLs to find content from specific website sections or domains. Supports wildcards (* and ?) for partial URL matching. - article_id (Optional[List[str]]): Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. - cluster_id (Optional[List[str]]): Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. - sort_by (Optional[AllEndpointSortBy]): Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - var_from (Optional[datetime]): Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - to (Optional[datetime]): Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - add_date_from (Optional[datetime]): Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - add_date_to (Optional[datetime]): Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - refresh_date_from (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - refresh_date_to (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - medium (Optional[List[str]]): Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. - source (Optional[List[str]]): Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. - source_group (Optional[List[str]]): Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. - exclude_source_group (Optional[List[str]]): Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). - exclude_source (Optional[List[str]]): Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. - paywall (Optional[bool]): Filter to show only results where the source has a paywall (true) or does not have a paywall (false). - byline (Optional[List[str]]): Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. - author (Optional[List[str]]): Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. - exclude_author (Optional[List[str]]): Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. - journalist_id (Optional[List[str]]): Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. - exclude_journalist_id (Optional[List[str]]): Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. - language (Optional[List[str]]): Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. - exclude_language (Optional[List[str]]): Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. - search_translation (Optional[bool]): Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. - label (Optional[List[str]]): Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. - exclude_label (Optional[List[str]]): Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. - category (Optional[List[str]]): Filter by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized articles. Multiple values create an OR filter. - exclude_category (Optional[List[str]]): Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. - topic (Optional[List[str]]): Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. - exclude_topic (Optional[List[str]]): Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. - link_to (Optional[str]): Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. - show_reprints (Optional[bool]): Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. - reprint_group_id (Optional[str]): Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. - city (Optional[List[str]]): Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_city (Optional[List[str]]): A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. - area (Optional[List[str]]): Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. - state (Optional[List[str]]): Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_state (Optional[List[str]]): A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). - county (Optional[List[str]]): A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. - exclude_county (Optional[List[str]]): Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter - locations_country (Optional[List[str]]): Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. - country (Optional[List[str]]): Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. - exclude_locations_country (Optional[List[str]]): Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. - location (Optional[List[str]]): Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. - lat (Optional[float]): Latitude of the center point to search places - lon (Optional[float]): Longitude of the center point to search places - max_distance (Optional[float]): Maximum distance (in km) from starting point to search articles by tagged places - source_city (Optional[List[str]]): Find articles published by sources that are located within a given city. - source_county (Optional[List[str]]): Find articles published by sources that are located within a given county. - source_country (Optional[List[str]]): Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). - source_state (Optional[List[str]]): Find articles published by sources that are located within a given state. - source_lat (Optional[float]): Latitude of the center point to search articles created by local publications. - source_lon (Optional[float]): Latitude of the center point to search articles created by local publications. - source_max_distance (Optional[float]): Maximum distance from starting point to search articles created by local publications. - person_wikidata_id (Optional[List[str]]): Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. - exclude_person_wikidata_id (Optional[List[str]]): Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. - person_name (Optional[List[str]]): Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. - exclude_person_name (Optional[List[str]]): Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. - company_id (Optional[List[str]]): Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. - exclude_company_id (Optional[List[str]]): Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. - company_name (Optional[str]): Filter articles by company name mentions. Performs an exact match on company names. - company_domain (Optional[List[str]]): Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. - exclude_company_domain (Optional[List[str]]): Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. - company_symbol (Optional[List[str]]): Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. - exclude_company_symbol (Optional[List[str]]): A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. - show_num_results (Optional[bool]): Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. - positive_sentiment_from (Optional[float]): Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - positive_sentiment_to (Optional[float]): Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - neutral_sentiment_from (Optional[float]): Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - neutral_sentiment_to (Optional[float]): Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - negative_sentiment_from (Optional[float]): Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - negative_sentiment_to (Optional[float]): Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - taxonomy (Optional[List[str]]): Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) - prefix_taxonomy (Optional[str]): Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance - show_highlighting (Optional[bool]): When set to true, enables text highlighting in search results. - highlight_fragment_size (Optional[int]): Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. - highlight_num_fragments (Optional[int]): Controls the maximum number of highlighted fragments to return per field. - highlight_pre_tag (Optional[str]): Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. - highlight_post_tag (Optional[str]): Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. - highlight_q (Optional[str]): Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + q (Optional[str]): String. Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + title (Optional[str]): String. Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + desc (Optional[str]): String. Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + content (Optional[str]): String. Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. + summary (Optional[str]): String. Search within article summary fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + url (Optional[str]): String. Search query on the url field. Semantic similar to q parameter. E.g. could be used for querying certain website sections, e.g. source=cnn.com&url=travel. + article_id (Optional[List[str]]): String Array. Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. + cluster_id (Optional[List[str]]): String Array. Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. + sort_by (Optional[AllEndpointSortBy]): String. Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + to (Optional[datetime]): Date. Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + add_date_from (Optional[datetime]): Date. Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + add_date_to (Optional[datetime]): Date. Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + refresh_date_from (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + refresh_date_to (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + medium (Optional[List[str]]): String Array. Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. + exclude_source_group (Optional[List[str]]): String Array. Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). + exclude_source (Optional[List[str]]): String Array. Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. + watchlist (Optional[List[str]]): String Array. Filter articles using watchlists of people and companies. Multiple values create an OR filter to include articles mentioning any entity from the specified watchlists. + exclude_watchlist (Optional[List[str]]): String Array. Exclude articles mentioning entities from specified watchlists. Multiple values create an AND-exclude filter, removing content mentioning any entity from the specified watchlists. + paywall (Optional[bool]): Boolean. Filter to show only results where the source has a paywall (true) or does not have a paywall (false). + byline (Optional[List[str]]): String Array. Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. + author (Optional[List[str]]): String Array. Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. + exclude_author (Optional[List[str]]): String Array. Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. + journalist_id (Optional[List[str]]): String Array. Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. + exclude_journalist_id (Optional[List[str]]): String Array. Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. + language (Optional[List[str]]): String Array. Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. + exclude_language (Optional[List[str]]): String Array. Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. + search_translation (Optional[bool]): Boolean. Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. + label (Optional[List[str]]): String Array. Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. + exclude_label (Optional[List[str]]): String Array. Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. + category (Optional[List[str]]): String Array. Filter by categories. Categories are general themes that the article is about. Examples of categories: Tech, Politics, etc. If multiple parameters are passed, they will be applied as OR operations. Use 'none' to search uncategorized articles. + exclude_category (Optional[List[str]]): String Array. Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. + topic (Optional[List[str]]): String Array. Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + exclude_topic (Optional[List[str]]): String Array. Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. + link_to (Optional[str]): String. Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. + show_reprints (Optional[bool]): Boolean. Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. + reprint_group_id (Optional[str]): String. Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. + city (Optional[List[str]]): String Array. Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_city (Optional[List[str]]): String Array. A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. + area (Optional[List[str]]): String Array. Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_state (Optional[List[str]]): String Array. A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). + county (Optional[List[str]]): String Array. A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. + exclude_county (Optional[List[str]]): String Array. Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter + locations_country (Optional[List[str]]): String Array. Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + exclude_locations_country (Optional[List[str]]): String Array. Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. + location (Optional[List[str]]): String Array. Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. + lat (Optional[float]): Float. Latitude of the center point to search places + lon (Optional[float]): Float. Longitude of the center point to search places + max_distance (Optional[float]): Float. Maximum distance (in km) from starting point to search articles by tagged places + source_city (Optional[List[str]]): String Array. Find articles published by sources that are located within a given city. + source_county (Optional[List[str]]): String Array. Find articles published by sources that are located within a given county. + source_country (Optional[List[str]]): String Array. Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). + source_state (Optional[List[str]]): String Array. Find articles published by sources that are located within a given state. + source_lat (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_lon (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_max_distance (Optional[float]): Float. Maximum distance from starting point to search articles created by local publications. + person_wikidata_id (Optional[List[str]]): String Array. Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. + exclude_person_wikidata_id (Optional[List[str]]): String Array. Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. + person_name (Optional[List[str]]): String Array. Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + exclude_person_name (Optional[List[str]]): String Array. Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. + company_id (Optional[List[str]]): String Array. Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. + exclude_company_id (Optional[List[str]]): String Array. Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. + company_name (Optional[str]): String. Filter articles by company name mentions. Performs an exact match on company names. + company_domain (Optional[List[str]]): String Array. Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. + exclude_company_domain (Optional[List[str]]): String Array. Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. + company_symbol (Optional[List[str]]): String Array. Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. + exclude_company_symbol (Optional[List[str]]): String Array. A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. + show_num_results (Optional[bool]): Boolean. Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + taxonomy (Optional[List[str]]): String Array. Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) + prefix_taxonomy (Optional[str]): String. Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. Returns: QuerySearchResult: The response @@ -698,6 +1268,8 @@ async def search_articles_async( params["desc"] = desc if content is not None: params["content"] = content + if summary is not None: + params["summary"] = summary if url is not None: params["url"] = url if article_id is not None: @@ -732,6 +1304,10 @@ async def search_articles_async( params["excludeSourceGroup"] = exclude_source_group if exclude_source is not None: params["excludeSource"] = exclude_source + if watchlist is not None: + params["watchlist"] = watchlist + if exclude_watchlist is not None: + params["excludeWatchlist"] = exclude_watchlist if paywall is not None: params["paywall"] = paywall if byline is not None: @@ -891,21 +1467,21 @@ def search_companies( Browse or search for companies Perigon tracks using name, domain, ticker symbol, industry, and more. Supports Boolean search logic and filtering by metadata such as country, exchange, employee count, and IPO date. Args: - id (Optional[List[str]]): Filter by unique company identifiers. Multiple values create an OR filter. - symbol (Optional[List[str]]): Filter by company stock ticker symbols (e.g., AAPL, MSFT, GOOGL). Multiple values create an OR filter. - domain (Optional[List[str]]): Filter by company domains or websites (e.g., apple.com, microsoft.com). Multiple values create an OR filter. - country (Optional[List[str]]): Filter by company headquarters country. Multiple values create an OR filter. - exchange (Optional[List[str]]): Filter by stock exchange where companies are listed (e.g., NASDAQ, NYSE). Multiple values create an OR filter. - num_employees_from (Optional[int]): Filter for companies with at least this many employees. - num_employees_to (Optional[int]): Filter for companies with no more than this many employees. - ipo_from (Optional[datetime]): Filter for companies that went public on or after this date. Accepts ISO 8601 format (e.g., 2023-01-01T00:00:00) or yyyy-mm-dd format. - ipo_to (Optional[datetime]): Filter for companies that went public on or before this date. Accepts ISO 8601 format (e.g., 2023-12-31T23:59:59) or yyyy-mm-dd format. - q (Optional[str]): Primary search query for filtering companies across name, alternative names, domains, and ticker symbols. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - name (Optional[str]): Search within company names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - industry (Optional[str]): Filter by company industry classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - sector (Optional[str]): Filter by company sector classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - size (Optional[int]): The number of companies to return per page in the paginated response. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. + id (Optional[List[str]]): String Array. Filter by unique company identifiers. Multiple values create an OR filter. + symbol (Optional[List[str]]): String Array. Filter by company stock ticker symbols (e.g., AAPL, MSFT, GOOGL). Multiple values create an OR filter. + domain (Optional[List[str]]): String Array. Filter by company domains or websites (e.g., apple.com, microsoft.com). Multiple values create an OR filter. + country (Optional[List[str]]): String Array. Filter by company headquarters country. Multiple values create an OR filter. + exchange (Optional[List[str]]): String Array. Filter by stock exchange where companies are listed (e.g., NASDAQ, NYSE). Multiple values create an OR filter. + num_employees_from (Optional[int]): Integer. Filter for companies with at least this many employees. + num_employees_to (Optional[int]): Integer. Filter for companies with no more than this many employees. + ipo_from (Optional[datetime]): Date. Filter for companies that went public on or after this date. Accepts ISO 8601 format (e.g., 2023-01-01T00:00:00) or yyyy-mm-dd format. + ipo_to (Optional[datetime]): Date. Filter for companies that went public on or before this date. Accepts ISO 8601 format (e.g., 2023-12-31T23:59:59) or yyyy-mm-dd format. + q (Optional[str]): String. Primary search query for filtering companies across name, alternative names, domains, and ticker symbols. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search within company names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + industry (Optional[str]): String. Filter by company industry classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + sector (Optional[str]): String. Filter by company sector classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + size (Optional[int]): Integer. The number of companies to return per page in the paginated response. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. Returns: CompanySearchResult: The response @@ -974,21 +1550,21 @@ async def search_companies_async( Async variant of search_companies. Browse or search for companies Perigon tracks using name, domain, ticker symbol, industry, and more. Supports Boolean search logic and filtering by metadata such as country, exchange, employee count, and IPO date. Args: - id (Optional[List[str]]): Filter by unique company identifiers. Multiple values create an OR filter. - symbol (Optional[List[str]]): Filter by company stock ticker symbols (e.g., AAPL, MSFT, GOOGL). Multiple values create an OR filter. - domain (Optional[List[str]]): Filter by company domains or websites (e.g., apple.com, microsoft.com). Multiple values create an OR filter. - country (Optional[List[str]]): Filter by company headquarters country. Multiple values create an OR filter. - exchange (Optional[List[str]]): Filter by stock exchange where companies are listed (e.g., NASDAQ, NYSE). Multiple values create an OR filter. - num_employees_from (Optional[int]): Filter for companies with at least this many employees. - num_employees_to (Optional[int]): Filter for companies with no more than this many employees. - ipo_from (Optional[datetime]): Filter for companies that went public on or after this date. Accepts ISO 8601 format (e.g., 2023-01-01T00:00:00) or yyyy-mm-dd format. - ipo_to (Optional[datetime]): Filter for companies that went public on or before this date. Accepts ISO 8601 format (e.g., 2023-12-31T23:59:59) or yyyy-mm-dd format. - q (Optional[str]): Primary search query for filtering companies across name, alternative names, domains, and ticker symbols. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - name (Optional[str]): Search within company names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - industry (Optional[str]): Filter by company industry classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - sector (Optional[str]): Filter by company sector classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - size (Optional[int]): The number of companies to return per page in the paginated response. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. + id (Optional[List[str]]): String Array. Filter by unique company identifiers. Multiple values create an OR filter. + symbol (Optional[List[str]]): String Array. Filter by company stock ticker symbols (e.g., AAPL, MSFT, GOOGL). Multiple values create an OR filter. + domain (Optional[List[str]]): String Array. Filter by company domains or websites (e.g., apple.com, microsoft.com). Multiple values create an OR filter. + country (Optional[List[str]]): String Array. Filter by company headquarters country. Multiple values create an OR filter. + exchange (Optional[List[str]]): String Array. Filter by stock exchange where companies are listed (e.g., NASDAQ, NYSE). Multiple values create an OR filter. + num_employees_from (Optional[int]): Integer. Filter for companies with at least this many employees. + num_employees_to (Optional[int]): Integer. Filter for companies with no more than this many employees. + ipo_from (Optional[datetime]): Date. Filter for companies that went public on or after this date. Accepts ISO 8601 format (e.g., 2023-01-01T00:00:00) or yyyy-mm-dd format. + ipo_to (Optional[datetime]): Date. Filter for companies that went public on or before this date. Accepts ISO 8601 format (e.g., 2023-12-31T23:59:59) or yyyy-mm-dd format. + q (Optional[str]): String. Primary search query for filtering companies across name, alternative names, domains, and ticker symbols. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search within company names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + industry (Optional[str]): String. Filter by company industry classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + sector (Optional[str]): String. Filter by company sector classifications. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + size (Optional[int]): Integer. The number of companies to return per page in the paginated response. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. Returns: CompanySearchResult: The response @@ -1057,22 +1633,22 @@ def search_journalists( Search journalists using broad search attributes. Our database contains over 230,000 journalists from around the world and is refreshed frequently. Args: - id (Optional[List[str]]): Filter by unique journalist identifiers. Multiple values create an OR filter to find journalists matching any of the specified IDs. - q (Optional[str]): Primary search query for filtering journalists based on their name, title, and Twitter bio. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - name (Optional[str]): Search specifically within journalist names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - twitter (Optional[str]): Filter journalists by their exact Twitter handle, without the @ symbol. - size (Optional[int]): The number of journalists to return per page in the paginated response. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - source (Optional[List[str]]): Filter journalists by the publisher domains they write for. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. - topic (Optional[List[str]]): Filter journalists by the topics they frequently cover. Multiple values create an OR filter to find journalists covering any of the specified topics. - category (Optional[List[str]]): Filter journalists by the content categories they typically write about (e.g., Politics, Tech, Sports, Business). Multiple values create an OR filter. - label (Optional[List[str]]): Filter journalists by the type of content they typically produce (e.g., Opinion, Paid-news, Non-news). Multiple values create an OR filter. - min_monthly_posts (Optional[int]): Filter for journalists who publish at least this many articles per month. Used to identify more active journalists. - max_monthly_posts (Optional[int]): Filter for journalists who publish no more than this many articles per month. - country (Optional[List[str]]): Filter journalists by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). Multiple values create an OR filter. - updated_at_from (Optional[datetime]): Filter for journalist profiles updated on or after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - updated_at_to (Optional[datetime]): Filter for journalist profiles updated on or before this date. Accepts ISO 8601 format (e.g., 2023-03-01T23:59:59) or yyyy-mm-dd format. - show_num_results (Optional[bool]): Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. + id (Optional[List[str]]): String Array. Filter by unique journalist identifiers. Multiple values create an OR filter to find journalists matching any of the specified IDs. + q (Optional[str]): String. Primary search query for filtering journalists based on their name, title, and Twitter bio. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search specifically within journalist names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + twitter (Optional[str]): String. Filter journalists by their exact Twitter handle, without the @ symbol. + size (Optional[int]): Integer. The number of journalists to return per page in the paginated response. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + source (Optional[List[str]]): String Array. Filter journalists by the publisher domains they write for. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. + topic (Optional[List[str]]): String Array. Filter journalists by the top topics they cover. Topics are more specific themes that the article is about. Examples of topics: 'Economy', 'Real Estate', 'Cryptocurrency'. If multiple parameters are passed, they will be applied as OR operations. (Searches inside the topCategories data field.) + category (Optional[List[str]]): String Array. Filter journalists by the top categories they cover. Categories are general themes that the article is about. Examples of categories: Tech, Politics, etc. If multiple parameters are passed, they will be applied as OR operations. (Searches inside the topCategories data field.) + label (Optional[List[str]]): String Array. Filter journalists by the most common label tagged to the articles they publish. This accepts labels like 'Opinion' or 'Pop Culture'. (Searches the topLabels data field.) + min_monthly_posts (Optional[int]): Integer. Filter for journalists who publish at least this many articles per month. Used to identify more active journalists. + max_monthly_posts (Optional[int]): Integer. Filter for journalists who publish no more than this many articles per month. + country (Optional[List[str]]): String Array. Filter journalists by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). Multiple values create an OR filter. + updated_at_from (Optional[datetime]): Date. Filter for journalist profiles updated on or after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + updated_at_to (Optional[datetime]): Date. Filter for journalist profiles updated on or before this date. Accepts ISO 8601 format (e.g., 2023-03-01T23:59:59) or yyyy-mm-dd format. + show_num_results (Optional[bool]): Boolean. Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. Returns: JournalistSearchResult: The response @@ -1144,22 +1720,22 @@ async def search_journalists_async( Async variant of search_journalists. Search journalists using broad search attributes. Our database contains over 230,000 journalists from around the world and is refreshed frequently. Args: - id (Optional[List[str]]): Filter by unique journalist identifiers. Multiple values create an OR filter to find journalists matching any of the specified IDs. - q (Optional[str]): Primary search query for filtering journalists based on their name, title, and Twitter bio. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - name (Optional[str]): Search specifically within journalist names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - twitter (Optional[str]): Filter journalists by their exact Twitter handle, without the @ symbol. - size (Optional[int]): The number of journalists to return per page in the paginated response. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - source (Optional[List[str]]): Filter journalists by the publisher domains they write for. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. - topic (Optional[List[str]]): Filter journalists by the topics they frequently cover. Multiple values create an OR filter to find journalists covering any of the specified topics. - category (Optional[List[str]]): Filter journalists by the content categories they typically write about (e.g., Politics, Tech, Sports, Business). Multiple values create an OR filter. - label (Optional[List[str]]): Filter journalists by the type of content they typically produce (e.g., Opinion, Paid-news, Non-news). Multiple values create an OR filter. - min_monthly_posts (Optional[int]): Filter for journalists who publish at least this many articles per month. Used to identify more active journalists. - max_monthly_posts (Optional[int]): Filter for journalists who publish no more than this many articles per month. - country (Optional[List[str]]): Filter journalists by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). Multiple values create an OR filter. - updated_at_from (Optional[datetime]): Filter for journalist profiles updated on or after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - updated_at_to (Optional[datetime]): Filter for journalist profiles updated on or before this date. Accepts ISO 8601 format (e.g., 2023-03-01T23:59:59) or yyyy-mm-dd format. - show_num_results (Optional[bool]): Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. + id (Optional[List[str]]): String Array. Filter by unique journalist identifiers. Multiple values create an OR filter to find journalists matching any of the specified IDs. + q (Optional[str]): String. Primary search query for filtering journalists based on their name, title, and Twitter bio. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search specifically within journalist names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + twitter (Optional[str]): String. Filter journalists by their exact Twitter handle, without the @ symbol. + size (Optional[int]): Integer. The number of journalists to return per page in the paginated response. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + source (Optional[List[str]]): String Array. Filter journalists by the publisher domains they write for. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. + topic (Optional[List[str]]): String Array. Filter journalists by the top topics they cover. Topics are more specific themes that the article is about. Examples of topics: 'Economy', 'Real Estate', 'Cryptocurrency'. If multiple parameters are passed, they will be applied as OR operations. (Searches inside the topCategories data field.) + category (Optional[List[str]]): String Array. Filter journalists by the top categories they cover. Categories are general themes that the article is about. Examples of categories: Tech, Politics, etc. If multiple parameters are passed, they will be applied as OR operations. (Searches inside the topCategories data field.) + label (Optional[List[str]]): String Array. Filter journalists by the most common label tagged to the articles they publish. This accepts labels like 'Opinion' or 'Pop Culture'. (Searches the topLabels data field.) + min_monthly_posts (Optional[int]): Integer. Filter for journalists who publish at least this many articles per month. Used to identify more active journalists. + max_monthly_posts (Optional[int]): Integer. Filter for journalists who publish no more than this many articles per month. + country (Optional[List[str]]): String Array. Filter journalists by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). Multiple values create an OR filter. + updated_at_from (Optional[datetime]): Date. Filter for journalist profiles updated on or after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + updated_at_to (Optional[datetime]): Date. Filter for journalist profiles updated on or before this date. Accepts ISO 8601 format (e.g., 2023-03-01T23:59:59) or yyyy-mm-dd format. + show_num_results (Optional[bool]): Boolean. Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. Returns: JournalistSearchResult: The response @@ -1220,12 +1796,12 @@ def search_people( Search and retrieve additional information on known persons that exist within Perigon's entity database and as referenced in any article response object. Our database contains over 650,000 people from around the world and is refreshed frequently. People data is derived from Wikidata and includes a wikidataId field that can be used to lookup even more information on Wikidata's website. Args: - name (Optional[str]): Search by person's name. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - wikidata_id (Optional[List[str]]): Filter by Wikidata entity IDs (e.g., Q7747, Q937). These are unique identifiers from Wikidata.org that precisely identify public figures and eliminate name ambiguity. Multiple values create an OR filter. - occupation_id (Optional[List[str]]): Filter by Wikidata occupation IDs (e.g., Q82955 for politician, Q33999 for actor, Q19546 for businessman). Finds people with specific professions. Multiple values create an OR filter. - occupation_label (Optional[str]): Search by occupation name (e.g., politician, actor, CEO, athlete). Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of people to return per page in the paginated response. + name (Optional[str]): String. Search by person's name. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + wikidata_id (Optional[List[str]]): String Array. Filter by Wikidata entity IDs (e.g., Q7747, Q937). These are unique identifiers from Wikidata.org that precisely identify public figures and eliminate name ambiguity. Multiple values create an OR filter. + occupation_id (Optional[List[str]]): String Array. Filter by Wikidata occupation IDs (e.g., Q82955 for politician, Q33999 for actor, Q19546 for businessman). Finds people with specific professions. Multiple values create an OR filter. + occupation_label (Optional[str]): String. Search by occupation name (e.g., politician, actor, CEO, athlete). Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of people to return per page in the paginated response. Returns: PeopleSearchResult: The response @@ -1267,12 +1843,12 @@ async def search_people_async( Async variant of search_people. Search and retrieve additional information on known persons that exist within Perigon's entity database and as referenced in any article response object. Our database contains over 650,000 people from around the world and is refreshed frequently. People data is derived from Wikidata and includes a wikidataId field that can be used to lookup even more information on Wikidata's website. Args: - name (Optional[str]): Search by person's name. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - wikidata_id (Optional[List[str]]): Filter by Wikidata entity IDs (e.g., Q7747, Q937). These are unique identifiers from Wikidata.org that precisely identify public figures and eliminate name ambiguity. Multiple values create an OR filter. - occupation_id (Optional[List[str]]): Filter by Wikidata occupation IDs (e.g., Q82955 for politician, Q33999 for actor, Q19546 for businessman). Finds people with specific professions. Multiple values create an OR filter. - occupation_label (Optional[str]): Search by occupation name (e.g., politician, actor, CEO, athlete). Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of people to return per page in the paginated response. + name (Optional[str]): String. Search by person's name. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + wikidata_id (Optional[List[str]]): String Array. Filter by Wikidata entity IDs (e.g., Q7747, Q937). These are unique identifiers from Wikidata.org that precisely identify public figures and eliminate name ambiguity. Multiple values create an OR filter. + occupation_id (Optional[List[str]]): String Array. Filter by Wikidata occupation IDs (e.g., Q82955 for politician, Q33999 for actor, Q19546 for businessman). Finds people with specific professions. Multiple values create an OR filter. + occupation_label (Optional[str]): String. Search by occupation name (e.g., politician, actor, CEO, athlete). Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of people to return per page in the paginated response. Returns: PeopleSearchResult: The response @@ -1331,30 +1907,30 @@ def search_sources( Search and filter the 142,000+ media sources available via the Perigon API. The result includes a list of individual media sources that were matched to your specific criteria. Args: - domain (Optional[List[str]]): Filter by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com, us?.nytimes.com). Multiple values create an OR filter. - name (Optional[str]): Search by source name or alternative names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - source_group (Optional[str]): Filter by predefined publisher bundles (e.g., top100, top50tech). Returns all sources within the specified group. See documentation for available source groups. - sort_by (Optional[SortBy]): Determines the source sorting order. Options include relevance (default, best match to query), globalRank (by overall traffic and popularity), monthlyVisits (by total monthly visitor count), and avgMonthlyPosts (by number of articles published monthly). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of sources to return per page in the paginated response. - min_monthly_visits (Optional[int]): Filter for sources with at least this many monthly visitors. Used to target publishers by audience size. - max_monthly_visits (Optional[int]): Filter for sources with no more than this many monthly visitors. Used to target publishers by audience size. - min_monthly_posts (Optional[int]): Filter for sources that publish at least this many articles per month. Used to target publishers by content volume. - max_monthly_posts (Optional[int]): Filter for sources that publish no more than this many articles per month. Used to target publishers by content volume. - country (Optional[List[str]]): Filter sources by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. - source_country (Optional[List[str]]): Filter for local publications based in specific countries. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. - source_state (Optional[List[str]]): Filter for local publications based in specific states or regions. Uses standard two-letter state codes in lowercase (e.g., ca, ny, tx). See documentation for supported state codes. Multiple values create an OR filter. - source_county (Optional[List[str]]): Filter for local publications based in specific counties. Multiple values create an OR filter. - source_city (Optional[List[str]]): Filter for local publications based in specific cities. Multiple values create an OR filter. - source_lat (Optional[float]): Latitude coordinate for filtering local publications by geographic proximity. Used with sourceLon and sourceMaxDistance for radius search. - source_lon (Optional[float]): Longitude coordinate for filtering local publications by geographic proximity. Used with sourceLat and sourceMaxDistance for radius search. - source_max_distance (Optional[float]): Maximum distance in kilometers from the coordinates defined by sourceLat and sourceLon. Defines the radius for local publication searches. - category (Optional[List[str]]): Filter sources by their primary content categories such as Politics, Tech, Sports, Business, or Finance. Returns sources that frequently cover these topics. Multiple values create an OR filter. - topic (Optional[List[str]]): Filter sources by their frequently covered topics (e.g., Markets, Cryptocurrency, Climate Change). Returns sources where the specified topic is among their top 10 covered areas. Multiple values create an OR filter. - label (Optional[List[str]]): Filter sources by their content label patterns (e.g., Opinion, Paid-news, Non-news). Returns sources where the specified label is common in their published content. See documentation for all available labels. Multiple values create an OR filter. - paywall (Optional[bool]): Filter by paywall status. Set to true to find sources with paywalls, or false to find sources without paywalls. - show_subdomains (Optional[bool]): Controls whether subdomains are included as separate results. When true (default), subdomains appear as distinct sources. When false, results are consolidated to parent domains only. - show_num_results (Optional[bool]): Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. + domain (Optional[List[str]]): String Array. Filter by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com, us?.nytimes.com). Multiple values create an OR filter. + name (Optional[str]): String. Search by source name or alternative names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + source_group (Optional[str]): String. Filter by predefined publisher bundles (e.g., top100, top50tech). Returns all sources within the specified group. See documentation for available source groups. + sort_by (Optional[SortBy]): String. Determines the source sorting order. Options include relevance (default, best match to query), globalRank (by overall traffic and popularity), monthlyVisits (by total monthly visitor count), and avgMonthlyPosts (by number of articles published monthly). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of sources to return per page in the paginated response. + min_monthly_visits (Optional[int]): Integer. Filter for sources with at least this many monthly visitors. Used to target publishers by audience size. + max_monthly_visits (Optional[int]): Integer. Filter for sources with no more than this many monthly visitors. Used to target publishers by audience size. + min_monthly_posts (Optional[int]): Integer. Filter for sources that publish at least this many articles per month. Used to target publishers by content volume. + max_monthly_posts (Optional[int]): Integer. Filter for sources that publish no more than this many articles per month. Used to target publishers by content volume. + country (Optional[List[str]]): String Array. Filter sources by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. + source_country (Optional[List[str]]): String Array. Filter for local publications based in specific countries. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. + source_state (Optional[List[str]]): String Array. Filter for local publications based in specific states or regions. Uses standard two-letter state codes in lowercase (e.g., ca, ny, tx). See documentation for supported state codes. Multiple values create an OR filter. + source_county (Optional[List[str]]): String Array. Filter for local publications based in specific counties. Multiple values create an OR filter. + source_city (Optional[List[str]]): String Array. Filter for local publications based in specific cities. Multiple values create an OR filter. + source_lat (Optional[float]): Float. Latitude coordinate for filtering local publications by geographic proximity. Used with sourceLon and sourceMaxDistance for radius search. + source_lon (Optional[float]): Float. Longitude coordinate for filtering local publications by geographic proximity. Used with sourceLat and sourceMaxDistance for radius search. + source_max_distance (Optional[float]): Float. Maximum distance in kilometers from the coordinates defined by sourceLat and sourceLon. Defines the radius for local publication searches. + category (Optional[List[str]]): String Array. Filter sources by their primary content categories such as Politics, Tech, Sports, Business, or Finance. Returns sources that frequently cover these topics. Multiple values create an OR filter. + topic (Optional[List[str]]): String Array. Filter sources by their frequently covered topics (e.g., Markets, Cryptocurrency, Climate Change). Returns sources where the specified topic is among their top 10 covered areas. Multiple values create an OR filter. + label (Optional[List[str]]): String Array. Filter sources by their content label patterns (e.g., Opinion, Paid-news, Non-news). Returns sources where the specified label is common in their published content. See documentation for all available labels. Multiple values create an OR filter. + paywall (Optional[bool]): Boolean. Filter by paywall status. Set to true to find sources with paywalls, or false to find sources without paywalls. + show_subdomains (Optional[bool]): Boolean. Controls whether subdomains are included as separate results. When true (default), subdomains appear as distinct sources. When false, results are consolidated to parent domains only. + show_num_results (Optional[bool]): Boolean. Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. Returns: SourceSearchResult: The response @@ -1450,30 +2026,30 @@ async def search_sources_async( Async variant of search_sources. Search and filter the 142,000+ media sources available via the Perigon API. The result includes a list of individual media sources that were matched to your specific criteria. Args: - domain (Optional[List[str]]): Filter by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com, us?.nytimes.com). Multiple values create an OR filter. - name (Optional[str]): Search by source name or alternative names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - source_group (Optional[str]): Filter by predefined publisher bundles (e.g., top100, top50tech). Returns all sources within the specified group. See documentation for available source groups. - sort_by (Optional[SortBy]): Determines the source sorting order. Options include relevance (default, best match to query), globalRank (by overall traffic and popularity), monthlyVisits (by total monthly visitor count), and avgMonthlyPosts (by number of articles published monthly). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of sources to return per page in the paginated response. - min_monthly_visits (Optional[int]): Filter for sources with at least this many monthly visitors. Used to target publishers by audience size. - max_monthly_visits (Optional[int]): Filter for sources with no more than this many monthly visitors. Used to target publishers by audience size. - min_monthly_posts (Optional[int]): Filter for sources that publish at least this many articles per month. Used to target publishers by content volume. - max_monthly_posts (Optional[int]): Filter for sources that publish no more than this many articles per month. Used to target publishers by content volume. - country (Optional[List[str]]): Filter sources by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. - source_country (Optional[List[str]]): Filter for local publications based in specific countries. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. - source_state (Optional[List[str]]): Filter for local publications based in specific states or regions. Uses standard two-letter state codes in lowercase (e.g., ca, ny, tx). See documentation for supported state codes. Multiple values create an OR filter. - source_county (Optional[List[str]]): Filter for local publications based in specific counties. Multiple values create an OR filter. - source_city (Optional[List[str]]): Filter for local publications based in specific cities. Multiple values create an OR filter. - source_lat (Optional[float]): Latitude coordinate for filtering local publications by geographic proximity. Used with sourceLon and sourceMaxDistance for radius search. - source_lon (Optional[float]): Longitude coordinate for filtering local publications by geographic proximity. Used with sourceLat and sourceMaxDistance for radius search. - source_max_distance (Optional[float]): Maximum distance in kilometers from the coordinates defined by sourceLat and sourceLon. Defines the radius for local publication searches. - category (Optional[List[str]]): Filter sources by their primary content categories such as Politics, Tech, Sports, Business, or Finance. Returns sources that frequently cover these topics. Multiple values create an OR filter. - topic (Optional[List[str]]): Filter sources by their frequently covered topics (e.g., Markets, Cryptocurrency, Climate Change). Returns sources where the specified topic is among their top 10 covered areas. Multiple values create an OR filter. - label (Optional[List[str]]): Filter sources by their content label patterns (e.g., Opinion, Paid-news, Non-news). Returns sources where the specified label is common in their published content. See documentation for all available labels. Multiple values create an OR filter. - paywall (Optional[bool]): Filter by paywall status. Set to true to find sources with paywalls, or false to find sources without paywalls. - show_subdomains (Optional[bool]): Controls whether subdomains are included as separate results. When true (default), subdomains appear as distinct sources. When false, results are consolidated to parent domains only. - show_num_results (Optional[bool]): Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. + domain (Optional[List[str]]): String Array. Filter by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com, us?.nytimes.com). Multiple values create an OR filter. + name (Optional[str]): String. Search by source name or alternative names. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + source_group (Optional[str]): String. Filter by predefined publisher bundles (e.g., top100, top50tech). Returns all sources within the specified group. See documentation for available source groups. + sort_by (Optional[SortBy]): String. Determines the source sorting order. Options include relevance (default, best match to query), globalRank (by overall traffic and popularity), monthlyVisits (by total monthly visitor count), and avgMonthlyPosts (by number of articles published monthly). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of sources to return per page in the paginated response. + min_monthly_visits (Optional[int]): Integer. Filter for sources with at least this many monthly visitors. Used to target publishers by audience size. + max_monthly_visits (Optional[int]): Integer. Filter for sources with no more than this many monthly visitors. Used to target publishers by audience size. + min_monthly_posts (Optional[int]): Integer. Filter for sources that publish at least this many articles per month. Used to target publishers by content volume. + max_monthly_posts (Optional[int]): Integer. Filter for sources that publish no more than this many articles per month. Used to target publishers by content volume. + country (Optional[List[str]]): String Array. Filter sources by countries they commonly cover in their reporting. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. + source_country (Optional[List[str]]): String Array. Filter for local publications based in specific countries. Uses ISO 3166-1 alpha-2 two-letter country codes in lowercase (e.g., us, gb, jp). See documentation for supported country codes. Multiple values create an OR filter. + source_state (Optional[List[str]]): String Array. Filter for local publications based in specific states or regions. Uses standard two-letter state codes in lowercase (e.g., ca, ny, tx). See documentation for supported state codes. Multiple values create an OR filter. + source_county (Optional[List[str]]): String Array. Filter for local publications based in specific counties. Multiple values create an OR filter. + source_city (Optional[List[str]]): String Array. Filter for local publications based in specific cities. Multiple values create an OR filter. + source_lat (Optional[float]): Float. Latitude coordinate for filtering local publications by geographic proximity. Used with sourceLon and sourceMaxDistance for radius search. + source_lon (Optional[float]): Float. Longitude coordinate for filtering local publications by geographic proximity. Used with sourceLat and sourceMaxDistance for radius search. + source_max_distance (Optional[float]): Float. Maximum distance in kilometers from the coordinates defined by sourceLat and sourceLon. Defines the radius for local publication searches. + category (Optional[List[str]]): String Array. Filter sources by their primary content categories such as Politics, Tech, Sports, Business, or Finance. Returns sources that frequently cover these topics. Multiple values create an OR filter. + topic (Optional[List[str]]): String Array. Filter sources by their frequently covered topics (e.g., Markets, Cryptocurrency, Climate Change). Returns sources where the specified topic is among their top 10 covered areas. Multiple values create an OR filter. + label (Optional[List[str]]): String Array. Filter sources by their content label patterns (e.g., Opinion, Paid-news, Non-news). Returns sources where the specified label is common in their published content. See documentation for all available labels. Multiple values create an OR filter. + paywall (Optional[bool]): Boolean. Filter by paywall status. Set to true to find sources with paywalls, or false to find sources without paywalls. + show_subdomains (Optional[bool]): Boolean. Controls whether subdomains are included as separate results. When true (default), subdomains appear as distinct sources. When false, results are consolidated to parent domains only. + show_num_results (Optional[bool]): Boolean. Controls whether to return the exact result count. When false (default), counts are capped at 10,000 for performance reasons. Set to true for precise counts in smaller result sets. Returns: SourceSearchResult: The response @@ -1586,58 +2162,60 @@ def search_stories( highlight_pre_tag: Optional[str] = None, highlight_post_tag: Optional[str] = None, highlight_q: Optional[str] = None, + expand_articles: Optional[bool] = None, ) -> StorySearchResult: """ - Search and filter all news stories available via the Perigon API. Each story aggregates key information across related articles, including AI-generated names, summaries, and key points. + Track evolving narratives and top news headlines with the '**Stories**' endpoint — it returns structured clusters of related articles with summaries, key points, sentiment scores, and metadata on top people, companies, topics, countries, and categories. Use it to monitor how news stories develop over time, who and what they impact, and where they're gaining traction globally. Each story represents a cluster of related articles grouped during processing. Articles are assigned to a single story, identified by the `clusterId` field. Once a story reaches five articles, a story title is automatically generated based on its content. Stories update as new coverage is processed and key details evolve. To fetch all articles within a specific story, query the `/articles/all` endpoint using the `clusterId` parameter. Args: - q (Optional[str]): Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - name (Optional[str]): Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations. - cluster_id (Optional[List[str]]): Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter. - exclude_cluster_id (Optional[List[str]]): Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories. - sort_by (Optional[SortBy]): Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - var_from (Optional[datetime]): 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 - to (Optional[datetime]): 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59 - initialized_from (Optional[datetime]): Filter for stories created after this date. Alternative parameter for filtering by story creation date. - initialized_to (Optional[datetime]): Filter for stories created before this date. Alternative parameter for filtering by story creation date. - updated_from (Optional[datetime]): Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines. - updated_to (Optional[datetime]): Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines. - topic (Optional[List[str]]): Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. - category (Optional[List[str]]): Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter. - taxonomy (Optional[List[str]]): Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter. - source (Optional[List[str]]): Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter. - source_group (Optional[List[str]]): Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter. - min_unique_sources (Optional[int]): Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3. - person_wikidata_id (Optional[List[str]]): Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals. - person_name (Optional[str]): Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. - company_id (Optional[List[str]]): Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint. - company_name (Optional[str]): Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field. - company_domain (Optional[List[str]]): Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint. - company_symbol (Optional[List[str]]): Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint. - country (Optional[List[str]]): Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. - state (Optional[List[str]]): Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. - city (Optional[List[str]]): Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. - area (Optional[List[str]]): Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. - min_cluster_size (Optional[int]): Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles. - max_cluster_size (Optional[int]): Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster. - name_exists (Optional[bool]): Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles. - positive_sentiment_from (Optional[float]): Filter articles with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - positive_sentiment_to (Optional[float]): Filter articles with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - neutral_sentiment_from (Optional[float]): Filter articles with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - neutral_sentiment_to (Optional[float]): Filter articles with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - negative_sentiment_from (Optional[float]): Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - negative_sentiment_to (Optional[float]): Filter articles with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - show_story_page_info (Optional[bool]): Parameter show_story_page_info - show_num_results (Optional[bool]): Show total number of results. By default set to false, will cap result count at 10000. - show_duplicates (Optional[bool]): Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown. - show_highlighting (Optional[bool]): When set to true, enables text highlighting in search results. - highlight_fragment_size (Optional[int]): Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. - highlight_num_fragments (Optional[int]): Controls the maximum number of highlighted fragments to return per field. - highlight_pre_tag (Optional[str]): Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. - highlight_post_tag (Optional[str]): Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. - highlight_q (Optional[str]): Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + q (Optional[str]): String. Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations. + cluster_id (Optional[List[str]]): String Array. Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter. + exclude_cluster_id (Optional[List[str]]): String Array. Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories. + sort_by (Optional[SortBy]): String. Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 + to (Optional[datetime]): Date. 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59 + initialized_from (Optional[datetime]): Date. Filter for stories created after this date. Alternative parameter for filtering by story creation date. + initialized_to (Optional[datetime]): Date. Filter for stories created before this date. Alternative parameter for filtering by story creation date. + updated_from (Optional[datetime]): Date. Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines. + updated_to (Optional[datetime]): Date. Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines. + topic (Optional[List[str]]): String Array. Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + category (Optional[List[str]]): String Array. Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter. + taxonomy (Optional[List[str]]): String Array. Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter. + min_unique_sources (Optional[int]): Integer. Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3. + person_wikidata_id (Optional[List[str]]): String Array. Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals. + person_name (Optional[str]): String. Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + company_id (Optional[List[str]]): String Array. Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint. + company_name (Optional[str]): String. Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field. + company_domain (Optional[List[str]]): String Array. Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint. + company_symbol (Optional[List[str]]): String Array. Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + city (Optional[List[str]]): String Array. Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + area (Optional[List[str]]): String Array. Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + min_cluster_size (Optional[int]): Integer. Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles. + max_cluster_size (Optional[int]): Integer. Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster. + name_exists (Optional[bool]): Boolean. Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + show_story_page_info (Optional[bool]): Boolean. + show_num_results (Optional[bool]): Boolean. Show total number of results. By default set to false, will cap result count at 10000. + show_duplicates (Optional[bool]): Boolean. Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown. + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + expand_articles (Optional[bool]): Boolean. Preview 5 articles from the cluster. Returns: StorySearchResult: The response @@ -1741,6 +2319,8 @@ def search_stories( params["highlightPostTag"] = highlight_post_tag if highlight_q is not None: params["highlightQ"] = highlight_q + if expand_articles is not None: + params["expandArticles"] = expand_articles params = _normalise_query(params) resp = self.api_client.request("GET", path, params=params) @@ -1797,58 +2377,60 @@ async def search_stories_async( highlight_pre_tag: Optional[str] = None, highlight_post_tag: Optional[str] = None, highlight_q: Optional[str] = None, + expand_articles: Optional[bool] = None, ) -> StorySearchResult: """ - Async variant of search_stories. Search and filter all news stories available via the Perigon API. Each story aggregates key information across related articles, including AI-generated names, summaries, and key points. + Async variant of search_stories. Track evolving narratives and top news headlines with the '**Stories**' endpoint — it returns structured clusters of related articles with summaries, key points, sentiment scores, and metadata on top people, companies, topics, countries, and categories. Use it to monitor how news stories develop over time, who and what they impact, and where they're gaining traction globally. Each story represents a cluster of related articles grouped during processing. Articles are assigned to a single story, identified by the `clusterId` field. Once a story reaches five articles, a story title is automatically generated based on its content. Stories update as new coverage is processed and key details evolve. To fetch all articles within a specific story, query the `/articles/all` endpoint using the `clusterId` parameter. Args: - q (Optional[str]): Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - name (Optional[str]): Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations. - cluster_id (Optional[List[str]]): Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter. - exclude_cluster_id (Optional[List[str]]): Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories. - sort_by (Optional[SortBy]): Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - var_from (Optional[datetime]): 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 - to (Optional[datetime]): 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59 - initialized_from (Optional[datetime]): Filter for stories created after this date. Alternative parameter for filtering by story creation date. - initialized_to (Optional[datetime]): Filter for stories created before this date. Alternative parameter for filtering by story creation date. - updated_from (Optional[datetime]): Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines. - updated_to (Optional[datetime]): Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines. - topic (Optional[List[str]]): Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. - category (Optional[List[str]]): Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter. - taxonomy (Optional[List[str]]): Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter. - source (Optional[List[str]]): Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter. - source_group (Optional[List[str]]): Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter. - min_unique_sources (Optional[int]): Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3. - person_wikidata_id (Optional[List[str]]): Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals. - person_name (Optional[str]): Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. - company_id (Optional[List[str]]): Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint. - company_name (Optional[str]): Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field. - company_domain (Optional[List[str]]): Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint. - company_symbol (Optional[List[str]]): Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint. - country (Optional[List[str]]): Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. - state (Optional[List[str]]): Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. - city (Optional[List[str]]): Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. - area (Optional[List[str]]): Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. - min_cluster_size (Optional[int]): Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles. - max_cluster_size (Optional[int]): Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster. - name_exists (Optional[bool]): Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles. - positive_sentiment_from (Optional[float]): Filter articles with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - positive_sentiment_to (Optional[float]): Filter articles with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - neutral_sentiment_from (Optional[float]): Filter articles with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - neutral_sentiment_to (Optional[float]): Filter articles with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - negative_sentiment_from (Optional[float]): Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - negative_sentiment_to (Optional[float]): Filter articles with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - show_story_page_info (Optional[bool]): Parameter show_story_page_info - show_num_results (Optional[bool]): Show total number of results. By default set to false, will cap result count at 10000. - show_duplicates (Optional[bool]): Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown. - show_highlighting (Optional[bool]): When set to true, enables text highlighting in search results. - highlight_fragment_size (Optional[int]): Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. - highlight_num_fragments (Optional[int]): Controls the maximum number of highlighted fragments to return per field. - highlight_pre_tag (Optional[str]): Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. - highlight_post_tag (Optional[str]): Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. - highlight_q (Optional[str]): Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + q (Optional[str]): String. Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + name (Optional[str]): String. Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations. + cluster_id (Optional[List[str]]): String Array. Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter. + exclude_cluster_id (Optional[List[str]]): String Array. Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories. + sort_by (Optional[SortBy]): String. Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00 + to (Optional[datetime]): Date. 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59 + initialized_from (Optional[datetime]): Date. Filter for stories created after this date. Alternative parameter for filtering by story creation date. + initialized_to (Optional[datetime]): Date. Filter for stories created before this date. Alternative parameter for filtering by story creation date. + updated_from (Optional[datetime]): Date. Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines. + updated_to (Optional[datetime]): Date. Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines. + topic (Optional[List[str]]): String Array. Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + category (Optional[List[str]]): String Array. Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter. + taxonomy (Optional[List[str]]): String Array. Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter. + min_unique_sources (Optional[int]): Integer. Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3. + person_wikidata_id (Optional[List[str]]): String Array. Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals. + person_name (Optional[str]): String. Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + company_id (Optional[List[str]]): String Array. Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint. + company_name (Optional[str]): String. Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field. + company_domain (Optional[List[str]]): String Array. Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint. + company_symbol (Optional[List[str]]): String Array. Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + city (Optional[List[str]]): String Array. Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + area (Optional[List[str]]): String Array. Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations. + min_cluster_size (Optional[int]): Integer. Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles. + max_cluster_size (Optional[int]): Integer. Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster. + name_exists (Optional[bool]): Boolean. Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + show_story_page_info (Optional[bool]): Boolean. + show_num_results (Optional[bool]): Boolean. Show total number of results. By default set to false, will cap result count at 10000. + show_duplicates (Optional[bool]): Boolean. Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown. + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + expand_articles (Optional[bool]): Boolean. Preview 5 articles from the cluster. Returns: StorySearchResult: The response @@ -1951,6 +2533,8 @@ async def search_stories_async( params["highlightPostTag"] = highlight_post_tag if highlight_q is not None: params["highlightQ"] = highlight_q + if expand_articles is not None: + params["expandArticles"] = expand_articles params = _normalise_query(params) resp = await self.api_client.request_async("GET", path, params=params) @@ -1965,6 +2549,7 @@ def search_summarizer( title: Optional[str] = None, desc: Optional[str] = None, content: Optional[str] = None, + summary: Optional[str] = None, url: Optional[str] = None, article_id: Optional[List[str]] = None, cluster_id: Optional[List[str]] = None, @@ -1982,6 +2567,8 @@ def search_summarizer( source_group: Optional[List[str]] = None, exclude_source_group: Optional[List[str]] = None, exclude_source: Optional[List[str]] = None, + watchlist: Optional[List[str]] = None, + exclude_watchlist: Optional[List[str]] = None, paywall: Optional[bool] = None, byline: Optional[List[str]] = None, author: Optional[List[str]] = None, @@ -2053,92 +2640,95 @@ def search_summarizer( Args: summary_body (SummaryBody): Parameter summary_body (required) - q (Optional[str]): Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - title (Optional[str]): Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - desc (Optional[str]): Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. - content (Optional[str]): Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. - url (Optional[str]): Search within article URLs to find content from specific website sections or domains. Supports wildcards (* and ?) for partial URL matching. - article_id (Optional[List[str]]): Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. - cluster_id (Optional[List[str]]): Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. - sort_by (Optional[AllEndpointSortBy]): Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - var_from (Optional[datetime]): Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - to (Optional[datetime]): Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - add_date_from (Optional[datetime]): Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - add_date_to (Optional[datetime]): Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - refresh_date_from (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - refresh_date_to (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - medium (Optional[List[str]]): Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. - source (Optional[List[str]]): Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. - source_group (Optional[List[str]]): Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. - exclude_source_group (Optional[List[str]]): Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). - exclude_source (Optional[List[str]]): Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. - paywall (Optional[bool]): Filter to show only results where the source has a paywall (true) or does not have a paywall (false). - byline (Optional[List[str]]): Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. - author (Optional[List[str]]): Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. - exclude_author (Optional[List[str]]): Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. - journalist_id (Optional[List[str]]): Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. - exclude_journalist_id (Optional[List[str]]): Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. - language (Optional[List[str]]): Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. - exclude_language (Optional[List[str]]): Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. - search_translation (Optional[bool]): Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. - label (Optional[List[str]]): Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. - exclude_label (Optional[List[str]]): Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. - category (Optional[List[str]]): Filter by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized articles. Multiple values create an OR filter. - exclude_category (Optional[List[str]]): Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. - topic (Optional[List[str]]): Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. - exclude_topic (Optional[List[str]]): Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. - link_to (Optional[str]): Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. - show_reprints (Optional[bool]): Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. - reprint_group_id (Optional[str]): Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. - city (Optional[List[str]]): Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_city (Optional[List[str]]): A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. - area (Optional[List[str]]): Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. - state (Optional[List[str]]): Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_state (Optional[List[str]]): A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). - county (Optional[List[str]]): A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. - exclude_county (Optional[List[str]]): Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter - locations_country (Optional[List[str]]): Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. - country (Optional[List[str]]): Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. - exclude_locations_country (Optional[List[str]]): Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. - location (Optional[List[str]]): Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. - lat (Optional[float]): Latitude of the center point to search places - lon (Optional[float]): Longitude of the center point to search places - max_distance (Optional[float]): Maximum distance (in km) from starting point to search articles by tagged places - source_city (Optional[List[str]]): Find articles published by sources that are located within a given city. - source_county (Optional[List[str]]): Find articles published by sources that are located within a given county. - source_country (Optional[List[str]]): Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). - source_state (Optional[List[str]]): Find articles published by sources that are located within a given state. - source_lat (Optional[float]): Latitude of the center point to search articles created by local publications. - source_lon (Optional[float]): Latitude of the center point to search articles created by local publications. - source_max_distance (Optional[float]): Maximum distance from starting point to search articles created by local publications. - person_wikidata_id (Optional[List[str]]): Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. - exclude_person_wikidata_id (Optional[List[str]]): Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. - person_name (Optional[List[str]]): Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. - exclude_person_name (Optional[List[str]]): Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. - company_id (Optional[List[str]]): Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. - exclude_company_id (Optional[List[str]]): Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. - company_name (Optional[str]): Filter articles by company name mentions. Performs an exact match on company names. - company_domain (Optional[List[str]]): Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. - exclude_company_domain (Optional[List[str]]): Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. - company_symbol (Optional[List[str]]): Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. - exclude_company_symbol (Optional[List[str]]): A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. - show_num_results (Optional[bool]): Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. - positive_sentiment_from (Optional[float]): Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - positive_sentiment_to (Optional[float]): Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - neutral_sentiment_from (Optional[float]): Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - neutral_sentiment_to (Optional[float]): Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - negative_sentiment_from (Optional[float]): Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - negative_sentiment_to (Optional[float]): Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - taxonomy (Optional[List[str]]): Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) - prefix_taxonomy (Optional[str]): Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance - show_highlighting (Optional[bool]): When set to true, enables text highlighting in search results. - highlight_fragment_size (Optional[int]): Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. - highlight_num_fragments (Optional[int]): Controls the maximum number of highlighted fragments to return per field. - highlight_pre_tag (Optional[str]): Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. - highlight_post_tag (Optional[str]): Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. - highlight_q (Optional[str]): Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + q (Optional[str]): String. Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + title (Optional[str]): String. Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + desc (Optional[str]): String. Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + content (Optional[str]): String. Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. + summary (Optional[str]): String. Search within article summary fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + url (Optional[str]): String. Search query on the url field. Semantic similar to q parameter. E.g. could be used for querying certain website sections, e.g. source=cnn.com&url=travel. + article_id (Optional[List[str]]): String Array. Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. + cluster_id (Optional[List[str]]): String Array. Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. + sort_by (Optional[AllEndpointSortBy]): String. Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + to (Optional[datetime]): Date. Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + add_date_from (Optional[datetime]): Date. Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + add_date_to (Optional[datetime]): Date. Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + refresh_date_from (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + refresh_date_to (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + medium (Optional[List[str]]): String Array. Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. + exclude_source_group (Optional[List[str]]): String Array. Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). + exclude_source (Optional[List[str]]): String Array. Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. + watchlist (Optional[List[str]]): String Array. Filter articles using watchlists of people and companies. Multiple values create an OR filter to include articles mentioning any entity from the specified watchlists. + exclude_watchlist (Optional[List[str]]): String Array. Exclude articles mentioning entities from specified watchlists. Multiple values create an AND-exclude filter, removing content mentioning any entity from the specified watchlists. + paywall (Optional[bool]): Boolean. Filter to show only results where the source has a paywall (true) or does not have a paywall (false). + byline (Optional[List[str]]): String Array. Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. + author (Optional[List[str]]): String Array. Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. + exclude_author (Optional[List[str]]): String Array. Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. + journalist_id (Optional[List[str]]): String Array. Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. + exclude_journalist_id (Optional[List[str]]): String Array. Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. + language (Optional[List[str]]): String Array. Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. + exclude_language (Optional[List[str]]): String Array. Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. + search_translation (Optional[bool]): Boolean. Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. + label (Optional[List[str]]): String Array. Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. + exclude_label (Optional[List[str]]): String Array. Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. + category (Optional[List[str]]): String Array. Filter by categories. Categories are general themes that the article is about. Examples of categories: Tech, Politics, etc. If multiple parameters are passed, they will be applied as OR operations. Use 'none' to search uncategorized articles. + exclude_category (Optional[List[str]]): String Array. Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. + topic (Optional[List[str]]): String Array. Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + exclude_topic (Optional[List[str]]): String Array. Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. + link_to (Optional[str]): String. Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. + show_reprints (Optional[bool]): Boolean. Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. + reprint_group_id (Optional[str]): String. Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. + city (Optional[List[str]]): String Array. Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_city (Optional[List[str]]): String Array. A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. + area (Optional[List[str]]): String Array. Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_state (Optional[List[str]]): String Array. A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). + county (Optional[List[str]]): String Array. A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. + exclude_county (Optional[List[str]]): String Array. Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter + locations_country (Optional[List[str]]): String Array. Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + exclude_locations_country (Optional[List[str]]): String Array. Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. + location (Optional[List[str]]): String Array. Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. + lat (Optional[float]): Float. Latitude of the center point to search places + lon (Optional[float]): Float. Longitude of the center point to search places + max_distance (Optional[float]): Float. Maximum distance (in km) from starting point to search articles by tagged places + source_city (Optional[List[str]]): String Array. Find articles published by sources that are located within a given city. + source_county (Optional[List[str]]): String Array. Find articles published by sources that are located within a given county. + source_country (Optional[List[str]]): String Array. Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). + source_state (Optional[List[str]]): String Array. Find articles published by sources that are located within a given state. + source_lat (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_lon (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_max_distance (Optional[float]): Float. Maximum distance from starting point to search articles created by local publications. + person_wikidata_id (Optional[List[str]]): String Array. Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. + exclude_person_wikidata_id (Optional[List[str]]): String Array. Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. + person_name (Optional[List[str]]): String Array. Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + exclude_person_name (Optional[List[str]]): String Array. Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. + company_id (Optional[List[str]]): String Array. Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. + exclude_company_id (Optional[List[str]]): String Array. Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. + company_name (Optional[str]): String. Filter articles by company name mentions. Performs an exact match on company names. + company_domain (Optional[List[str]]): String Array. Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. + exclude_company_domain (Optional[List[str]]): String Array. Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. + company_symbol (Optional[List[str]]): String Array. Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. + exclude_company_symbol (Optional[List[str]]): String Array. A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. + show_num_results (Optional[bool]): Boolean. Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + taxonomy (Optional[List[str]]): String Array. Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) + prefix_taxonomy (Optional[str]): String. Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. Returns: SummarySearchResult: The response @@ -2156,6 +2746,8 @@ def search_summarizer( params["desc"] = desc if content is not None: params["content"] = content + if summary is not None: + params["summary"] = summary if url is not None: params["url"] = url if article_id is not None: @@ -2190,6 +2782,10 @@ def search_summarizer( params["excludeSourceGroup"] = exclude_source_group if exclude_source is not None: params["excludeSource"] = exclude_source + if watchlist is not None: + params["watchlist"] = watchlist + if exclude_watchlist is not None: + params["excludeWatchlist"] = exclude_watchlist if paywall is not None: params["paywall"] = paywall if byline is not None: @@ -2336,6 +2932,7 @@ async def search_summarizer_async( title: Optional[str] = None, desc: Optional[str] = None, content: Optional[str] = None, + summary: Optional[str] = None, url: Optional[str] = None, article_id: Optional[List[str]] = None, cluster_id: Optional[List[str]] = None, @@ -2353,6 +2950,8 @@ async def search_summarizer_async( source_group: Optional[List[str]] = None, exclude_source_group: Optional[List[str]] = None, exclude_source: Optional[List[str]] = None, + watchlist: Optional[List[str]] = None, + exclude_watchlist: Optional[List[str]] = None, paywall: Optional[bool] = None, byline: Optional[List[str]] = None, author: Optional[List[str]] = None, @@ -2424,92 +3023,95 @@ async def search_summarizer_async( Args: summary_body (SummaryBody): Parameter summary_body (required) - q (Optional[str]): Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - title (Optional[str]): Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - desc (Optional[str]): Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. - content (Optional[str]): Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. - url (Optional[str]): Search within article URLs to find content from specific website sections or domains. Supports wildcards (* and ?) for partial URL matching. - article_id (Optional[List[str]]): Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. - cluster_id (Optional[List[str]]): Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. - sort_by (Optional[AllEndpointSortBy]): Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - var_from (Optional[datetime]): Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - to (Optional[datetime]): Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - add_date_from (Optional[datetime]): Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - add_date_to (Optional[datetime]): Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - refresh_date_from (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. - refresh_date_to (Optional[datetime]): Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. - medium (Optional[List[str]]): Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. - source (Optional[List[str]]): Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. - source_group (Optional[List[str]]): Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. - exclude_source_group (Optional[List[str]]): Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). - exclude_source (Optional[List[str]]): Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. - paywall (Optional[bool]): Filter to show only results where the source has a paywall (true) or does not have a paywall (false). - byline (Optional[List[str]]): Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. - author (Optional[List[str]]): Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. - exclude_author (Optional[List[str]]): Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. - journalist_id (Optional[List[str]]): Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. - exclude_journalist_id (Optional[List[str]]): Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. - language (Optional[List[str]]): Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. - exclude_language (Optional[List[str]]): Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. - search_translation (Optional[bool]): Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. - label (Optional[List[str]]): Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. - exclude_label (Optional[List[str]]): Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. - category (Optional[List[str]]): Filter by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized articles. Multiple values create an OR filter. - exclude_category (Optional[List[str]]): Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. - topic (Optional[List[str]]): Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. - exclude_topic (Optional[List[str]]): Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. - link_to (Optional[str]): Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. - show_reprints (Optional[bool]): Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. - reprint_group_id (Optional[str]): Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. - city (Optional[List[str]]): Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_city (Optional[List[str]]): A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. - area (Optional[List[str]]): Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. - state (Optional[List[str]]): Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. - exclude_state (Optional[List[str]]): A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). - county (Optional[List[str]]): A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. - exclude_county (Optional[List[str]]): Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter - locations_country (Optional[List[str]]): Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. - country (Optional[List[str]]): Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. - exclude_locations_country (Optional[List[str]]): Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. - location (Optional[List[str]]): Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. - lat (Optional[float]): Latitude of the center point to search places - lon (Optional[float]): Longitude of the center point to search places - max_distance (Optional[float]): Maximum distance (in km) from starting point to search articles by tagged places - source_city (Optional[List[str]]): Find articles published by sources that are located within a given city. - source_county (Optional[List[str]]): Find articles published by sources that are located within a given county. - source_country (Optional[List[str]]): Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). - source_state (Optional[List[str]]): Find articles published by sources that are located within a given state. - source_lat (Optional[float]): Latitude of the center point to search articles created by local publications. - source_lon (Optional[float]): Latitude of the center point to search articles created by local publications. - source_max_distance (Optional[float]): Maximum distance from starting point to search articles created by local publications. - person_wikidata_id (Optional[List[str]]): Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. - exclude_person_wikidata_id (Optional[List[str]]): Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. - person_name (Optional[List[str]]): Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. - exclude_person_name (Optional[List[str]]): Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. - company_id (Optional[List[str]]): Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. - exclude_company_id (Optional[List[str]]): Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. - company_name (Optional[str]): Filter articles by company name mentions. Performs an exact match on company names. - company_domain (Optional[List[str]]): Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. - exclude_company_domain (Optional[List[str]]): Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. - company_symbol (Optional[List[str]]): Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. - exclude_company_symbol (Optional[List[str]]): A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. - show_num_results (Optional[bool]): Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. - positive_sentiment_from (Optional[float]): Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - positive_sentiment_to (Optional[float]): Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. - neutral_sentiment_from (Optional[float]): Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - neutral_sentiment_to (Optional[float]): Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. - negative_sentiment_from (Optional[float]): Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - negative_sentiment_to (Optional[float]): Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. - taxonomy (Optional[List[str]]): Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) - prefix_taxonomy (Optional[str]): Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance - show_highlighting (Optional[bool]): When set to true, enables text highlighting in search results. - highlight_fragment_size (Optional[int]): Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. - highlight_num_fragments (Optional[int]): Controls the maximum number of highlighted fragments to return per field. - highlight_pre_tag (Optional[str]): Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. - highlight_post_tag (Optional[str]): Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. - highlight_q (Optional[str]): Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. + q (Optional[str]): String. Primary search query for filtering articles based on their title, description, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + title (Optional[str]): String. Search specifically within article headlines/titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + desc (Optional[str]): String. Search within article description fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + content (Optional[str]): String. Search within the full article body content. Supports Boolean logic, exact phrase matching with quotes, and wildcards for comprehensive content searching. + summary (Optional[str]): String. Search within article summary fields. Supports Boolean expressions, exact phrase matching with quotes, and wildcards for flexible pattern matching. + url (Optional[str]): String. Search query on the url field. Semantic similar to q parameter. E.g. could be used for querying certain website sections, e.g. source=cnn.com&url=travel. + article_id (Optional[List[str]]): String Array. Retrieve specific news articles by their unique article identifiers. Multiple IDs can be provided to return a collection of specific articles. + cluster_id (Optional[List[str]]): String Array. Filter results to only show content within a specific related content cluster. Returns articles grouped together as part of Perigon Stories based on topic relevance. + sort_by (Optional[AllEndpointSortBy]): String. Determines the article sorting order. Options include relevance (default), date/pubDate (newest publication date first), reverseDate (oldest publication date first), addDate (newest ingestion date first), reverseAddDate (oldest ingestion date first), and refreshDate (most recently updated in system first, often identical to addDate). + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + var_from (Optional[datetime]): Date. Filter for articles published after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + to (Optional[datetime]): Date. Filter for articles published before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + add_date_from (Optional[datetime]): Date. Filter for articles added to Perigon's system after this date. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + add_date_to (Optional[datetime]): Date. Filter for articles added to Perigon's system before this date. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + refresh_date_from (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system after this date. In most cases yields similar results to addDateFrom but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T00:00:00) or yyyy-mm-dd format. + refresh_date_to (Optional[datetime]): Date. Filter for articles refreshed/updated in Perigon's system before this date. In most cases yields similar results to addDateTo but can differ for updated content. Accepts ISO 8601 format (e.g., 2022-02-01T23:59:59) or yyyy-mm-dd format. + medium (Optional[List[str]]): String Array. Filter articles by their primary medium type. Accepts Article for written content or Video for video-based stories. Multiple values create an OR filter. + source (Optional[List[str]]): String Array. Filter articles by specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an OR filter. + source_group (Optional[List[str]]): String Array. Filter articles using Perigon's curated publisher bundles (e.g., top100, top25crypto). Multiple values create an OR filter to include articles from any of the specified bundles. + exclude_source_group (Optional[List[str]]): String Array. Exclude articles from specified Perigon source groups. Multiple values create an AND-exclude filter, removing content from publishers in any of the specified bundles (e.g., top10, top100). + exclude_source (Optional[List[str]]): String Array. Exclude articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). Multiple values create an AND-exclude filter. + watchlist (Optional[List[str]]): String Array. Filter articles using watchlists of people and companies. Multiple values create an OR filter to include articles mentioning any entity from the specified watchlists. + exclude_watchlist (Optional[List[str]]): String Array. Exclude articles mentioning entities from specified watchlists. Multiple values create an AND-exclude filter, removing content mentioning any entity from the specified watchlists. + paywall (Optional[bool]): Boolean. Filter to show only results where the source has a paywall (true) or does not have a paywall (false). + byline (Optional[List[str]]): String Array. Filter articles by author bylines. Works as an exact match for each author name provided. Multiple values create an OR filter to find articles by any of the specified authors. + author (Optional[List[str]]): String Array. Filter articles by specific author names. Works as an exact match for each name. Multiple values create an OR filter to find articles by any of the specified authors. + exclude_author (Optional[List[str]]): String Array. Exclude articles written by specific authors. Any article with an author name matching an entry in this list will be omitted from results. Multiple values create an AND-exclude filter. + journalist_id (Optional[List[str]]): String Array. Filter by unique journalist identifiers which can be found through the Journalist API or in the matchedAuthors field. Multiple values create an OR filter. + exclude_journalist_id (Optional[List[str]]): String Array. Exclude articles written by specific journalists identified by their unique IDs. Multiple values create an AND-exclude filter. + language (Optional[List[str]]): String Array. Filter articles by their language using ISO-639 two-letter codes (e.g., en, es, fr). Multiple values create an OR filter. + exclude_language (Optional[List[str]]): String Array. Exclude articles in specific languages using ISO-639 two-letter codes. Multiple values create an AND-exclude filter. + search_translation (Optional[bool]): Boolean. Expand search to include translated content fields for non-English articles. When true, searches translated title, description, and content fields. + label (Optional[List[str]]): String Array. Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. Multiple values create an OR filter. + exclude_label (Optional[List[str]]): String Array. Exclude articles with specific editorial labels. Multiple values create an AND-exclude filter, removing all content with any of these labels. + category (Optional[List[str]]): String Array. Filter by categories. Categories are general themes that the article is about. Examples of categories: Tech, Politics, etc. If multiple parameters are passed, they will be applied as OR operations. Use 'none' to search uncategorized articles. + exclude_category (Optional[List[str]]): String Array. Exclude articles with specific categories. Multiple values create an AND-exclude filter, removing all content with any of these categories. + topic (Optional[List[str]]): String Array. Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and articles can have multiple topics. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter. + exclude_topic (Optional[List[str]]): String Array. Exclude articles with specific topics. Multiple values create an AND-exclude filter, removing all content with any of these topics. + link_to (Optional[str]): String. Returns only articles that contain links to the specified URL pattern. Matches against the 'links' field in article responses. + show_reprints (Optional[bool]): Boolean. Controls whether to include reprinted content in results. When true (default), shows syndicated articles from wire services like AP or Reuters that appear on multiple sites. + reprint_group_id (Optional[str]): String. Returns all articles in a specific reprint group, including the original article and all its known reprints. Use when you want to see all versions of the same content. + city (Optional[List[str]]): String Array. Filters articles where a specified city plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the urban area in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_city (Optional[List[str]]): String Array. A list of cities to exclude from the results. Articles that are associated with any of the specified cities will be filtered out. + area (Optional[List[str]]): String Array. Filters articles where a specified area, such as a neighborhood, borough, or district, plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the area in question. If multiple parameters are passed, they will be applied as OR operations. + state (Optional[List[str]]): String Array. Filters articles where a specified state plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the state in question. If multiple parameters are passed, they will be applied as OR operations. + exclude_state (Optional[List[str]]): String Array. A list of states to exclude. Articles that include, or are associated with, any of the states provided here will be filtered out. This is especially useful if you want to ignore news tied to certain geographical areas (e.g., US states). + county (Optional[List[str]]): String Array. A list of counties to include (or specify) in the search results. This field filters the returned articles based on the county associated with the event or news. Only articles tagged with one of these counties will be included. + exclude_county (Optional[List[str]]): String Array. Excludes articles from specific counties or administrative divisions in the search results. Accepts either a single county name or a list of county names. County names should match the format used in article metadata (e.g., 'Los Angeles County', 'Cook County'). This parameter allows for more granular geographic filter + locations_country (Optional[List[str]]): String Array. Filters articles where a specified country plays a central role in the content, beyond mere mentions, to ensure the results are deeply relevant to the country in question. If multiple parameters are passed, they will be applied as OR operations. + country (Optional[List[str]]): String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations. + exclude_locations_country (Optional[List[str]]): String Array. Excludes articles where a specified country plays a central role in the content, ensuring results are not deeply relevant to the country in question. If multiple parameters are passed, they will be applied as AND operations, excluding articles relevant to any of the specified countries. + location (Optional[List[str]]): String Array. Return all articles that have the specified location. Location attributes are delimited by ':' between key and value, and '::' between attributes. Example: 'city:New York::state:NY'. + lat (Optional[float]): Float. Latitude of the center point to search places + lon (Optional[float]): Float. Longitude of the center point to search places + max_distance (Optional[float]): Float. Maximum distance (in km) from starting point to search articles by tagged places + source_city (Optional[List[str]]): String Array. Find articles published by sources that are located within a given city. + source_county (Optional[List[str]]): String Array. Find articles published by sources that are located within a given county. + source_country (Optional[List[str]]): String Array. Find articles published by sources that are located within a given country. Must be 2 character country code (i.e. us, gb, etc). + source_state (Optional[List[str]]): String Array. Find articles published by sources that are located within a given state. + source_lat (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_lon (Optional[float]): Float. Latitude of the center point to search articles created by local publications. + source_max_distance (Optional[float]): Float. Maximum distance from starting point to search articles created by local publications. + person_wikidata_id (Optional[List[str]]): String Array. Filter articles by Wikidata IDs of mentioned people. Refer to the /people endpoint for a complete list of tracked individuals. + exclude_person_wikidata_id (Optional[List[str]]): String Array. Exclude articles mentioning people with specific Wikidata IDs. Creates an AND-exclude filter to remove content about these individuals. Uses precise identifiers to avoid name ambiguity. + person_name (Optional[List[str]]): String Array. Filter articles by exact person name matches. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint. + exclude_person_name (Optional[List[str]]): String Array. Exclude articles mentioning specific people by name. Creates an AND-exclude filter to remove content about these individuals. + company_id (Optional[List[str]]): String Array. Filter articles by company identifiers. For a complete list of tracked companies, refer to the /companies endpoint. + exclude_company_id (Optional[List[str]]): String Array. Exclude articles mentioning companies with specific identifiers. Creates an AND-exclude filter to remove content about these corporate entities. + company_name (Optional[str]): String. Filter articles by company name mentions. Performs an exact match on company names. + company_domain (Optional[List[str]]): String Array. Filter articles by company domains (e.g., apple.com). For available company entities, consult the /companies endpoint. + exclude_company_domain (Optional[List[str]]): String Array. Exclude articles related to companies with specific domains. Creates an AND-exclude filter to remove content about these companies. + company_symbol (Optional[List[str]]): String Array. Filter articles by company stock symbols. For available company entities and their symbols, consult the /companies endpoint. + exclude_company_symbol (Optional[List[str]]): String Array. A list of stock symbols (ticker symbols) that identify companies to be excluded. Articles related to companies using any of these symbols will be omitted, which is useful for targeting or avoiding specific public companies. + show_num_results (Optional[bool]): Boolean. Whether to show the total number of all matched articles. Default value is false which makes queries a bit more efficient but also counts up to 10000 articles. + positive_sentiment_from (Optional[float]): Float. Filter articles with a positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + positive_sentiment_to (Optional[float]): Float. Filter articles with a positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone. + neutral_sentiment_from (Optional[float]): Float. Filter articles with a neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + neutral_sentiment_to (Optional[float]): Float. Filter articles with a neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone. + negative_sentiment_from (Optional[float]): Float. Filter articles with a negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + negative_sentiment_to (Optional[float]): Float. Filter articles with a negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone. + taxonomy (Optional[List[str]]): String Array. Filters by Google Content Categories. This field will accept 1 or more categories, must pass the full name of the category. Example: taxonomy=/Finance/Banking/Other, /Finance/Investing/Funds. [Full list](https://cloud.google.com/natural-language/docs/categories) + prefix_taxonomy (Optional[str]): String. Filters by Google Content Categories. This field will filter by the category prefix only. Example: prefixTaxonomy=/Finance + show_highlighting (Optional[bool]): Boolean. When set to true, enables text highlighting in search results. + highlight_fragment_size (Optional[int]): Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified. + highlight_num_fragments (Optional[int]): Integer. Controls the maximum number of highlighted fragments to return per field. + highlight_pre_tag (Optional[str]): String. Defines the HTML tag that appears before highlighted text. Defaults to '' if not specified. + highlight_post_tag (Optional[str]): String. Defines the HTML tag that appears after highlighted text. Defaults to '' if not specified. + highlight_q (Optional[str]): String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change. Returns: SummarySearchResult: The response @@ -2526,6 +3128,8 @@ async def search_summarizer_async( params["desc"] = desc if content is not None: params["content"] = content + if summary is not None: + params["summary"] = summary if url is not None: params["url"] = url if article_id is not None: @@ -2560,6 +3164,10 @@ async def search_summarizer_async( params["excludeSourceGroup"] = exclude_source_group if exclude_source is not None: params["excludeSource"] = exclude_source + if watchlist is not None: + params["watchlist"] = watchlist + if exclude_watchlist is not None: + params["excludeWatchlist"] = exclude_watchlist if paywall is not None: params["paywall"] = paywall if byline is not None: @@ -2711,11 +3319,11 @@ def search_topics( Search through all available Topics that exist within the Perigon Database. Args: - name (Optional[str]): Search for topics by exact name or partial text match. Does not support wildcards. Examples include Markets, Cryptocurrency, Climate Change, etc. - category (Optional[str]): Filter topics by broad article categories such as Politics, Tech, Sports, Business, Finance, Entertainment, etc. - subcategory (Optional[str]): Filter topics by their specific subcategory. Subcategories provide more granular classification beyond the main category, such as TV or Event. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of topics to return per page in the paginated response. + name (Optional[str]): String. Search for topics by exact name or partial text match. Does not support wildcards. Examples include Markets, Cryptocurrency, Climate Change, etc. + category (Optional[str]): String. Filter topics by broad article categories such as Politics, Tech, Sports, Business, Finance, Entertainment, etc. + subcategory (Optional[str]): String. Filter topics by their specific subcategory. Subcategories provide more granular classification beyond the main category, such as TV or Event. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of topics to return per page in the paginated response. Returns: TopicSearchResult: The response @@ -2754,11 +3362,11 @@ async def search_topics_async( Async variant of search_topics. Search through all available Topics that exist within the Perigon Database. Args: - name (Optional[str]): Search for topics by exact name or partial text match. Does not support wildcards. Examples include Markets, Cryptocurrency, Climate Change, etc. - category (Optional[str]): Filter topics by broad article categories such as Politics, Tech, Sports, Business, Finance, Entertainment, etc. - subcategory (Optional[str]): Filter topics by their specific subcategory. Subcategories provide more granular classification beyond the main category, such as TV or Event. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of topics to return per page in the paginated response. + name (Optional[str]): String. Search for topics by exact name or partial text match. Does not support wildcards. Examples include Markets, Cryptocurrency, Climate Change, etc. + category (Optional[str]): String. Filter topics by broad article categories such as Politics, Tech, Sports, Business, Finance, Entertainment, etc. + subcategory (Optional[str]): String. Filter topics by their specific subcategory. Subcategories provide more granular classification beyond the main category, such as TV or Event. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of topics to return per page in the paginated response. Returns: TopicSearchResult: The response @@ -2811,38 +3419,39 @@ def search_wikipedia( show_num_results: Optional[bool] = None, page: Optional[int] = None, size: Optional[int] = None, - sort_by: Optional[SortBy] = None, + sort_by: Optional[str] = None, ) -> WikipediaSearchResult: """ Search and filter all Wikipedia pages available via the Perigon API. The result includes a list of individual pages that were matched to your specific criteria. Args: - q (Optional[str]): Primary search query for filtering pages based on their title, summary, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - title (Optional[str]): Search specifically within page titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - summary (Optional[str]): Search specifically within page summary. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - text (Optional[str]): Search specifically within the page's content (across all sections). Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - reference (Optional[str]): Search specifically across page's references. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - id (Optional[List[str]]): Retrieve specific pages by their unique Perigon identifiers. Multiple IDs can be provided to return a collection of specific pages. - wiki_page_id (Optional[List[int]]): Retrieve specific pages by their Wikipedia identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. - wiki_revision_id (Optional[List[int]]): Retrieve specific pages by their Wikipedia revision identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. This ID changes each time a page is edited. - wiki_code (Optional[List[str]]): Retrieve pages only from specified wiki projects. Currently, the only accepted value is `enwiki`. - wiki_namespace (Optional[List[int]]): Retrieve pages only from specified wiki namespace. Currently, only the main namespace (0) is available. - wikidata_id (Optional[List[str]]): Retrieve pages by the ids corresponding to their Wikidata entities. - wikidata_instance_of_id (Optional[List[str]]): Retrieve all pages whose Wikidata entities are instances of these provided ids. - wikidata_instance_of_label (Optional[List[str]]): Retrieve all pages whose Wikidata entities are instances of these ids (provided as labels). - category (Optional[List[str]]): Retrieve all pages for specified categories. - section_id (Optional[List[str]]): Retrieve pages containing provided section ids. Each section ID is unique. - wiki_revision_from (Optional[datetime]): Retrieve pages modified after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - wiki_revision_to (Optional[datetime]): Retrieve pages modified before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - scraped_at_from (Optional[datetime]): Retrieve pages scraped after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - scraped_at_to (Optional[datetime]): Retrieve pages scraped before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - pageviews_from (Optional[int]): Retrieve pages with the average number of views per day higher than the provided value. - pageviews_to (Optional[int]): Retrieve pages with the average number of views per day lower than the provided value. - with_pageviews (Optional[bool]): Retrieve pages that have any viewership statistics available for them. If `false` (the default) - return all pages. - show_num_results (Optional[bool]): Whether to show the total number of all matched pages. Default value is false which makes queries a bit more efficient but also counts up to 10000 pages. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - sort_by (Optional[SortBy]): Determines the Wikipedia page sorting order. Options include relevance (default), revisionTsDesc (recently edited first), revisionTsAsc (recently edited last), pageViewsDesc (highest viewership first), pageViewsAsc (highest viewership last), scrapedAtDesc (recently scraped first), scrapedAtAsc (recently scraped last). + q (Optional[str]): String. Primary search query for filtering pages based on their title, summary, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + title (Optional[str]): String. Search specifically within page titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + summary (Optional[str]): String. Search specifically within page summary. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + text (Optional[str]): String. Search specifically within the page's content (across all sections). Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + reference (Optional[str]): String. Search specifically across page's references. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + id (Optional[List[str]]): String Array. Retrieve specific pages by their unique Perigon identifiers. Multiple IDs can be provided to return a collection of specific pages. + wiki_page_id (Optional[List[int]]): Integer Array. Retrieve specific pages by their Wikipedia identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. + wiki_revision_id (Optional[List[int]]): Integer Array. Retrieve specific pages by their Wikipedia revision identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. This ID changes each time a page is edited. + wiki_code (Optional[List[str]]): String Array. Retrieve pages only from specified wiki projects. Currently, the only accepted value is `enwiki`. + wiki_namespace (Optional[List[int]]): Integer Array. Retrieve pages only from specified wiki namespace. Currently, only the main namespace (0) is available. + wikidata_id (Optional[List[str]]): String Array. Retrieve pages by the ids corresponding to their Wikidata entities. + wikidata_instance_of_id (Optional[List[str]]): String Array. Retrieve all pages whose Wikidata entities are instances of these provided ids. + wikidata_instance_of_label (Optional[List[str]]): String Array. Retrieve all pages whose Wikidata entities are instances of these ids (provided as labels). + category (Optional[List[str]]): String Array. Retrieve all pages for specified categories. + section_id (Optional[List[str]]): String Array. Retrieve pages containing provided section ids. Each section ID is unique. + wiki_revision_from (Optional[datetime]): Date. Retrieve pages modified after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + wiki_revision_to (Optional[datetime]): Date. Retrieve pages modified before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + scraped_at_from (Optional[datetime]): Date. Retrieve pages scraped after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + scraped_at_to (Optional[datetime]): Date. Retrieve pages scraped before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + pageviews_from (Optional[int]): Integer. Retrieve pages with the average number of views per day higher than the provided value. + pageviews_to (Optional[int]): Integer. Retrieve pages with the average number of views per day lower than the provided value. + with_pageviews (Optional[bool]): Boolean. Retrieve pages that have any viewership statistics available for them. If `false` (the default) - return all pages. + show_num_results (Optional[bool]): Boolean. Whether to show the total number of all matched pages. Default value is false which makes queries a bit more efficient but also counts up to 10000 pages. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + sort_by (Optional[str]): String. Determines the Wikipedia page sorting order. Options include relevance (default), revisionTsDesc (recently edited first), revisionTsAsc (recently edited last), pageViewsDesc (highest viewership first), pageViewsAsc (highest viewership last), scrapedAtDesc (recently scraped first), scrapedAtAsc (recently scraped last). + Allowed values: 'relevance', 'revisionTsDesc', 'revisionTsAsc', 'pageViewsDesc', 'pageViewsAsc', 'scrapedAtDesc', 'scrapedAtAsc' Returns: WikipediaSearchResult: The response @@ -2938,38 +3547,39 @@ async def search_wikipedia_async( show_num_results: Optional[bool] = None, page: Optional[int] = None, size: Optional[int] = None, - sort_by: Optional[SortBy] = None, + sort_by: Optional[str] = None, ) -> WikipediaSearchResult: """ Async variant of search_wikipedia. Search and filter all Wikipedia pages available via the Perigon API. The result includes a list of individual pages that were matched to your specific criteria. Args: - q (Optional[str]): Primary search query for filtering pages based on their title, summary, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. - title (Optional[str]): Search specifically within page titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - summary (Optional[str]): Search specifically within page summary. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - text (Optional[str]): Search specifically within the page's content (across all sections). Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - reference (Optional[str]): Search specifically across page's references. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. - id (Optional[List[str]]): Retrieve specific pages by their unique Perigon identifiers. Multiple IDs can be provided to return a collection of specific pages. - wiki_page_id (Optional[List[int]]): Retrieve specific pages by their Wikipedia identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. - wiki_revision_id (Optional[List[int]]): Retrieve specific pages by their Wikipedia revision identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. This ID changes each time a page is edited. - wiki_code (Optional[List[str]]): Retrieve pages only from specified wiki projects. Currently, the only accepted value is `enwiki`. - wiki_namespace (Optional[List[int]]): Retrieve pages only from specified wiki namespace. Currently, only the main namespace (0) is available. - wikidata_id (Optional[List[str]]): Retrieve pages by the ids corresponding to their Wikidata entities. - wikidata_instance_of_id (Optional[List[str]]): Retrieve all pages whose Wikidata entities are instances of these provided ids. - wikidata_instance_of_label (Optional[List[str]]): Retrieve all pages whose Wikidata entities are instances of these ids (provided as labels). - category (Optional[List[str]]): Retrieve all pages for specified categories. - section_id (Optional[List[str]]): Retrieve pages containing provided section ids. Each section ID is unique. - wiki_revision_from (Optional[datetime]): Retrieve pages modified after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - wiki_revision_to (Optional[datetime]): Retrieve pages modified before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - scraped_at_from (Optional[datetime]): Retrieve pages scraped after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - scraped_at_to (Optional[datetime]): Retrieve pages scraped before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. - pageviews_from (Optional[int]): Retrieve pages with the average number of views per day higher than the provided value. - pageviews_to (Optional[int]): Retrieve pages with the average number of views per day lower than the provided value. - with_pageviews (Optional[bool]): Retrieve pages that have any viewership statistics available for them. If `false` (the default) - return all pages. - show_num_results (Optional[bool]): Whether to show the total number of all matched pages. Default value is false which makes queries a bit more efficient but also counts up to 10000 pages. - page (Optional[int]): The specific page of results to retrieve in the paginated response. Starts at 0. - size (Optional[int]): The number of articles to return per page in the paginated response. - sort_by (Optional[SortBy]): Determines the Wikipedia page sorting order. Options include relevance (default), revisionTsDesc (recently edited first), revisionTsAsc (recently edited last), pageViewsDesc (highest viewership first), pageViewsAsc (highest viewership last), scrapedAtDesc (recently scraped first), scrapedAtAsc (recently scraped last). + q (Optional[str]): String. Primary search query for filtering pages based on their title, summary, and content. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching. + title (Optional[str]): String. Search specifically within page titles. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + summary (Optional[str]): String. Search specifically within page summary. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + text (Optional[str]): String. Search specifically within the page's content (across all sections). Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + reference (Optional[str]): String. Search specifically across page's references. Supports Boolean operators, exact phrases with quotes, and wildcards for matching title variations. + id (Optional[List[str]]): String Array. Retrieve specific pages by their unique Perigon identifiers. Multiple IDs can be provided to return a collection of specific pages. + wiki_page_id (Optional[List[int]]): Integer Array. Retrieve specific pages by their Wikipedia identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. + wiki_revision_id (Optional[List[int]]): Integer Array. Retrieve specific pages by their Wikipedia revision identifiers. These are unique only in a combination with `wikiCode` parameter. Multiple IDs can be provided to return a collection of specific pages. This ID changes each time a page is edited. + wiki_code (Optional[List[str]]): String Array. Retrieve pages only from specified wiki projects. Currently, the only accepted value is `enwiki`. + wiki_namespace (Optional[List[int]]): Integer Array. Retrieve pages only from specified wiki namespace. Currently, only the main namespace (0) is available. + wikidata_id (Optional[List[str]]): String Array. Retrieve pages by the ids corresponding to their Wikidata entities. + wikidata_instance_of_id (Optional[List[str]]): String Array. Retrieve all pages whose Wikidata entities are instances of these provided ids. + wikidata_instance_of_label (Optional[List[str]]): String Array. Retrieve all pages whose Wikidata entities are instances of these ids (provided as labels). + category (Optional[List[str]]): String Array. Retrieve all pages for specified categories. + section_id (Optional[List[str]]): String Array. Retrieve pages containing provided section ids. Each section ID is unique. + wiki_revision_from (Optional[datetime]): Date. Retrieve pages modified after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + wiki_revision_to (Optional[datetime]): Date. Retrieve pages modified before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + scraped_at_from (Optional[datetime]): Date. Retrieve pages scraped after this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + scraped_at_to (Optional[datetime]): Date. Retrieve pages scraped before this date. Accepts ISO 8601 format (e.g., 2023-03-01T00:00:00) or yyyy-mm-dd format. + pageviews_from (Optional[int]): Integer. Retrieve pages with the average number of views per day higher than the provided value. + pageviews_to (Optional[int]): Integer. Retrieve pages with the average number of views per day lower than the provided value. + with_pageviews (Optional[bool]): Boolean. Retrieve pages that have any viewership statistics available for them. If `false` (the default) - return all pages. + show_num_results (Optional[bool]): Boolean. Whether to show the total number of all matched pages. Default value is false which makes queries a bit more efficient but also counts up to 10000 pages. + page (Optional[int]): Integer. The specific page of results to retrieve in the paginated response. Starts at 0. + size (Optional[int]): Integer. The number of articles to return per page in the paginated response. + sort_by (Optional[str]): String. Determines the Wikipedia page sorting order. Options include relevance (default), revisionTsDesc (recently edited first), revisionTsAsc (recently edited last), pageViewsDesc (highest viewership first), pageViewsAsc (highest viewership last), scrapedAtDesc (recently scraped first), scrapedAtAsc (recently scraped last). + Allowed values: 'relevance', 'revisionTsDesc', 'revisionTsAsc', 'pageViewsDesc', 'pageViewsAsc', 'scrapedAtDesc', 'scrapedAtAsc' Returns: WikipediaSearchResult: The response diff --git a/perigon/models/__init__.py b/perigon/models/__init__.py index 09d200b..a92a07f 100644 --- a/perigon/models/__init__.py +++ b/perigon/models/__init__.py @@ -20,12 +20,6 @@ from perigon.models.article_search_filter import ArticleSearchFilter from perigon.models.article_search_params import ArticleSearchParams from perigon.models.articles_vector_search_result import ArticlesVectorSearchResult -from perigon.models.auth_exception import AuthException -from perigon.models.auth_exception_cause import AuthExceptionCause -from perigon.models.auth_exception_cause_stack_trace_inner import ( - AuthExceptionCauseStackTraceInner, -) -from perigon.models.auth_exception_suppressed_inner import AuthExceptionSuppressedInner from perigon.models.category_holder import CategoryHolder from perigon.models.category_with_score_holder import CategoryWithScoreHolder from perigon.models.company import Company @@ -35,11 +29,10 @@ from perigon.models.coordinate import Coordinate from perigon.models.coordinate_filter import CoordinateFilter from perigon.models.entity_holder import EntityHolder +from perigon.models.error_response import ErrorResponse from perigon.models.event_type_holder import EventTypeHolder from perigon.models.id_name_holder import IdNameHolder -from perigon.models.illegal_parameter_exception import IllegalParameterException from perigon.models.image_holder import ImageHolder -from perigon.models.internal_error_exception import InternalErrorException from perigon.models.journalist import Journalist from perigon.models.journalist_search_result import JournalistSearchResult from perigon.models.key_point import KeyPoint @@ -49,7 +42,6 @@ from perigon.models.location_holder import LocationHolder from perigon.models.name_count import NameCount from perigon.models.news_cluster import NewsCluster -from perigon.models.not_found_exception import NotFoundException from perigon.models.people_search_result import PeopleSearchResult from perigon.models.person import Person from perigon.models.person_count import PersonCount @@ -67,11 +59,13 @@ from perigon.models.source_location import SourceLocation from perigon.models.source_search_result import SourceSearchResult from perigon.models.source_top_stat_holder import SourceTopStatHolder +from perigon.models.stat_result import StatResult +from perigon.models.story_history_record import StoryHistoryRecord +from perigon.models.story_history_result import StoryHistoryResult from perigon.models.story_search_result import StorySearchResult from perigon.models.summary_body import SummaryBody from perigon.models.summary_search_result import SummarySearchResult from perigon.models.symbol_holder import SymbolHolder -from perigon.models.too_many_requests_exception import TooManyRequestsException from perigon.models.topic_dto import TopicDto from perigon.models.topic_holder import TopicHolder from perigon.models.topic_labels import TopicLabels diff --git a/perigon/models/article.py b/perigon/models/article.py index 8ce3524..32753d7 100644 --- a/perigon/models/article.py +++ b/perigon/models/article.py @@ -68,6 +68,9 @@ class Article(BaseModel): title: Optional[StrictStr] = None description: Optional[StrictStr] = None content: Optional[StrictStr] = None + en_content_word_count: Optional[StrictInt] = Field( + default=None, alias="enContentWordCount" + ) medium: Optional[StrictStr] = None links: Optional[List[StrictStr]] = None labels: Optional[List[LabelHolder]] = None @@ -120,6 +123,7 @@ class Article(BaseModel): "title", "description", "content", + "enContentWordCount", "medium", "links", "labels", @@ -307,6 +311,11 @@ def to_dict(self) -> Dict[str, Any]: if self.cluster_id is None and "cluster_id" in self.model_fields_set: _dict["clusterId"] = None + # set to None if source (nullable) is None + # and model_fields_set contains the field + if self.source is None and "source" in self.model_fields_set: + _dict["source"] = None + # set to None if image_url (nullable) is None # and model_fields_set contains the field if self.image_url is None and "image_url" in self.model_fields_set: @@ -357,6 +366,14 @@ def to_dict(self) -> Dict[str, Any]: if self.content is None and "content" in self.model_fields_set: _dict["content"] = None + # set to None if en_content_word_count (nullable) is None + # and model_fields_set contains the field + if ( + self.en_content_word_count is None + and "en_content_word_count" in self.model_fields_set + ): + _dict["enContentWordCount"] = None + # set to None if medium (nullable) is None # and model_fields_set contains the field if self.medium is None and "medium" in self.model_fields_set: @@ -422,6 +439,11 @@ def to_dict(self) -> Dict[str, Any]: if self.companies is None and "companies" in self.model_fields_set: _dict["companies"] = None + # set to None if sentiment (nullable) is None + # and model_fields_set contains the field + if self.sentiment is None and "sentiment" in self.model_fields_set: + _dict["sentiment"] = None + # set to None if summary (nullable) is None # and model_fields_set contains the field if self.summary is None and "summary" in self.model_fields_set: @@ -489,6 +511,11 @@ def to_dict(self) -> Dict[str, Any]: if self.people is None and "people" in self.model_fields_set: _dict["people"] = None + # set to None if cluster (nullable) is None + # and model_fields_set contains the field + if self.cluster is None and "cluster" in self.model_fields_set: + _dict["cluster"] = None + # set to None if journalists (nullable) is None # and model_fields_set contains the field if self.journalists is None and "journalists" in self.model_fields_set: @@ -531,6 +558,7 @@ def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: "title": obj.get("title"), "description": obj.get("description"), "content": obj.get("content"), + "enContentWordCount": obj.get("enContentWordCount"), "medium": obj.get("medium"), "links": obj.get("links"), "labels": ( diff --git a/perigon/models/article_search_filter.py b/perigon/models/article_search_filter.py index 19b7cb8..f7983e5 100644 --- a/perigon/models/article_search_filter.py +++ b/perigon/models/article_search_filter.py @@ -484,6 +484,19 @@ def to_dict(self) -> Dict[str, Any]: if self.source_city is None and "source_city" in self.model_fields_set: _dict["sourceCity"] = None + # set to None if coordinates (nullable) is None + # and model_fields_set contains the field + if self.coordinates is None and "coordinates" in self.model_fields_set: + _dict["coordinates"] = None + + # set to None if source_coordinates (nullable) is None + # and model_fields_set contains the field + if ( + self.source_coordinates is None + and "source_coordinates" in self.model_fields_set + ): + _dict["sourceCoordinates"] = None + # set to None if company_id (nullable) is None # and model_fields_set contains the field if self.company_id is None and "company_id" in self.model_fields_set: diff --git a/perigon/models/article_search_params.py b/perigon/models/article_search_params.py index de9a70c..dd91635 100644 --- a/perigon/models/article_search_params.py +++ b/perigon/models/article_search_params.py @@ -43,19 +43,19 @@ class ArticleSearchParams(BaseModel): ) pub_date_to: Optional[datetime] = Field( default=None, - description="'pubDateFrom' filter, will search articles published before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Date time in ISO format, ie. 2024-01-01T00:00:00", + description="'pubDateTo' filter, will search articles published before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Date time in ISO format, ie. 2024-01-01T00:00:00", alias="pubDateTo", ) show_reprints: Optional[StrictBool] = Field( - default=None, + default=True, description="Whether to return reprints in the response or not. Reprints are usually wired articles from sources like AP or Reuters that are reprinted in multiple sources at the same time. By default, this parameter is 'true'.", alias="showReprints", ) size: Optional[Annotated[int, Field(le=100, strict=True, ge=1)]] = Field( - default=None, description="The number of items per page." + default=10, description="The number of items per page." ) page: Optional[Annotated[int, Field(le=10000, strict=True, ge=0)]] = Field( - default=None, description="The page number to retrieve." + default=0, description="The page number to retrieve." ) __properties: ClassVar[List[str]] = [ "prompt", @@ -107,6 +107,11 @@ def to_dict(self) -> Dict[str, Any]: # override the default output from pydantic by calling `to_dict()` of filter if self.filter: _dict["filter"] = self.filter.to_dict() + # set to None if filter (nullable) is None + # and model_fields_set contains the field + if self.filter is None and "filter" in self.model_fields_set: + _dict["filter"] = None + # set to None if pub_date_from (nullable) is None # and model_fields_set contains the field if self.pub_date_from is None and "pub_date_from" in self.model_fields_set: @@ -153,9 +158,13 @@ def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: ), "pubDateFrom": obj.get("pubDateFrom"), "pubDateTo": obj.get("pubDateTo"), - "showReprints": obj.get("showReprints"), - "size": obj.get("size"), - "page": obj.get("page"), + "showReprints": ( + obj.get("showReprints") + if obj.get("showReprints") is not None + else True + ), + "size": obj.get("size") if obj.get("size") is not None else 10, + "page": obj.get("page") if obj.get("page") is not None else 0, } ) return _obj diff --git a/perigon/models/company.py b/perigon/models/company.py index c304838..0ad9b0d 100644 --- a/perigon/models/company.py +++ b/perigon/models/company.py @@ -302,6 +302,11 @@ def to_dict(self) -> Dict[str, Any]: if self.revenue is None and "revenue" in self.model_fields_set: _dict["revenue"] = None + # set to None if web_resources (nullable) is None + # and model_fields_set contains the field + if self.web_resources is None and "web_resources" in self.model_fields_set: + _dict["webResources"] = None + return _dict @classmethod diff --git a/perigon/models/error_response.py b/perigon/models/error_response.py new file mode 100644 index 0000000..32ec17b --- /dev/null +++ b/perigon/models/error_response.py @@ -0,0 +1,107 @@ +# coding: utf-8 + +""" +Perigon API + +The Perigon API provides access to comprehensive news and web content data. To use the API, simply sign up for a Perigon Business Solutions account to obtain your API key. Your available features may vary based on your plan. See the Authentication section for details on how to use your API key. + +The version of the OpenAPI document: 1.0.0 +Contact: data@perigon.io +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + + +from __future__ import annotations + +import json +import pprint +import re # noqa: F401 +from typing import Any, ClassVar, Dict, List, Optional, Set + +from pydantic import BaseModel, ConfigDict, StrictInt, StrictStr +from typing_extensions import Self + + +class ErrorResponse(BaseModel): + """ + ErrorResponse + """ # noqa: E501 + + status: Optional[StrictInt] = None + message: Optional[StrictStr] = None + timestamp: Optional[StrictInt] = None + __properties: ClassVar[List[str]] = ["status", "message", "timestamp"] + + model_config = ConfigDict( + populate_by_name=True, + validate_assignment=True, + protected_namespaces=(), + ) + + def to_str(self) -> str: + """Returns the string representation of the model using alias""" + return pprint.pformat(self.model_dump(by_alias=True)) + + def to_json(self) -> str: + """Returns the JSON representation of the model using alias""" + # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead + return json.dumps(self.to_dict()) + + @classmethod + def from_json(cls, json_str: str) -> Optional[Self]: + """Create an instance of ErrorResponse from a JSON string""" + return cls.from_dict(json.loads(json_str)) + + def to_dict(self) -> Dict[str, Any]: + """Return the dictionary representation of the model using alias. + + This has the following differences from calling pydantic's + `self.model_dump(by_alias=True)`: + + * `None` is only added to the output dict for nullable fields that + were set at model initialization. Other fields with value `None` + are ignored. + """ + excluded_fields: Set[str] = set([]) + + _dict = self.model_dump( + by_alias=True, + exclude=excluded_fields, + exclude_none=True, + ) + # set to None if status (nullable) is None + # and model_fields_set contains the field + if self.status is None and "status" in self.model_fields_set: + _dict["status"] = None + + # set to None if message (nullable) is None + # and model_fields_set contains the field + if self.message is None and "message" in self.model_fields_set: + _dict["message"] = None + + # set to None if timestamp (nullable) is None + # and model_fields_set contains the field + if self.timestamp is None and "timestamp" in self.model_fields_set: + _dict["timestamp"] = None + + return _dict + + @classmethod + def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: + """Create an instance of ErrorResponse from a dict""" + if obj is None: + return None + + if not isinstance(obj, dict): + return cls.model_validate(obj) + + _obj = cls.model_validate( + { + "status": obj.get("status"), + "message": obj.get("message"), + "timestamp": obj.get("timestamp"), + } + ) + return _obj diff --git a/perigon/models/news_cluster.py b/perigon/models/news_cluster.py index 6107264..f4be56d 100644 --- a/perigon/models/news_cluster.py +++ b/perigon/models/news_cluster.py @@ -338,6 +338,11 @@ def to_dict(self) -> Dict[str, Any]: ): _dict["summaryReferences"] = None + # set to None if image_source (nullable) is None + # and model_fields_set contains the field + if self.image_source is None and "image_source" in self.model_fields_set: + _dict["imageSource"] = None + # set to None if image_url (nullable) is None # and model_fields_set contains the field if self.image_url is None and "image_url" in self.model_fields_set: @@ -366,6 +371,11 @@ def to_dict(self) -> Dict[str, Any]: ): _dict["selectedArticles"] = None + # set to None if sentiment (nullable) is None + # and model_fields_set contains the field + if self.sentiment is None and "sentiment" in self.model_fields_set: + _dict["sentiment"] = None + # set to None if unique_count (nullable) is None # and model_fields_set contains the field if self.unique_count is None and "unique_count" in self.model_fields_set: diff --git a/perigon/models/person.py b/perigon/models/person.py index a6cb174..847bb28 100644 --- a/perigon/models/person.py +++ b/perigon/models/person.py @@ -162,6 +162,21 @@ def to_dict(self) -> Dict[str, Any]: if self.name is None and "name" in self.model_fields_set: _dict["name"] = None + # set to None if gender (nullable) is None + # and model_fields_set contains the field + if self.gender is None and "gender" in self.model_fields_set: + _dict["gender"] = None + + # set to None if date_of_birth (nullable) is None + # and model_fields_set contains the field + if self.date_of_birth is None and "date_of_birth" in self.model_fields_set: + _dict["dateOfBirth"] = None + + # set to None if date_of_death (nullable) is None + # and model_fields_set contains the field + if self.date_of_death is None and "date_of_death" in self.model_fields_set: + _dict["dateOfDeath"] = None + # set to None if description (nullable) is None # and model_fields_set contains the field if self.description is None and "description" in self.model_fields_set: @@ -187,6 +202,11 @@ def to_dict(self) -> Dict[str, Any]: if self.political_party is None and "political_party" in self.model_fields_set: _dict["politicalParty"] = None + # set to None if image (nullable) is None + # and model_fields_set contains the field + if self.image is None and "image" in self.model_fields_set: + _dict["image"] = None + # set to None if abstract (nullable) is None # and model_fields_set contains the field if self.abstract is None and "abstract" in self.model_fields_set: diff --git a/perigon/models/place.py b/perigon/models/place.py index 409b711..68acc68 100644 --- a/perigon/models/place.py +++ b/perigon/models/place.py @@ -174,6 +174,11 @@ def to_dict(self) -> Dict[str, Any]: if self.neighbourhood is None and "neighbourhood" in self.model_fields_set: _dict["neighbourhood"] = None + # set to None if coordinates (nullable) is None + # and model_fields_set contains the field + if self.coordinates is None and "coordinates" in self.model_fields_set: + _dict["coordinates"] = None + return _dict @classmethod diff --git a/perigon/models/scored_data_article.py b/perigon/models/scored_data_article.py index 857c180..c235bb4 100644 --- a/perigon/models/scored_data_article.py +++ b/perigon/models/scored_data_article.py @@ -80,6 +80,11 @@ def to_dict(self) -> Dict[str, Any]: if self.score is None and "score" in self.model_fields_set: _dict["score"] = None + # set to None if data (nullable) is None + # and model_fields_set contains the field + if self.data is None and "data" in self.model_fields_set: + _dict["data"] = None + return _dict @classmethod diff --git a/perigon/models/scored_data_wiki_data.py b/perigon/models/scored_data_wiki_data.py index 421932f..d353f76 100644 --- a/perigon/models/scored_data_wiki_data.py +++ b/perigon/models/scored_data_wiki_data.py @@ -80,6 +80,11 @@ def to_dict(self) -> Dict[str, Any]: if self.score is None and "score" in self.model_fields_set: _dict["score"] = None + # set to None if data (nullable) is None + # and model_fields_set contains the field + if self.data is None and "data" in self.model_fields_set: + _dict["data"] = None + return _dict @classmethod diff --git a/perigon/models/source.py b/perigon/models/source.py index 23ea49b..3fcf792 100644 --- a/perigon/models/source.py +++ b/perigon/models/source.py @@ -226,6 +226,11 @@ def to_dict(self) -> Dict[str, Any]: if self.paywall is None and "paywall" in self.model_fields_set: _dict["paywall"] = None + # set to None if location (nullable) is None + # and model_fields_set contains the field + if self.location is None and "location" in self.model_fields_set: + _dict["location"] = None + # set to None if top_categories (nullable) is None # and model_fields_set contains the field if self.top_categories is None and "top_categories" in self.model_fields_set: @@ -285,6 +290,21 @@ def to_dict(self) -> Dict[str, Any]: if self.global_rank is None and "global_rank" in self.model_fields_set: _dict["globalRank"] = None + # set to None if logo_large (nullable) is None + # and model_fields_set contains the field + if self.logo_large is None and "logo_large" in self.model_fields_set: + _dict["logoLarge"] = None + + # set to None if logo_fav_icon (nullable) is None + # and model_fields_set contains the field + if self.logo_fav_icon is None and "logo_fav_icon" in self.model_fields_set: + _dict["logoFavIcon"] = None + + # set to None if logo_square (nullable) is None + # and model_fields_set contains the field + if self.logo_square is None and "logo_square" in self.model_fields_set: + _dict["logoSquare"] = None + return _dict @classmethod diff --git a/perigon/models/source_holder.py b/perigon/models/source_holder.py index a8f1080..351ec06 100644 --- a/perigon/models/source_holder.py +++ b/perigon/models/source_holder.py @@ -86,6 +86,11 @@ def to_dict(self) -> Dict[str, Any]: if self.paywall is None and "paywall" in self.model_fields_set: _dict["paywall"] = None + # set to None if location (nullable) is None + # and model_fields_set contains the field + if self.location is None and "location" in self.model_fields_set: + _dict["location"] = None + return _dict @classmethod diff --git a/perigon/models/source_location.py b/perigon/models/source_location.py index ba98abc..fab6d85 100644 --- a/perigon/models/source_location.py +++ b/perigon/models/source_location.py @@ -104,6 +104,11 @@ def to_dict(self) -> Dict[str, Any]: if self.city is None and "city" in self.model_fields_set: _dict["city"] = None + # set to None if coordinates (nullable) is None + # and model_fields_set contains the field + if self.coordinates is None and "coordinates" in self.model_fields_set: + _dict["coordinates"] = None + return _dict @classmethod diff --git a/perigon/models/stat_result.py b/perigon/models/stat_result.py new file mode 100644 index 0000000..346484d --- /dev/null +++ b/perigon/models/stat_result.py @@ -0,0 +1,97 @@ +# coding: utf-8 + +""" +Perigon API + +The Perigon API provides access to comprehensive news and web content data. To use the API, simply sign up for a Perigon Business Solutions account to obtain your API key. Your available features may vary based on your plan. See the Authentication section for details on how to use your API key. + +The version of the OpenAPI document: 1.0.0 +Contact: data@perigon.io +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + + +from __future__ import annotations + +import json +import pprint +import re # noqa: F401 +from typing import Any, ClassVar, Dict, List, Optional, Set + +from pydantic import BaseModel, ConfigDict, StrictInt +from typing_extensions import Self + + +class StatResult(BaseModel): + """ + StatResult + """ # noqa: E501 + + status: Optional[StrictInt] = None + results: Optional[List[Dict[str, Any]]] = None + __properties: ClassVar[List[str]] = ["status", "results"] + + model_config = ConfigDict( + populate_by_name=True, + validate_assignment=True, + protected_namespaces=(), + ) + + def to_str(self) -> str: + """Returns the string representation of the model using alias""" + return pprint.pformat(self.model_dump(by_alias=True)) + + def to_json(self) -> str: + """Returns the JSON representation of the model using alias""" + # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead + return json.dumps(self.to_dict()) + + @classmethod + def from_json(cls, json_str: str) -> Optional[Self]: + """Create an instance of StatResult from a JSON string""" + return cls.from_dict(json.loads(json_str)) + + def to_dict(self) -> Dict[str, Any]: + """Return the dictionary representation of the model using alias. + + This has the following differences from calling pydantic's + `self.model_dump(by_alias=True)`: + + * `None` is only added to the output dict for nullable fields that + were set at model initialization. Other fields with value `None` + are ignored. + """ + excluded_fields: Set[str] = set([]) + + _dict = self.model_dump( + by_alias=True, + exclude=excluded_fields, + exclude_none=True, + ) + # set to None if status (nullable) is None + # and model_fields_set contains the field + if self.status is None and "status" in self.model_fields_set: + _dict["status"] = None + + # set to None if results (nullable) is None + # and model_fields_set contains the field + if self.results is None and "results" in self.model_fields_set: + _dict["results"] = None + + return _dict + + @classmethod + def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: + """Create an instance of StatResult from a dict""" + if obj is None: + return None + + if not isinstance(obj, dict): + return cls.model_validate(obj) + + _obj = cls.model_validate( + {"status": obj.get("status"), "results": obj.get("results")} + ) + return _obj diff --git a/perigon/models/story_history_record.py b/perigon/models/story_history_record.py new file mode 100644 index 0000000..3166710 --- /dev/null +++ b/perigon/models/story_history_record.py @@ -0,0 +1,184 @@ +# coding: utf-8 + +""" +Perigon API + +The Perigon API provides access to comprehensive news and web content data. To use the API, simply sign up for a Perigon Business Solutions account to obtain your API key. Your available features may vary based on your plan. See the Authentication section for details on how to use your API key. + +The version of the OpenAPI document: 1.0.0 +Contact: data@perigon.io +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + + +from __future__ import annotations + +import json +import pprint +import re # noqa: F401 +from typing import Any, ClassVar, Dict, List, Optional, Set + +from pydantic import BaseModel, ConfigDict, Field, StrictStr +from typing_extensions import Self + +from perigon.models.key_point import KeyPoint +from perigon.models.question import Question + + +class StoryHistoryRecord(BaseModel): + """ + StoryHistoryRecord + """ # noqa: E501 + + cluster_id: Optional[StrictStr] = Field(default=None, alias="clusterId") + created_at: Optional[StrictStr] = Field(default=None, alias="createdAt") + name: Optional[StrictStr] = None + triggered_at: Optional[StrictStr] = Field(default=None, alias="triggeredAt") + summary: Optional[StrictStr] = None + short_summary: Optional[StrictStr] = Field(default=None, alias="shortSummary") + changelog: Optional[StrictStr] = None + key_points: Optional[List[KeyPoint]] = Field(default=None, alias="keyPoints") + questions: Optional[List[Question]] = None + __properties: ClassVar[List[str]] = [ + "clusterId", + "createdAt", + "name", + "triggeredAt", + "summary", + "shortSummary", + "changelog", + "keyPoints", + "questions", + ] + + model_config = ConfigDict( + populate_by_name=True, + validate_assignment=True, + protected_namespaces=(), + ) + + def to_str(self) -> str: + """Returns the string representation of the model using alias""" + return pprint.pformat(self.model_dump(by_alias=True)) + + def to_json(self) -> str: + """Returns the JSON representation of the model using alias""" + # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead + return json.dumps(self.to_dict()) + + @classmethod + def from_json(cls, json_str: str) -> Optional[Self]: + """Create an instance of StoryHistoryRecord from a JSON string""" + return cls.from_dict(json.loads(json_str)) + + def to_dict(self) -> Dict[str, Any]: + """Return the dictionary representation of the model using alias. + + This has the following differences from calling pydantic's + `self.model_dump(by_alias=True)`: + + * `None` is only added to the output dict for nullable fields that + were set at model initialization. Other fields with value `None` + are ignored. + """ + excluded_fields: Set[str] = set([]) + + _dict = self.model_dump( + by_alias=True, + exclude=excluded_fields, + exclude_none=True, + ) + # override the default output from pydantic by calling `to_dict()` of each item in key_points (list) + _items = [] + if self.key_points: + for _item_key_points in self.key_points: + if _item_key_points: + _items.append(_item_key_points.to_dict()) + _dict["keyPoints"] = _items + # override the default output from pydantic by calling `to_dict()` of each item in questions (list) + _items = [] + if self.questions: + for _item_questions in self.questions: + if _item_questions: + _items.append(_item_questions.to_dict()) + _dict["questions"] = _items + # set to None if cluster_id (nullable) is None + # and model_fields_set contains the field + if self.cluster_id is None and "cluster_id" in self.model_fields_set: + _dict["clusterId"] = None + + # set to None if created_at (nullable) is None + # and model_fields_set contains the field + if self.created_at is None and "created_at" in self.model_fields_set: + _dict["createdAt"] = None + + # set to None if name (nullable) is None + # and model_fields_set contains the field + if self.name is None and "name" in self.model_fields_set: + _dict["name"] = None + + # set to None if triggered_at (nullable) is None + # and model_fields_set contains the field + if self.triggered_at is None and "triggered_at" in self.model_fields_set: + _dict["triggeredAt"] = None + + # set to None if summary (nullable) is None + # and model_fields_set contains the field + if self.summary is None and "summary" in self.model_fields_set: + _dict["summary"] = None + + # set to None if short_summary (nullable) is None + # and model_fields_set contains the field + if self.short_summary is None and "short_summary" in self.model_fields_set: + _dict["shortSummary"] = None + + # set to None if changelog (nullable) is None + # and model_fields_set contains the field + if self.changelog is None and "changelog" in self.model_fields_set: + _dict["changelog"] = None + + # set to None if key_points (nullable) is None + # and model_fields_set contains the field + if self.key_points is None and "key_points" in self.model_fields_set: + _dict["keyPoints"] = None + + # set to None if questions (nullable) is None + # and model_fields_set contains the field + if self.questions is None and "questions" in self.model_fields_set: + _dict["questions"] = None + + return _dict + + @classmethod + def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: + """Create an instance of StoryHistoryRecord from a dict""" + if obj is None: + return None + + if not isinstance(obj, dict): + return cls.model_validate(obj) + + _obj = cls.model_validate( + { + "clusterId": obj.get("clusterId"), + "createdAt": obj.get("createdAt"), + "name": obj.get("name"), + "triggeredAt": obj.get("triggeredAt"), + "summary": obj.get("summary"), + "shortSummary": obj.get("shortSummary"), + "changelog": obj.get("changelog"), + "keyPoints": ( + [KeyPoint.from_dict(_item) for _item in obj["keyPoints"]] + if obj.get("keyPoints") is not None + else None + ), + "questions": ( + [Question.from_dict(_item) for _item in obj["questions"]] + if obj.get("questions") is not None + else None + ), + } + ) + return _obj diff --git a/perigon/models/story_history_result.py b/perigon/models/story_history_result.py new file mode 100644 index 0000000..853e3e7 --- /dev/null +++ b/perigon/models/story_history_result.py @@ -0,0 +1,105 @@ +# coding: utf-8 + +""" +Perigon API + +The Perigon API provides access to comprehensive news and web content data. To use the API, simply sign up for a Perigon Business Solutions account to obtain your API key. Your available features may vary based on your plan. See the Authentication section for details on how to use your API key. + +The version of the OpenAPI document: 1.0.0 +Contact: data@perigon.io +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + + +from __future__ import annotations + +import json +import pprint +import re # noqa: F401 +from typing import Any, ClassVar, Dict, List, Optional, Set + +from pydantic import BaseModel, ConfigDict, Field, StrictInt +from typing_extensions import Self + +from perigon.models.story_history_record import StoryHistoryRecord + + +class StoryHistoryResult(BaseModel): + """ + Story history result + """ # noqa: E501 + + status: StrictInt + num_results: StrictInt = Field(alias="numResults") + results: List[StoryHistoryRecord] + __properties: ClassVar[List[str]] = ["status", "numResults", "results"] + + model_config = ConfigDict( + populate_by_name=True, + validate_assignment=True, + protected_namespaces=(), + ) + + def to_str(self) -> str: + """Returns the string representation of the model using alias""" + return pprint.pformat(self.model_dump(by_alias=True)) + + def to_json(self) -> str: + """Returns the JSON representation of the model using alias""" + # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead + return json.dumps(self.to_dict()) + + @classmethod + def from_json(cls, json_str: str) -> Optional[Self]: + """Create an instance of StoryHistoryResult from a JSON string""" + return cls.from_dict(json.loads(json_str)) + + def to_dict(self) -> Dict[str, Any]: + """Return the dictionary representation of the model using alias. + + This has the following differences from calling pydantic's + `self.model_dump(by_alias=True)`: + + * `None` is only added to the output dict for nullable fields that + were set at model initialization. Other fields with value `None` + are ignored. + """ + excluded_fields: Set[str] = set([]) + + _dict = self.model_dump( + by_alias=True, + exclude=excluded_fields, + exclude_none=True, + ) + # override the default output from pydantic by calling `to_dict()` of each item in results (list) + _items = [] + if self.results: + for _item_results in self.results: + if _item_results: + _items.append(_item_results.to_dict()) + _dict["results"] = _items + return _dict + + @classmethod + def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: + """Create an instance of StoryHistoryResult from a dict""" + if obj is None: + return None + + if not isinstance(obj, dict): + return cls.model_validate(obj) + + _obj = cls.model_validate( + { + "status": obj.get("status"), + "numResults": obj.get("numResults"), + "results": ( + [StoryHistoryRecord.from_dict(_item) for _item in obj["results"]] + if obj.get("results") is not None + else None + ), + } + ) + return _obj diff --git a/perigon/models/summary_body.py b/perigon/models/summary_body.py index 0c9ebd1..6612444 100644 --- a/perigon/models/summary_body.py +++ b/perigon/models/summary_body.py @@ -47,8 +47,8 @@ class SummaryBody(BaseModel): description="The maximum number of articles that should be returned in the response. This can be used to return fewer than maxArticleCount results.", alias="returnedArticleCount", ) - summarize_fields: Optional[StrictStr] = Field( - default=["TITLE", "CONTENT", "SUMMARY"], + summarize_fields: Optional[List[StrictStr]] = Field( + default=None, description="Which article fields to include when generating the summary. Up to three values from TITLE, CONTENT, SUMMARY.", alias="summarizeFields", ) @@ -101,10 +101,11 @@ def summarize_fields_validate_enum(cls, value): if value is None: return value - if value not in set(["TITLE", "CONTENT", "SUMMARY"]): - raise ValueError( - "must be one of enum values ('TITLE', 'CONTENT', 'SUMMARY')" - ) + for i in value: + if i not in set(["TITLE", "CONTENT", "SUMMARY"]): + raise ValueError( + "each list item must be one of ('TITLE', 'CONTENT', 'SUMMARY')" + ) return value @field_validator("method") @@ -258,11 +259,7 @@ def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: if obj.get("returnedArticleCount") is not None else 10 ), - "summarizeFields": ( - obj.get("summarizeFields") - if obj.get("summarizeFields") is not None - else ["TITLE", "CONTENT", "SUMMARY"] - ), + "summarizeFields": obj.get("summarizeFields"), "method": ( obj.get("method") if obj.get("method") is not None else "ARTICLES" ), diff --git a/perigon/models/topic_dto.py b/perigon/models/topic_dto.py index cc20d92..dec9166 100644 --- a/perigon/models/topic_dto.py +++ b/perigon/models/topic_dto.py @@ -105,6 +105,11 @@ def to_dict(self) -> Dict[str, Any]: if self.name is None and "name" in self.model_fields_set: _dict["name"] = None + # set to None if labels (nullable) is None + # and model_fields_set contains the field + if self.labels is None and "labels" in self.model_fields_set: + _dict["labels"] = None + return _dict @classmethod diff --git a/perigon/models/wikidata_political_party_holder.py b/perigon/models/wikidata_political_party_holder.py index f51b106..6d1f189 100644 --- a/perigon/models/wikidata_political_party_holder.py +++ b/perigon/models/wikidata_political_party_holder.py @@ -90,6 +90,16 @@ def to_dict(self) -> Dict[str, Any]: if self.label is None and "label" in self.model_fields_set: _dict["label"] = None + # set to None if start_time (nullable) is None + # and model_fields_set contains the field + if self.start_time is None and "start_time" in self.model_fields_set: + _dict["startTime"] = None + + # set to None if end_time (nullable) is None + # and model_fields_set contains the field + if self.end_time is None and "end_time" in self.model_fields_set: + _dict["endTime"] = None + return _dict @classmethod diff --git a/perigon/models/wikidata_position_holder.py b/perigon/models/wikidata_position_holder.py index d408cc1..f6ed0bb 100644 --- a/perigon/models/wikidata_position_holder.py +++ b/perigon/models/wikidata_position_holder.py @@ -101,6 +101,21 @@ def to_dict(self) -> Dict[str, Any]: if self.label is None and "label" in self.model_fields_set: _dict["label"] = None + # set to None if start_time (nullable) is None + # and model_fields_set contains the field + if self.start_time is None and "start_time" in self.model_fields_set: + _dict["startTime"] = None + + # set to None if end_time (nullable) is None + # and model_fields_set contains the field + if self.end_time is None and "end_time" in self.model_fields_set: + _dict["endTime"] = None + + # set to None if employer (nullable) is None + # and model_fields_set contains the field + if self.employer is None and "employer" in self.model_fields_set: + _dict["employer"] = None + return _dict @classmethod diff --git a/perigon/models/wikipedia_search_params.py b/perigon/models/wikipedia_search_params.py index d5871b8..6cef98e 100644 --- a/perigon/models/wikipedia_search_params.py +++ b/perigon/models/wikipedia_search_params.py @@ -57,10 +57,10 @@ class WikipediaSearchParams(BaseModel): alias="pageviewsTo", ) size: Optional[Annotated[int, Field(le=100, strict=True, ge=1)]] = Field( - default=None, description="The number of items per page." + default=10, description="The number of items per page." ) page: Optional[Annotated[int, Field(le=10000, strict=True, ge=0)]] = Field( - default=None, description="The page number to retrieve." + default=0, description="The page number to retrieve." ) __properties: ClassVar[List[str]] = [ "prompt", @@ -113,6 +113,11 @@ def to_dict(self) -> Dict[str, Any]: # override the default output from pydantic by calling `to_dict()` of filter if self.filter: _dict["filter"] = self.filter.to_dict() + # set to None if filter (nullable) is None + # and model_fields_set contains the field + if self.filter is None and "filter" in self.model_fields_set: + _dict["filter"] = None + # set to None if wiki_revision_from (nullable) is None # and model_fields_set contains the field if ( @@ -172,8 +177,8 @@ def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: "wikiRevisionTo": obj.get("wikiRevisionTo"), "pageviewsFrom": obj.get("pageviewsFrom"), "pageviewsTo": obj.get("pageviewsTo"), - "size": obj.get("size"), - "page": obj.get("page"), + "size": obj.get("size") if obj.get("size") is not None else 10, + "page": obj.get("page") if obj.get("page") is not None else 0, } ) return _obj From cf58b49bbfdb000a664ff3cf4a1fb3426097ed71 Mon Sep 17 00:00:00 2001 From: Islem Maboud Date: Fri, 26 Sep 2025 16:08:33 +0100 Subject: [PATCH 2/3] fix: update tests to work with the summarize endpoint nullable values --- perigon/api/v1_api.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/perigon/api/v1_api.py b/perigon/api/v1_api.py index b86e885..857ec88 100644 --- a/perigon/api/v1_api.py +++ b/perigon/api/v1_api.py @@ -2919,7 +2919,7 @@ def search_summarizer( params = _normalise_query(params) resp = self.api_client.request( - "POST", path, params=params, json=summary_body.model_dump(by_alias=True) + "POST", path, params=params, json=summary_body.model_dump(by_alias=True, exclude_none=True) ) resp.raise_for_status() return SummarySearchResult.model_validate(resp.json()) @@ -3301,7 +3301,7 @@ async def search_summarizer_async( params = _normalise_query(params) resp = await self.api_client.request_async( - "POST", path, params=params, json=summary_body.model_dump(by_alias=True) + "POST", path, params=params, json=summary_body.model_dump(by_alias=True, exclude_none=True) ) resp.raise_for_status() return SummarySearchResult.model_validate(resp.json()) From 4c891333a907e7c4b6a20187e9ef1c4c572741c4 Mon Sep 17 00:00:00 2001 From: Islem Maboud Date: Fri, 26 Sep 2025 16:08:50 +0100 Subject: [PATCH 3/3] fix: update tests to work with the summarize endpoint nullable values --- perigon/api/v1_api.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/perigon/api/v1_api.py b/perigon/api/v1_api.py index 857ec88..8a77eca 100644 --- a/perigon/api/v1_api.py +++ b/perigon/api/v1_api.py @@ -2919,7 +2919,10 @@ def search_summarizer( params = _normalise_query(params) resp = self.api_client.request( - "POST", path, params=params, json=summary_body.model_dump(by_alias=True, exclude_none=True) + "POST", + path, + params=params, + json=summary_body.model_dump(by_alias=True, exclude_none=True), ) resp.raise_for_status() return SummarySearchResult.model_validate(resp.json()) @@ -3301,7 +3304,10 @@ async def search_summarizer_async( params = _normalise_query(params) resp = await self.api_client.request_async( - "POST", path, params=params, json=summary_body.model_dump(by_alias=True, exclude_none=True) + "POST", + path, + params=params, + json=summary_body.model_dump(by_alias=True, exclude_none=True), ) resp.raise_for_status() return SummarySearchResult.model_validate(resp.json())