openapi: 3.0.0 info: version: 8.1.0 title: Event Registry REST API description: | REST API of Event Registry / NewsAPI.ai. **Changes in 8.1.0** - the sentiment filters are named `minSentiment` and `maxSentiment` (the previously documented `minSentimentArticle`, `maxSentimentArticle`, `minSentimentEvent` and `maxSentimentEvent` were never read by the API and were silently ignored), - added the endpoint for searching mentions of event types (`/api/v1/eventType/mention/getMentions`) and the related `suggestEventTypes`, `suggestIndustries`, `sdg/getItems`, `sasb/getItems` and `esg/getItems` endpoints, - added the `keywordSearchMode`, `ignoreKeywordSearchMode`, `sourceOper`, `sourceGroupOper`, `authorOper` and `hasDuplicateFilter` parameters, - updated the lists of the supported `resultType` and sorting values, - `getArticlesForTopicPage` and `getEventsForTopicPage` document the `topicPage`, `onlyAfterTm` and `maxDaysBack` parameters, - `getEventForText` is documented as the synchronous call that it is, - added the missing `include*` flags and fixed some of the documented default values. license: name: MIT servers: - url: 'https://eventregistry.org' # # ANALYTICS endpoints # tags: - name: Text Analytics description: https://analytics.eventregistry.org/api/v1 - name: Articles description: https://eventregistry.org - name: Events description: https://eventregistry.org - name: Mentions description: https://eventregistry.org - name: Autosuggest description: https://eventregistry.org - name: Other description: https://eventregistry.org paths: /annotate: get: tags: - Text Analytics summary: identify people, locations, organizations and things mentioned in the document description: | The endpoint is able to semantically annotate the provided document. The semantic annotation includes identification of people, locations, organizations and things mentioned in the document. The annotations all have a unique URI that is a url to the Wikipedia page for the concept. operationId: annotate servers: - url: 'https://analytics.eventregistry.org/api/v1' parameters: - $ref: '#/components/parameters/apiKey' - name: text in: query required: true description: >- Define a text that you'll like to see annotated. schema: type: string - name: minLinkFrequency in: query description: >- The minimum number of times the phrase should appear in the link in order for use to use it as a candidate for the annotation. schema: type: integer default: 3 - name: minLinkRelFrequency in: query description: >- Consider the candidate only if the given text points to the candidate with probability above this value. Value between 0 and 1. schema: type: number format: double default: 0.01 - name: nWordsToIgnoreFromList in: query description: >- Use this setting to ignore common phrases. If a phrase consists entirely of very frequent words, it will be ignore. A word is considered frequent if it is one of the most frequent words (in terms of document frequency) in the Wikipedia of the corresponding language. If 0 it will disable this heuristic. schema: type: integer default: 200 - name: minPMentionGivenPhrase in: query description: >- 'Probability that the given phrase, if found on Wikipedia, is annotated with the concept. If non-zero, it can help to remove the common words.' schema: type: number format: double default: 0.03 - name: pageRankSqThreshold in: query description: >- 'Probability that the given phrase, if found on Wikipedia, is annotated with the concept. If non-zero, it can help to remove the common words.' schema: type: number format: double default: 0.95 - name: applyPageRankSqThreshold in: query description: >- 'Apply pageRankSqThreshold to the requested response.' schema: type: boolean responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/Annotation' /categorize: get: tags: - Text Analytics summary: Categorize the content into a set of predefined categories description: | The categorization of your content into a predefined set of categories. The `dmoz` taxonomy contains over 5000 categories and can only be used for documents in English languge. The `news` taxonomy contains only 8 top level categories commonly used to categorize the news content, but can be applied for any language. The categorization into both taxonomies can work well only on documents of decent size (like news articles). operationId: categorize servers: - url: 'https://analytics.eventregistry.org/api/v1' parameters: - $ref: '#/components/parameters/apiKey' - name: text in: query required: true description: >- Define a text that you'll like to see categorized. schema: type: string - name: taxonomy in: query required: true description: >- Define the taxonomy in which you'll want to categorize the selected text schema: type: string enum: - dmoz - news - iptc responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/Categorization' /semanticSimilarity: get: tags: - Text Analytics summary: Compute semantic similarity of two documents, potentially in different languages description: This API endpoint allows you to compare two documents, potentially in different languages, and compute the semantic similarity between them. operationId: semanticSimilarity servers: - url: 'https://analytics.eventregistry.org/api/v1' parameters: - $ref: '#/components/parameters/apiKey' - name: text1 in: query required: true description: >- The first text that'll be used in the comparison. schema: type: string - name: text2 in: query required: true description: >- The second text that'll be used in the comparison. schema: type: string responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/Similarity' /sentiment: get: tags: - Text Analytics summary: Vocabulary based sentiment detection description: | Compute the sentiment using a vocabulary based approach. The sentiment classification only works for English language. operationId: sentiment servers: - url: 'https://analytics.eventregistry.org/api/v1' parameters: - $ref: '#/components/parameters/apiKey' - name: text in: query required: true description: >- The text that will be used to calculate sentiment. schema: type: string - name: sentences in: query description: >- Number of sentences on which to compute the sentiment. schema: type: integer default: 10 responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/Sentiment' /sentimentRNN: get: tags: - Text Analytics summary: Neural networks based approach to sentiment detection description: | Compute the sentiment using a neural network model. The sentiment classification only works for English language. operationId: sentimentRNN servers: - url: 'https://analytics.eventregistry.org/api/v1' parameters: - $ref: '#/components/parameters/apiKey' - name: text in: query required: true description: >- The text that will be used to calculate sentiment. schema: type: string - name: sentences in: query description: >- Number of sentences on which to compute the sentiment. schema: type: integer default: 10 responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/Sentiment' /extractArticleInfo: get: tags: - Text Analytics summary: Extract article information (title, body, authors, ...) from article URL operationId: extractArticleInfo servers: - url: 'https://analytics.eventregistry.org/api/v1' parameters: - $ref: '#/components/parameters/apiKey' - name: url in: query required: true description: >- Define an article URL, that'll be used to extract the article information. schema: type: string responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/ExtractArticleInfo' /detectLanguage: get: tags: - Text Analytics summary: Detect the language of the input text operationId: detectLanguage servers: - url: 'https://analytics.eventregistry.org/api/v1' parameters: - $ref: '#/components/parameters/apiKey' - name: text in: query required: true description: >- Define a text that'll be used to detect the language in which it's written. schema: type: string responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/DetectLanguage' # # ARTICLE endpoint # /api/v1/article/getArticles: get: tags: - Articles summary: Obtain articles that match one or more search conditions description: | Identify the news articles that match a certain set of search criteria. The search conditions can be specified by setting the `query` parameter, or by specifying one or multiple search parameters, such as `keyword`, `conceptUri`, `sourceUri`, etc. 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 (when `resultType = articles`) or one of the various aggregates (summaries) of the matching articles. In case of `resultType = timeAggr`, for example, the returned data will contain information *when* were the articles matching the search criteria published. Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-articles-get-articles)**. Details about the returned information is available on the **[data model page](https://github.com/EventRegistry/event-registry-python/wiki/Data-models)**. operationId: getArticles parameters: - $ref: '#/components/parameters/apiKey' - name: resultType in: query description: >- Define what kind of results of the search you would like to get. Default value: articles. schema: default: articles type: string enum: - articles - uriWgtList - langAggr - timeAggr - sourceAggr - sourceExAggr - authorAggr - keywordAggr - locAggr - conceptAggr - conceptGraph - conceptTrends - categoryAggr - dateMentionAggr - sentimentAggr - recentActivityArticles - $ref: '#/components/parameters/articlesPage' - $ref: '#/components/parameters/articlesCount' - $ref: '#/components/parameters/articlesSortBy' - $ref: '#/components/parameters/articlesSortByAsc' - $ref: '#/components/parameters/articleBodyLen' - $ref: '#/components/parameters/dataType' # filters - $ref: '#/components/parameters/queryArticles' - $ref: '#/components/parameters/keywordArticle' - $ref: '#/components/parameters/conceptUriArticle' - $ref: '#/components/parameters/categoryUriArticle' - $ref: '#/components/parameters/sourceUriArticle' - $ref: '#/components/parameters/sourceLocationUriArticle' - $ref: '#/components/parameters/sourceGroupUriArticle' - $ref: '#/components/parameters/authorUriArticle' - $ref: '#/components/parameters/locationUriArticle' - $ref: '#/components/parameters/langArticle' - $ref: '#/components/parameters/dateStartArticle' - $ref: '#/components/parameters/dateEndArticle' - $ref: '#/components/parameters/dateMentionStart' - $ref: '#/components/parameters/dateMentionEnd' - $ref: '#/components/parameters/keywordLoc' - $ref: '#/components/parameters/keywordOperArticle' - $ref: '#/components/parameters/conceptOperArticle' - $ref: '#/components/parameters/categoryOperArticle' - $ref: '#/components/parameters/keywordSearchMode' - $ref: '#/components/parameters/sourceOper' - $ref: '#/components/parameters/sourceGroupOper' - $ref: '#/components/parameters/authorOper' - $ref: '#/components/parameters/ignoreKeywordArticle' - $ref: '#/components/parameters/ignoreConceptUriArticle' - $ref: '#/components/parameters/ignoreCategoryUriArticle' - $ref: '#/components/parameters/ignoreSourceUriArticle' - $ref: '#/components/parameters/ignoreSourceLocationUriArticle' - $ref: '#/components/parameters/ignoreSourceGroupUriArticle' - $ref: '#/components/parameters/ignoreLocationUriArticle' - $ref: '#/components/parameters/ignoreAuthorUriArticle' - $ref: '#/components/parameters/ignoreLangArticle' - $ref: '#/components/parameters/ignoreKeywordLoc' - $ref: '#/components/parameters/ignoreKeywordSearchMode' - $ref: '#/components/parameters/startSourceRankPercentile' - $ref: '#/components/parameters/endSourceRankPercentile' - $ref: '#/components/parameters/minSentimentArticle' - $ref: '#/components/parameters/maxSentimentArticle' - $ref: '#/components/parameters/isDuplicateFilter' - $ref: '#/components/parameters/hasDuplicateFilter' - $ref: '#/components/parameters/eventFilter' # returned details - $ref: '#/components/parameters/includeArticleTitle' - $ref: '#/components/parameters/includeArticleBasicInfo' - $ref: '#/components/parameters/includeArticleBody' - $ref: '#/components/parameters/includeArticleUrl' - $ref: '#/components/parameters/includeArticleEventUri' - $ref: '#/components/parameters/includeArticleStoryUri' - $ref: '#/components/parameters/includeArticleSocialScore' - $ref: '#/components/parameters/includeArticleSentiment' - $ref: '#/components/parameters/includeArticleConcepts' - $ref: '#/components/parameters/includeArticleCategories' - $ref: '#/components/parameters/includeArticleLocation' - $ref: '#/components/parameters/includeArticleImage' - $ref: '#/components/parameters/includeArticleAuthors' - $ref: '#/components/parameters/includeArticleVideos' - $ref: '#/components/parameters/includeArticleLinks' - $ref: '#/components/parameters/includeArticleExtractedDates' - $ref: '#/components/parameters/includeArticleDuplicateList' - $ref: '#/components/parameters/includeArticleOriginalArticle' - $ref: '#/components/parameters/includeSourceTitle' - $ref: '#/components/parameters/includeSourceDescription' - $ref: '#/components/parameters/includeSourceLocation' - $ref: '#/components/parameters/includeSourceRanking' - $ref: '#/components/parameters/includeSourceImage' - $ref: '#/components/parameters/includeSourceSocialMedia' - $ref: '#/components/parameters/includeConceptLabel' - $ref: '#/components/parameters/includeConceptImage' - $ref: '#/components/parameters/includeConceptDescription' - $ref: '#/components/parameters/includeConceptSynonyms' - $ref: '#/components/parameters/includeConceptTrendingScore' - $ref: '#/components/parameters/conceptLang' - $ref: '#/components/parameters/includeCategoryParentUri' - $ref: '#/components/parameters/includeLocationGeoLocation' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' - $ref: '#/components/parameters/includeLocationCountryDetails' - $ref: '#/components/parameters/includeLocationLabel' - $ref: '#/components/parameters/includeLocationWikiUri' - $ref: '#/components/parameters/includeLocationPlaceFeatureCode' - $ref: '#/components/parameters/includeLocationPlaceCountry' responses: '200': description: Response content: application/json: schema: allOf: - $ref: '#/components/schemas/Articles' - $ref: '#/components/schemas/UriWgtList' - $ref: '#/components/schemas/ConceptAggr' - $ref: '#/components/schemas/KeywordAggr' - $ref: '#/components/schemas/TimeAggr' - $ref: '#/components/schemas/SourceAggr' - $ref: '#/components/schemas/ConceptGraph' - $ref: '#/components/schemas/CategoryAggr' - $ref: '#/components/schemas/RecentActivityArticles' /api/v1/article/getArticlesForTopicPage: get: tags: - Articles summary: Obtain articles that match a user generated topic page description: > Retrieve the news articles that match the topic page that the user generated on the [monitoring page](https://eventregistry.org/monitoring). The topic page has to be created using the web interface and can be defined by a list of concepts, keywords, news sources, categories and other available conditions. Each topic page has a unique id, called a URI. When you open the topic page, the URI is displayed in the url in the browser. Use that URI as the `uri` parameter when making the API calls. Compared to the `getArticles` endpoint, this endpoint is well suited when you want to find articles that match a broader topic that can be defined using a set of concepts and keywords. These concepts and keywords don't all need to be mentioned in an article, but the more of them are mentioned, the higher will the article be in the list of results. By default, the returned articles are sorted based on how well they match the topic, but you can also change the sorting by setting the `articlesSortBy` parameter. The results of the search can be the list of matching articles (when `resultType = articles`, default) or one of the various aggregates (summaries) of the matching articles. In case of `resultType = timeAggr`, for example, the returned data will contain information *when* were the articles matching the topic were published. Details about the returned information is available on the **[data model page](https://github.com/EventRegistry/event-registry-python/wiki/Data-models)**. operationId: getArticlesForTopicPage parameters: - $ref: '#/components/parameters/apiKey' - name: uri in: query description: >- URI of the topic page for which you wish to retrieve matching articles. Obtain the URI from the URL on the [monitoring page](https://eventregistry.org/monitoring) when the topic page is opened. Either `uri` or `topicPage` parameter has to be provided. schema: type: string - $ref: '#/components/parameters/topicPage' - name: resultType in: query description: >- Define what kind of results of the search you would like to get. schema: default: articles type: string enum: - articles - uriWgtList - langAggr - timeAggr - sourceAggr - sourceExAggr - authorAggr - keywordAggr - locAggr - conceptAggr - conceptGraph - conceptTrends - categoryAggr - dateMentionAggr - sentimentAggr - $ref: '#/components/parameters/maxDaysBack' - $ref: '#/components/parameters/onlyAfterTm' - $ref: '#/components/parameters/articlesPage' - $ref: '#/components/parameters/articlesCount' - $ref: '#/components/parameters/articlesSortByRel' - $ref: '#/components/parameters/articlesSortByAsc' - $ref: '#/components/parameters/dataType' # returned details - $ref: '#/components/parameters/articleBodyLen' - $ref: '#/components/parameters/includeArticleTitle' - $ref: '#/components/parameters/includeArticleBasicInfo' - $ref: '#/components/parameters/includeArticleBody' - $ref: '#/components/parameters/includeArticleUrl' - $ref: '#/components/parameters/includeArticleEventUri' - $ref: '#/components/parameters/includeArticleStoryUri' - $ref: '#/components/parameters/includeArticleSocialScore' - $ref: '#/components/parameters/includeArticleSentiment' - $ref: '#/components/parameters/includeArticleConcepts' - $ref: '#/components/parameters/includeArticleCategories' - $ref: '#/components/parameters/includeArticleLocation' - $ref: '#/components/parameters/includeArticleImage' - $ref: '#/components/parameters/includeArticleAuthors' - $ref: '#/components/parameters/includeArticleVideos' - $ref: '#/components/parameters/includeArticleLinks' - $ref: '#/components/parameters/includeArticleExtractedDates' - $ref: '#/components/parameters/includeArticleDuplicateList' - $ref: '#/components/parameters/includeArticleOriginalArticle' - $ref: '#/components/parameters/includeSourceTitle' - $ref: '#/components/parameters/includeSourceDescription' - $ref: '#/components/parameters/includeSourceLocation' - $ref: '#/components/parameters/includeSourceRanking' - $ref: '#/components/parameters/includeSourceImage' - $ref: '#/components/parameters/includeSourceSocialMedia' - $ref: '#/components/parameters/includeConceptLabel' - $ref: '#/components/parameters/includeConceptImage' - $ref: '#/components/parameters/includeConceptDescription' - $ref: '#/components/parameters/includeConceptSynonyms' - $ref: '#/components/parameters/includeConceptTrendingScore' - $ref: '#/components/parameters/conceptLang' - $ref: '#/components/parameters/includeCategoryParentUri' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' - $ref: '#/components/parameters/includeLocationCountryDetails' - $ref: '#/components/parameters/includeLocationLabel' - $ref: '#/components/parameters/includeLocationWikiUri' - $ref: '#/components/parameters/includeLocationPlaceFeatureCode' - $ref: '#/components/parameters/includeLocationPlaceCountry' responses: '200': description: Response content: application/json: schema: allOf: - $ref: '#/components/schemas/Articles' /api/v1/article/getArticle: get: tags: - Articles summary: Obtain details about a single or multiple news articles description: | Given a list of article URIs, obtain article details with all available meta-information. Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-articles-get-article)**. Details about the returned information is available on the **[data model page](https://github.com/EventRegistry/event-registry-python/wiki/Data-models)**. operationId: getArticle parameters: - $ref: '#/components/parameters/apiKey' - name: articleUri in: query required: true description: >- Articles are identifiable by their unique IDs (called URIs) that are assigned by Event Registry. Provide URI or a set of URIs. schema: type: array items: type: string - name: resultType in: query description: >- Define what kind of results you would like to get. schema: type: array items: default: info type: string enum: - info - duplicatedArticles - originalArticle - name: infoArticleBodyLen in: query description: >- Set the size of the article body that'll be returned in the response. Use -1 for full article body. schema: type: integer default: 300 # returned details - $ref: '#/components/parameters/includeArticleTitle' - $ref: '#/components/parameters/includeArticleBasicInfo' - $ref: '#/components/parameters/includeArticleBody' - $ref: '#/components/parameters/includeArticleUrl' - $ref: '#/components/parameters/includeArticleEventUri' - $ref: '#/components/parameters/includeArticleStoryUri' - $ref: '#/components/parameters/includeArticleSocialScore' - $ref: '#/components/parameters/includeArticleSentiment' - $ref: '#/components/parameters/includeArticleConcepts' - $ref: '#/components/parameters/includeArticleCategories' - $ref: '#/components/parameters/includeArticleLocation' - $ref: '#/components/parameters/includeArticleImage' - $ref: '#/components/parameters/includeArticleAuthors' - $ref: '#/components/parameters/includeArticleVideos' - $ref: '#/components/parameters/includeArticleLinks' - $ref: '#/components/parameters/includeArticleExtractedDates' - $ref: '#/components/parameters/includeArticleDuplicateList' - $ref: '#/components/parameters/includeArticleOriginalArticle' - $ref: '#/components/parameters/includeConceptLabel' - $ref: '#/components/parameters/includeConceptImage' - $ref: '#/components/parameters/includeConceptDescription' - $ref: '#/components/parameters/includeConceptSynonyms' - $ref: '#/components/parameters/includeConceptTrendingScore' - $ref: '#/components/parameters/conceptLang' - $ref: '#/components/parameters/includeSourceTitle' - $ref: '#/components/parameters/includeSourceDescription' - $ref: '#/components/parameters/includeSourceLocation' - $ref: '#/components/parameters/includeSourceRanking' - $ref: '#/components/parameters/includeSourceImage' - $ref: '#/components/parameters/includeSourceSocialMedia' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' - $ref: '#/components/parameters/includeLocationCountryDetails' - $ref: '#/components/parameters/includeLocationLabel' - $ref: '#/components/parameters/includeLocationWikiUri' - $ref: '#/components/parameters/includeLocationPlaceFeatureCode' - $ref: '#/components/parameters/includeLocationPlaceCountry' responses: '200': description: Response content: application/json: schema: type: object properties: uri: allOf: - type: object properties: info: $ref: '#/components/schemas/Article' - type: object properties: duplicatedArticles: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: $ref: '#/components/schemas/Article' - type: object properties: originalArticle: $ref: '#/components/schemas/Article' /api/v1/minuteStreamArticles: get: tags: - Articles summary: The minute stream of news articles added to Event Registry description: | The API endpoint allows the user to obtain the full list of news articles added to Event Registry in the last minute. This is the only API call that also allows returning more than 100 articles per call. If more than 100 articles are returned, then correspondingly higher number of tokens are used per call. Without any additional filters, the API will return 100 articles added in the last minute. By specifying filters like `lang`, `keyword`, `conceptUri` and others, you can however limit the recently added content to only the subset that matches these filters. Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-articles-minute-stream-articles)**. operationId: minuteStreamArticles parameters: - $ref: '#/components/parameters/apiKey' - name: recentActivityArticlesMaxArticleCount in: query description: | The maximum number of articles to return. Maximum value specified can be 2.000. The number of used tokens will correspond to the number of returned articles (for 300 returned articles, 3 tokens will be used, etc.). schema: type: integer default: 100 maximum: 2000 - name: recentActivityArticles*UpdatesAfterUri in: query description: | The actual names of the parameters should be `recentActivityArticlesNewsUpdatesAfterUri`, `recentActivityArticlesBlogUpdatesAfterUri` and `recentActivityArticlesPrUpdatesAfterUri`, depending on which `dataType` parameters you require. Specifying the parameter(s) will only return articles that were added since the articles with the provided URI were added. If you are repeatedly calling the endpoint, using this parameter is the best way to ensure that all matching content is retrieved. schema: type: string - name: recentActivityArticlesUpdatesAfterMinsAgo in: query description: | The parameter can be used to retrieve not only the last minute of articles, but more minutes. When using some filtering parameters below you use can use this parameter to call `minuteStreamArticles` endpoint only every few minutes and still retrieve all added content matching your filters. The value should be at most 240 (4 hours). schema: type: integer - name: recentActivityArticlesUpdatesAfterTm in: query description: > The parameter can be used to retrieve articles that were collected after the specified time. The value should be in format `YYYY-MM-DDTHH:MM:SS` and should represent datetime in UTC timezone. The value should be at most 4 hours in the past. schema: type: string - $ref: '#/components/parameters/articleBodyLen' - $ref: '#/components/parameters/dataType' - $ref: '#/components/parameters/keywordArticle' - $ref: '#/components/parameters/conceptUriArticle' - $ref: '#/components/parameters/categoryUriArticle' - $ref: '#/components/parameters/sourceUriArticle' - $ref: '#/components/parameters/sourceLocationUriArticle' - $ref: '#/components/parameters/sourceGroupUriArticle' - $ref: '#/components/parameters/authorUriArticle' - $ref: '#/components/parameters/locationUriArticle' - $ref: '#/components/parameters/langArticle' - $ref: '#/components/parameters/keywordLoc' - $ref: '#/components/parameters/keywordOperArticle' - $ref: '#/components/parameters/conceptOperArticle' - $ref: '#/components/parameters/categoryOperArticle' - $ref: '#/components/parameters/keywordSearchMode' - $ref: '#/components/parameters/sourceOper' - $ref: '#/components/parameters/sourceGroupOper' - $ref: '#/components/parameters/authorOper' - $ref: '#/components/parameters/startSourceRankPercentile' - $ref: '#/components/parameters/endSourceRankPercentile' - $ref: '#/components/parameters/minSentimentArticle' - $ref: '#/components/parameters/maxSentimentArticle' - $ref: '#/components/parameters/isDuplicateFilter' - $ref: '#/components/parameters/hasDuplicateFilter' - $ref: '#/components/parameters/eventFilter' responses: '200': description: Response content: application/json: schema: type: object properties: recentActivityArticles: type: object properties: currTime: type: string activity: type: array items: $ref: '#/components/schemas/Article' /api/v1/articleMapper: get: tags: - Articles summary: Mapping of the article URLs to the internal article URIs description: | You can use this API call if you need to map an article URL to the article URI that is used internally in Event Registry. Using the article URI you can then retrieve article information using the endpoint `/getArticle`. Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-articles-article-mapper)**. operationId: articleMapper parameters: - $ref: '#/components/parameters/apiKey' - name: articleUrl in: query description: Define the requested article URL. required: true schema: type: string - name: includeAllVersions in: query description: >- Set this parameter to true to include all versions of the article. schema: type: boolean - name: deep in: query description: >- schema: type: boolean responses: '200': description: Returns an object which has the requested article URL as a key and the URI as its value. content: application/json: schema: type: object properties: url: type: array items: type: string # # EVENT endpoint # /api/v1/event/getEvents: get: tags: - Events summary: Retrieve a list of events that match one or more search conditions description: | Identify the world events that match a certain set of search criteria. The search conditions can be specified by setting the `query` parameter, or by specifying one or multiple search parameters, such as `keyword`, `conceptUri`, `sourceUri`, etc. 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 events (when `resultType = events`) or one of the various aggregates (summaries) of the matching events. In case of `resultType = locAggr`, for example, the returned data will contain the geographic locations where the events matching criteria occured. Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-events-get-events)**. Details about the returned information is available on the **[data model page](https://github.com/EventRegistry/event-registry-python/wiki/Data-models)**. operationId: getEvents parameters: - $ref: '#/components/parameters/apiKey' - name: resultType in: query description: >- Define what kind of results you would like to get. schema: type: array items: default: events type: string enum: - events - uriWgtList - timeAggr - locAggr - locTimeAggr - sourceAggr - authorAggr - keywordAggr - conceptAggr - conceptGraph - conceptTrends - categoryAggr - breakingEvents - sentimentAggr - dateMentionAggr - recentActivityEvents - $ref: '#/components/parameters/eventsPage' - $ref: '#/components/parameters/eventsCount' - $ref: '#/components/parameters/eventsSortBy' - $ref: '#/components/parameters/eventsSortByAsc' # filters - $ref: '#/components/parameters/eventQuery' - $ref: '#/components/parameters/keywordEvent' - $ref: '#/components/parameters/conceptUriEvent' - $ref: '#/components/parameters/categoryUriEvent' - $ref: '#/components/parameters/sourceUriEvent' - $ref: '#/components/parameters/sourceLocationUriEvent' - $ref: '#/components/parameters/sourceGroupUriEvent' - $ref: '#/components/parameters/authorUriEvent' - $ref: '#/components/parameters/locationUriEvent' - $ref: '#/components/parameters/langEvent' - $ref: '#/components/parameters/dateStartEvent' - $ref: '#/components/parameters/dateEndEvent' - $ref: '#/components/parameters/minSentimentEvent' - $ref: '#/components/parameters/maxSentimentEvent' - $ref: '#/components/parameters/minArticlesInEvent' - $ref: '#/components/parameters/maxArticlesInEvent' - $ref: '#/components/parameters/reportingDateStart' - $ref: '#/components/parameters/reportingDateEnd' - $ref: '#/components/parameters/dateMentionStart' - $ref: '#/components/parameters/dateMentionEnd' - $ref: '#/components/parameters/keywordLoc' - $ref: '#/components/parameters/keywordOperEvent' - $ref: '#/components/parameters/conceptOperEvent' - $ref: '#/components/parameters/categoryOperEvent' - $ref: '#/components/parameters/keywordSearchMode' - $ref: '#/components/parameters/sourceOper' - $ref: '#/components/parameters/sourceGroupOper' - $ref: '#/components/parameters/authorOper' - $ref: '#/components/parameters/ignoreKeywordEvent' - $ref: '#/components/parameters/ignoreConceptUriEvent' - $ref: '#/components/parameters/ignoreCategoryUriEvent' - $ref: '#/components/parameters/ignoreSourceUriEvent' - $ref: '#/components/parameters/ignoreSourceLocationUriEvent' - $ref: '#/components/parameters/ignoreSourceGroupUriEvent' - $ref: '#/components/parameters/ignoreAuthorUriEvent' - $ref: '#/components/parameters/ignoreLocationUriEvent' - $ref: '#/components/parameters/ignoreLangEvent' - $ref: '#/components/parameters/ignoreKeywordLoc' - $ref: '#/components/parameters/ignoreKeywordSearchMode' # returned details - $ref: '#/components/parameters/includeEventTitle' - $ref: '#/components/parameters/includeEventSummary' - $ref: '#/components/parameters/includeEventSocialScore' - $ref: '#/components/parameters/includeEventSentiment' - $ref: '#/components/parameters/includeEventLocation' - $ref: '#/components/parameters/includeEventDate' - $ref: '#/components/parameters/includeEventArticleCounts' - $ref: '#/components/parameters/includeEventConcepts' - $ref: '#/components/parameters/includeEventCategories' - $ref: '#/components/parameters/includeEventCommonDates' - $ref: '#/components/parameters/includeEventInfoArticle' - $ref: '#/components/parameters/includeEventStories' - $ref: '#/components/parameters/eventImageCount' - $ref: '#/components/parameters/includeConceptLabel' - $ref: '#/components/parameters/includeConceptImage' - $ref: '#/components/parameters/includeConceptDescription' - $ref: '#/components/parameters/includeConceptSynonyms' - $ref: '#/components/parameters/conceptLang' - $ref: '#/components/parameters/includeStoryBasicStats' - $ref: '#/components/parameters/includeStoryTitle' - $ref: '#/components/parameters/includeStorySummary' - $ref: '#/components/parameters/includeStoryLocation' - $ref: '#/components/parameters/includeStoryDate' - $ref: '#/components/parameters/includeStoryConcepts' - $ref: '#/components/parameters/includeStoryCategories' - $ref: '#/components/parameters/includeStoryMedoidArticle' - $ref: '#/components/parameters/includeStoryInfoArticle' - $ref: '#/components/parameters/includeStoryCommonDates' - $ref: '#/components/parameters/includeStorySocialScore' - $ref: '#/components/parameters/storyImageCount' - $ref: '#/components/parameters/includeCategoryParentUri' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' - $ref: '#/components/parameters/includeLocationCountryDetails' - $ref: '#/components/parameters/includeLocationLabel' - $ref: '#/components/parameters/includeLocationWikiUri' - $ref: '#/components/parameters/includeLocationPlaceFeatureCode' - $ref: '#/components/parameters/includeLocationPlaceCountry' responses: '200': description: Response content: application/json: schema: allOf: - $ref: '#/components/schemas/Events' - $ref: '#/components/schemas/UriWgtList' - $ref: '#/components/schemas/ConceptAggr' - $ref: '#/components/schemas/KeywordAggr' - $ref: '#/components/schemas/LocAggr' - $ref: '#/components/schemas/TimeAggr' - $ref: '#/components/schemas/SourceAggr' - $ref: '#/components/schemas/ConceptGraph' - $ref: '#/components/schemas/CategoryAggr' - $ref: '#/components/schemas/RecentActivityEvents' /api/v1/event/getEventsForTopicPage: get: tags: - Events summary: Obtain events that match a user generated topic page description: > Retrieve the events that match the topic page the user generated on the [monitoring page](https://eventregistry.org/monitoring). The topic page has to be created using the web interface and can be defined by a list of concepts, keywords, news sources, categories and other available conditions. Each topic page has a uniqe id, called a URI. When you open the topic page, the URI is displayed in the url in the browser. Use that URI as the `uri` parameter when making the API calls. Compared to the `getEvents` endpoint, this endpoint is well suited when you want to find events that match a broader topic that can be defined using a set of concepts and keywords. These concepts and keywords don't all need to be mentioned in an event, but the more of them are mentioned, the higher will the event be in the list of results. By default, the returned events are sorted based on how well they match the topic, but you can also change the sorting by setting the `eventsSortBy` parameter. The results of the search can be the list of matching events (when `resultType = events`, default) or one of the various aggregates (summaries) of the matching events. In case of `resultType = timeAggr`, for example, the returned data will contain information *when* the matching events occurred. Details about the returned information is available on the **[data model page](https://github.com/EventRegistry/event-registry-python/wiki/Data-models)**. operationId: getEventsForTopicPage parameters: - $ref: '#/components/parameters/apiKey' - name: uri in: query description: >- URI of the topic page for which you wish to retrieve matching events. Obtain the URI from the URL on the [monitoring page](https://eventregistry.org/monitoring) when the topic page is opened. Either `uri` or `topicPage` parameter has to be provided. schema: type: string - $ref: '#/components/parameters/topicPage' - name: resultType in: query description: >- Define what kind of results you would like to get. schema: default: events type: string enum: - events - uriWgtList - timeAggr - locAggr - locTimeAggr - sourceAggr - authorAggr - keywordAggr - conceptAggr - conceptGraph - conceptTrends - categoryAggr - breakingEvents - sentimentAggr - dateMentionAggr - $ref: '#/components/parameters/maxDaysBackEvents' - $ref: '#/components/parameters/onlyAfterTmEvents' - $ref: '#/components/parameters/eventsPage' - $ref: '#/components/parameters/eventsCount' - $ref: '#/components/parameters/eventsSortByRel' - $ref: '#/components/parameters/eventsSortByAsc' # returned details - $ref: '#/components/parameters/includeEventTitle' - $ref: '#/components/parameters/includeEventSummary' - $ref: '#/components/parameters/includeEventSocialScore' - $ref: '#/components/parameters/includeEventSentiment' - $ref: '#/components/parameters/includeEventLocation' - $ref: '#/components/parameters/includeEventDate' - $ref: '#/components/parameters/includeEventArticleCounts' - $ref: '#/components/parameters/includeEventConcepts' - $ref: '#/components/parameters/includeEventCategories' - $ref: '#/components/parameters/includeEventCommonDates' - $ref: '#/components/parameters/includeEventInfoArticle' - $ref: '#/components/parameters/includeEventStories' - $ref: '#/components/parameters/eventImageCount' - $ref: '#/components/parameters/includeConceptLabel' - $ref: '#/components/parameters/includeConceptImage' - $ref: '#/components/parameters/includeConceptDescription' - $ref: '#/components/parameters/includeConceptSynonyms' - $ref: '#/components/parameters/conceptLang' - $ref: '#/components/parameters/includeStoryBasicStats' - $ref: '#/components/parameters/includeStoryTitle' - $ref: '#/components/parameters/includeStorySummary' - $ref: '#/components/parameters/includeStoryLocation' - $ref: '#/components/parameters/includeStoryDate' - $ref: '#/components/parameters/includeStoryConcepts' - $ref: '#/components/parameters/includeStoryCategories' - $ref: '#/components/parameters/includeStoryMedoidArticle' - $ref: '#/components/parameters/includeStoryInfoArticle' - $ref: '#/components/parameters/includeStoryCommonDates' - $ref: '#/components/parameters/includeStorySocialScore' - $ref: '#/components/parameters/storyImageCount' - $ref: '#/components/parameters/includeCategoryParentUri' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' - $ref: '#/components/parameters/includeLocationCountryDetails' - $ref: '#/components/parameters/includeLocationLabel' - $ref: '#/components/parameters/includeLocationWikiUri' - $ref: '#/components/parameters/includeLocationPlaceFeatureCode' - $ref: '#/components/parameters/includeLocationPlaceCountry' responses: '200': description: Response content: application/json: schema: allOf: - $ref: '#/components/schemas/Events' /api/v1/event/getEvent: get: tags: - Events summary: Obtain details about a single event description: | The endpoint can be used to retrieve detailed information about a single event of interest. The event of interest should be provided with the `eventUri` parameter. For each event you can retrieve multiple properties. The most common is retrieving the list of articles that discuss the event. Alternatively, you can also generate various summaries, by using some other `returnType` value. The `keywordAggr` return type will, for example, return the top keywords that are mentioned in the articles about the event. If you would like retrieve only a subset of articles assigned to the event, you can do so by specifying one of the available filters (`keyword`, `conceptUri`, etc.). Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-events-get-event)**. Details about the returned information is available on the **[data model page](https://github.com/EventRegistry/event-registry-python/wiki/Data-models)**. operationId: getEvent parameters: - $ref: '#/components/parameters/apiKey' - name: eventUri in: query required: true description: >- Specify the URI of the event you would like to see returned. schema: type: string - name: resultType in: query description: >- Define what kind of results you would like to get. Each result type corresponds to the prefix that'll be used for other parameters. schema: default: info type: string enum: - info - articles - articleUris - keywordAggr - sourceExAggr - dateMentionAggr - articleTrend - similarEvents - name: articlesLang in: query description: >- if resultType is `articles` then use this parameter if you wish to obtain only articles about the event in specific language(s). schema: type: array items: type: string - name: articlesIncludeDuplicates in: query description: > if resultType is `articles` then set this value to `true` in order to return also articles that are copies of other articles (possibly from other news sources). schema: type: boolean default: "false" # filter event's articles to a subset based on this criteria - $ref: '#/components/parameters/keywordArticle' - $ref: '#/components/parameters/conceptUriArticle' - $ref: '#/components/parameters/categoryUriArticle' - $ref: '#/components/parameters/sourceUriArticle' - $ref: '#/components/parameters/sourceLocationUriArticle' - $ref: '#/components/parameters/sourceGroupUriArticle' - $ref: '#/components/parameters/authorUriArticle' - $ref: '#/components/parameters/locationUriArticle' - $ref: '#/components/parameters/langArticle' - $ref: '#/components/parameters/dateStartArticle' - $ref: '#/components/parameters/dateEndArticle' - $ref: '#/components/parameters/dateMentionStart' - $ref: '#/components/parameters/dateMentionEnd' - $ref: '#/components/parameters/keywordLoc' - $ref: '#/components/parameters/keywordOperArticle' - $ref: '#/components/parameters/conceptOperArticle' - $ref: '#/components/parameters/categoryOperArticle' - $ref: '#/components/parameters/keywordSearchMode' - $ref: '#/components/parameters/sourceOper' - $ref: '#/components/parameters/sourceGroupOper' - $ref: '#/components/parameters/authorOper' - $ref: '#/components/parameters/startSourceRankPercentile' - $ref: '#/components/parameters/endSourceRankPercentile' - $ref: '#/components/parameters/minSentimentArticle' - $ref: '#/components/parameters/maxSentimentArticle' # returned details - $ref: '#/components/parameters/includeEventTitle' - $ref: '#/components/parameters/includeEventSummary' - $ref: '#/components/parameters/includeEventSocialScore' - $ref: '#/components/parameters/includeEventSentiment' - $ref: '#/components/parameters/includeEventLocation' - $ref: '#/components/parameters/includeEventDate' - $ref: '#/components/parameters/includeEventArticleCounts' - $ref: '#/components/parameters/includeEventConcepts' - $ref: '#/components/parameters/includeEventCategories' - $ref: '#/components/parameters/includeEventCommonDates' - $ref: '#/components/parameters/includeEventInfoArticle' - $ref: '#/components/parameters/includeEventStories' - $ref: '#/components/parameters/eventImageCount' - $ref: '#/components/parameters/includeConceptLabel' - $ref: '#/components/parameters/includeConceptImage' - $ref: '#/components/parameters/includeConceptDescription' - $ref: '#/components/parameters/includeConceptSynonyms' - $ref: '#/components/parameters/includeConceptTrendingScore' - $ref: '#/components/parameters/conceptLang' - $ref: '#/components/parameters/includeStoryBasicStats' - $ref: '#/components/parameters/includeStoryTitle' - $ref: '#/components/parameters/includeStorySummary' - $ref: '#/components/parameters/includeStoryLocation' - $ref: '#/components/parameters/includeStoryDate' - $ref: '#/components/parameters/includeStoryConcepts' - $ref: '#/components/parameters/includeStoryCategories' - $ref: '#/components/parameters/includeStoryMedoidArticle' - $ref: '#/components/parameters/includeStoryInfoArticle' - $ref: '#/components/parameters/includeStoryCommonDates' - $ref: '#/components/parameters/includeStorySocialScore' - $ref: '#/components/parameters/storyImageCount' - $ref: '#/components/parameters/includeArticleTitle' - $ref: '#/components/parameters/includeArticleBasicInfo' - $ref: '#/components/parameters/includeArticleBody' - $ref: '#/components/parameters/includeArticleUrl' - $ref: '#/components/parameters/includeArticleEventUri' - $ref: '#/components/parameters/includeArticleStoryUri' - $ref: '#/components/parameters/includeArticleSocialScore' - $ref: '#/components/parameters/includeArticleSentiment' - $ref: '#/components/parameters/includeArticleConcepts' - $ref: '#/components/parameters/includeArticleCategories' - $ref: '#/components/parameters/includeArticleLocation' - $ref: '#/components/parameters/includeArticleImage' - $ref: '#/components/parameters/includeArticleAuthors' - $ref: '#/components/parameters/includeArticleVideos' - $ref: '#/components/parameters/includeArticleLinks' - $ref: '#/components/parameters/includeArticleExtractedDates' - $ref: '#/components/parameters/includeArticleDuplicateList' - $ref: '#/components/parameters/includeArticleOriginalArticle' - $ref: '#/components/parameters/articleBodyLen' - $ref: '#/components/parameters/includeSourceTitle' - $ref: '#/components/parameters/includeSourceDescription' - $ref: '#/components/parameters/includeSourceLocation' - $ref: '#/components/parameters/includeSourceRanking' - $ref: '#/components/parameters/includeSourceImage' - $ref: '#/components/parameters/includeSourceSocialMedia' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' - $ref: '#/components/parameters/includeLocationCountryDetails' - $ref: '#/components/parameters/includeLocationLabel' - $ref: '#/components/parameters/includeLocationWikiUri' - $ref: '#/components/parameters/includeLocationPlaceFeatureCode' - $ref: '#/components/parameters/includeLocationPlaceCountry' responses: '200': description: Response content: application/json: schema: type: object properties: uri: allOf: - type: object properties: info: $ref: '#/components/schemas/Event' - type: object properties: articles: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: $ref: '#/components/schemas/Article' - type: object properties: articleUris: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: type: string - $ref: '#/components/schemas/KeywordAggr' - $ref: '#/components/schemas/SourceExAggr' - $ref: '#/components/schemas/DateMentionAggr' - type: object properties: articleTrend: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: $ref: '#/components/schemas/Article' - type: object properties: similarEvents: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: $ref: '#/components/schemas/Event' /api/v1/minuteStreamEvents: get: tags: - Events summary: The stream of events that were added or updated in the last minute description: | The API endpoint allows the user to obtain the full list of events that were added or updated in Event Registry in the last minute. This is the only API call that also allows returning more than 50 events per call. If more than 50 events are returned, then correspondingly higher number of tokens are used per call. Without any additional filters, the API will return *all* events added/updated in the last minute. By specifying filters like `lang`, `keyword`, `conceptUri` and others, you can however limit the returned content to only the subset that matches these filters. Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-events-minute-stream-events)**. operationId: minuteStreamEvents parameters: - $ref: '#/components/parameters/apiKey' - name: recentActivityEventsMaxEventCount in: query description: | The maximum number of events to return. Maximum value specified can be 2.000. The number of used tokens will correspond to the number of returned events. For 200 returned events, for example, 4*5 tokens will be used - 5 tokens for each 50 events. schema: type: integer default: 50 maximum: 2000 - name: recentActivityEventsUpdatesAfterMinsAgo in: query description: > The parameter can be used to retrieve not only the last minute of events, but more minutes. When using some filtering parameters below you use can use this parameter to call `minuteStreamEvents` endpoint only every few minutes and still retrieve all added content matching your filters. The value should be at most 240 (4 hours). schema: type: integer - name: recentActivityEventsUpdatesAfterTm in: query description: > The parameter can be used to retrieve events that were updated after the specified time. The value should be in format `YYYY-MM-DDTHH:MM:SS` and should represent datetime in UTC timezone. The value should be at most 4 hours in the past. schema: type: string - $ref: '#/components/parameters/keywordEvent' - $ref: '#/components/parameters/conceptUriEvent' - $ref: '#/components/parameters/categoryUriEvent' - $ref: '#/components/parameters/sourceUriEvent' - $ref: '#/components/parameters/sourceLocationUriEvent' - $ref: '#/components/parameters/sourceGroupUriEvent' - $ref: '#/components/parameters/authorUriEvent' - $ref: '#/components/parameters/locationUriEvent' - $ref: '#/components/parameters/keywordLoc' - $ref: '#/components/parameters/keywordOperEvent' - $ref: '#/components/parameters/conceptOperEvent' - $ref: '#/components/parameters/categoryOperEvent' - $ref: '#/components/parameters/keywordSearchMode' - $ref: '#/components/parameters/sourceOper' - $ref: '#/components/parameters/sourceGroupOper' - $ref: '#/components/parameters/authorOper' - $ref: '#/components/parameters/langEvent' - $ref: '#/components/parameters/minArticlesInEvent' - $ref: '#/components/parameters/maxArticlesInEvent' responses: '200': description: Response content: application/json: schema: type: object properties: recentActivityEvents: type: object properties: activity: type: array items: type: string eventInfo: type: object properties: eventUri: $ref: '#/components/schemas/Event' /api/v1/event/getBreakingEvents: get: tags: - Events summary: Retrieve the list of breaking events description: | Use this API endpoint to obtain a list of breaking events and their breaking score. The breaking events are events (a) that occured very recently, (b) for which we have collected many articles about them in a short time span and (c) for which the intensity of reporting is increasing. Examples of use are provided on the **[examples page](https://eventregistry.org/documentation/examples#event-registry-api-examples-events-get-breaking-events)**. operationId: getBreakingEvents parameters: - $ref: '#/components/parameters/apiKey' - name: breakingEventsCount in: query description: >- Number of breaking events to return (at most 100) schema: default: 100 type: integer - name: breakingEventsPage in: query description: >- Page of the results to return schema: type: integer default: 1 - name: breakingEventsMinBreakingScore in: query description: >- Score of how much should event at least be "breaking" in order to return it. Minimum value is 0. schema: type: number format: double default: 0.2 # returned details - $ref: '#/components/parameters/includeEventTitle' - $ref: '#/components/parameters/includeEventSummary' - $ref: '#/components/parameters/includeEventSocialScore' - $ref: '#/components/parameters/includeEventSentiment' - $ref: '#/components/parameters/includeEventLocation' - $ref: '#/components/parameters/includeEventDate' - $ref: '#/components/parameters/includeEventArticleCounts' - $ref: '#/components/parameters/includeEventConcepts' - $ref: '#/components/parameters/includeEventCategories' - $ref: '#/components/parameters/includeEventCommonDates' - $ref: '#/components/parameters/includeEventInfoArticle' - $ref: '#/components/parameters/includeEventStories' - $ref: '#/components/parameters/eventImageCount' - $ref: '#/components/parameters/includeConceptLabel' - $ref: '#/components/parameters/includeConceptImage' - $ref: '#/components/parameters/includeConceptDescription' - $ref: '#/components/parameters/includeConceptSynonyms' - $ref: '#/components/parameters/conceptLang' - $ref: '#/components/parameters/includeStoryBasicStats' - $ref: '#/components/parameters/includeStoryTitle' - $ref: '#/components/parameters/includeStorySummary' - $ref: '#/components/parameters/includeStoryLocation' - $ref: '#/components/parameters/includeStoryDate' - $ref: '#/components/parameters/includeStoryConcepts' - $ref: '#/components/parameters/includeStoryCategories' - $ref: '#/components/parameters/includeStoryMedoidArticle' - $ref: '#/components/parameters/includeStoryInfoArticle' - $ref: '#/components/parameters/includeStoryCommonDates' - $ref: '#/components/parameters/includeStorySocialScore' - $ref: '#/components/parameters/storyImageCount' - $ref: '#/components/parameters/includeCategoryParentUri' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' - $ref: '#/components/parameters/includeLocationCountryDetails' - $ref: '#/components/parameters/includeLocationLabel' - $ref: '#/components/parameters/includeLocationWikiUri' - $ref: '#/components/parameters/includeLocationPlaceFeatureCode' - $ref: '#/components/parameters/includeLocationPlaceCountry' responses: '200': description: Response content: application/json: schema: allOf: - $ref: '#/components/schemas/Events' # # MENTION endpoints # /api/v1/eventType/mention/getMentions: get: tags: - Mentions summary: Obtain mentions of event types that match one or more search conditions description: | Identify the mentions that match a certain set of search criteria. A mention is a sentence in a news article, in which we have identified that a certain type of an event (an *event type*, such as a product launch, an acquisition or a layoff) is being reported. Each mention contains the sentence, the information about the article in which it was found, the identified event type and the *slots* - the concepts (companies, people, locations, ...) that have a role in the mentioned event. The search conditions can be specified by setting the `query` parameter, or by specifying one or multiple search parameters, such as `eventTypeUri`, `keyword`, `conceptUri`, `industryUri`, `sourceUri`, etc. At least one positive condition has to be provided. To remove some of the results matching the *positive* conditions, you can specify some *negative* conditions using `ignoreKeyword`, `ignoreEventTypeUri`, and other `ignore*` parameters. The results of the search can be the list of matching mentions (when `resultType = mentions`) or one of the various aggregates (summaries) of the matching mentions. In case of `resultType = timeAggr`, for example, the returned data will contain information *when* were the mentions matching the search criteria published. Only a single `resultType` can be requested in a call. The same call can be made by calling the path `/api/v1/eventType/mention` and providing the parameter `action=getMentions`. The parameters can also be sent as a JSON object in the body of a POST request. operationId: getMentions parameters: - $ref: '#/components/parameters/apiKey' - name: resultType in: query description: >- Define what kind of results of the search you would like to get. `mentions` (the list of matching mentions), `uriWgtList` (only the URIs of the matching mentions), `timeAggr` (the number of matching mentions per day), `conceptAggr` (the top concepts mentioned in the matching mentions), `eventTypeAggr` (the distribution of the event types of the matching mentions), `categoryAggr` (the top categories of the matching mentions), `sourceAggr` (the top news sources of the matching mentions), `keywordAggr` (the top keywords in the matching mentions), `sentimentAggr` (the distribution of the sentiment of the matching mentions), `sentimentTimeAggr` (the sentiment of the matching mentions over time) and `recentActivityMentions` (the matching mentions that were added most recently). schema: default: mentions type: string enum: - mentions - uriWgtList - timeAggr - conceptAggr - eventTypeAggr - categoryAggr - sourceAggr - keywordAggr - sentimentAggr - sentimentTimeAggr - recentActivityMentions - $ref: '#/components/parameters/mentionsPage' - $ref: '#/components/parameters/mentionsCount' - $ref: '#/components/parameters/mentionsSortBy' - $ref: '#/components/parameters/mentionsSortByAsc' # filters - $ref: '#/components/parameters/queryMentions' - $ref: '#/components/parameters/eventTypeUriMention' - $ref: '#/components/parameters/keywordMention' - $ref: '#/components/parameters/conceptUriMention' - $ref: '#/components/parameters/categoryUriMention' - $ref: '#/components/parameters/industryUriMention' - $ref: '#/components/parameters/sdgUriMention' - $ref: '#/components/parameters/sasbUriMention' - $ref: '#/components/parameters/esgUriMention' - $ref: '#/components/parameters/sourceUriMention' - $ref: '#/components/parameters/sourceLocationUriMention' - $ref: '#/components/parameters/sourceGroupUriMention' - $ref: '#/components/parameters/locationUriMention' - $ref: '#/components/parameters/langMention' - $ref: '#/components/parameters/dateStartMention' - $ref: '#/components/parameters/dateEndMention' - $ref: '#/components/parameters/keywordLocMention' - $ref: '#/components/parameters/keywordSearchMode' - $ref: '#/components/parameters/keywordOperMention' - $ref: '#/components/parameters/conceptOperMention' - $ref: '#/components/parameters/categoryOperMention' - $ref: '#/components/parameters/sourceOper' - $ref: '#/components/parameters/sourceGroupOper' - $ref: '#/components/parameters/ignoreEventTypeUriMention' - $ref: '#/components/parameters/ignoreKeywordMention' - $ref: '#/components/parameters/ignoreConceptUriMention' - $ref: '#/components/parameters/ignoreCategoryUriMention' - $ref: '#/components/parameters/ignoreIndustryUriMention' - $ref: '#/components/parameters/ignoreSdgUriMention' - $ref: '#/components/parameters/ignoreSasbUriMention' - $ref: '#/components/parameters/ignoreEsgUriMention' - $ref: '#/components/parameters/ignoreSourceUriMention' - $ref: '#/components/parameters/ignoreSourceLocationUriMention' - $ref: '#/components/parameters/ignoreSourceGroupUriMention' - $ref: '#/components/parameters/ignoreLocationUriMention' - $ref: '#/components/parameters/ignoreLangMention' - $ref: '#/components/parameters/ignoreKeywordLocMention' - $ref: '#/components/parameters/ignoreKeywordSearchMode' - $ref: '#/components/parameters/startSourceRankPercentile' - $ref: '#/components/parameters/endSourceRankPercentile' - $ref: '#/components/parameters/minSentimentMention' - $ref: '#/components/parameters/maxSentimentMention' - $ref: '#/components/parameters/minSentenceIndex' - $ref: '#/components/parameters/maxSentenceIndex' - $ref: '#/components/parameters/showDuplicatesMention' - $ref: '#/components/parameters/mentionUri' - $ref: '#/components/parameters/mentionUriWgtList' # parameters of the individual result types - name: uriWgtListPage in: query description: >- Determines the page of the results to return (starting from 1). Relevant when `resultType = uriWgtList`. schema: type: integer default: 1 - name: uriWgtListCount in: query description: >- Define how many mention URIs (up to 50000) will be returned. The value should always be provided explicitly. Relevant when `resultType = uriWgtList`. schema: type: integer maximum: 50000 - name: uriWgtListSortBy in: query description: >- Choose the criteria for sorting the returned mention URIs. The supported values are the same as for the `mentionsSortBy` parameter. Relevant when `resultType = uriWgtList`. schema: type: string default: none - name: uriWgtListSortByAsc in: query description: >- Should the results be ordered in ascending order or descending order (default). Relevant when `resultType = uriWgtList`. schema: default: "false" type: boolean - name: conceptAggrConceptCount in: query description: >- The number of top concepts to return. Relevant when `resultType = conceptAggr`. schema: type: integer default: 20 - name: conceptAggrConceptCountPerType in: query description: >- If you wish to limit the number of top concepts per type (person, org, loc, wiki) then set this parameter. Relevant when `resultType = conceptAggr`. schema: type: integer - name: conceptAggrScoring in: query description: >- How should the top concepts be computed. `importance` (takes into account how frequently a concept is mentioned and how relevant it is in a mention), `frequency` (ranks the concepts simply by how frequently the concept is mentioned in the results) and `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). Relevant when `resultType = conceptAggr`. schema: type: string default: importance enum: - importance - frequency - uniqueness - name: conceptAggrSampleSize in: query description: >- On what sample of the matching mentions should the aggregate be computed. Relevant when `resultType = conceptAggr`. schema: type: integer - name: categoryAggrSampleSize in: query description: >- On what sample of the matching mentions should the aggregate be computed. Relevant when `resultType = categoryAggr`. schema: type: integer - name: categoryAggrScoring in: query description: >- How should the categories be scored. `frequency` counts the mentions that have the category, `importance` sums the weights of the category in the mentions. Relevant when `resultType = categoryAggr`. schema: type: string default: frequency enum: - frequency - importance - name: sourceAggrSourceCount in: query description: >- The number of top sources to return (at most 500). Relevant when `resultType = sourceAggr`. schema: type: integer default: 50 maximum: 500 - name: keywordAggrSampleSize in: query description: >- On what sample of the matching mentions should the aggregate be computed (at most 20000). Relevant when `resultType = keywordAggr`. schema: type: integer maximum: 20000 - name: sentimentAggrSentimentType in: query description: >- Which sentiment should be used when computing the aggregate - the sentiment of the sentence (`sentence`), of the article in which the sentence appears (`article`) or the sentiment associated with the event type of the mention (`eventType`). Relevant when `resultType = sentimentAggr`. schema: type: string default: sentence enum: - sentence - article - eventType - name: recentActivityMentionsMaxMentionCount in: query description: >- The maximum number of mentions to return (at most 2000). Relevant when `resultType = recentActivityMentions`. schema: type: integer default: 100 maximum: 2000 - name: recentActivityMentionsUpdatesAfterUri in: query description: >- Return only the mentions that were added after the mention with the provided URI was added. Relevant when `resultType = recentActivityMentions`. schema: type: string - name: recentActivityMentionsUpdatesAfterTm in: query description: >- Return only the mentions that were added after the specified time. The value should be in format `YYYY-MM-DDTHH:MM:SS` and should represent datetime in UTC timezone. Provide either this parameter or `recentActivityMentionsUpdatesAfterMinsAgo`, but not both. Relevant when `resultType = recentActivityMentions`. schema: type: string - name: recentActivityMentionsUpdatesAfterMinsAgo in: query description: >- Return only the mentions that were added in the specified number of last minutes. Provide either this parameter or `recentActivityMentionsUpdatesAfterTm`, but not both. Relevant when `resultType = recentActivityMentions`. schema: type: integer - name: recentActivityMentionsUpdatesUntilTm in: query description: >- Return only the mentions that were added until the specified time (in case you don't want the most recent mentions). The value should be in format `YYYY-MM-DDTHH:MM:SS` and should represent datetime in UTC timezone. Provide either this parameter or `recentActivityMentionsUpdatesUntilMinsAgo`, but not both. Relevant when `resultType = recentActivityMentions`. schema: type: string - name: recentActivityMentionsUpdatesUntilMinsAgo in: query description: >- Return only the mentions that were added at least the specified number of minutes ago. Provide either this parameter or `recentActivityMentionsUpdatesUntilTm`, but not both. Relevant when `resultType = recentActivityMentions`. schema: type: integer - name: recentActivityMentionsMandatorySourceLocation in: query description: >- Return only the mentions for which the geographic location of the news source is known. Relevant when `resultType = recentActivityMentions`. schema: type: boolean default: "false" # returned details - $ref: '#/components/parameters/includeMentionBasicInfo' - $ref: '#/components/parameters/includeMentionSlots' - $ref: '#/components/parameters/includeMentionCategories' - $ref: '#/components/parameters/includeMentionFrameworks' - $ref: '#/components/parameters/includeSourceTitle' - $ref: '#/components/parameters/includeSourceDescription' - $ref: '#/components/parameters/includeSourceLocation' - $ref: '#/components/parameters/includeSourceRanking' - $ref: '#/components/parameters/includeLocationGeoLocation' - $ref: '#/components/parameters/includeLocationPopulation' - $ref: '#/components/parameters/includeLocationGeoNamesId' - $ref: '#/components/parameters/includeLocationCountryArea' - $ref: '#/components/parameters/includeLocationCountryContinent' responses: '200': description: Response content: application/json: schema: allOf: - $ref: '#/components/schemas/Mentions' - $ref: '#/components/schemas/UriWgtList' - $ref: '#/components/schemas/TimeAggr' - $ref: '#/components/schemas/ConceptAggr' - $ref: '#/components/schemas/EventTypeAggr' - $ref: '#/components/schemas/SourceAggr' - $ref: '#/components/schemas/KeywordAggr' - $ref: '#/components/schemas/RecentActivityMentions' /api/v1/eventType/sdg/getItems: get: tags: - Mentions summary: Retrieve the list of the UN Sustainable Development Goals (SDG) description: > Returns the list of SDGs and their URIs. The URIs can be used as the values of the `sdgUri` parameter when searching for mentions. operationId: getSdgItems parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/includeEventTypes' responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/FrameworkItems' /api/v1/eventType/sasb/getItems: get: tags: - Mentions summary: Retrieve the list of the SASB categories description: > Returns the list of SASB categories and their URIs. The URIs can be used as the values of the `sasbUri` parameter when searching for mentions. operationId: getSasbItems parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/includeEventTypes' responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/FrameworkItems' /api/v1/eventType/esg/getItems: get: tags: - Mentions summary: Retrieve the list of the ESG categories description: > Returns the list of ESG categories and their URIs. The URIs can be used as the values of the `esgUri` parameter when searching for mentions. operationId: getEsgItems parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/includeEventTypes' responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/FrameworkItems' # # AUTOSUGGEST endpoints # /api/v1/suggestConceptsFast: get: tags: - Autosuggest summary: Retrieve the concept URI for a given concept label/prefix description: > Use the API to map the concept label into the concept URI that can be used when specifying the `conceptUri` filter in various API calls. The label can also be a partial name. The returned value will contain an array of concepts that match the input label. The concepts are sorted based on how frequently they occur in Event Registry data. Most often, the first candidate is the value you want to use. operationId: suggestConceptsFast parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prefix' - name: lang in: query required: true description: >- What the `prefix` is matched against. An ISO3 language code matches the concept labels in that language. `ticker`, `isin` and `cik` match a company's stock ticker symbol, its ISIN or its SEC Central Index Key (without the leading zeros), and `domain` matches an organization's domain name (e.g. `apple.com`). You can specify several values. schema: type: array items: type: string enum: - eng - spa - deu - zho - slv - cat - por - ita - fra - rus - ara - hrv - srp - ticker - isin - cik - domain example: eng responses: '200': description: Response content: application/json: schema: type: array items: $ref: '#/components/schemas/ConceptTag' /api/v1/suggestCategoriesFast: get: tags: - Autosuggest summary: Retrieve the category URI for a given category label/prefix description: > Use the API to map the category label into the category URI that can be used when specifying the `categoryUri` filter in various API calls. The label can also be a partial name. The returned value will contain an array of candidates that match the input label. The returned list is sorted based on how frequently the category occurs in Event Registry data. operationId: suggestCategoriesFast parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prefix' responses: '200': description: Response content: application/json: schema: type: array items: type: object properties: uri: type: string label: type: string /api/v1/suggestSourcesFast: get: tags: - Autosuggest summary: Retrieve the source URI for a given source name or url description: > Use the API to map the source name or partial domain name to the source URI that can be used when specifying the `sourceUri` filter in various API calls. The source name can also be a partial name. The returned value will contain an array of source candidates that match the input label. The returned list is sorted based on the number of articles that we have collected from this source. operationId: suggestSourcesFast parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prefix' responses: '200': description: Response content: application/json: schema: type: array items: type: object properties: uri: type: string dataType: type: string title: type: string /api/v1/suggestAuthorsFast: get: tags: - Autosuggest summary: Retrieve the author URI for a given author name description: > Use the API to map the author name to the author URI that can be used when specifying the `authorUri` filter in various API calls. Since it's possible that there are multiple authors with the same name you can also specify the source domain name in the query (e.g. 'amy more nytimes.com') to make sure that the returned author will come from the news source of interest. The returned value will contain an array of author candidates that match the input name. The returned list is sorted based on the number of articles that we have collected from the author. operationId: suggestAuthorsFast parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prefix' responses: '200': description: Response content: application/json: schema: type: array items: type: object properties: uri: type: string dataType: type: string title: type: string /api/v1/suggestLocationsFast: get: tags: - Autosuggest summary: Retrieve the location URI for a given location name description: > Use the API to map the location name (city or country) to a location URI that can be used when specifying the `locationUri` filter in various API calls. The location name can also be a partial name. The returned value will contain an array of location candidates that match the input label. operationId: suggestLocationsFast parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prefix' responses: '200': description: Response content: application/json: schema: type: array items: type: object properties: type: type: string wikiUri: type: string label: $ref: '#/components/schemas/Label' lat: type: integer long: type: integer /api/v1/eventType/suggestEventTypes: get: tags: - Autosuggest summary: Retrieve the event type URI for a given event type label/prefix description: > Use the API to map the event type label into the event type URI that can be used when specifying the `eventTypeUri` filter when searching for mentions. The label can also be a partial name. The returned value will contain an array of event types that match the input label. operationId: suggestEventTypes parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prefix' - $ref: '#/components/parameters/suggestPage' - $ref: '#/components/parameters/suggestCount' responses: '200': description: Response content: application/json: schema: type: array items: $ref: '#/components/schemas/EventType' /api/v1/eventType/suggestIndustries: get: tags: - Autosuggest summary: Retrieve the industry URI for a given industry label/prefix description: > Use the API to map the industry label into the industry URI that can be used when specifying the `industryUri` filter when searching for mentions. The label can also be a partial name. The returned value will contain an array of industries that match the input label. operationId: suggestIndustries parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prefix' - $ref: '#/components/parameters/suggestPage' - $ref: '#/components/parameters/suggestCount' responses: '200': description: Response content: application/json: schema: type: array items: type: object properties: uri: type: string label: type: string # # OTHER endpoints # # /api/v1/trends/getConceptTrendGroups: # get: # tags: # - Other # summary: The API can be used to obtain a list of currently top trending concepts (people, locations, organizations, or non-entities) # operationId: getConceptTrendGroups # parameters: # - $ref: '#/components/parameters/apiKey' # - name: conceptType # in: query # description: >- # Request trending of concepts of specified types # schema: # type: array # items: # type: string # enum: # - person # - org # - loc # - wiki # - name: source # in: query # description: >- # Source information from which to compute top trends. # schema: # type: string # enum: # - news # - social # - name: conceptCount # in: query # description: >- # Number of top trends to return. # schema: # type: integer # responses: # '200': # description: Response # content: # application/json: # schema: # type: object # properties: # uri: # type: array # items: # type: object # properties: # uri: # type: string # dataType: # type: string # title: # type: string /api/v1/getEventForText: get: tags: - Other summary: Identify the recent events that best match your input text description: > Given a paragraph or a longer text, the API endpoint can provide you the recent events that best match the text. The call is synchronous - the request is answered once the matching is computed, which can take several seconds. There is no request id to poll for. If the matching is not computed in about 30 seconds, an object with the `error` property is returned. Since the text can be long, the parameters can also be sent in the body of a POST request. When `resultType = info` (default) the returned object contains the `topStories` array with the best matching stories (clusters of articles in a single language). Each item contains the `storyUri`, the `eventUri` of the event to which the story belongs, the `storyInfo` object with the details about the story and `cosSim`, which is the cosine similarity between the text and the story. When `resultType = articles`, the returned value contains the list of articles in the best matching story (in the `articles` property of an object stored under the story URI). Only recent events (events from the last few days) can be matched. operationId: getEventForText parameters: - $ref: '#/components/parameters/apiKey' - name: text in: query required: true description: >- Text for which to find the most related events schema: type: string - name: lang in: query required: true description: >- The language in which the provided `text` is (ISO3 language code). schema: type: string example: eng - name: resultType in: query description: >- Choose what kind of information should be returned. `info` returns the list of the best matching stories and their events, `articles` returns the articles in the best matching story. schema: default: info type: string enum: - info - articles - name: topClustersCount in: query description: >- The number of the best matching stories to return (at most 50). schema: type: integer default: 10 maximum: 50 - name: minCosSim in: query description: >- Relevant when `resultType = articles`. The minimum cosine similarity that the best matching story has to have with the text in order to return its articles. If the similarity is lower, an object with the `info` property is returned instead. schema: type: number format: double default: 0.2 responses: '200': description: The best matching stories (`resultType = info`) or the articles in the best matching story (`resultType = articles`) content: application/json: schema: type: object properties: topStories: type: array items: type: object properties: storyUri: type: string eventUri: type: string storyInfo: $ref: '#/components/schemas/Story' cosSim: type: number format: double components: securitySchemes: api_key: type: apiKey name: apiKey in: query schemas: MultipleItems: type: object properties: totalResults: type: integer page: type: integer count: type: integer pages: type: integer MultipleItemsForVisualization: type: object properties: warning: type: string usedResults: type: integer totalResults: type: integer Label: type: object properties: eng: type: string TrendingScore: type: object properties: news: type: object properties: score: type: number format: double testPopFq: type: integer nullPopFq: type: integer CategoryTag: type: object properties: uri: type: string label: type: string wgt: type: integer Category: type: object properties: uri: type: string label: type: string parentUri: type: string childrenUris: type: array items: type: string trendingScore: $ref: '#/components/schemas/TrendingScore' count: type: integer Location: type: object properties: type: type: string label: $ref: '#/components/schemas/Label' Source: type: object properties: uri: type: string dataType: type: string title: type: string description: type: string location: $ref: '#/components/schemas/Location' locationValidated: type: boolean ranking: type: object properties: importanceRank: type: integer ConceptTag: type: object properties: uri: type: string type: type: string score: type: integer label: $ref: '#/components/schemas/Label' Concept: allOf: - $ref: '#/components/schemas/ConceptTag' - type: object properties: image: type: string synonyms: type: object trendingScore: $ref: '#/components/schemas/TrendingScore' location: $ref: '#/components/schemas/Location' Story: type: object properties: uri: type: string articleCount: type: integer lang: type: string avgCos: type: number format: double variance: type: number format: double eventUri: type: string title: type: string isUserSetTitle: type: boolean concepts: type: array items: $ref: '#/components/schemas/Concept' location: $ref: '#/components/schemas/Location' isUserSetLocation: type: boolean categories: type: array items: $ref: '#/components/schemas/CategoryTag' medoidArticle: $ref: '#/components/schemas/Article' storyDate: type: string isUserSetDate: type: boolean extractedDate: type: string averageDate: type: string images: type: array items: type: string commonDates: type: array items: type: object properties: amb: type: boolean imp: type: boolean date: type: string textStart: type: integer textEnd: type: integer freq: type: integer socialScore: type: number format: double wgt: type: integer Event: type: object properties: uri: type: string concepts: type: array items: $ref: '#/components/schemas/Concept' stories: type: array items: $ref: '#/components/schemas/Story' eventDate: type: string totalArticleCount: type: integer title: $ref: '#/components/schemas/Label' summary: $ref: '#/components/schemas/Label' location: $ref: '#/components/schemas/Location' categories: $ref: '#/components/schemas/CategoryTag' images: type: array items: type: string articleCounts: type: object properties: eng: type: integer socialScore: type: number format: double commonDates: type: array items: type: object properties: amb: type: boolean imp: type: boolean date: type: string textStart: type: integer textEnd: type: integer freq: type: integer wgt: type: integer Article: type: object properties: uri: type: string lang: type: string isDuplicate: type: boolean date: type: string time: type: string dateTime: type: string sim: type: number format: double url: type: string title: type: string body: type: string source: $ref: '#/components/schemas/Source' concepts: type: array items: $ref: '#/components/schemas/Concept' categories: type: array items: $ref: '#/components/schemas/CategoryTag' 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: $ref: '#/components/schemas/Location' 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 AnnotationSettings: type: object properties: pageRankSqThreshold: type: integer applyPageRankSqThreshold: type: boolean minPMentionGivenPhrase: type: integer maxMentionEntropy: type: integer maxTargetsPerMention: type: integer useLogLinkCounts: type: boolean candSelectionUseLinearizedPageRank: type: boolean candSelectionPageRankThreshold: type: integer candSelectionCosineWeight: type: integer candSelectionLinkCtxCosineWeight: type: integer candSelectionUseLinkProb: type: string semanticSimilarity: type: string secondaryAnnotLanguage: type: string minLinkFrequency: type: integer minLinkRelFrequency: type: integer nWordsToIgnoreFromList: type: integer extraVocabsToInclude: type: array items: type: object altLabelSetsToUse: type: array items: type: string AnnotationStats: type: object properties: iFrom: type: integer iTo: type: integer normForm: type: string synsetIds: type: array items: type: integer AnnotationLanguageCandidate: type: object properties: langNo: type: integer langCode: type: string percent: type: integer normScore: type: integer AnnotationLanguageDetails: type: object properties: topLangNo: type: integer topLangCode: type: string candidates: type: array items: $ref: '#/components/schemas/AnnotationLanguageCandidate' textBytes: type: integer validPrefBytes: type: integer isReliable: type: boolean chunks: type: array items: type: string Annotation: type: object properties: annotations: type: array items: type: object properties: url: type: string example: http://en.wikipedia.org/wiki/Microsoft title: type: string example: Microsoft lang: type: string example: eng secUrl: type: string example: http://en.wikipedia.org/wiki/Microsoft secTitle: type: string example: Microsoft secLang: type: string example: eng dbPediaIri: type: string example: http://dbpedia.org/resource/Microsoft dbPediaTypes: type: array items: type: string example: >- ["Agent", "Organisation", "Company"] type: type: string example: org wgt: type: number format: double example: 0.9 pageRank: type: number format: double example: 0.254 wikiDataItemId: type: string example: Q2283 wikiDataClassIds: type: array items: type: string support: type: array items: type: object properties: chFrom: type: integer example: 0 chTo: type: integer example: 8 pMentionGivenSurface: type: number format: double example: 0.255 text: type: string example: Microsoft wFrom: type: integer example: 0 wTo: type: integer example: 0 wikiLang: type: string example: en spaces: type: array items: type: string words: type: array items: type: string normWords: type: array items: type: string ranges: type: array items: type: integer minPageRank: type: integer maxDfThreshold: type: integer altLabelSetsUsed: type: array items: type: string linkSourcesAvailable: type: boolean verbs: type: array items: $ref: '#/components/schemas/AnnotationStats' nouns: type: array items: $ref: '#/components/schemas/AnnotationStats' adjectives: type: array items: $ref: '#/components/schemas/AnnotationStats' adverbs: type: array items: $ref: '#/components/schemas/AnnotationStats' timeTotalMs: type: integer timeAnnotationMs: type: integer timeBuildJsonMs: type: integer incIdxTimestampUtc: type: string fnRegIdx: type: string fnWikiData: type: string settings: $ref: '#/components/schemas/AnnotationSettings' language: type: string languageAutodetectInfo: type: string languageAutodetectDetails: $ref: '#/components/schemas/AnnotationLanguageDetails' CategorizationObject: type: object properties: label: type: string example: dmoz/Business/Investing/Stocks_and_Bonds score: type: number format: double example: 0.123 Categorization: type: object properties: categories: type: array items: $ref: '#/components/schemas/CategorizationObject' keywords: type: array items: type: object properties: keyword: type: string example: Investing wgt: type: number format: double example: 0.24 Similarity: type: object properties: similarity: type: number format: double Sentiment: type: object properties: avgSent: type: number format: double sentimentPerSent: type: array items: type: number format: double ExtractArticleInfoObject: type: object properties: url: type: string anchorText: type: string ExtractArticleInfoSource: type: object properties: url: type: string title: type: string ExtractArticleInfo: type: object properties: title: type: string body: type: string links: type: array items: $ref: '#/components/schemas/ExtractArticleInfoObject' videos: type: array items: $ref: '#/components/schemas/ExtractArticleInfoObject' date: type: string time: type: string datetime: type: string image: type: string keywords: type: array items: type: string description: type: string authors: type: array items: type: string twitterSite: type: string twitterSiteId: type: string fbSourceUrl: type: string fbAuthorUrl: type: string fbPages: type: array items: type: string source: $ref: '#/components/schemas/ExtractArticleInfoSource' url: type: string DetectLanguageObject: type: object properties: name: type: string code: type: string percent: type: integer score: type: integer DetectLanguageChunk: type: object properties: name: type: string code: type: string offset: type: integer bytes: type: integer DetectLanguage: type: object properties: reliable: type: boolean textBytes: type: integer languages: type: array items: $ref: '#/components/schemas/DetectLanguageObject' chunks: type: array items: $ref: '#/components/schemas/DetectLanguageChunk' Articles: type: object properties: articles: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: $ref: '#/components/schemas/Article' Events: type: object properties: events: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: $ref: '#/components/schemas/Event' UriWgtList: type: object properties: uriWgtList: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: type: string ConceptAggr: type: object properties: conceptAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: $ref: '#/components/schemas/Concept' KeywordAggr: type: object properties: keywordAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: type: object properties: keyword: type: string weight: type: number format: double LocAggr: type: object properties: keywordAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: type: object properties: count: type: string concept: type: object properties: uri: type: string type: type: string label: $ref: '#/components/schemas/Label' location: $ref: '#/components/schemas/Location' TimeAggr: type: object properties: timeAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: type: object properties: date: type: string count: type: integer SourceAggr: type: object properties: sourceAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: type: object properties: source: $ref: '#/components/schemas/Source' counts: type: object properties: frequency: type: integer ratio: type: number format: double SourceExAggr: type: object properties: sourceAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: type: object properties: source: $ref: '#/components/schemas/Source' counts: type: object properties: date: type: string count: type: integer DateMentionAggr: type: object properties: dateMentionAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: type: object properties: date: type: string count: type: integer ConceptGraph: type: object properties: conceptGraph: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: concepts: type: array items: $ref: '#/components/schemas/Concept' links: type: array items: type: object properties: uri1: type: string uri2: type: string score: type: integer CategoryAggr: type: object properties: categoryAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: $ref: '#/components/schemas/Category' RecentActivityArticles: type: object properties: recentActivityArticles: type: object properties: currTime: type: string activity: type: array items: type: object RecentActivityEvents: type: object properties: recentActivityEvents: type: object properties: currTime: type: string activity: type: array items: type: object EventType: type: object properties: uri: type: string label: type: string FrameworkItems: type: object properties: results: type: array items: type: object properties: uri: type: string label: type: string eventTypes: type: array items: type: string Mention: type: object properties: uri: type: string lang: type: string date: type: string time: type: string dateTime: type: string articleUri: type: string articleUrl: type: string articleTitle: type: string articleImageUrl: type: string sentence: type: string sentenceResolved: type: string sentenceIndex: type: integer eventType: $ref: '#/components/schemas/EventType' articleSentiment: type: number format: double sentenceSentiment: type: number format: double eventTypeSentiment: type: number format: double isDuplicate: type: boolean isDuplicateOf: type: string factLevel: type: string factLevelProb: type: number format: double location: $ref: '#/components/schemas/Location' frameworks: type: object properties: sdg: $ref: '#/components/schemas/EventType' sasb: $ref: '#/components/schemas/EventType' esg: $ref: '#/components/schemas/EventType' categories: type: array items: $ref: '#/components/schemas/CategoryTag' source: $ref: '#/components/schemas/Source' slots: type: array items: type: object properties: uri: type: string type: type: string label: type: string validSlots: type: boolean wgt: type: integer relevance: type: integer Mentions: type: object properties: mentions: allOf: - $ref: '#/components/schemas/MultipleItems' - type: object properties: results: type: array items: $ref: '#/components/schemas/Mention' EventTypeAggr: type: object properties: eventTypeAggr: allOf: - $ref: '#/components/schemas/MultipleItemsForVisualization' - type: object properties: results: type: array items: type: object properties: uri: type: string label: type: string count: type: integer RecentActivityMentions: type: object properties: recentActivityMentions: type: object properties: currTime: type: string newestUpdate: type: string oldestUpdate: type: string activity: type: array items: $ref: '#/components/schemas/Mention' parameters: apiKey: name: apiKey required: true in: query description: >- Your API key schema: type: string prefix: name: prefix in: query description: >- Determine the search condition. schema: type: string articlesPage: name: articlesPage in: query description: >- Determines the page of the results to return (starting from 1). Relevant when `resultType = articles`. schema: type: integer default: 1 example: articlesCount: name: articlesCount in: query description: >- Define how many articles (up to 100) will be returned. Relevant when `resultType = articles`. schema: default: 100 type: integer articlesSortBy: name: articlesSortBy in: query description: > 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), `cosSim` (closeness of the article to the centroid of the event it belongs to), `none` (no sorting). The values `socialScore` and `facebookShares` are no longer supported (social data is not collected anymore) - if provided, the results are returned unsorted. An unrecognized value is treated as `date`. Relevant when `resultType = articles`. schema: default: date type: string enum: - date - rel - sourceImportance - sourceImportanceRank - sourceAlexaGlobalRank - sourceAlexaCountryRank - cosSim - none articlesSortByRel: name: articlesSortBy in: query description: >- 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), `cosSim` (closeness of the article to the centroid of the event it belongs to), `none` (no sorting). The values `socialScore` and `facebookShares` are no longer supported (social data is not collected anymore) - if provided, the results are returned unsorted. An unrecognized value is treated as `date`. Relevant when `resultType = articles`. schema: default: rel type: string enum: - date - rel - sourceImportance - sourceImportanceRank - sourceAlexaGlobalRank - sourceAlexaCountryRank - cosSim - none articlesSortByAsc: name: articlesSortByAsc in: query description: >- Should the results be ordered in ascending order or descending order (default). Relevant when `resultType = articles`. schema: default: "false" type: boolean topicPage: name: topicPage in: query description: >- The definition of the topic page (a JSON object), provided directly in the request, instead of referencing a stored topic page with the `uri` parameter. Either `uri` or `topicPage` parameter has to be provided. schema: type: object maxDaysBack: name: maxDaysBack in: query description: >- The returned articles should not be older than this number of days. If the value is not specified, then the value set in the topic definition will be used. The parameter is ignored if `onlyAfterTm` is provided. schema: type: integer onlyAfterTm: name: onlyAfterTm in: query description: >- Only include in the results articles that were found after the specified date-time. The parameter should be in the format `YYYY-MM-DDTHH:MM:SS`, where the value should be in the UTC timezone. The value is very handy if you want to repeatedly call the API endpoint and make sure that you don't receive the same articles multiple times. schema: type: string maxDaysBackEvents: name: maxDaysBack in: query description: >- The returned events should not be older than this number of days. If the value is not specified, then the value set in the topic definition will be used. The parameter is ignored if `onlyAfterTm` is provided. schema: type: integer onlyAfterTmEvents: name: onlyAfterTm in: query description: >- Only include in the results the events that contain at least one story (a cluster of articles in a single language) that was created after the specified date-time. The parameter should be in the format `YYYY-MM-DDTHH:MM:SS`, where the value should be in the UTC timezone. schema: type: string eventsPage: name: eventsPage in: query description: >- Determines the page of the results to return (starting from 1). Relevant when `resultType = events`. schema: type: integer default: 1 example: eventsCount: name: eventsCount in: query description: >- Define how many events (up to 50) will be returned. Relevant when `resultType = events`. schema: default: 50 type: integer eventsSortBy: name: eventsSortBy in: query description: >- Set how you would like to sort your results. `date` (by event date), `rel` (relevance to the query), `size` (number of articles), `none` (no sorting). The value `socialScore` is no longer supported (social data is not collected anymore) - if provided, the results are returned unsorted. Relevant when `resultType = events`. schema: default: date type: string enum: - date - rel - size - none eventsSortByRel: name: eventsSortBy in: query description: >- Set how you would like to sort your results. `date` (by event date), `rel` (relevance to the query), `size` (number of articles), `none` (no sorting). The value `socialScore` is no longer supported (social data is not collected anymore) - if provided, the results are returned unsorted. Relevant when `resultType = events`. schema: default: rel type: string enum: - date - rel - size - none eventsSortByAsc: name: eventsSortByAsc in: query description: >- Should the results be ordered in ascending order or descending order (default) based on the sorting criteria. Relevant when `resultType = events`. schema: default: "false" type: boolean queryArticles: name: query in: query description: >- 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 the query parameters specified directly (`keyword`, `conceptUri`, `sourceUri`, `categoryUri`, etc) will be ignored. schema: type: object properties: conceptUri: type: array items: type: string sourceUri: type: array items: type: string sourceLocationUri: type: array items: type: string locationUri: type: array items: type: string eventQuery: name: query in: query description: >- 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-events#advanced-query-language) format. If you specify the `query` parameter, then the query parameters specified directly (`keyword`, `conceptUri`, `sourceUri`, `categoryUri`, etc) will be ignored. schema: type: object properties: conceptUri: type: array items: type: string sourceUri: type: array items: type: string sourceLocationUri: type: array items: type: string locationUri: type: array items: type: string keywordEvent: name: keyword in: query description: >- Find events in which news articles mention the specified keyword or a phrase. If you specify multiple `keyword` parameters, then only events with articles that mention all of them will be returned, unless you specify `keywordOper` parameter and set it to 'or'. schema: type: array items: type: string example: Barack Obama ignoreKeywordEvent: name: ignoreKeyword in: query description: >- Ignore events in which news articles mention the specified keyword or phrase. If you specify multiple `ignoreKeyword` parameters, then events with articles that mention any of these keywords will be ignored. schema: type: array items: type: string example: Donald Trump conceptUriEvent: name: conceptUri in: query description: >- Find events for which the concept with concept uri is important. You can specify up to 50 concepts in a single search. If multiple `conceptUri` parameters are provided, then only events that are about all specified concepts will be returned, unless you specify `conceptOper` parameter and set it to 'or'. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggConcepts) to get concept URI value for a specified concept label. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/World_Health_Organization ignoreConceptUriEvent: name: ignoreConceptUri in: query description: >- Ignore events for which the concept with concept uri is important. You can specify up to 50 concepts in a single search. If you specify multiple `ignoreConceptUri` parameters, then events that mention any of them will be ignored. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggConcepts) to get value for a specified concept label. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/World_Health_Organization categoryUriEvent: name: categoryUri in: query description: >- Find events that are about a particular category. You can specify up to 20 categories in a single search. If multiple `categoryUri` parameters are provided, then events that are about any of the specified categories will be returned, unless you specify `categoryOper` parameter and set it to 'and'. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggCategories) to get value for a specified category name. schema: type: array items: type: string example: dmoz/Business/Accounting ignoreCategoryUriEvent: name: ignoreCategoryUri in: query description: >- Ignore events that are about a particular category. You can specify up to 20 categories in a single search. If you specify multiple `ignoreCategoryUri` parameters, then events that mention any of them will be ignored. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggCategories) to get value for a specified category name. schema: type: array items: type: string example: dmoz/Business/Accounting sourceUriEvent: name: sourceUri in: query description: >- Find events that contain one or more articles that have been written by a specific news source. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSources) to get value for a source name. schema: type: array items: type: string example: bbc.co.uk ignoreSourceUriEvent: name: ignoreSourceUri in: query description: >- Ignore events that contain one or more articles that have been written by a news source. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSources) to get value for a source name. schema: type: array items: type: string example: bbc.co.uk sourceLocationUriEvent: name: sourceLocationUri in: query description: >- Find events that contain one or more articles by news sources located at the given geographic location (city or a country). Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/Germany ignoreSourceLocationUriEvent: name: ignoreSourceLocationUri in: query description: >- Ignore events that contain one or more articles by news sources located at the given geographic location (city or a country). Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/Olsberg,_Germany sourceGroupUriEvent: name: sourceGroupUri in: query description: >- Find events that contain one or more articles by news sources that are assigned to the predefined group of news sources. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSourceGroups) to get value for a source group or find the uri. schema: type: array items: type: string example: general/ERtop10 ignoreSourceGroupUriEvent: name: ignoreSourceGroupUri in: query description: >- Ignore events that contain one or more articles by news sources that are assigned to the specified group of news sources. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSourceGroups) to get value for a source group or find the uri. schema: type: array items: type: string example: general/ERtop10 authorUriEvent: name: authorUri in: query description: >- Find events that contain articles that were written by a particular author. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggAuthors) to get value for author uri based on the author name (and potentially source url). schema: type: array items: type: string example: mark_mazzetti@nytimes.com ignoreAuthorUriEvent: name: ignoreAuthorUri in: query description: >- Ignore events that contain articles, which were written by a particular author. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggAuthors) to get value for author uri based on the author name (and potentially source url). schema: type: array items: type: string example: mark_mazzetti@nytimes.com locationUriEvent: name: locationUri in: query description: >- Find events that occurred at a particular geographic location. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get URI value for a given location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/United_States ignoreLocationUriEvent: name: ignoreLocationUri in: query description: >- Ignore events that occurred at a particular geographic location. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get URI value for a given location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/United_States langEvent: name: lang in: query description: >- Find events that contain articles in the specified language(s). schema: type: array items: type: string enum: - eng - spa - deu - zho - slv - cat - por - ita - fra - rus - ara - tur - hrv - srp - ind - ces - slk - pol - eus - hun - nld - swe - fin - dan - ell - ron - bul - ukr - fas - hin - urd - vie example: eng ignoreLangEvent: name: ignoreLang in: query description: >- Ignore events that contain articles in the specified language(s). schema: type: array items: type: string enum: - eng - spa - deu - zho - slv - cat - por - ita - fra - rus - ara - tur - hrv - srp - ind - ces - slk - pol - eus - hun - nld - swe - fin - dan - ell - ron - bul - ukr - fas - hin - urd - vie example: deu keywordArticle: name: keyword in: query description: > 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'. schema: type: array items: type: string example: Barack Obama ignoreKeywordArticle: name: ignoreKeyword in: query description: > 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. schema: type: array items: type: string example: Donald Trump conceptUriArticle: name: conceptUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggConcepts) to get concept URI value for a specified concept label. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/World_Health_Organization ignoreConceptUriArticle: name: ignoreConceptUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggConcepts) to get value for a specified concept label. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/World_Health_Organization categoryUriArticle: name: categoryUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggCategories) to get value for a specified category name. schema: type: array items: type: string example: dmoz/Business/Accounting ignoreCategoryUriArticle: name: ignoreCategoryUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggCategories) to get value for a specified category name. schema: type: array items: type: string example: dmoz/Business/Accounting sourceUriArticle: name: sourceUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggSources) to get value for a source name. schema: type: array items: type: string example: bbc.co.uk ignoreSourceUriArticle: name: ignoreSourceUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggSources) to get value for a source name. schema: type: array items: type: string example: bbc.co.uk sourceLocationUriArticle: name: sourceLocationUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/Germany ignoreSourceLocationUriArticle: name: ignoreSourceLocationUri in: query description: > 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](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/Olsberg,_Germany sourceGroupUriArticle: name: sourceGroupUri in: query description: > Find articles that were published by news sources that are assigned to some predefined group of news sources. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSourceGroups) to get value for a source group or find the uri. schema: type: array items: type: string example: general/ERtop10 ignoreSourceGroupUriArticle: name: ignoreSourceGroupUri in: query description: > Ignore articles that were published by news sources that are assigned to some predefined group of news sources. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSourceGroups) to get value for a source group or find the uri. schema: type: array items: type: string example: general/ERtop10 authorUriArticle: name: authorUri in: query description: >- Find articles that were written by a particular author. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggAuthors) to get value for author uri based on the author name (and potentially source url). schema: type: array items: type: string example: mark_mazzetti@nytimes.com ignoreAuthorUriArticle: name: ignoreAuthorUri in: query description: >- Ignore articles that were written by a particular author. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggAuthors) to get value for author uri based on the author name (and potentially source url). schema: type: array items: type: string example: mark_mazzetti@nytimes.com locationUriArticle: name: locationUri in: query description: >- Find articles that describe something that occured at a particular location (based on the location mentioned in the dateline). Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/United_States ignoreLocationUriArticle: name: ignoreLocationUri in: query description: >- Ignore articles that describe something that occured at a particular location (based on the location mentioned in the dateline). Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/United_States langArticle: name: lang in: query description: >- Find articles in the specific language(s). If not specified, all languages will be included. You can specify at most 5 languages in a single search. schema: type: array items: type: string enum: - eng - spa - deu - zho - slv - cat - por - ita - fra - rus - ara - tur - hrv - srp - ind - ces - slk - pol - eus - hun - nld - swe - fin - dan - ell - ron - bul - ukr - fas - hin - urd - vie example: eng ignoreLangArticle: name: ignoreLang in: query description: >- Ignore articles in the specified language(s). You can specify at most 5 languages in a single search. schema: type: array items: type: string enum: - eng - spa - deu - zho - slv - cat - por - ita - fra - rus - ara - tur - hrv - srp - ind - ces - slk - pol - eus - hun - nld - swe - fin - dan - ell - ron - bul - ukr - fas - hin - urd - vie example: deu dateStartArticle: name: dateStart in: query description: >- The starting date on or after the articles of interest were published. schema: type: string example: "2018-01-03" dateEndArticle: name: dateEnd in: query description: >- The last date on which the articles of interest were published. schema: type: string example: "2018-01-10" dateStartEvent: name: dateStart in: query description: >- Limit the events to those that occured on or after this date. The date of the event is extracted from the news articles about the event and are potentially quite different than the dates when the articles about the event were published. schema: type: string example: "2018-01-03" dateEndEvent: name: dateEnd in: query description: >- Limit the events to those that occured before or on this date. The date of the event is extracted from the news articles about the event and are potentially quite different than the dates when the articles about the event were published. schema: type: string example: "2018-01-10" reportingDateStart: name: reportingDateStart in: query description: >- Limit the events to those for which the reporting date was on or after this date. The reporting date is computed by analyzing all the dates when the articles about an event were published and computing the average value. schema: type: string example: "2018-01-03" reportingDateEnd: name: reportingDateEnd in: query description: >- Limit the events to those for which the reporting date was before or on this date. The reporting date is computed by analyzing all the dates when the articles about an event were published and computing the average value. schema: type: string example: "2018-01-10" dateMentionStart: name: dateMentionStart in: query description: >- Ignore events (that contain one or more articles) or articles that explicitly mention a date that is equal or greater than `dateMentionStart`. schema: type: string example: "2018-01-10" dateMentionEnd: name: dateMentionEnd in: query description: >- Ignore events (that contain one or more articles) or articles that explicitly mention a date that is lower or equal to `dateMentionEnd`. schema: type: string example: "2018-01-10" keywordLoc: name: keywordLoc in: query description: >- Where should we look when searching using the keywords provided by the `keyword` parameter. `body` (default) searches only in the article body, `title` only in the article title and `title,body` in both. schema: type: string default: "body" enum: - body - title - title,body keywordOperArticle: name: keywordOper in: query description: >- 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. schema: type: string default: "and" enum: - and - or keywordOperEvent: name: keywordOper in: query description: >- 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 about an event; if 'or' then an event will be returned if it's articles mentions any of the provided keywords. schema: type: string default: "and" enum: - and - or ignoreKeywordLoc: name: ignoreKeywordLoc in: query description: >- Where should we look when searching using the keywords provided by the `ignoreKeyword` parameter. `body` (default) searches only in the article body, `title` only in the article title and `title,body` in both. schema: type: string default: "body" enum: - body - title - title,body keywordSearchMode: name: keywordSearchMode in: query description: >- The search mode used for the values provided in the `keyword` parameter. `phrase` (default) treats each keyword as a phrase (the words have to appear together), `exact` treats the keyword as a query expression that can contain Boolean operators and proximity operators (e.g. `(biden or "Barack Obama" not Michelle) near/3 Trump`), `simple` treats the keyword as a free text, where the results are ranked based on how well they match the provided words. schema: type: string default: "phrase" enum: - simple - exact - phrase ignoreKeywordSearchMode: name: ignoreKeywordSearchMode in: query description: >- The search mode used for the values provided in the `ignoreKeyword` parameter. See `keywordSearchMode` for the description of the values. schema: type: string default: "phrase" enum: - simple - exact - phrase sourceOper: name: sourceOper in: query description: >- If multiple sources are provided with the `sourceUri` parameter, what should be the Boolean operator used between them. schema: type: string default: "or" enum: - and - or sourceGroupOper: name: sourceGroupOper in: query description: >- If multiple source groups are provided with the `sourceGroupUri` parameter, what should be the Boolean operator used between them. schema: type: string default: "or" enum: - and - or authorOper: name: authorOper in: query description: >- If multiple authors are provided with the `authorUri` parameter, what should be the Boolean operator used between them. schema: type: string default: "or" enum: - and - or conceptOperArticle: name: conceptOper in: query description: >- 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. schema: type: string default: "and" enum: - and - or conceptOperEvent: name: conceptOper in: query description: >- 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 event; if 'or' then an event will be returned if it mentions any of the provided concepts. schema: type: string default: "and" enum: - and - or categoryOperArticle: name: categoryOper in: query description: >- 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. schema: type: string default: "or" enum: - and - or categoryOperEvent: name: categoryOper in: query description: >- 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 event; if 'or' then an event will be returned if it mentions any of the provided categories. schema: type: string default: "or" enum: - and - or startSourceRankPercentile: name: startSourceRankPercentile in: query description: >- 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. schema: type: integer default: "0" endSourceRankPercentile: name: endSourceRankPercentile in: query description: >- 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. schema: type: integer default: "100" minSentimentArticle: name: minSentiment in: query description: >- 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. schema: type: number format: double minimum: -1 maximum: 1 maxSentimentArticle: name: maxSentiment in: query description: >- 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. schema: type: number format: double minimum: -1 maximum: 1 minSentimentEvent: name: minSentiment in: query description: >- the minimum value of the sentiment, the event 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 events covered in English, since the sentiment can only be computed for English language. schema: type: number format: double minimum: -1 maximum: 1 maxSentimentEvent: name: maxSentiment in: query description: >- the maximum value of the sentiment, the event 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 events covered in English, since the sentiment can only be computed for English language. schema: type: number format: double minimum: -1 maximum: 1 isDuplicateFilter: name: isDuplicateFilter in: query description: >- Some articles can be duplicates of other articles. What should be done with them. `skipDuplicates` (skip the articles that are duplicates of other articles), `keepOnlyDuplicates` (return only the duplicate articles), `keepAll` (no filtering, default). schema: type: string default: "keepAll" enum: - skipDuplicates - keepOnlyDuplicates - keepAll hasDuplicateFilter: name: hasDuplicateFilter in: query description: >- Some articles are later copied by others. What should be done with such articles. `skipHasDuplicates` (skip the articles that have been later copied by others), `keepOnlyHasDuplicates` (return only the articles that have been later copied by others), `keepAll` (no filtering, default). schema: type: string default: "keepAll" enum: - skipHasDuplicates - keepOnlyHasDuplicates - keepAll eventFilter: name: eventFilter in: query description: >- Some articles describe a known event and some don't. This filter allows you to filter the resulting articles based on this criteria. schema: type: string default: "keepAll" enum: - skipArticlesWithoutEvent - keepOnlyArticlesWithoutEvent - keepAll dataType: name: dataType in: query description: >- What data types should we search? news content (default, `news`), press releases (`pr`) or blogs (`blog`). schema: type: array default: news items: type: string enum: - news - pr - blog minArticlesInEvent: name: minArticlesInEvent in: query description: >- Find events that have been reported in at least `minArticlesInEvent` articles (regardless of language). schema: type: integer maxArticlesInEvent: name: maxArticlesInEvent in: query description: >- Find events that have not been reported in more than `maxArticlesInEvent` articles (regardless of language) schema: type: integer includeArticleTitle: name: includeArticleTitle in: query description: >- Set this parameter to true to include the article title in the response. schema: type: boolean default: "true" includeArticleBasicInfo: name: includeArticleBasicInfo in: query description: >- Set this parameter to true to include the core article information in the response. schema: type: boolean default: "true" includeArticleBody: name: includeArticleBody in: query description: >- Set this parameter to true to include the article body in the response. schema: type: boolean default: "true" includeArticleEventUri: name: includeArticleEventUri in: query description: >- Set this parameter to true to include the uri of the event (to which the article belongs) in the response. schema: type: boolean default: "true" includeArticleSocialScore: name: includeArticleSocialScore in: query description: >- Set this parameter to true to include the information about how many times the article was shared on different social media. schema: type: boolean default: "false" includeArticleSentiment: name: includeArticleSentiment in: query description: >- Set this parameter to true to include the article sentiment in the response (value will be non-null only for English articles). schema: type: boolean default: "true" includeArticleConcepts: name: includeArticleConcepts in: query description: >- Set this parameter to true to include the article concepts in the response. schema: type: boolean default: "false" includeArticleCategories: name: includeArticleCategories in: query description: >- Set this parameter to true to include the article categories in the response. schema: type: boolean default: "false" includeArticleLocation: name: includeArticleLocation in: query description: >- Set this parameter to true to include the article location in the response. schema: type: boolean default: "false" includeArticleImage: name: includeArticleImage in: query description: >- Set this parameter to true to include the article image in the response. schema: type: boolean default: "true" includeArticleAuthors: name: includeArticleAuthors in: query description: >- Set this parameter to true to include the article authors in the response. schema: type: boolean default: "true" includeArticleVideos: name: includeArticleVideos in: query description: >- Set this parameter to true to include the article videos in the response. schema: type: boolean default: "false" includeArticleLinks: name: includeArticleLinks in: query description: >- Set this parameter to true to include the article links in the response. schema: type: boolean default: "false" includeArticleExtractedDates: name: includeArticleExtractedDates in: query description: >- Set this parameter to true to include article extracted dates in the response. schema: type: boolean default: "false" includeArticleDuplicateList: name: includeArticleDuplicateList in: query description: >- Set this parameter to true to include the list of duplicate articles in the response. schema: type: boolean default: "false" includeArticleOriginalArticle: name: includeArticleOriginalArticle in: query description: >- Set this parameter to true to include the original article in the response. schema: type: boolean default: "false" articleBodyLen: name: articleBodyLen in: query description: >- Set the size of the article body that'll be returned in the response. Use -1 for full article body. schema: type: integer default: -1 includeEventTitle: name: includeEventTitle in: query description: >- Set this parameter to true to include the event title in the response. schema: type: boolean default: "true" includeEventSummary: name: includeEventSummary in: query description: >- Set this parameter to true to include the event summary in the response. schema: type: boolean default: "true" includeEventSocialScore: name: includeEventSocialScore in: query description: >- Set this parameter to true to include the event social score in the response. schema: type: boolean default: "false" includeEventSentiment: name: includeEventSentiment in: query description: >- Set this parameter to true to include the event sentiment in the response. schema: type: boolean default: "true" includeEventLocation: name: includeEventLocation in: query description: >- Set this parameter to true to include the event location in the response. schema: type: boolean default: "true" includeEventDate: name: includeEventDate in: query description: >- Set this parameter to true to include the event date in the response. schema: type: boolean default: "true" includeEventArticleCounts: name: includeEventArticleCounts in: query description: >- Set this parameter to true to include the article counts for events in the response. schema: type: boolean default: "true" includeEventConcepts: name: includeEventConcepts in: query description: >- Set this parameter to true to include the event concepts in the response. schema: type: boolean default: "true" includeEventCategories: name: includeEventCategories in: query description: >- Set this parameter to true to include the event categories in the response. schema: type: boolean default: "true" includeEventCommonDates: name: includeEventCommonDates in: query description: >- Set this parameter to true to include the event commmon dates in the response. schema: type: boolean default: "false" includeEventStories: name: includeEventStories in: query description: >- Set this parameter to true to include the event stories in the response. schema: type: boolean default: "false" eventImageCount: name: eventImageCount in: query description: >- Define how many images you would like to have in the response. schema: type: integer default: "0" includeStoryBasicStats: name: includeStoryBasicStats in: query description: >- Set this parameter to true to include story basic stats in the response. schema: type: boolean default: "true" includeStoryTitle: name: includeStoryTitle in: query description: >- Set this parameter to true to include the story title in the response. schema: type: boolean default: "false" includeStoryLocation: name: includeStoryLocation in: query description: >- Set this parameter to true to include the story location in the response. schema: type: boolean default: "true" includeStoryDate: name: includeStoryDate in: query description: >- Set this parameter to true to include the story date in the response. schema: type: boolean default: "false" includeStoryConcepts: name: includeStoryConcepts in: query description: >- Set this parameter to true to include the story concepts in the response. schema: type: boolean default: "false" includeStoryCategories: name: includeStoryCategories in: query description: >- Set this parameter to true to include the story categories in the response. schema: type: boolean default: "false" includeStoryMedoidArticle: name: includeStoryMedoidArticle in: query description: >- Set this parameter to true to include story medoid article in the response. schema: type: boolean default: "false" includeStoryCommonDates: name: includeStoryCommonDates in: query description: >- Set this parameter to true to include story common dates in the response. schema: type: boolean default: "false" storyImageCount: name: storyImageCount in: query description: >- Define how many images you would like to have in the response. schema: type: integer default: 0 includeSourceTitle: name: includeSourceTitle in: query description: >- Set this parameter to true to include the source title in the response. schema: type: boolean default: "true" includeSourceDescription: name: includeSourceDescription in: query description: >- Set this parameter to true to include the source description in the response. schema: type: boolean default: "false" includeSourceLocation: name: includeSourceLocation in: query description: >- Set this parameter to true to include the source location in the response. schema: type: boolean default: "false" includeSourceRanking: name: includeSourceRanking in: query description: >- Set this parameter to true to include the source ranking in the response. schema: type: boolean default: "false" includeConceptLabel: name: includeConceptLabel in: query description: >- Set this parameter to true to include the concept label in the response. schema: type: boolean default: "true" includeConceptImage: name: includeConceptImage in: query description: >- Set this parameter to true to include the concept image in the response. schema: type: boolean default: "false" includeConceptDescription: name: includeConceptDescription in: query description: >- Set this parameter to true to include the concept description in the response. schema: type: boolean default: "false" includeConceptSynonyms: name: includeConceptSynonyms in: query description: >- Set this parameter to true to include the concept synonyms in the response. schema: type: boolean default: "false" includeConceptTrendingScore: name: includeConceptTrendingScore in: query description: >- Set this parameter to true to include concept trending score in the response. schema: type: boolean default: "false" conceptLang: name: conceptLang in: query description: >- Define the language of the concept label. schema: type: string default: eng includeCategoryParentUri: name: includeCategoryParentUri in: query description: >- Set this parameter to true to include category parent uri in the response. schema: type: boolean default: "false" includeCategoryChildrenUris: name: includeCategoryChildrenUris in: query description: >- Set this parameter to true to include category children uris in the response. schema: type: boolean default: "false" includeCategoryTrendingScore: name: includeCategoryTrendingScore in: query description: >- Set this parameter to true to include category trending score in the response. schema: type: boolean default: "false" includeLocationGeoLocation: name: includeLocationGeoLocation in: query description: >- Set to true to include the geo location (latitude, longitude) for items that are locations schema: type: boolean default: "false" includeLocationPopulation: name: includeLocationPopulation in: query description: >- Set to true to include the population size of the location schema: type: boolean default: "false" includeLocationGeoNamesId: name: includeLocationGeoNamesId in: query description: >- Set to true to include the GeoNames id of the location schema: type: boolean default: "false" includeLocationCountryArea: name: includeLocationCountryArea in: query description: >- Set to true to include the are of the location in squared km. schema: type: boolean default: "false" includeLocationCountryContinent: name: includeLocationCountryContinent in: query description: >- Set to true to get the continent of the country for location objects. schema: type: boolean default: "false" includeArticleUrl: name: includeArticleUrl in: query description: >- Set this parameter to true to include the article url in the response. schema: type: boolean default: "true" includeArticleStoryUri: name: includeArticleStoryUri in: query description: >- Set this parameter to true to include the uri of the story (cluster of articles in a single language, to which the article belongs) in the response. schema: type: boolean default: "false" includeEventInfoArticle: name: includeEventInfoArticle in: query description: >- Set this parameter to true to include for each language the article from which the title and the summary of the event were extracted. schema: type: boolean default: "false" includeStorySummary: name: includeStorySummary in: query description: >- Set this parameter to true to include the story summary in the response. schema: type: boolean default: "false" includeStoryInfoArticle: name: includeStoryInfoArticle in: query description: >- Set this parameter to true to include the article from which the title and the summary of the story were extracted. schema: type: boolean default: "false" includeStorySocialScore: name: includeStorySocialScore in: query description: >- Set this parameter to true to include the story social score in the response. schema: type: boolean default: "false" includeSourceImage: name: includeSourceImage in: query description: >- Set this parameter to true to include the images associated with the source in the response. schema: type: boolean default: "false" includeSourceSocialMedia: name: includeSourceSocialMedia in: query description: >- Set this parameter to true to include the social media accounts used by the source in the response. schema: type: boolean default: "false" includeLocationLabel: name: includeLocationLabel in: query description: >- Set to true to include the label of the location schema: type: boolean default: "true" includeLocationWikiUri: name: includeLocationWikiUri in: query description: >- Set to true to include the Wikipedia URI of the location schema: type: boolean default: "false" includeLocationCountryDetails: name: includeLocationCountryDetails in: query description: >- Set to true to include additional details about the country for location objects that are countries. schema: type: boolean default: "false" includeLocationPlaceFeatureCode: name: includeLocationPlaceFeatureCode in: query description: >- Set to true to include the GeoNames feature code for location objects that are places. schema: type: boolean default: "false" includeLocationPlaceCountry: name: includeLocationPlaceCountry in: query description: >- Set to true to include the information about the country in which the place is located, for location objects that are places. schema: type: boolean default: "true" suggestPage: name: page in: query description: >- Determines the page of the suggestions to return (starting from 1). schema: type: integer default: 1 suggestCount: name: count in: query description: >- The number of suggestions to return. schema: type: integer default: 20 includeEventTypes: name: includeEventTypes in: query description: >- Set this parameter to true to include for each item also the list of URIs of the event types that are associated with it. schema: type: boolean default: "false" mentionsPage: name: mentionsPage in: query description: >- Determines the page of the results to return (starting from 1). Relevant when `resultType = mentions`. schema: type: integer default: 1 mentionsCount: name: mentionsCount in: query description: >- Define how many mentions (up to 100) will be returned. Relevant when `resultType = mentions`. schema: default: 100 type: integer maximum: 100 mentionsSortBy: name: mentionsSortBy in: query description: > Choose the criteria for sorting the mentions. `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), `sourceAlexaCountryRank` (country rank of the news source), `none` (no sorting). Relevant when `resultType = mentions`. schema: default: date type: string enum: - date - rel - sourceImportance - sourceImportanceRank - sourceAlexaGlobalRank - sourceAlexaCountryRank - none mentionsSortByAsc: name: mentionsSortByAsc in: query description: >- Should the results be ordered in ascending order or descending order (default). Relevant when `resultType = mentions`. schema: default: "false" type: boolean queryMentions: name: query in: query description: >- Query object with one or more search conditions. The object has to contain the `$query` property with the search conditions (the same conditions as the ones that can be provided as individual parameters, which can be combined using `$and`, `$or` and `$not`) and can contain the `$filter` property with the filters (`startSourceRankPercentile`, `endSourceRankPercentile`, `minSentiment`, `maxSentiment`, `minSentenceIndex`, `maxSentenceIndex`, `showDuplicates`). If you specify the `query` parameter, then the search conditions and filters must not be specified also as individual parameters (`keyword`, `conceptUri`, `eventTypeUri`, etc). schema: type: object eventTypeUriMention: name: eventTypeUri in: query description: > Find mentions that report about the specified type of event. Since each mention has a single event type, if multiple `eventTypeUri` parameters are provided, mentions of any of the specified event types will be returned. Use the `suggestEventTypes` endpoint to get the event type URI for a given label. schema: type: array items: type: string ignoreEventTypeUriMention: name: ignoreEventTypeUri in: query description: > Ignore mentions that report about the specified type of event. If you specify multiple `ignoreEventTypeUri` parameters, then mentions of any of the specified event types will be ignored. schema: type: array items: type: string keywordMention: name: keyword in: query description: > Find mentions that contain the specified keyword or a phrase. If you specify multiple `keyword` parameters, then only mentions that contain all of them will be returned, unless you specify `keywordOper` parameter and set it to 'or'. schema: type: array items: type: string example: acquisition ignoreKeywordMention: name: ignoreKeyword in: query description: > Ignore mentions that contain the specified keyword or phrase. If you specify multiple `ignoreKeyword` parameters, then mentions that contain any of these keywords will be ignored. schema: type: array items: type: string conceptUriMention: name: conceptUri in: query description: > Find mentions in which the concept with the concept uri is mentioned. If multiple `conceptUri` parameters are provided, then only mentions that mention all specified concepts will be returned, unless you specify `conceptOper` parameter and set it to 'or'. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggConcepts) to get concept URI value for a specified concept label. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/Microsoft ignoreConceptUriMention: name: ignoreConceptUri in: query description: > Ignore mentions in which the concept with the concept uri is mentioned. If you specify multiple `ignoreConceptUri` parameters then mentions that mention any of them will be ignored. schema: type: array items: type: string categoryUriMention: name: categoryUri in: query description: > Find mentions from the articles that are assigned to a particular category. If multiple `categoryUri` parameters are provided, then mentions from articles in any of the specified categories will be returned, unless you specify `categoryOper` parameter and set it to 'and'. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggCategories) to get value for a specified category name. schema: type: array items: type: string ignoreCategoryUriMention: name: ignoreCategoryUri in: query description: > Ignore mentions from the articles that are assigned to a particular category. If you specify multiple `ignoreCategoryUri` parameters then mentions from articles in any of the specified categories will be ignored. schema: type: array items: type: string industryUriMention: name: industryUri in: query description: > Find mentions that relate to companies in a certain industry. Use the `suggestIndustries` endpoint to get the industry URI for a given label. schema: type: array items: type: string ignoreIndustryUriMention: name: ignoreIndustryUri in: query description: > Ignore mentions that relate to companies in any of the provided industries. schema: type: array items: type: string sdgUriMention: name: sdgUri in: query description: > Find mentions of the event types that are associated with a particular UN Sustainable Development Goal (SDG). If multiple `sdgUri` parameters are provided, then mentions related to any of the specified SDGs will be returned. Use the `sdg/getItems` endpoint to get the list of valid URIs. schema: type: array items: type: string ignoreSdgUriMention: name: ignoreSdgUri in: query description: > Ignore mentions of the event types that are associated with a particular SDG. schema: type: array items: type: string sasbUriMention: name: sasbUri in: query description: > Find mentions of the event types that are associated with a particular SASB category. If multiple `sasbUri` parameters are provided, then mentions related to any of the specified SASB categories will be returned. Use the `sasb/getItems` endpoint to get the list of valid URIs. schema: type: array items: type: string ignoreSasbUriMention: name: ignoreSasbUri in: query description: > Ignore mentions of the event types that are associated with a particular SASB category. schema: type: array items: type: string esgUriMention: name: esgUri in: query description: > Find mentions of the event types that are associated with a particular ESG category. If multiple `esgUri` parameters are provided, then mentions related to any of the specified ESG categories will be returned. Use the `esg/getItems` endpoint to get the list of valid URIs. schema: type: array items: type: string example: esg/environment ignoreEsgUriMention: name: ignoreEsgUri in: query description: > Ignore mentions of the event types that are associated with a particular ESG category. schema: type: array items: type: string sourceUriMention: name: sourceUri in: query description: > Find mentions from the articles that have been published by a news source. If you specify multiple `sourceUri` parameters, then mentions from any of the specified sources will be returned. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSources) to get value for a source name. schema: type: array items: type: string example: bbc.co.uk ignoreSourceUriMention: name: ignoreSourceUri in: query description: > Ignore mentions from the articles that have been published by a news source. If you specify multiple `ignoreSourceUri` parameters, then mentions from any of the specified sources will be ignored. schema: type: array items: type: string sourceLocationUriMention: name: sourceLocationUri in: query description: > Find mentions from the articles that were published by news sources located at the given geographic location (city or country). If you specify multiple `sourceLocationUri` parameters, then mentions from sources from any of the specified locations will be returned. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/Germany ignoreSourceLocationUriMention: name: ignoreSourceLocationUri in: query description: > Ignore mentions from the articles that were published by news sources located at the given geographic location (city or country). schema: type: array items: type: string sourceGroupUriMention: name: sourceGroupUri in: query description: > Find mentions from the articles that were published by news sources that are assigned to some predefined group of news sources. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggSourceGroups) to get value for a source group or find the uri. schema: type: array items: type: string example: general/ERtop10 ignoreSourceGroupUriMention: name: ignoreSourceGroupUri in: query description: > Ignore mentions from the articles that were published by news sources that are assigned to some predefined group of news sources. schema: type: array items: type: string locationUriMention: name: locationUri in: query description: >- Find mentions that describe something that occurred at a particular location (city or country). If you specify multiple `locationUri` parameters, then mentions related to any of the specified locations will be returned. Check [autosuggest methods](https://eventregistry.org/documentation?tab=suggLocations) to get value for a location name. schema: type: array items: type: string example: http://en.wikipedia.org/wiki/United_States ignoreLocationUriMention: name: ignoreLocationUri in: query description: >- Ignore mentions that describe something that occurred at a particular location (city or country). schema: type: array items: type: string langMention: name: lang in: query description: >- Find mentions in the specific language(s) (ISO3 language codes). If not specified, all languages will be included. schema: type: array items: type: string example: eng ignoreLangMention: name: ignoreLang in: query description: >- Ignore mentions in the specified language(s) (ISO3 language codes). schema: type: array items: type: string dateStartMention: name: dateStart in: query description: >- The starting date (in the `YYYY-MM-DD` format) on or after the mentions of interest were published. schema: type: string example: "2024-01-03" dateEndMention: name: dateEnd in: query description: >- The last date (in the `YYYY-MM-DD` format) on which the mentions of interest were published. schema: type: string example: "2024-01-10" keywordLocMention: name: keywordLoc in: query description: >- Where should we look when searching using the keywords provided by the `keyword` parameter. `sentence` (default) searches in the sentence of the mention, `title` in the title of the article in which the mention was found and `title,sentence` in both. schema: type: string default: "sentence" enum: - sentence - title - title,sentence ignoreKeywordLocMention: name: ignoreKeywordLoc in: query description: >- Where should we look when searching using the keywords provided by the `ignoreKeyword` parameter. `sentence` (default) searches in the sentence of the mention, `title` in the title of the article in which the mention was found and `title,sentence` in both. schema: type: string default: "sentence" enum: - sentence - title - title,sentence keywordOperMention: name: keywordOper in: query description: >- 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 mention; if 'or' then a mention will be returned if it contains any of the provided keywords. schema: type: string default: "and" enum: - and - or conceptOperMention: name: conceptOper in: query description: >- 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 mention; if 'or' then a mention will be returned if it mentions any of the provided concepts. schema: type: string default: "and" enum: - and - or categoryOperMention: name: categoryOper in: query description: >- 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 assigned to the article with the mention; if 'or' (default) then any of the provided categories is sufficient. schema: type: string default: "or" enum: - and - or minSentimentMention: name: minSentiment in: query description: >- The minimum value of the sentiment that the returned mentions should have. Valid value is any floating number between -1 (very negative) to 1 (very positive). The filter uses the sentiment that is associated with the event type of the mention (the `eventTypeSentiment` value of the mention). schema: type: number format: double minimum: -1 maximum: 1 maxSentimentMention: name: maxSentiment in: query description: >- The maximum value of the sentiment that the returned mentions should have. Valid value is any floating number between -1 (very negative) to 1 (very positive). The filter uses the sentiment that is associated with the event type of the mention (the `eventTypeSentiment` value of the mention). schema: type: number format: double minimum: -1 maximum: 1 minSentenceIndex: name: minSentenceIndex in: query description: >- The minimum index of the sentence in the article that a mention should have in order to be included in the results. Index 0 represents the article title. schema: type: integer minimum: 0 maxSentenceIndex: name: maxSentenceIndex in: query description: >- The maximum index of the sentence in the article that a mention should have in order to be included in the results. Index 0 represents the article title. schema: type: integer minimum: 0 showDuplicatesMention: name: showDuplicates in: query description: >- Set this parameter to true to include in the results also the duplicate mentions. By default, the duplicates are removed. schema: type: boolean default: "false" mentionUri: name: mentionUri in: query description: >- Instead of specifying the search conditions, you can provide the list of URIs of the mentions on which the requested result should be computed. If the parameter is provided, the search conditions are ignored. schema: type: array items: type: string mentionUriWgtList: name: mentionUriWgtList in: query description: >- Instead of specifying the search conditions, you can provide a comma separated list of items in the form `mentionUri:weight` (as returned when `resultType = uriWgtList`), on which the requested result should be computed. If the parameter is provided, the search conditions are ignored. schema: type: string includeMentionBasicInfo: name: includeMentionBasicInfo in: query description: >- Set this parameter to true to include the core mention information (the sentence, the information about the article, the event type, the sentiment, the location, ...) in the response. schema: type: boolean default: "true" includeMentionSlots: name: includeMentionSlots in: query description: >- Set this parameter to true to include the slots - the list of concepts that have a role in the mentioned event - in the response. schema: type: boolean default: "true" includeMentionCategories: name: includeMentionCategories in: query description: >- Set this parameter to true to include the categories of the article, in which the mention was found, in the response. schema: type: boolean default: "false" includeMentionFrameworks: name: includeMentionFrameworks in: query description: >- Set this parameter to true to include the frameworks (SDG, SASB, ESG) with which the event type of the mention is associated in the response. schema: type: boolean default: "true"