Source: https://eventregistry.org/documentation?tab=searchEventsForTopic # Get events for a topic page Obtain events that match a user generated topic page. Retrieve the events that match the topic page the user generated on the [Media 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 (e.g. "240f6a12-b9d8-40a6-b1c6-a220e31d08de"). Use that URI as the `uri` parameter when making the API calls. Compared to the [Get Events](/documentation?tab=searchEvents) API call, this endpoint is ideal when you want to find events that match a broader topic that can be defined using a set of concepts, keywords, categories, etc. These concepts and keywords don't all need to be mentioned in an event, but the more of them are mentioned, the higher the event will 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 sorting parameter. The results of the search can be the list of matching events (default) or one of the various aggregates (summaries) of the matching events. In case of the aggregates, for example, the returned data can contain the geographic locations, where the events matching criteria occured, date of the matching events, etc. **Endpoint:** GET | POST `https://eventregistry.org/api/v1/event/getEventsForTopicPage` **Headers:** Content-Type: application/json #### `Parameters` #### `apiKey` string (required) Your API key #### `uri` string (required) 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. #### `resultType` string | string[] Define what kind of results you would like to get. Available values: `events`, `uriWgtList`, `timeAggr`, `locAggr`, `locTimeAggr`, `sourceAggr`, `authorAggr`, `keywordAggr`, `conceptAggr`, `conceptGraph`, `categoryAggr`, `breakingEvents`, `sentimentAggr`, `dateMentionAggr` Default value: `events` #### `eventsPage` integer Determines the page of the results to return (starting from 1). Relevant when `resultType = events`. Default value: `1` #### `eventsCount` integer Define how many events (up to 50) will be returned. Relevant when `resultType = events`. Default value: `50` #### `eventsSortBy` string Set how you would like to sort your results. `date` (by event date), `rel` (relevance to the query), `size` (number of articles). Relevant when `resultType = events`. Available values: `date`, `rel`, `size` Default value: `rel` #### `eventsSortByAsc` boolean Should the results be ordered in ascending order or descending order (default) based on the sorting criteria. Relevant when `resultType = events`. Default value: `false` #### `Returned Details` The API call can return more or less meta-data information about the events, articles, concepts, categories, sources and locations. Click to see the available properties that can be specified to determine the amount of returned information. #### `includeEventTitle` boolean Set this parameter to true to include the event title in the response. Default value: `true` #### `includeEventSummary` boolean Set this parameter to true to include the event title in the response. Default value: `false` #### `includeEventSocialScore` boolean Set this parameter to true to include the event social score in the response. Default value: `false` #### `includeEventSentiment` boolean Set this parameter to true to include the event sentiment in the response. Default value: `true` #### `includeEventLocation` boolean Set this parameter to true to include the event location in the response. Default value: `true` #### `includeEventDate` boolean Set this parameter to true to include the event date in the response. Default value: `true` #### `includeEventArticleCounts` boolean Set this parameter to true to include the article counts for events in the response. Default value: `true` #### `includeEventConcepts` boolean Set this parameter to true to include the event concepts in the response. Default value: `true` #### `includeEventCategories` boolean Set this parameter to true to include the event categories in the response. Default value: `true` #### `includeEventCommonDates` boolean Set this parameter to true to include the event commmon dates in the response. Default value: `false` #### `includeEventStories` boolean Set this parameter to true to include the event stories in the response. Default value: `false` #### `eventImageCount` integer Define how many images you would like to have in the response. Default value: `0` #### `includeConceptLabel` boolean Set this parameter to true to include the concept label in the response. Default value: `true` #### `includeConceptImage` boolean Set this parameter to true to include the concept image in the response. Default value: `false` #### `includeConceptSynonyms` boolean Set this parameter to true to include the concept synonyms in the response. Default value: `false` #### `conceptLang` string Define the language of the concept label. Default value: `eng` #### `includeStoryBasicStats` boolean Set this parameter to true to include story basic stats in the response. Default value: `false` #### `includeStoryTitle` boolean Set this parameter to true to include the story title in the response. Default value: `false` #### `includeStoryLocation` boolean Set this parameter to true to include the story location in the response. Default value: `false` #### `includeStoryDate` boolean Set this parameter to true to include the story date in the response. Default value: `false` #### `includeStoryConcepts` boolean Set this parameter to true to include the story concepts in the response. Default value: `false` #### `includeStoryCategories` boolean Set this parameter to true to include the story categories in the response. Default value: `false` #### `includeStoryMedoidArticle` boolean Set this parameter to true to include story medoid article in the response. Default value: `false` #### `includeStoryCommonDates` boolean Set this parameter to true to include story common dates in the response. Default value: `false` #### `storyImageCount` integer Define how many images you would like to have in the response. Default value: `0` #### `includeCategoryParentUri` boolean Set this parameter to true to include category parent uri in the response. Default value: `false` #### `includeLocationPopulation` boolean Set to true to include the population size of the location. Default value: `false` #### `includeLocationGeoNamesId` boolean Set to true to include the GeoNames id of the location. Default value: `false` #### `includeLocationCountryArea` boolean Set to true to include the are of the location in squared km. Default value: `false` #### `includeLocationCountryContinent` boolean Set to true to get the continent of the country for location objects. Default value: `false` ## Request examples ### Example 1 Retrieve events that match a public topic page related to Renewable energy (with uri 240f6a12-b9d8-40a6-b1c6-a220e31d08de). Return events sorted by relevance (most relevant first). Request body: ```json { "uri": "240f6a12-b9d8-40a6-b1c6-a220e31d08de", "infoArticleBodyLen": -1, "resultType": "events", "eventsSortBy": "rel", "apiKey": "YOUR_API_KEY" } ``` ```python from eventregistry import * er = EventRegistry(apiKey = YOUR_API_KEY) t = TopicPage(er) # load the topic page with the given uri t.loadTopicPageFromER("240f6a12-b9d8-40a6-b1c6-a220e31d08de") # retrieve the first page of 100 results. To get the next page, call with page=2, ... res = t.getEvents(page = 1) for event in res.get("events", {}).get("results", []): print(event) ``` ```javascript var er = new erBase.EventRegistry(); var topic = new erBase.TopicPage(er); topic.loadTopicPageFromER("240f6a12-b9d8-40a6-b1c6-a220e31d08de").then(() => { return topic.getEvents({page: 1}); }).then((events) => { for (var i = 0; i < events.length; i++) { console.log(events[i]); } }); ``` ```typescript const er = new EventRegistry(); const topic = new TopicPage(er); topic.loadTopicPageFromER("240f6a12-b9d8-40a6-b1c6-a220e31d08de").then(() => { return topic.getEvents({page: 1}); }).then((events) => { for (const event of events) { console.log(event); } }); ``` ### Example 2 Build a custom topic page on the fly (without the user interface) to find events related to renewable energy. ```python from eventregistry import * er = EventRegistry(apiKey = YOUR_API_KEY) # manually create a new topic page topic = TopicPage(er) topic.addKeyword("renewable energy", 30) topic.addConcept(er.getConceptUri("biofuel"), 50) topic.addConcept(er.getConceptUri("solar energy"), 50) topic.addCategory(er.getCategoryUri("renewable"), 50) # return only articles that are about some event that we have detected topic.setArticleHasEventFilter("skipArticlesWithoutEvent") # get first two pages of events, sorted by relevance events1 = topic.getEvents(page=1) events2 = topic.getEvents(page=2) ``` ```javascript const er = new EventRegistry(); const topic = new TopicPage(er); Promise.all([ er.getConceptUri("biofuel"), er.getConceptUri("solar energy"), er.getCategoryUri("renewable"), ]).then((uris) => { topic.addKeyword("renewable energy", 30); topic.addConcept(uris[0], 50); topic.addConcept(uris[1], 50); topic.addCategory(uris[2], 50); topic.articleHasEventFilter = "skipArticlesWithoutEvent"; return topic.getEvents({page: 1}); }).then(() => { return topic.getEvents({page: 2}); }); ``` ```typescript async function createTopicPage() { const er = new EventRegistry(); const topic = new TopicPage(er); topic.addKeyword("renewable energy", 30); topic.addConcept(await er.getConceptUri("biofuel"), 50); topic.addConcept(await er.getConceptUri("solar energy"), 50); topic.addCategory(await er.getCategoryUri("renewable"), 50); topic.articleHasEventFilter = "skipArticlesWithoutEvent"; const events1 = await topic.getEvents({page: 1}); const events2 = await topic.getEvents({page: 2}); } ``` ## Example output ```json { "events": { "results": [ { "uri": "eng-8625782", "concepts": [ { "uri": "http://en.wikipedia.org/wiki/Tesla,_Inc.", "type": "org", "score": 100, "label": { "eng": "Tesla, Inc." } }, { "uri": "http://en.wikipedia.org/wiki/Electrochemical_cell", "type": "wiki", "score": 83, "label": { "eng": "Electrochemical cell" } }, { "uri": "http://en.wikipedia.org/wiki/Shanghai", "type": "loc", "score": 74, "label": { "eng": "Shanghai" }, "location": { "type": "place", "label": { "eng": "Shanghai" }, "country": { "type": "country", "label": { "eng": "China" } } } }, { "META": "other concepts..." } ], "eventDate": "2023-05-16", "totalArticleCount": 6, "title": { "eng": "Tesla applies to expand Shanghai plant, add pouch battery cell output" }, "summary": { "eng": "(Reuters) - Tesla (NASDAQ: TSLA ) Inc has applied for regulatory clearance to expand its Shanghai plant and to begin producing for the first time pouch-type battery cells, albeit in small numbers.\n\nAn undated public notice said the potential expansion would give the Shanghai Gigafactory the capacity to produce 1.75 million powertrain units annually, up from 1.25 million currently.\n\nIt was not clear from the notice, posted on the website of the district where the factory is located, whether Tesla " }, "infoArticle": { "eng": { "uri": "7546618078", "lang": "eng", "isDuplicate": false, "date": "2023-05-16", "time": "08:29:00", "dateTime": "2023-05-16T08:29:00Z", "dateTimePub": "2023-05-16T08:22:00Z", "dataType": "news", "sim": 0.9450980424880981, "url": "https://za.investing.com/news/tesla-applies-to-expand-shanghai-plant-add-pouch-battery-cell-output-2766295", "source": { "uri": "za.investing.com", "dataType": "news", "title": "Investing.com South Africa" } } }, "location": { "type": "place", "label": { "eng": "Shanghai" }, "country": { "type": "country", "label": { "eng": "China" } } }, "categories": [ { "uri": "dmoz/Science/Biology/Cryobiology", "label": "dmoz/Science/Biology/Cryobiology", "wgt": 100 }, { "uri": "dmoz/Science/Biology/Cell_Biology", "label": "dmoz/Science/Biology/Cell Biology", "wgt": 100 }, { "uri": "dmoz/Business/Energy/Fuel_Cells", "label": "dmoz/Business/Energy/Fuel Cells", "wgt": 100 }, { "uri": "news/Business", "label": "news/Business", "wgt": 56 } ], "images": [ "https://i-invdn-com.investing.com/news/https://i-invdn-com.investing.com/akapi-images/800x450/f63a488c70de29ce8dec307c117aea22_w_800_h_450.jpg" ], "articleCounts": { "eng": 6 }, "socialScore": 0, "sentiment": 0.05882352941176472, "wgt": 421891200, "relevance": 100 }, { "#META ITEM": "other events..." } ], "totalResults": 903, "page": 1, "count": 50, "pages": 19 } } ``` ## Output schema ```json { "type": "object", "properties": { "events": { "type": "object", "properties": { "totalResults": { "type": "integer" }, "page": { "type": "integer" }, "count": { "type": "integer" }, "pages": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "concepts": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "type": { "type": "string" }, "score": { "type": "integer" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } }, "image": { "type": "string" }, "synonyms": { "type": "object", "properties": {} }, "trendingScore": { "type": "object", "properties": { "news": { "type": "object", "properties": { "score": { "type": "double" }, "testPopFq": { "type": "integer" }, "nullPopFq": { "type": "integer" } } } } }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } } } } }, "stories": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "articleCount": { "type": "integer" }, "lang": { "type": "string" }, "avgCos": { "type": "double" }, "variance": { "type": "double" }, "title": { "type": "string" }, "isUserSetTitle": { "type": "boolean" }, "concepts": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "type": { "type": "string" }, "score": { "type": "integer" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } }, "image": { "type": "string" }, "synonyms": { "type": "object", "properties": {} }, "trendingScore": { "type": "object", "properties": { "news": { "type": "object", "properties": { "score": { "type": "double" }, "testPopFq": { "type": "integer" }, "nullPopFq": { "type": "integer" } } } } }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } } } } }, "location": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } } }, "isUserSetLocation": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "label": { "type": "string" }, "wgt": { "type": "integer" } } } }, "medoidArticle": { "type": "object", "properties": { "uri": { "type": "string" }, "lang": { "type": "string" }, "isDuplicate": { "type": "boolean" }, "date": { "type": "string" }, "time": { "type": "string" }, "dateTime": { "type": "string" }, "sim": { "type": "double" }, "url": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "source": { "type": "object", "properties": { "uri": { "type": "string" }, "dataType": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } }, "locationValidated": { "type": "boolean" }, "ranking": { "type": "object", "properties": { "importanceRank": { "type": "integer" } } } } }, "concepts": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "type": { "type": "string" }, "score": { "type": "integer" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } }, "image": { "type": "string" }, "synonyms": { "type": "object", "properties": {} }, "trendingScore": { "type": "object", "properties": { "news": { "type": "object", "properties": { "score": { "type": "double" }, "testPopFq": { "type": "integer" }, "nullPopFq": { "type": "integer" } } } } }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } } } } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string" }, "label": { "type": "string" }, "wgt": { "type": "integer" } } } }, "links": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "array", "items": { "type": "string" } }, "image": { "type": "string" }, "duplicateList": { "type": "array", "items": { "type": "string" } }, "originalArticle": { "type": "string" }, "eventUri": { "type": "string" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } }, "extractedDates": { "type": "array", "items": { "type": "object", "properties": { "amb": { "type": "boolean" }, "imp": { "type": "boolean" }, "date": { "type": "string" }, "textStart": { "type": "integer" }, "textEnd": { "type": "integer" } } } }, "shares": { "type": "object", "properties": { "facebook": { "type": "integer" } } }, "wgt": { "type": "integer" } } }, "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": "double" }, "wgt": { "type": "integer" } } } }, "eventDate": { "type": "string" }, "totalArticleCount": { "type": "integer" }, "title": { "type": "object", "properties": { "eng": { "type": "string" } } }, "summary": { "type": "object", "properties": { "eng": { "type": "string" } } }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "object", "properties": { "eng": { "type": "string" } } } } }, "categories": { "type": "object", "properties": { "uri": { "type": "string" }, "label": { "type": "string" }, "wgt": { "type": "integer" } } }, "images": { "type": "array", "items": { "type": "string" } }, "articleCounts": { "type": "object", "properties": { "eng": { "type": "integer" } } }, "socialScore": { "type": "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" } } } } } } } } ```