Searching for mentions

In Event Registry we can identify in the articles individual sentences that express an interesting relation of a certain type. Each such relation that we identify we call a mention and we provide several properties for each mention. A subset of the provided properties can be seen in the following example:

{
    "uri": "7536951383-0",
    # sentence identified in an article that is expressing a relation
    "sentence": "Swedish Orphan Biovitrum to acquire CTI BioPharma in a deal valued at $1.7 billion.",
    "sentenceIndex": 0,
    # type of the detected relation
    "eventType": {
        "uri": "et/business/acquisitions-mergers/acquisition/approved",
        "label": "et/business/acquisitions-mergers/acquisition/approved"
    },
    "lang": "eng",
    "dateTime": "2023-05-10T07:52:00Z",
    "articleUri": "7536951383",
    # URL of the article in which we found the sentence
    "articleUrl": "https://www.marketwatch.com/story/swedish-orphan-biovitrum-to-acquire-cti-biopharma-in-a-deal-valued-at-1-7-billion-70a7b809",
    "articleTitle": "Swedish Orphan Biovitrum to acquire CTI BioPharma in a deal valued at $1.7 billion",
    # sentiment
    "articleSentiment": 0.5450980392156863,
    "sentenceSentiment": 0.4431372549019608,
    "eventTypeSentiment": 0.589994161,
    "isDuplicate": false,
    # how factual is the sentence?
    "factLevel": "fact",
    "source": {
        "uri": "marketwatch.com",
        "title": "MarketWatch"
    },
    # mentioned entities
    "slots": [
        {
            "uri": "http://en.wikipedia.org/wiki/Swedish_Orphan_Biovitrum",
            "label": "Swedish Orphan Biovitrum",
            "text": "Swedish Orphan Biovitrum",
            "type": "org",
            "synonyms": {
                "isin": [
                    "US8703211065"
                ]
            }
        },
        ...
    ]
}

The complete list of properties that can be returned for each mention can be found in the Mention data model.

In order to search for mentions in Event Registry, we provide two classes - QueryMentions and QueryMentionsIter. Both classes can be used to find mentions using a set of various types of search conditions.

The class QueryMentionsIter is used to obtain an iterator, that makes it very easy to iterate over all mentions that match the search conditions. Alternatively, the QueryMentions class can be used to obtain a broader range of information about the matching mentions in various forms. In case of QueryMentions, the results can be not only the list of mentions but also a time distribution when mentions were published, distribution of top news sources that wrote the matching articles, top concepts mentioned in the mentions, etc.

QueryMentionsIter

Example of usage

Before describing the class, here is an example of use that prints the list of 100 latest mentions related to changes of stock prices for companies that are in the transportation business. The mentions should also be from the articles that were published during April 2023.

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)
iter = QueryMentionsIter(
    eventTypeUri = "et/business/stock-prices/stock-price",
    industryUri= "sectors/Transportation",
    dateStart = "2023-04-01",
    dateEnd = "2023-04-30"
)

# iterate over first 100 mentions. Increase maxItems or remove it completely to get more/all results
for m in iter.execQuery(er, sortBy = "date", maxItems = 100):
    print(m)

Constructor

QueryMentionsIter is a derived class from QueryMentions. It's constructor can accept the following arguments:

QueryMentionsIter(
    eventTypeUri = None,
    keywords = None,
    conceptUri = None,
    categoryUri = None,
    sourceUri = None,
    sourceLocationUri = None,
    sourceGroupUri = None,
    industryUri = None,
    sdgUri = None,
    sasbUri = None,
    esgUri = None,
    locationUri = None,
    lang = None,
    dateStart = None,
    dateEnd = None,

    ignoreEventTypeUri = None,
    ignoreKeywords = None,
    ignoreConceptUri = None,
    ignoreCategoryUri = None,
    ignoreSourceUri = None,
    ignoreSourceLocationUri = None,
    ignoreSourceGroupUri = None,
    ignoreIndustryUri = None,
    ignoreSdgUri = None,
    ignoreSasbUri = None,
    ignoreEsgUri = None,
    ignoreLocationUri = None,
    ignoreLang = None,
    showDuplicates = False,
    startSourceRankPercentile = 0,
    endSourceRankPercentile = 100,
    minSentiment = -1,
    maxSentiment = 1,
    dataType = "news",
    requestedResult = None)

The parameters for which you don't specify a value will be ignored. In order for the query to be valid (=it can be executed by Event Registry), it has to have at least one positive condition (conditions that start with ignore* do not count as positive conditions). The meaning of the arguments is the following

• eventTypeUri: find mentions that express a certain type of a relation. A single event type can be provided as a string, multiple event types can be provided as a list of strings. Since each mention can only have one event type, if multiple event types are provided, an or condition is used between them.

• keywords: find mentions where the sentence contains the specified keywords. A single keyword/phrase can be provided as a string, multiple keywords/phrases can be provided as a list of strings. Use QueryItems.AND() if all provided keywords/phrases should be mentioned, or QueryItems.OR() if any of the keywords/phrases should be mentioned.

• conceptUri: find mentions where the sentence mentions the concept with concept URI. A single concept URI can be provided as a string, multiple concept URIs can be provided as a list of strings. Use QueryItems.AND() if all provided concepts should be mentioned, or QueryItems.OR() if any of the concepts should be mentioned. To obtain a concept URI based on a (partial) concept label use EventRegistry.getConceptUri().

• categoryUri: find mentions that are assigned to a particular category. A single category URI can be provided as a string, multiple category URIs can be provided as a list of strings. Use QueryItems.AND() if all provided categories should be mentioned, or QueryItems.OR() if any of the categories should be mentioned. A category URI can be obtained based on a (partial) category name using EventRegistry.getCategoryUri().

• sourceUri: find mentions where the sentence is from an article that was written by a news source sourceUri. If multiple sources should be considered, use QueryItems.OR() to provide a list of sources. Source URI for a given (partial) news source name can be obtained using EventRegistry.getNewsSourceUri().

• sourceLocationUri: find mentions where the sentence is from an article that was written by news sources located at the given geographic location. If multiple source locations are provided, then put them into a list inside QueryItems.OR(). Location URI can either be a city or a country. Location URI for a given (partial) name can be obtained using EventRegistry.getLocationUri().

• sourceGroupUri: find mentions where the sentence is from an article that was written by a news source that is assigned to the specified source group(s). If multiple source groups are provided, then put them into a list inside QueryItems.OR(). Source group URI for a given name can be obtained using EventRegistry.getSourceGroupUri().

• industryUri: find mentions that relate to companies in a certain industry. If multiple industries should be considered, use QueryItems.OR() to provide multiple industries. Industry URI for a given industry name can be obtained using EventRegistry.suggestIndustries().

• sdgUri: find mentions that are about event types that are associated with a particular SDG. If multiple SDGs should be considered, use QueryItems.OR() to provide multiple SDGs. SDG URI for a given SDG can be obtained using EventRegistry.getSdgUris().

• sasbUri: find mentions that are about event types that are associated with a particular SASB category. If multiple SASB categories should be considered, use QueryItems.OR() to provide multiple SASB categories. SASB URI for a given SASB category can be obtained using EventRegistry.getSasbUris().

• esgUri: find mentions that are about event types that are associated with a particular ESG category. If multiple ESGs should be considered, use QueryItems.OR() to provide multiple ESGs. Possible values are esg/environment, esg/social, esg/governance.

• locationUri: find mentions that describe an event that occurred at a particular location. A mention will be associated with that location if it's mentioned in the dateline of the article, where the sentence appears. Location URI can either be a city or a country. If multiple locations are provided, resulting events have to match any of the locations. Location URI for a given name can be obtained using EventRegistry.getLocationUri().

• lang: find mentions that are written in the specified language. If more than one language is specified, resulting mentions have to be written in any of the languages. Specify the value as string or list in QueryItems.OR(). See supported languages for the list of language codes to use.

• dateStart: find mentions that were written on or after dateStart. The date should be provided in YYYY-MM-DD format, datetime.time or datetime.datetime.

• dateEnd: find mentions that occurred before or on dateEnd. The date should be provided in YYYY-MM-DD format, datetime.time or datetime.datetime.

• ignoreEventTypeUri: ignore mentions that are associated with certain event types. Specify the value as string or list in QueryItems.OR().

• ignoreKeywords: ignore mentions where the sentence mentions the provided keywords. Specify the value as string or list in QueryItems.OR() or QueryItems.AND().

• ignoreConceptUri: ignore mentions that are associated with the provided concepts. Specify the value as string or list in QueryItems.OR() or QueryItems.AND().

• ignoreCategoryUri: ignore mentions that are associated with the provided set of categories. Specify the value as string or list in QueryItems.OR() or QueryItems.AND().

• ignoreSourceUri: ignore mentions that contain sentences from articles from certain news sources. Specify the value as string or list in QueryItems.OR().

• ignoreSourceLocationUri: ignore mentions that contain sentences from articles which have been written by news sources located at the specified geographic location(s). Specify the value as string or list in QueryItems.OR().

• ignoreSourceGroupUri: ignore mentions that contain sentences from articles which have been written by news sources assigned to the specified source groups. Specify the value as string or list in QueryItems.OR().

• ignoreIndustryUri: ignore mentions where the sentence mentions a company from a certain industry. Specify the value as string or list in QueryItems.OR().

• ignoreSdgUri: ignore mentions where the sentence contains an event type belonging to a certain SDG. Specify the value as string or list in QueryItems.OR().

• ignoreSasbUri: ignore mentions where the sentence contains an event type belonging to a certain SASB category. Specify the value as string or list in QueryItems.OR().

• ignoreEsgUri: ignore mentions where the sentence contains an event type belonging to a certain ESG. Specify the value as string or list in QueryItems.OR().

• showDuplicates: should we show return duplicate mentions?

• startSourceRankPercentile and endSourceRankPercentile: The parameters can be used to filter the returned mentions to include only those that are from news sources that are of a certain ranking. Sources are ranked according to the global Alexa site ranking. By setting startSourceRankPercentile to 0 and endSourceRankPercentile to 20 would, for example, return only articles from top-ranked news sources that would amount to about approximately 20% of all matching content. Note: 20 percentiles do not represent 20% of all top sources. The value is used to identify the subset of news sources that generate approximately 20% of our collected news content.

• minSentiment: what should be the minimum sentiment value of the sentence? The range is from -1 (very negative) to 1 (very positive). NOTE: By setting a non-default value, the results will automatically be filtered to the English language only, since sentiment can only be computed for the English language.

• maxSentiment: what should be the maximum sentiment value of the sentence? The range is from -1 (very negative) to 1 (very positive). NOTE: By setting a non-default value, the results will automatically be filtered to the English language only, since sentiment can only be computed for the English language.

• minSentenceIndex: what should be the minimum index of the sentence in the article in order to be included in the results.

• maxSentenceIndex: what should be the maximum index of the sentence in the article in order to be included in the results.

• requestedResult: the information that should be returned as the result of the query. If None then by default we set RequestMentionsInfo().

When two or more parameters are specified in the constructor, the results will be computed in a way so that all conditions will be met. For example, if you specify QueryMentionsIter(keywords = "ChatGPT", conceptUri = "http://en.wikipedia.org/wiki/OpenAI") then all the resulting mentions will mention phrase ChatGPT and will be annotated with concept OpenAI.

Creating QueryMentionsIter using static methods

The QueryMentionsIter class can also be initialized in two other ways:

QueryMentionsIter.initWithMentionUriList(uriList) is a static method that can be used to specify the set of mention URIs that you want to use as a result. In this case, no query conditions are used and this set is used as the resulting set. All the return information about the mentions will be based on this set of mentions.

QueryMentionsIter.initWithComplexQuery(query) is another static method that can be used to create a complex query based on the advanced query language. You can call the method by providing an instance of ComplexMentionQuery class. Alternatively, you can also call the method with a python dictionary or a string containing the JSON object matching the language (see the examples).

Methods

The class has two main methods: count() and execQuery().

count(er) simply returns the number of mentions that match the specified conditions. er is the instance of EventRegistry class.

execQuery method has the following format:

execQuery(er,
    sortBy = "rel",
    sortByAsc = False,
    returnInfo = ReturnInfo(),
    maxItems = -1)

• er: an instance of the EventRegistry class.
• sortBy: sets the order in which the resulting mentions are sorted, before returning. Options: date (publishing date), cosSim (closeness to the centroid of the associated event), rel (relevance to the query), 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).
• sortByAsc: should the results be sorted in ascending order.
• returnInfo: sets the properties of various types of data that is returned (sources, ...). See details.
• maxItems: max number of mentions to return by the iterator. Use the default (-1) to simply return all matching mentions. By setting the value to a positive number, the iterator will stop downloading mentions once the number is reached.

QueryMentions

Example of usage

Before describing the QueryMentions() class and the details that can be requested, let's look at an example of it's usage:

from eventregistry import *
er = EventRegistry(apiKey = YOUR_API_KEY)
q = QueryMentions(
    # find sentences that mention the company Apple
    conceptUri = er.getConceptUri("Apple"),
    # find the relations related to labor issues
    eventTypeUri = "et/business/labor-issues")
# get the first 100 mentions matching these conditions
ret1 = er.execQuery(q)

# get the time distribution of mentions over all the time period
q.setRequestedResult(RequestMentionsTimeAggr())
ret2 = er.execQuery(q)

The returned information about mentions in ret1 follows the Mention data model.

Constructor

QueryMentions constructor accepts the same arguments as QueryMentionsIter

Creating QueryMentions using static methods

The QueryMentions class can also be initialized in two other ways:

QueryMentions.initWithMentionUriList() is a static method that can be used to specify the set of mention URIs that you want to use as the result. In this case, no query conditions are used and this set is used as the resulting set. All the return information about the mentions will be based on the provided set of mention URIs.

QueryMentions.initWithComplexQuery() is another static method that can be used to create a complex query based on the advanced query language. You can call the method by providing an instance of ComplexMentionQuery class. Alternatively, you can also call the method with a python dictionary or a string containing the JSON object matching the language (see the examples).

Returned information

When executing the query, there will be a set of mentions that will match the specified criteria. What information about these mentions is to be returned however still needs to be determined. Do you want to get the details about these mentions? Do you want instead to see the timeline distribution of the results? Maybe you want to see the top concepts that appear in the results?

What information about the results you want to retrieve is set by calling the setRequestedResult() method. The setRequestedResult() accepts as an argument an instance that has a base class RequestMentions. Below are the classes that can be specified in the setRequestedResult() calls:

RequestMentionsInfo

RequestMentionsInfo(page = 1,
    count = 100,
    sortBy = "date", sortByAsc = False,
    returnInfo = ReturnInfo())

RequestMentionsInfo will provide detailed information about the resulting mentions.

• page: determines the page of the results to return (starting from 1).
• count: determines the number of mentions to return. Max mentions that can be returned per call is 100.
• sortBy: sets the order in which the resulting mentions are sorted, before returning. Options: date (publishing date), rel (relevance to the query), sourceImportance (manually curated score of source importance - high value, high importance), sourceImportanceRank (reverse of sourceImportance), sourceAlexaGlobalRank (global rank of the news source), or sourceAlexaCountryRank (country rank of the news source).
• sortByAsc: should the results be sorted in ascending order.
• returnInfo: sets the properties of various types of data that is returned (mentions, sources, concepts, ...). See details.

RequestMentionsUriWgtList

RequestMentionsUriWgtList(page = 1,
    count = 10000,
    sortBy = "fq", sortByAsc = False)

RequestMentionsUriWgtList returns a simple list of mention URIs and their weight (that is used for sorting the results) in format {uri}:{wgt} that match criteria. Useful if you wish to obtain the full list of mention URIs in a single query.

• page: determines the page of the results to return (starting from 1).
• count: determines the number of results to return in a single call. Max results per call can be 50.000.
• sortBy: sets the order in which the resulting mentions are sorted, before returning. Options: date (publishing date), rel (relevance to the query), sourceImportance (manually curated score of source importance - high value, high importance), sourceImportanceRank (reverse of sourceImportance), sourceAlexaGlobalRank (global rank of the news source), or sourceAlexaCountryRank (country rank of the news source).
• sortByAsc: should the results be sorted in ascending order

RequestMentionsTimeAggr

RequestMentionsTimeAggr()

RequestMentionsTimeAggr returns information about how the mentions are distributed over time. The constructor does not accept any additional parameters.

RequestMentionsConceptAggr

RequestMentionsConceptAggr(conceptCount=25,
    conceptCountPerType = None,
    conceptScoring = "importance",
    mentionsSampleSize = 10000,
    returnInfo = ReturnInfo())

RequestMentionsConceptAggr returns a list of top concepts that are mentioned the most in the resulting mentions.

• conceptCount: number of top concepts to return (at most 500).
• conceptCountPerType: if you wish to limit the number of top concepts per type (person, org, loc, wiki) then set this to some number. If you want to get an equal number of concepts for each type then set conceptCountPerType to conceptCount/4 (since there are 4 concept types).
• conceptScoring: how should the top concepts be computed. Possible values are "importance" (takes into account how frequently a concept is mentioned and how relevant it is in the mention); "frequency" (ranks the concepts simply by how frequently the concept is mentioned in the results); "uniqueness" (computes what are the top concepts that are frequently mentioned in the results of your search query but less frequently mentioned in the news in general).
• mentionsSampleSize: on what sample of results should the aggregate be computed (at most 20.000).
• returnInfo: what details about the concepts should be included in the returned information.

RequestMentionsSourceAggr

RequestMentionsSourceAggr(sourceCount = 50,
    returnInfo = ReturnInfo())

RequestMentionsSourceAggr provides a list of top news sources that have written the most articles from which we have extracted the mentions in the results.

• sourceCount: the number of top sources to return
• returnInfo: what details about the sources should be included in the returned information.

RequestMentionsCategoryAggr

RequestMentionsCategoryAggr(mentionsSampleSize = 20000,
    returnInfo = ReturnInfo())

RequestMentionsCategoryAggr returns information about what are the top categories (topics) associated with the articles, from which we have extracted the resulting mentions.

• mentionsSampleSize: on what sample of results should the aggregate be computed (at most 50.000)
• returnInfo: what details about the categories should be included in the returned information

RequestMentionsKeywordAggr

RequestMentionsKeywordAggr(mentionsSampleSize = 500)

RequestMentionsKeywordAggr returns the keywords that summarize the best the resulting mentions.

• mentionsSampleSize: the sample size of mentions on which to compute the keywords. Maximum 20.000.

RequestMentionsConceptGraph

RequestMentionsConceptGraph(conceptCount = 25,
    linkCount = 50,
    mentionsSampleSize = 10000,
    skipQueryConcepts = True,
    returnInfo = ReturnInfo())

RequestMentionsConceptGraph returns a graph of concepts. Concepts are connected if they frequently occur in the same mentions.

• conceptCount: number of top concepts (nodes) to return
• linkCount: number of edges in the graph
• mentionsSampleSize: on what sample of mentions should the graph be computed
• skipQueryConcepts: should the concepts that were used in the search be ignored from the results
• returnInfo: the details about the types of returned data to include. See details.

RequestMentionsRecentActivity

RequestMentionsRecentActivity(maxMentionCount = 100,
    updatesAfterTm = None,
    updatesAfterMinsAgo = None,
    updatesUntilTm = None,
    updatesUntilMinsAgo = None,
    mandatorySourceLocation = False,
    returnInfo = ReturnInfo())

RequestMentionsRecentActivity is to be used to get the mentions that match the particular set of search conditions and were added to Event Registry after the specified time.

• maxMentionCount: maximum number of mentions to return (max 2000). If more than 100 mentions are requested then the correspondingly higher number of tokens will be used with a single call
• updatesAfterTm: starting time after which the resulting mentions should be imported into Event Registry. Specify a datetime instance or a string in format 'YYYY-MM-DDTHH:MM:SS.SSSS' that represents time in ISO format. When making consecutive calls, you can use value currTime returned from a previous call.
• updatesAfterMinsAgo: instead of specifying the updatesAfterTm you can also simply ask to get content that was published after some minutes ago. You can use this if you are calling the API at regular time intervals.
• updatesUntilTm: ending time before which the resulting mentions should be imported into Event Registry. Specify a datetime instance or a string in format 'YYYY-MM-DDTHH:MM:SS.SSSS' that represents time in ISO format.
• updatesUntilMinsAgo: instead of specifying the updatesUntilTm you can also simply ask to get content that was published before this number of minutes ago.
• mandatorySourceLocation: should we return just the mentions that are from articles that have a known source location?
• returnInfo: the details about the types of returned data to include. See details.

Advanced query language

For many users, simply providing a list of concepts, keywords, sources etc. is not sufficient and a more complex way of specifying a query is required. For such purposes, we provide a query language where conditions can be specified in a particular JSON object, that resembles the query language used by the MongoDB. The grammar for the language is as follows:

ComplexMentionQuery ::=
{
    "$query": CombinedQuery | BaseQuery,

    "$filter": null | {
        "showDuplicates": null | true | false,
        "startSourceRankPercentile": null | 0 | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90,
        "endSourceRankPercentile": null | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100,
        "minSentiment": null | float([-1,1]),
        "maxSentiment": null | float([-1,1]),
        "minSentenceIndex": null | int,
        "maxSentenceIndex": null | int,
    }
}

CombinedQuery ::=
{
    "$or": [ CombinedQuery | BaseQuery, ... ],
    "$not": null | CombinedQuery | BaseQuery
}

CombinedQuery ::=
{
    "$and": [ CombinedQuery | BaseQuery, ... ],
    "$not": null | CombinedQuery | BaseQuery
}

BaseQuery ::=
{
    "eventTypeUri": null | string | { "$or": [ string, ... ]},
    "conceptUri": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},
    "keyword": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},
    "categoryUri": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},
    "lang": null | string | { "$or": [ string, ... ]} | { "$and": [ string, ... ]},

    "sourceUri": null | string | { "$or": [ string, ... ]},
    "sourceLocationUri": null | string | { "$or": [ string, ... ]},
    "sourceGroupUri": null | string | { "$or": [ string, ... ]},

    "industryUri": null | string | { "$or": [ string, ... ]},
    "sdgUri": null | string | { "$or": [ string, ... ]},
    "esgUri": null | string | { "$or": [ string, ... ]},
    "sasbUri": null | string | { "$or": [ string, ... ]},

    "locationUri": null | string | { "$or": [ string, ... ]},

    "dateStart": null | string,
    "dateEnd": null | string,

    "$not": null | CombinedQuery | BaseQuery
}

Explanation

Each complex query needs to be a JSON object that has a $query key. The $query key must contain another JSON object that should be parsable as a CombinedQuery or a BaseQuery. A CombinedQuery can be used to specify a list of conditions, where all ($and) or any ($or) conditions should hold. The CombinedQuery can also contain a $not key containing another CombinedQuery or BaseQuery defining the results that should be excluded from the results computed by the $and or $or conditions.

The BaseQuery represents a JSON object with actual conditions to search for. These (positive) conditions can include event types, concepts, keywords, categories, sources, etc. to search for. If multiple conditions are specified, for example, a conceptUri as well as a sourceUri, then results will have to match all the conditions. The BaseQuery can also contain the $not key specifying results to exclude from the results matching the positive conditions of the BaseQuery. A BaseQuery containing only the $not key is not a valid query (since it has no positive conditions to exclude results from).

The root node of the complex query can also have a $filter object. It can contain details on how the resulting mentions should be additionally filtered. You can determine what to do with the duplicates (mentions that are representing the same relation, but using a slightly different language), what should be the sentiment of the returned mentions, and where in the article should the resulting mentions be extracted from (by specifying the minimum and maximum sentence index).

Using this language you can specify queries that are not possible to express using the constructor parameters in QueryMentions or QueryMentionsIter.

Examples

Here are some examples of queries and what they would return:

Example 1: A query that would return the list of mentions that are related to products and services and also mention either Microsoft, OpenAI or Google. Additionally, the returned mentions should contain sentences that are either from the title of the article or the first sentence.

{
    "$query": {
        "$and": [
            {
                "eventTypeUri": "et/business/products-services",
            },
            {
                "conceptUri": {
                    "$or": [
                        "http://en.wikipedia.org/wiki/Microsoft",
                        "http://en.wikipedia.org/wiki/OpenAI",
                        "http://en.wikipedia.org/wiki/Google"
                    ]
                }
            }
        ]
    },
    "$filter": {
        "maxSentenceIndex": 1
    }
}

Example 2: A query that would return the list of mentions from April 2023 related to stock price and mention companies that are in the transportation business:

{
    "$query": {
        "eventTypeUri": "et/business/stock-prices/stock-price",
        "industryUri": "sectors/Transportation",
        "dateStart": "2023-04-01",
        "dateEnd": "2023-04-30"
    }
}

Depending on your preference, you can build such JSONs for these complex queries yourself or you can use the associated classes such as ComplexMentionQuery(), CombinedQuery() and BaseQuery(). Below is an example where we search for mentions that express relations related to products and services and also mention either Microsoft, OpenAI or Google:

er = EventRegistry()
productsUri = er.getEventTypeUri("services")
microsoftUri = er.getConceptUri("Microsoft")
openaiUri = er.getConceptUri("OpenAI")
googleUri = er.getConceptUri("Google")
cq = ComplexArticleQuery(
    query = CombinedQuery.AND(
        [
            BaseQuery(eventTypeUri = productsUri),
            BaseQuery(conceptUri =  QueryItems.OR([microsoftUri, openaiUri, googleUri]))
        ]
    )
q = QueryMentions.initWithComplexQuery(cq)
res = er.execQuery(q)

If you've built the Python dictionary with the query yourself, you can also use like this:

er = EventRegistry()
q = QueryMentions.initWithComplexQuery({ '$query': { ... } })
res = er.execQuery(q)

In this case, you need to make sure you're providing valid query parameters in the provided JSON object.

Similarly, if you would like to use the QueryMentionsIter to quickly iterate over the results, you can also use the initWithComplexQuery method like this:

er = EventRegistry()
iter = QueryMentionsIter.initWithComplexQuery({ '$query': { ... } })
for mention in iter.execQuery(er):
    print(mention)