Source: https://eventregistry.org/documentation?tab=searchArticles # Get articles Find news articles that match one or more search conditions. The search conditions can be specifying by setting one or multiple search parameters, such as `keyword`, `conceptUri`, `sourceUri`, `categoryUri`, `dateStart`, etc. If you need to specify a complex query with nested conditions that use a combination of Boolean AND, OR and NOT operators, then best approach is to specify the `query` parameter. To remove some of the results matching the **positive** conditions, you can specify some **negative** conditions using `ignoreKeyword`, `ignoreSourceUri`, and other `ignore*` parameters. The results of the search can be the list of matching articles (default) or one of the various aggregates (summaries) of the matching articles. These aggregates can include information like when the articles were published, which are the top sources publishing resulting articles, the sentiment distribution, category distribution, etc. Each search can return up to 100 articles per call. If the query matches more than 100 articles, you can retrieve them by using `articlesPage` parameter and setting it to value 2, 3, 4, etc to retrieve additional pages of results. Each call will count as one search action (regardless of the number of returned articles). **Endpoint:** GET | POST `https://eventregistry.org/api/v1/article/getArticles` **Headers:** Content-Type: application/json #### `Parameters` #### `apiKey` string (required) Your API key #### `resultType` string Define what kind of results of the search you would like to get. Available values: `articles`, `uriWgtList`, `langAggr`, `timeAggr`, `sourceAggr`, `sourceExAggr`, `authorAggr`, `keywordAggr`, `locAggr`, `conceptAggr`, `conceptGraph`, `categoryAggr`, `dateMentionAggr`, `sentimentAggr`, `recentActivityArticles` Default value: `articles` #### `articlesPage` integer Determines the page of the results to return (starting from 1). Relevant when `resultType = articles`. Default value: `1` #### `articlesCount` integer Define how many articles (up to 100) will be returned. Relevant when `resultType = articles`. Default value: `100` #### `articlesSortBy` string Choose the criteria for sorting the news articles. `rel` (relevance to the query), `date` (publishing date), `sourceImportance` (manually curated score of source importance - high value, high importance), `sourceImportanceRank` (reverse of sourceImportance), `sourceAlexaGlobalRank` (global rank of the news source), `sourceAlexaCountryRank` (country rank of the news source). Relevant when `resultType = articles`. Available values: `date`, `rel`, `sourceImportance`, `sourceAlexaGlobalRank`, `sourceAlexaCountryRank` Default value: `date` #### `articlesSortByAsc` boolean Should the results be ordered in ascending order or descending order (default). Relevant when `resultType = articles`. Default value: `false` #### `articleBodyLen` integer Set the size of the article body that'll be returned in the response. Use -1 for full article body. Default value: `-1` #### `dataType` string | string[] What data types should we search? news content (default, `news`), press releases (`pr`) or blogs (`blog`). Available values: `news`, `pr`, `blog` Default value: `news` #### `forceMaxDataTimeWindow` integer If you want to make sure that you are making queries just on the last month of data (to ensure smallest use of tokens) and you don't want to specify the `dateStart` and `dateEnd` parameters, then you can specify the `forceMaxDataTimeWindow` parameter and set it to 31 or 7 (the only two valid values). It determines the maximum age of the returned content. Don't specify the parameter if you want to search also the data that is older than 7 or 31 days. Available values: `7`, `31` #### `Filters` Click to see different parameters that you can specify in order to filter the articles #### `query` object Query object with one or more search conditions. The `query` object should match the [Advanced Query Language](https://github.com/EventRegistry/event-registry-python/wiki/Searching-for-articles#advanced-query-language) format. If you specify the `query` parameter, then other query parameters like `keyword`, `conceptUri`, `sourceUri`, etc. should not be specified. #### `keyword` string | string[] Find articles that mention the specified keyword or a phrase. You can specify at most 60 keywords in a single search. If you specify multiple `keyword` parameters, then only articles that mention all of them will be returned, unless you specify `keywordOper` parameter and set it to `or`. Use the `keywordSearchMode` parameter to control how the keyword is matched; see the [keyword search modes](/documentation?tab=keyword_search_options) section. Example value: `Barack Obama` #### `conceptUri` string | string[] Find articles that mention the concept with a concept uri. You can specify at most 50 concepts in a single search. If multiple `conceptUri` parameters are provided, then only articles that are about all specified concepts will be returned, unless you specify `conceptOper` parameter and set it to `or`. Check [autosuggest methods](/documentation?tab=suggConcepts) to get concept URI value for a specified concept label. Example value: `http://en.wikipedia.org/wiki/World_Health_Organization` #### `categoryUri` string | string[] Find articles that are assigned to a particular category. You can specify at most 20 categories in a single search. If multiple `categoryUri` parameters are provided, then articles that are about any of the specified categories will be returned, unless you specify `categoryOper` parameter and set it to `and`. Check [autosuggest methods](/documentation?tab=suggCategories) to get value for a specified category name. Example value: `dmoz/Business/Accounting` #### `sourceUri` string | string[] Find articles that have been published by a news source. If you specify multiple `sourceUri` parameters, then articles from any of the specified sources will be returned. Check [autosuggest methods](/documentation?tab=suggSources) to get value for a source name. Example value: `bbc.co.uk` #### `sourceLocationUri` string | string[] Find articles that were published by news sources located at the given geographic location (city or country). If you specify multiple `sourceLocationUri` parameters, then articles from sources from any of the specified sources will be returned. Check [autosuggest methods](/documentation?tab=suggLocations) to get value for a location name. Example value: `http://en.wikipedia.org/wiki/Germany` #### `sourceGroupUri` string | string[] Find articles that were published by news sources that are assigned to some predefined group of news sources. Example value: `general/ERtop10` #### `authorUri` string | string[] Find articles that were written by a particular author. Check [autosuggest methods](/documentation?tab=suggAuthors) to get value for author uri based on the author name (and potentially source url). Example value: `mark_mazzetti@nytimes.com` #### `locationUri` string | string[] Find articles that describe something that occured at a particular location (based on the location mentioned in the dateline). Check [autosuggest methods](/documentation?tab=suggLocations) to get value for a location name. NOTE: If a location will not be specified in the dateline (immediate start of the article), the article will not be returned. Consider also using `conceptUri` to find articles that mention a particular location. Example value: `http://en.wikipedia.org/wiki/United_States` #### `lang` string | string[] Find articles in the specified language(s). If parameter is not set, articles in all languages will be included. You can specify at most 5 languages in a single search. Specify languages using their ISO3 language codes. The full list of languages and their ISO3 codes can be found on [this page](https://github.com/EventRegistry/event-registry-python/wiki/Supported-languages). Example value: `eng` #### `dateStart` string The starting date on or after the articles of interest were published. The date should be in the YYYY-MM-DD format. Example value: `2018-01-03` #### `dateEnd` string The last date on which the articles of interest were published. The date should be in the YYYY-MM-DD format. Example value: `2018-01-10` #### `dateMentionStart` string Find articles that explicitly mention a date that is equal or greater than `dateMentionStart`. The date should be in the YYYY-MM-DD format. Example value: `2018-01-10` #### `dateMentionEnd` string Find articles that explicitly mention a date that is lower or equal to `dateMentionEnd`. The date should be in the YYYY-MM-DD format. Example value: `2018-01-10` #### `keywordLoc` string What data should be used when searching using the keywords provided by `keywords` parameter. Available values: `body`, `title`, `title,body` Default value: `body` #### `keywordOper` string If more keywords are provided with the `keyword` parameter, what should be the Boolean operator used. If `and` (default) then all of the specified keywords have to be present in the article; if `or` then an article will be returned if it mentions any of the provided keywords. Available values: `and`, `or` Default value: `and` #### `keywordSearchMode` string Determines how the keywords provided with the `keyword` parameter are matched against the content. Use `phrase` (default) to match the keyword as an exact phrase, `exact` to use the Boolean query language (with `AND`, `OR`, `NOT`, `NEAR` and `NEXT` operators), or `simple` for a relevance-based search that does not require all terms to be present. See the [keyword search modes](/documentation?tab=keyword_search_options) section for details and examples. Available values: `phrase`, `exact`, `simple` Default value: `phrase` #### `conceptOper` string If more concepts are provided with the `conceptUri` parameter, what should be the Boolean operator used. If `and` (default) then all of the specified concepts have to be present in the article; if `or` then an article will be returned if it mentions any of the provided concepts. Available values: `and`, `or` Default value: `and` #### `categoryOper` string If more categories are provided with the `categoryUri` parameter, what should be the Boolean operator used. If `and` then all of the specified categories have to be present in the article; if `or` then an article will be returned if it mentions any of the provided categories. Available values: `and`, `or` Default value: `or` #### `ignoreKeyword` string | string[] Ignore articles that mention the specified keyword or phrase. You can specify at most 60 keywords in a single search. If you specify multiple `ignoreKeyword` parameters, then articles that mention any of these keywords will be ignored. Example value: `Donald Trump` #### `ignoreConceptUri` string | string[] Ignore articles that mention the concept with concept uri. You can specify at most 50 concepts in a single search. If you specify multiple `ignoreConceptUri` parameters then articles that mention any of them will be ignored. Check [autosuggest methods](/documentation?tab=suggConcepts) to get value for a specified concept label. Example value: `http://en.wikipedia.org/wiki/World_Health_Organization` #### `ignoreCategoryUri` string | string[] Ignore articles that are assigned into a particular category. You can specify at most 20 categories in a single search. If you specify multiple `ignoreCategoryUri` parameters then articles that mention any of them will be ignored. Check [autosuggest methods](/documentation?tab=suggCategories) to get value for a specified category name. Example value: `dmoz/Business/Accounting` #### `ignoreSourceUri` string | string[] Ignore articles that have been published by a news source. If you specify multiple `ignoreSourceUri` parameters, then articles from any of the specified sources will be ignored. Check [autosuggest methods](/documentation?tab=suggSources) to get value for a source name. Example value: `bbc.co.uk` #### `ignoreSourceLocationUri` string | string[] Ignore articles that were published by news sources located at the given geographic location (city or country). If you specify multiple `ignoreSourceLocationUri` parameters, then articles from sources from any of the specified sources will be ignored. Check [autosuggest methods](/documentation?tab=suggLocations) to get value for a location name. Example value: `http://en.wikipedia.org/wiki/Olsberg,_Germany` #### `ignoreSourceGroupUri` string | string[] Ignore articles that were published by news sources that are assigned to some predefined group of news sources. Example value: `general/ERtop10` #### `ignoreLocationUri` string | string[] Ignore articles that describe something that occured at a particular location (based on the location mentioned in the dateline). Check [autosuggest methods](/documentation?tab=suggLocations) to get value for a location name. Example value: `http://en.wikipedia.org/wiki/United_States` #### `ignoreAuthorUri` string | string[] Ignore articles that were written by a particular author. Check [autosuggest methods](/documentation?tab=suggAuthors) to get value for author uri based on the author name (and potentially source url). Example value: `mark_mazzetti@nytimes.com` #### `ignoreLang` string | string[] Ignore articles in the specified language(s). You can specify at most 5 languages in a single search. Specify languages using their ISO3 language codes. The full list of languages and their ISO3 codes can be found on [this page](https://github.com/EventRegistry/event-registry-python/wiki/Supported-languages). Example value: `deu` #### `ignoreKeywordLoc` string What data should be used when searching using the keywords provided by parameter. Available values: `body`, `title`, `title,body` Default value: `body` #### `startSourceRankPercentile` integer Starting [ranking percentile of the sources](https://github.com/EventRegistry/event-registry-python/wiki/Source-filtering#filtering-of-sources-based-on-their-ranking) to consider in the results (default: 0). Value should be in range 0-90 and divisible by 10. Default value: `0` #### `endSourceRankPercentile` integer Ending [ranking percentile of the sources](https://github.com/EventRegistry/event-registry-python/wiki/Source-filtering#filtering-of-sources-based-on-their-ranking) to consider in the results (default: 100). Value should be in range 10-100 and divisible by 10. Default value: `100` #### `minSentiment` integer The minimum value of the sentiment, the article should have. Valid value is any floating number between -1 (very negative) to 1 (very positive). 0 represents neutral sentiment. Note that setting the value will automatically reduce results to just English articles, since the sentiment can only be computed for English language. #### `maxSentiment` integer The maximum value of the sentiment, the article should have. Valid value is any floating number between -1 (very negative) to 1 (very positive). 0 represents neutral sentiment. Note that setting the value will automatically reduce results to just English articles, since the sentiment can only be computed for English language. #### `isDuplicateFilter` string Some articles can be duplicates of other articles. What should be done with them. Available values: `skipDuplicates`, `keepOnlyDuplicates`, `keepAll` Default value: `keepAll` #### `eventFilter` string Some articles describe a known event and some don't. This filter allows you to filter the resulting articles based on this criteria. Available values: `skipArticlesWithoutEvent`, `keepOnlyArticlesWithoutEvent`, `keepAll` Default value: `keepAll` #### `Returned Details` The API call can return more or less meta-data information about the articles, concepts, categories, sources and locations. Click to see the available properties that can be specified to determine the amount of returned information. #### `includeArticleTitle` boolean Set this parameter to true to include the article title in the response. Default value: `true` #### `includeArticleBasicInfo` boolean Set this parameter to true to include the core article information in the response. Default value: `true` #### `includeArticleBody` boolean Set this parameter to true to include the article body in the response. Default value: `true` #### `includeArticleEventUri` boolean Set this parameter to true to include the uri of the event (to which the article belongs) in the response. Default value: `true` #### `includeArticleSocialScore` boolean Set this parameter to true to include the information about how many times the article was shared on different social media. Default value: `false` #### `includeArticleSentiment` boolean Set this parameter to true to include the article sentiment in the response (value will be non-null only for English articles). Default value: `true` #### `includeArticleConcepts` boolean Set this parameter to true to include the article concepts in the response. Default value: `false` #### `includeArticleCategories` boolean Set this parameter to true to include the article categories in the response. Default value: `false` #### `includeArticleLocation` boolean Set this parameter to true to include the article location in the response. Default value: `false` #### `includeArticleImage` boolean Set this parameter to true to include the article image in the response. Default value: `true` #### `includeArticleAuthors` boolean Set this parameter to true to include the article authors in the response. Default value: `true` #### `includeArticleVideos` boolean Set this parameter to true to include the article videos in the response. Default value: `false` #### `includeArticleLinks` boolean Set this parameter to true to include the article links in the response. Default value: `false` #### `includeArticleExtractedDates` boolean Set this parameter to true to include article extracted dates in the response. Default value: `false` #### `includeArticleDuplicateList` boolean Set this parameter to true to include the list of duplicate articles in the response. Default value: `false` #### `includeArticleOriginalArticle` boolean Set this parameter to true to include the original article in the response. Default value: `false` #### `includeSourceTitle` boolean Set this parameter to true to include the source title in the response. Default value: `true` #### `includeSourceDescription` boolean Set this parameter to true to include the source description in the response. Default value: `false` #### `includeSourceLocation` boolean Set this parameter to true to include the source location in the response. Default value: `false` #### `includeSourceRanking` boolean Set this parameter to true to include the source ranking in the response. Default value: `false` #### `includeConceptLabel` boolean Set this parameter to true to include the concept label in the response. Default value: `true` #### `includeConceptImage` boolean Set this parameter to true to include the concept image in the response. Default value: `false` #### `includeConceptSynonyms` boolean Set this parameter to true to include the concept synonyms in the response. Default value: `false` #### `conceptLang` string Define the language of the concept label. Default value: `eng` #### `includeCategoryParentUri` boolean Set this parameter to true to include category parent uri in the response. Default value: `false` #### `includeLocationGeoLocation` boolean Set to true to include the geo location (latitude, longitude) for items that are locations. Default value: `false` #### `includeLocationPopulation` boolean Set to true to include the population size of the location. Default value: `false` #### `includeLocationGeoNamesId` boolean Set to true to include the GeoNames id of the location. Default value: `false` #### `includeLocationCountryArea` boolean Set to true to include the are of the location in squared km. Default value: `false` #### `includeLocationCountryContinent` boolean Set to true to get the continent of the country for location objects. Default value: `false` ## Request examples ### Example 1 Find articles (news articles and PR content) that mention the phrase 'Tesla Inc' and return 100 latest articles with full article body. Return only articles from sources from USA, Canada and UK. Exclude the paywalled sources. Limit the search to the last month only (using `forceMaxDataTimeWindow` parameter). Repeat the query multiple times and increase the `articlesPage` parameter, to retrieve more results. Request body: ```json { "action": "getArticles", "keyword": "Tesla Inc", "sourceLocationUri": [ "http://en.wikipedia.org/wiki/United_States", "http://en.wikipedia.org/wiki/Canada", "http://en.wikipedia.org/wiki/United_Kingdom" ], "ignoreSourceGroupUri": "paywall/paywalled_sources", "articlesPage": 1, "articlesCount": 100, "articlesSortBy": "date", "articlesSortByAsc": false, "dataType": [ "news", "pr" ], "forceMaxDataTimeWindow": 31, "resultType": "articles", "apiKey": "YOUR_API_KEY" } ``` ```python from eventregistry import * # since we want recent results, just prevent use of archive - in this way we don't need to set any date constraints er = EventRegistry(apiKey = YOUR_API_KEY, allowUseOfArchive = False) q = QueryArticlesIter( keywords = "Tesla Inc", sourceLocationUri=QueryItems.OR([ "http://en.wikipedia.org/wiki/United_Kingdom", "http://en.wikipedia.org/wiki/United_States", "http://en.wikipedia.org/wiki/Canada"]), ignoreSourceGroupUri="paywall/paywalled_sources", dataType= ["news", "pr"]) # we limit here the results to 100. If you want more, remove or increasae maxItems for article in q.execQuery(er, sortBy="date", sortByAsc=False, maxItems=100): print(article) # alternatively, the same query using the query language could look something like this: qStr = """ { "$query": { keyword": "Tesla Inc", "sourceLocationUri": { "$or": [ "http://en.wikipedia.org/wiki/United_Kingdom", "http://en.wikipedia.org/wiki/United_States", "http://en.wikipedia.org/wiki/Canada" ]}, "$not": { "sourceGroupUri": "paywall/paywalled_sources" } }, "$filter": { "dataType": ["news", "pr"] } } """ q = QueryArticlesIter.initWithComplexQuery(qStr) ``` ```javascript var er = new erBase.EventRegistry({ allowUseOfArchive: false }); var requestArticlesInfo = new erBase.RequestArticlesInfo({count: 100, sortBy: "date", sortByAsc: false}); var q1 = new erBase.QueryArticles({ keyword: "Tesla Inc", sourceLocationUri: [ "http://en.wikipedia.org/wiki/United_States", "http://en.wikipedia.org/wiki/Canada", "http://en.wikipedia.org/wiki/United_Kingdom", ], ignoreSourceGroupUri: "paywall/paywalled_sources", }); q1.setRequestedResult(requestArticlesInfo); er.execQuery(q1).then((response) => { console.info(response); }); ``` ```typescript const er = new EventRegistry({allowUseOfArchive: false}); const requestArticlesInfo = new RequestArticlesInfo({count: 100, sortBy: "date", sortByAsc: false}); const q1 = new QueryArticles({ keyword: "Tesla Inc", sourceLocationUri: [ "http://en.wikipedia.org/wiki/United_States", "http://en.wikipedia.org/wiki/Canada", "http://en.wikipedia.org/wiki/United_Kingdom", ], ignoreSourceGroupUri: "paywall/paywalled_sources", }); q1.setRequestedResult(requestArticlesInfo); er.execQuery(q1).then((response) => { console.info(response); }); ``` ### Example 2 Find the English or German articles published in the last month by sources ranked among top 30% that mention the words 'Barack' and 'Obama', but not necessarily together as a phrase. The articles should also not mention 'Michelle' or 'Sasha'. The matching articles are sorted by source importance from best to worst ranked. Return the first 30 articles containing the list of mentioned concepts, article categories, image and article location. Request body: ```json { "action": "getArticles", "keyword": [ "Barack", "Obama" ], "keywordOper": "and", "lang": [ "eng", "deu" ], "ignoreKeyword": [ "Michelle", "Sasha" ], "startSourceRankPercentile": 0, "endSourceRankPercentile": 30, "articlesPage": 1, "articlesCount": 30, "articlesSortBy": "sourceImportance", "articlesSortByAsc": false, "articlesArticleBodyLen": -1, "includeArticleConcepts": true, "includeArticleCategories": true, "includeArticleImage": true, "includeArticleSocialScore": true, "includeArticleLocation": true, "resultType": "articles", "apiKey": "YOUR_API_KEY", "forceMaxDataTimeWindow": 31 } ``` ```python from eventregistry import * # since we want results from last month, just prevent use of archive - in this way we don't need to set any date constraints er = EventRegistry(apiKey = YOUR_API_KEY, allowUseOfArchive = False) q = QueryArticlesIter( keywords=QueryItems.AND(["Barack", "Obama"]), lang=["eng", "deu"], ignoreKeywords=QueryItems.OR(["Michelle", "Sasha"]), startSourceRankPercentile=0, endSourceRankPercentile=30, dataType = ["news", "blog"]) for article in q.execQuery(er, sortBy="sourceImportance", sortByAsc=False, returnInfo=ReturnInfo( articleInfo = ArticleInfoFlags(concepts = True, categories = True, location = True, image = True)), maxItems=30): print(article) # alternatively, the same query using the query language could look something like this: qStr = """ { "$query": { "keyword": { "$and": ["Barack", "Obama"] }, "lang": { "$or": ["eng", "deu"] }, "$not": { "keyword": { "$or": ["Michelle", "Sasha"] }, } }, "$filter": { "endSourceRankPercentile": 30, "dataType": ["news", "blog"] } } """ q = QueryArticlesIter.initWithComplexQuery(qStr) ``` ```javascript var er = new erBase.EventRegistry({allowUseOfArchive: false}); var articleInfo = new erBase.ArticleInfoFlags({ concepts: true, categories: true, location: true, image: true }); var returnInfo = new erBase.ReturnInfo({articleInfo}); var requestArticlesInfo = new erBase.RequestArticlesInfo({count: 30, sortBy: "sourceImportance", sortByAsc: false, returnInfo: returnInfo}); var q1 = new erBase.QueryArticles({ keywords: ["Barack", "Obama"], ignoreKeywords: ["Michelle", "Sasha"], lang: ["eng", "deu"], startSourceRankPercentile: 0, endSourceRankPercentile: 30, dataType: ["news", "blog"]}); q1.setRequestedResult(requestArticlesInfo); er.execQuery(q1).then((response) => { console.info(response); }); ``` ```typescript const er = new EventRegistry({allowUseOfArchive: false}); const articleInfo = new ArticleInfoFlags({ concepts: true, categories: true, location: true, image: true }); const returnInfo = new ReturnInfo({articleInfo}); const requestArticlesInfo = new RequestArticlesInfo({count: 30, sortBy: "sourceImportance", sortByAsc: false, returnInfo: returnInfo}); const q1 = new QueryArticles({ keywords: ["Barack", "Obama"], ignoreKeywords: ["Michelle", "Sasha"], lang: ["eng", "deu"], startSourceRankPercentile: 0, endSourceRankPercentile: 30, dataType: ["news", "blog"]}); q1.setRequestedResult(requestArticlesInfo); er.execQuery(q1).then((response) => { console.info(response); }); ``` ### Example 3 Find articles that mention George Clooney that were written by sources located in Germany or Los Angeles. The query will return 100 articles. Repeat the query multiple times and increase the `articlesPage` parameter, to retrieve more results. Request body: ```json { "action": "getArticles", "conceptUri": "http://en.wikipedia.org/wiki/George_Clooney", "sourceLocationUri": [ "http://en.wikipedia.org/wiki/Germany", "http://en.wikipedia.org/wiki/Los_Angeles_County,_California" ], "articlesPage": 1, "articlesCount": 100, "articlesSortBy": "date", "articlesSortByAsc": false, "articlesArticleBodyLen": -1, "resultType": "articles", "apiKey": "YOUR_API_KEY", "forceMaxDataTimeWindow": 31 } ``` ```python from eventregistry import * er = EventRegistry(apiKey = YOUR_API_KEY, allowUseOfArchive = False) clooneyUri = er.getConceptUri("Clooney") # returns "http://en.wikipedia.org/wiki/George_Clooney" germanyUri = er.getLocationUri("Germany") # returns "http://en.wikipedia.org/wiki/Germany" laUri = er.getLocationUri("Los Angeles") # returns "http://en.wikipedia.org/wiki/Los_Angeles_County,_California" q = QueryArticlesIter( conceptUri = clooneyUri, sourceLocationUri = [ germanyUri, laUri]) # we limit here the results to 200. If you want more, remove or increasae maxItems for article in q.execQuery(er, sortBy="date", sortByAsc=False, maxItems=200): print(article) # alternatively, the same query using the query language could look something like this: qStr = """ { "$query": { "conceptUri": "http://en.wikipedia.org/wiki/George_Clooney", "sourceLocationUri": { "$or": [ "http://en.wikipedia.org/wiki/Germany", "http://en.wikipedia.org/wiki/Los_Angeles_County,_California" ] } } } """ q = QueryArticlesIter.initWithComplexQuery(qStr) ``` ```javascript var er = new erBase.EventRegistry({allowUseOfArchive: false}); var requestArticlesInfo = new erBase.RequestArticlesInfo({count: 100, sortBy: "date", sortByAsc: false}); var q1 = new erBase.QueryArticles({ conceptUri: "http://en.wikipedia.org/wiki/George_Clooney", sourceLocationUri: [ "http://en.wikipedia.org/wiki/Germany", "http://en.wikipedia.org/wiki/Los_Angeles_County,_California", ], }); q1.setRequestedResult(requestArticlesInfo); er.execQuery(q1).then((response) => { console.info(response); }); ``` ```typescript const er = new EventRegistry({allowUseOfArchive: false}); const requestArticlesInfo = new RequestArticlesInfo({count: 100, sortBy: "date", sortByAsc: false}); const q1 = new QueryArticles({ conceptUri: "http://en.wikipedia.org/wiki/George_Clooney", sourceLocationUri: [ "http://en.wikipedia.org/wiki/Germany", "http://en.wikipedia.org/wiki/Los_Angeles_County,_California", ], }); q1.setRequestedResult(requestArticlesInfo); er.execQuery(q1).then((response) => { console.info(response); }); ``` ### Example 4 Find articles published on 2017-04-22 that either mention Barack Obama or mention keyword Trump, and are associated with business category. Because we need an OR between Trump and Obama, we need to use the query language (specifying the `conceptUri` and `keyword` parameters using the regular `QueryArticlesIter` constructor would find results where both of them need to be mentioned). Using the query language you can easily specify nested subqueries containing Boolean 'AND' and 'OR' segments. Return 100 articles sorted by relevance to the query. Repeat the query multiple times and increase the `articlesPage` parameter, to retrieve more results. Request body: ```json { "action": "getArticles", "query": { "$query": { "$and": [ { "dateStart": "2017-04-22", "dateEnd": "2017-04-22", "categoryUri": "dmoz/Business" }, { "$or": [ { "conceptUri": "http://en.wikipedia.org/wiki/Barack_Obama" }, { "keyword": "Trump" } ] } ] } }, "articlesPage": 1, "articlesCount": 100, "articlesSortBy": "rel", "articlesSortByAsc": false, "articlesArticleBodyLen": -1, "resultType": "articles", "apiKey": "YOUR_API_KEY" } ``` ```python from eventregistry import * er = EventRegistry(apiKey = YOUR_API_KEY) qStr = """ { "$query": { "$and": [ { "dateStart": "2017-04-22", "dateEnd": "2017-04-22", "categoryUri": "dmoz/Business" }, { "$or": [ { "conceptUri": "http://en.wikipedia.org/wiki/Barack_Obama" }, { "keyword": "Trump" } ] } ] } } """ q = QueryArticlesIter.initWithComplexQuery(qStr) for article in q.execQuery(er): print(article) ``` ```javascript var er = new EventRegistry(); var qStr = ` { $query: { $and: [ { dateStart: "2017-04-22", dateEnd: "2017-04-22", categoryUri: "dmoz/Business", }, { $or: [ { conceptUri: "http://en.wikipedia.org/wiki/Barack_Obama", }, { keyword: "Trump", }, ], }, ], }, } `; var q1 = erBase.QueryArticles.initWithComplexQuery(qStr); er.execQuery(q1).then((response) => { console.info(response); }); ``` ```typescript const er = new EventRegistry(); const qStr = ` { $query: { $and: [ { dateStart: "2017-04-22", dateEnd: "2017-04-22", categoryUri: "dmoz/Business" }, { $or: [ { conceptUri: "http://en.wikipedia.org/wiki/Barack_Obama" }, { keyword: "Trump" } ] } ] } } `; const q1 = QueryArticles.initWithComplexQuery(qStr); er.execQuery(q1).then((response) => { console.info(response); }); ``` ### Example 5 Find articles that match a larger set of conditions provided using the `query` parameter. The conditions also include a negation part, where we want to exclude any articles that mention Barack Obama or were published by BBC. Request body: ```json { "query": { "$query": { "$or": [ { "dateStart": "2017-02-05", "dateEnd": "2017-02-05" }, { "conceptUri": "http://en.wikipedia.org/wiki/Donald_Trump" }, { "categoryUri": "dmoz/Society/Politics" }, { "$and": [ { "conceptUri": "http://en.wikipedia.org/wiki/Angela_Merkel" }, { "categoryUri": "dmoz/Business" } ] } ], "$not": { "$or": [ { "sourceUri": "bbc.com" }, { "conceptUri": "http://en.wikipedia.org/wiki/Barack_Obama" } ] } } }, "resultType": "articles", "apiKey": "YOUR_API_KEY" } ``` ```python from eventregistry import * er = EventRegistry(apiKey = YOUR_API_KEY) qStr = """ { "$query": { "$or": [ { "dateStart": "2017-02-05", "dateEnd": "2017-02-05" }, { "conceptUri": "http://en.wikipedia.org/wiki/Donald_Trump" }, { "categoryUri": "dmoz/Society/Politics" }, { "$and": [ { "conceptUri": "http://en.wikipedia.org/wiki/Angela_Merkel" }, { "categoryUri": "dmoz/Business" } ] } ], "$not": { "$or": [ { "sourceUri": "bbc.com" }, { "conceptUri": "http://en.wikipedia.org/wiki/Barack_Obama" } ] } } } """ q = QueryArticlesIter.initWithComplexQuery(qStr) for article in q.execQuery(er, sortBy = "date", maxItems = 100): print(article) ``` ```javascript var er = new erBase.EventRegistry(); var qStr = ` { $query: { $or: [ { "dateStart": "2017-02-05", dateEnd: "2017-02-05" }, { "conceptUri": "http://en.wikipedia.org/wiki/Donald_Trump" }, { categoryUri: "dmoz/Society/Politics" }, { $and: [ { "conceptUri": "http://en.wikipedia.org/wiki/Angela_Merkel" }, { "categoryUri": "dmoz/Business" } ] } ], $not: { $or: [ { "sourceUri": "bbc.com" }, { "conceptUri": "http://en.wikipedia.org/wiki/Barack_Obama" } ] } } } `; var q1 = erBase.QueryArticles.initWithComplexQuery(qStr); er.execQuery(q1).then((response) => { console.info(response); }); ``` ```typescript const er = new EventRegistry(); const qStr = ` { $query: { $or: [ { "dateStart": "2017-02-05", dateEnd: "2017-02-05" }, { "conceptUri": "http://en.wikipedia.org/wiki/Donald_Trump" }, { categoryUri: "dmoz/Society/Politics" }, { $and: [ { "conceptUri": "http://en.wikipedia.org/wiki/Angela_Merkel" }, { "categoryUri": "dmoz/Business" } ] } ], $not: { $or: [ { "sourceUri": "bbc.com" }, { "conceptUri": "http://en.wikipedia.org/wiki/Barack_Obama" } ] } } } `; const q1 = QueryArticles.initWithComplexQuery(qStr); er.execQuery(q1).then((response) => { console.info(response); }); ``` ### Example 6 Find articles mentioning "virus" and retrieve (a) top keywords from them, (b) number of articles per day and (c) the list of categories associated with these articles. ```python from eventregistry import * # since we want to analyze recent results, just prevent use of archive - in this way we don't need to set any date constraints er = EventRegistry(apiKey = YOUR_API_KEY, allowUseOfArchive = False) virusUri = er.getConceptUri("virus") q = QueryArticles(conceptUri=virusUri, lang="eng") # ask for the top keywords related to articles that mention virus q.setRequestedResult(RequestArticlesKeywordAggr()) res = er.execQuery(q) for kw in res.get("keywordAggr", {}).get("results", []): print(kw["keyword"]) # how many articles were published per day mentioning virus? q.setRequestedResult(RequestArticlesTimeAggr()) res = er.execQuery(q) for kw in res.get("timeAggr", {}).get("results", []): print(kw["date"] + ": " + str(kw["count"])) q.setRequestedResult(RequestArticlesCategoryAggr()) res = er.execQuery(q) for kw in res.get("categoryAggr", {}).get("results", []): print(kw["label"] + ": " + str(kw["count"])) ``` ```javascript var er = new erBase.EventRegistry(); er.getConceptUri("virus").then((virusUri) => { var q = new erBase.QueryArticles({conceptUri: virusUri}); q.setRequestedResult(new erBase.RequestArticlesKeywordAggr()); er.execQuery(q).then((response) => { console.log(response.keywordAggr.results); q.setRequestedResult(new erBase.RequestArticlesTimeAggr()); return er.execQuery(q); }).then((response) => { console.log(response.timeAggr.results); q.setRequestedResult(new erBase.RequestArticlesCategoryAggr()); return er.execQuery(q); }).then((response) => { console.log(response.categoryAggr.results); }); }); ``` ```typescript async function fetch() { const er = new EventRegistry(); const conceptUri = await er.getConceptUri("virus"); const q = new QueryArticles({conceptUri}); q.setRequestedResult(new RequestArticlesKeywordAggr()); const response1 = await er.execQuery(q); console.log(response1.keywordAggr.results); q.setRequestedResult(new RequestArticlesTimeAggr()); const response2 = await er.execQuery(q); console.log(response2.timeAggr.results); q.setRequestedResult(new RequestArticlesCategoryAggr()); const response3 = await er.execQuery(q); console.log(response3.categoryAggr.results); } ``` ## Example output ```json { "articles": { "results": [ { "uri": "7546825937", "lang": "eng", "isDuplicate": false, "date": "2023-05-16", "time": "10:35:00", "dateTime": "2023-05-16T10:35:00Z", "dateTimePub": "2023-05-16T10:34:00Z", "dataType": "news", "sim": 0, "url": "https://www.rmol.co/20230516/22538-tesla-changed-a-deadline-for-investor-proposals-angering-activists/", "title": "Tesla Changed A Deadline For Investor Proposals, Angering Activists | RMOL", "body": "Tesla investors will have fewer opportunities to express discontent with management at the company's annual meeting, which is taking place Tuesday in Austin, Texas, (trimmed) ...", "source": { "uri": "rmol.co", "dataType": "news", "title": "rmol.co" }, "authors": [], "concepts": [ { "uri": "http://en.wikipedia.org/wiki/Tesla,_Inc.", "type": "org", "score": 5, "label": { "eng": "Tesla, Inc." } }, { "uri": "http://en.wikipedia.org/wiki/Shareholder", "type": "wiki", "score": 4, "label": { "eng": "Shareholder" } }, { "uri": "http://en.wikipedia.org/wiki/Automotive_industry", "type": "wiki", "score": 3, "label": { "eng": "Automotive industry" } }, { "uri": "http://en.wikipedia.org/wiki/Austin,_Texas", "type": "loc", "score": 3, "label": { "eng": "Austin, Texas" }, "location": { "type": "place", "label": { "eng": "Austin, Texas" }, "country": { "type": "country", "label": { "eng": "United States" } } } }, { "#META ITEM": "other concepts..." } ], "image": "https://www.rmol.co/wp-content/uploads/2023/05/16tesla-fckq-facebookJumbo-4859007.jpg", "eventUri": null, "shares": {}, "sentiment": 0.01960784313725483, "wgt": 421929300, "relevance": 100 }, { "#META ITEM": "other articles..." } ], "totalResults": 38246, "page": 1, "count": 100, "pages": 383 } } ``` ## Output schema ```json { "type": "object", "properties": { "articles": { "type": "object", "properties": { "totalResults": { "type": "integer" }, "page": { "type": "integer" }, "count": { "type": "integer" }, "pages": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "lang": { "type": "string" }, "isDuplicate": { "type": "boolean" }, "date": { "type": "string" }, "time": { "type": "string" }, "dateTime": { "type": "string" }, "sim": { "type": "double" }, "url": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "source": { "type": "object", "properties": { "uri": { "type": "string" }, "dataType": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } }, "locationValidated": { "type": "boolean" }, "ranking": { "type": "object", "properties": { "importanceRank": { "type": "integer" } } } } }, "concepts": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "type": { "type": "string" }, "score": { "type": "integer" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } }, "image": { "type": "string" }, "synonyms": { "type": "object", "properties": {} }, "trendingScore": { "type": "object", "properties": { "news": { "type": "object", "properties": { "score": { "type": "double" }, "testPopFq": { "type": "integer" }, "nullPopFq": { "type": "integer" } } } } }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } } } } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "label": { "type": "string" }, "wgt": { "type": "integer" } } } }, "links": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "image": { "type": "string" }, "duplicateList": { "type": "array", "items": { "type": "string" } }, "originalArticle": { "type": "string" }, "eventUri": { "type": "string" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } }, "extractedDates": { "type": "array", "items": { "type": "object", "properties": { "amb": { "type": "boolean" }, "imp": { "type": "boolean" }, "date": { "type": "string" }, "textStart": { "type": "integer" }, "textEnd": { "type": "integer" } } } }, "shares": { "type": "object", "properties": { "facebook": { "type": "integer" } } }, "wgt": { "type": "integer" } } } } } }, "uriWgtList": { "type": "object", "properties": { "totalResults": { "type": "integer" }, "page": { "type": "integer" }, "count": { "type": "integer" }, "pages": { "type": "integer" }, "results": { "type": "array", "items": { "type": "string" } } } }, "conceptAggr": { "type": "object", "properties": { "warning": { "type": "string" }, "usedResults": { "type": "integer" }, "totalResults": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "type": { "type": "string" }, "score": { "type": "integer" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } }, "image": { "type": "string" }, "synonyms": { "type": "object", "properties": {} }, "trendingScore": { "type": "object", "properties": { "news": { "type": "object", "properties": { "score": { "type": "double" }, "testPopFq": { "type": "integer" }, "nullPopFq": { "type": "integer" } } } } }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } } } } } } }, "keywordAggr": { "type": "object", "properties": { "warning": { "type": "string" }, "usedResults": { "type": "integer" }, "totalResults": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "weight": { "type": "double" } } } } } }, "timeAggr": { "type": "object", "properties": { "warning": { "type": "string" }, "usedResults": { "type": "integer" }, "totalResults": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "count": { "type": "double" } } } } } }, "sourceAggr": { "type": "object", "properties": { "warning": { "type": "string" }, "usedResults": { "type": "integer" }, "totalResults": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "dataType": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } }, "locationValidated": { "type": "boolean" }, "ranking": { "type": "object", "properties": { "importanceRank": { "type": "integer" } } } } } } } }, "conceptGraph": { "type": "object", "properties": { "warning": { "type": "string" }, "usedResults": { "type": "integer" }, "totalResults": { "type": "integer" }, "concepts": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "type": { "type": "string" }, "score": { "type": "integer" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } }, "image": { "type": "string" }, "synonyms": { "type": "object", "properties": {} }, "trendingScore": { "type": "object", "properties": { "news": { "type": "object", "properties": { "score": { "type": "double" }, "testPopFq": { "type": "integer" }, "nullPopFq": { "type": "integer" } } } } }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } } } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "uri1": { "type": "string" }, "uri2": { "type": "string" }, "score": { "type": "integer" } } } } } }, "categoryAggr": { "type": "object", "properties": { "warning": { "type": "string" }, "usedResults": { "type": "integer" }, "totalResults": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "example": "dmoz/Business/Investing/Stocks_and_Bonds" }, "score": { "type": "double", "example": 0.123 } } } } } }, "recentActivityArticles": { "type": "object", "properties": { "currTime": { "type": "string" }, "activity": { "type": "array", "items": { "type": "object", "properties": {} } } } } } } ```