Source: https://eventregistry.org/documentation?tab=query_language

# Search query language

## Simple queries

For simple queries, you can specify parameters such as keyword, conceptUri, categoryUri, sourceUri, etc. directly in the query parameters of the API call. This allows you to specify queries where multiple different conditions have to be met.

To control the `keyword` parameter is matched against articles — as an exact phrase, a Boolean expression, or a relevance-based search — see the section.

```

            {
    "conceptUri": "http://en.wikipedia.org/wiki/OpenAI",
    "conceptUri": "http://en.wikipedia.org/wiki/Amazon_(company)",
    "keyword": "AWS",
    "categoryUri": "news/Business",
    "sourceGroupUri": "business/top100",
    "apiKey": "YOUR_API_KEY"
}
```

Making a POST request with a JSON body from the example above would return you the list of articles that mention both companies, keyword "AWS", are categorized into Business category and are published by top 100 business news sources. As you can see, each added condition, additionally restrains the set of returned articles.

## Advanced query language

For many users, however, a more complex way of specifying a query is required - such that contains a combination of , and conditions. 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 MongoDB. Using this language you can specify queries that are not possible to express directly using parameters `keyword`, `conceptUri`, `categoryUri`, etc.

When using the advanced query language, you specify the search conditions using a `query` parameter which contains a JSON object. The details of what the JSON object should look like are described in the sections below.

**Note:** When using the `query` parameter, you are not allowed to also specify regular parameters such as `keyword`, `conceptUri`, `sourceUri`, etc. as in the first example. Using a query like that would return an error since it is not clear how the regular parameters should be combined with the conditions specified in the `query` parameter.

```

            {
    "query": {          # JSON object matching the ComplexArticleQuery grammar below
        "$query": {
            ...
        }
    },
    "apiKey": "YOUR_API_KEY"
}
```

## Query grammar

```

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

    "$filter": null | {
        "dataType": null | "news" | "blog" | "pr" | ["news", ...]
        "isDuplicate": null | "keepAll" | "skipDuplicates" | "keepOnlyDuplicates",
        "hasEvent": null | "keepAll" | "skipArticlesWithoutEvent" | "keepOnlyArticlesWithoutEvent",
        "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])
    }
}

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

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

BaseQuery ::=
{
    "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, ... ]},

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

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

    "dateStart": null | string,
    "dateEnd": null | string,
    "dateMention": null | [string, ... ],

    "keywordLoc": null | "body" | "title" | "title,body",
    "keywordSearchMode": null | "simple" | "exact" | "phrase",

    "minArticlesInEvent": null | int,
    "maxArticlesInEvent": null | int,

    "$not": null | CombinedQuery | BaseQuery
}
```

## Explanation

Each complex article query needs to be a JSON object that has a `$query` key and optionally a `$filter` 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 (`$and`) or (`$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 concepts, keywords, categories, sources, authors, 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. A `BaseQuery` containing only the `$not` key is *not* a valid query (since it has no positive conditions to exclude results from).

The complex article query can also have a `$filter` object. It can contain information about which data types to search for — the `dataType` property — which can be a simple string value or an array of values. You can also specify what should happen with articles that are (a) duplicates of other articles, (b) were later copied by other sources, and (c) are describing an event. Finally, you can also set the `startSourceRankPercentile` and `endSourceRankPercentile` filters to limit the results to certain subsets of news sources based on global Alexa ranking. By setting `startSourceRankPercentile` to 0 and `endSourceRankPercentile` to 20 you can limit the results to top-ranking news sources so that the resulting number of articles will be approximately 20% of all content that would be received without the filter.

## Examples

A query that returns articles that mention the concept AI or the phrases "deep learning" or "machine learning", while excluding results that mention "data mining" in the article title. The results should also have a positive sentiment (>0.2) and should not be duplicates of other articles.

```

            {
    "query": {
        "$query": {
            "$or": [
                { "conceptUri": "http://en.wikipedia.org/wiki/Artificial_Intelligence" },
                {
                    "keyword": {
                        "$or": [ "deep learning", "machine learning" ]
                    }
                }
            ],
            "$not": {
                "keyword": "data mining",
                "keywordLoc": "title"
            }
        },
        "$filter": {
            "minSentiment": 0.2,
            "isDuplicate": "skipDuplicates"
        }
    },
    "apiKey": "YOUR_API_KEY"
}
```

A query that returns politics-related articles about both Donald Trump and Hillary Clinton, or business-related news that mention Elon Musk:

```

            {
    "query": {
        "$query": {
            "$or": [
                {
                    "conceptUri": {
                        "$and": [
                            "http://en.wikipedia.org/wiki/Donald_Trump",
                            "http://en.wikipedia.org/wiki/Hillary_Rodham_Clinton"
                        ]
                    },
                    "categoryUri": "dmoz/Society/Politics"
                },
                {
                    "conceptUri": "http://en.wikipedia.org/wiki/Elon_Musk",
                    "categoryUri": "dmoz/Business"
                }
            ]
        }
    },
    "apiKey": "YOUR_API_KEY"
}
```