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

# Get articles for topic page

Obtain articles that match a user generated topic page.

Retrieve the news articles that match the topic page that 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 unique 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 parameter when making the API calls. Compared to the [Get Articles](/documentation?tab=searchArticles) 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 (default) or one of the various aggregates (summaries) of the matching articles. In case of the aggregates, for example, the returned data can contain information about when the articles matching the topic were published, who published them, etc.

**Endpoint:** GET | POST `https://eventregistry.org/api/v1/article/getArticlesForTopicPage`

**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 articles. Obtain the URI from the URL on the [monitoring page](https://eventregistry.org/monitoring) when the topic page is opened.

#### `resultType`

string

Define what kind of results of the search you would like to get.

Available values: `articles`, `uriWgtList`, `langAggr`, `timeAggr`, `sourceAggr`, `sourceExAggr`, `authorAggr`, `keywordAggr`, `locAggr`, `conceptAggr`, `conceptGraph`, `categoryAggr`, `dateMentionAggr`, `sentimentAggr`

Default value: `articles`

#### `maxDaysBack`

integer

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.

#### `onlyAfterTm`

string

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.

#### `articlesPage`

integer

Determines the page of the results to return (starting from 1). Relevant when `resultType = articles`.

Default value: `1`

#### `articlesCount`

integer

Define how many articles (up to 100) will be returned. Relevant when `resultType = articles`.

Default value: `100`

#### `articlesSortBy`

string

Choose the criteria for sorting the news articles. `rel` (relevance to the query), `date` (publishing date), `sourceImportance` (manually curated score of source importance - high value, high importance), `sourceImportanceRank` (reverse of sourceImportance), `sourceAlexaGlobalRank` (global rank of the news source), `sourceAlexaCountryRank` (country rank of the news source). Relevant when `resultType = articles`.

Available values: `date`, `rel`, `sourceImportance`, `sourceAlexaGlobalRank`, `sourceAlexaCountryRank`

Default value: `date`

#### `articlesSortByAsc`

boolean

Should the results be ordered in ascending order or descending order (default). Relevant when `resultType = articles`.

Default value: `false`

#### `dataType`

string | string[]

What data types should we search? news content (default, `news`), press releases (`pr`) or blogs (`blog`).

Available values: `news`, `pr`, `blog`

Default value: `news`

#### `Returned Details`

The API call can return more or less meta-data information about the articles, concepts, categories, sources and locations. Click to see the available properties that can be specified to determine the amount of returned information.

#### `articleBodyLen`

integer

Set the size of the article body that'll be returned in the response. Use -1 for full article body.

Default value: `-1`

#### `includeArticleTitle`

boolean

Set this parameter to true to include the article title in the response.

Default value: `true`

#### `includeArticleBasicInfo`

boolean

Set this parameter to true to include the core article information in the response.

Default value: `true`

#### `includeArticleBody`

boolean

Set this parameter to true to include the article body in the response.

Default value: `true`

#### `includeArticleEventUri`

boolean

Set this parameter to true to include the uri of the event (to which the article belongs) in the response.

Default value: `true`

#### `includeArticleSocialScore`

boolean

Set this parameter to true to include the information about how many times the article was shared on different social media.

Default value: `false`

#### `includeArticleSentiment`

boolean

Set this parameter to true to include the article sentiment in the response (value will be non-null only for English articles).

Default value: `true`

#### `includeArticleConcepts`

boolean

Set this parameter to true to include the article concepts in the response.

Default value: `false`

#### `includeArticleCategories`

boolean

Set this parameter to true to include the article categories in the response.

Default value: `false`

#### `includeArticleLocation`

boolean

Set this parameter to true to include the article location in the response.

Default value: `false`

#### `includeArticleImage`

boolean

Set this parameter to true to include the article image in the response.

Default value: `true`

#### `includeArticleAuthors`

boolean

Set this parameter to true to include the article authors in the response.

Default value: `true`

#### `includeArticleVideos`

boolean

Set this parameter to true to include the article videos in the response.

Default value: `false`

#### `includeArticleLinks`

boolean

Set this parameter to true to include the article links in the response.

Default value: `false`

#### `includeArticleExtractedDates`

boolean

Set this parameter to true to include article extracted dates in the response.

Default value: `false`

#### `includeArticleDuplicateList`

boolean

Set this parameter to true to include the list of duplicate articles in the response.

Default value: `false`

#### `includeArticleOriginalArticle`

boolean

Set this parameter to true to include the original article in the response.

Default value: `false`

#### `includeSourceTitle`

boolean

Set this parameter to true to include the source title in the response.

Default value: `true`

#### `includeSourceDescription`

boolean

Set this parameter to true to include the source description in the response.

Default value: `false`

#### `includeSourceLocation`

boolean

Set this parameter to true to include the source location in the response.

Default value: `false`

#### `includeSourceRanking`

boolean

Set this parameter to true to include the source ranking in the response.

Default value: `false`

#### `includeConceptLabel`

boolean

Set this parameter to true to include the concept label in the response.

Default value: `true`

#### `includeConceptImage`

boolean

Set this parameter to true to include the concept image in the response.

Default value: `false`

#### `includeConceptSynonyms`

boolean

Set this parameter to true to include the concept synonyms in the response.

Default value: `false`

#### `conceptLang`

string

Define the language of the concept label.

Default value: `eng`

#### `includeCategoryParentUri`

boolean

Set this parameter to true to include category parent uri in the response.

Default value: `false`

#### `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 articles that match a public topic page related to Renewable energy (with uri 240f6a12-b9d8-40a6-b1c6-a220e31d08de). Return articles sorted by relevance (most relevant first).

Request body:

```json
{
  "uri": "240f6a12-b9d8-40a6-b1c6-a220e31d08de",
  "infoArticleBodyLen": -1,
  "resultType": "articles",
  "articlesSortBy": "fq",
  "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.getArticles(page = 1)
for art in res.get("articles", {}).get("results", []):
    print(art)
```

```javascript
var er = new erBase.EventRegistry();
                    var topic = new erBase.TopicPage(er);
                    topic.loadTopicPageFromER("240f6a12-b9d8-40a6-b1c6-a220e31d08de").then(() => {
                        return topic.getArticles({page: 1});
                    }).then((articles) => {
                        for (var i = 0; i < articles.length; i++) {
                            console.log(articles[i]);
                        }
                    });
```

```typescript
const er = new EventRegistry();
                    const topic = new TopicPage(er);
                    topic.loadTopicPageFromER("240f6a12-b9d8-40a6-b1c6-a220e31d08de").then(() => {
                        return topic.getArticles({page: 1});
                    }).then((articles) => {
                        for (const article of articles) {
                            console.log(article);
                        }
                    });
```

### Example 2

Build a custom topic page on the fly (without the user interface) to find articles 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 2 pages of articles sorted by relevance to the topic page
arts1 = topic.getArticles(page=1, sortBy="rel")
arts2 = topic.getArticles(page=2, sortBy="rel")
```

```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.getArticles({page: 1, sortBy: "rel"});
                    }).then(() => {
                        return topic.getArticles({page: 2, sortBy: "rel"});
                    });
```

```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 arts1 = await topic.getArticles({page: 1, sortBy: "rel"});
                        const arts2 = await topic.getArticles({page: 2, sortBy: "rel"});
                    }
```

## Example output

```json
{
  "articles": {
    "results": [
      {
        "uri": "7546825937",
        "lang": "eng",
        "isDuplicate": false,
        "date": "2023-05-16",
        "time": "10:35:00",
        "dateTime": "2023-05-16T10:35:00Z",
        "dateTimePub": "2023-05-16T10:34:00Z",
        "dataType": "news",
        "sim": 0,
        "url": "https://www.rmol.co/20230516/22538-tesla-changed-a-deadline-for-investor-proposals-angering-activists/",
        "title": "Tesla Changed A Deadline For Investor Proposals, Angering Activists | RMOL",
        "body": "Tesla investors will have fewer opportunities to express discontent with management at the company's annual meeting, which is taking place Tuesday in Austin, Texas, (trimmed) ...",
        "source": {
          "uri": "rmol.co",
          "dataType": "news",
          "title": "rmol.co"
        },
        "authors": [],
        "concepts": [
          {
            "uri": "http://en.wikipedia.org/wiki/Tesla,_Inc.",
            "type": "org",
            "score": 5,
            "label": {
              "eng": "Tesla, Inc."
            }
          },
          {
            "uri": "http://en.wikipedia.org/wiki/Shareholder",
            "type": "wiki",
            "score": 4,
            "label": {
              "eng": "Shareholder"
            }
          },
          {
            "uri": "http://en.wikipedia.org/wiki/Automotive_industry",
            "type": "wiki",
            "score": 3,
            "label": {
              "eng": "Automotive industry"
            }
          },
          {
            "uri": "http://en.wikipedia.org/wiki/Austin,_Texas",
            "type": "loc",
            "score": 3,
            "label": {
              "eng": "Austin, Texas"
            },
            "location": {
              "type": "place",
              "label": {
                "eng": "Austin, Texas"
              },
              "country": {
                "type": "country",
                "label": {
                  "eng": "United States"
                }
              }
            }
          },
          {
            "#META ITEM": "other concepts..."
          }
        ],
        "image": "https://www.rmol.co/wp-content/uploads/2023/05/16tesla-fckq-facebookJumbo-4859007.jpg",
        "eventUri": null,
        "shares": {},
        "sentiment": 0.01960784313725483,
        "wgt": 421929300,
        "relevance": 100
      },
      {
        "#META ITEM": "other articles..."
      }
    ],
    "totalResults": 38246,
    "page": 1,
    "count": 100,
    "pages": 383
  }
}
```

## Output schema

```json
{
  "type": "object",
  "properties": {
    "articles": {
      "type": "object",
      "properties": {
        "totalResults": {
          "type": "integer"
        },
        "page": {
          "type": "integer"
        },
        "count": {
          "type": "integer"
        },
        "pages": {
          "type": "integer"
        },
        "results": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "uri": {
                "type": "string"
              },
              "lang": {
                "type": "string"
              },
              "isDuplicate": {
                "type": "boolean"
              },
              "date": {
                "type": "string"
              },
              "time": {
                "type": "string"
              },
              "dateTime": {
                "type": "string"
              },
              "sim": {
                "type": "double"
              },
              "url": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "body": {
                "type": "string"
              },
              "source": {
                "type": "object",
                "properties": {
                  "uri": {
                    "type": "string"
                  },
                  "dataType": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "location": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "label": {
                        "type": "object",
                        "properties": {
                          "eng": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "locationValidated": {
                    "type": "boolean"
                  },
                  "ranking": {
                    "type": "object",
                    "properties": {
                      "importanceRank": {
                        "type": "integer"
                      }
                    }
                  }
                }
              },
              "concepts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "uri": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "score": {
                      "type": "integer"
                    },
                    "label": {
                      "type": "object",
                      "properties": {
                        "eng": {
                          "type": "string"
                        }
                      }
                    },
                    "image": {
                      "type": "string"
                    },
                    "synonyms": {
                      "type": "object",
                      "properties": {}
                    },
                    "trendingScore": {
                      "type": "object",
                      "properties": {
                        "news": {
                          "type": "object",
                          "properties": {
                            "score": {
                              "type": "double"
                            },
                            "testPopFq": {
                              "type": "integer"
                            },
                            "nullPopFq": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    },
                    "location": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "label": {
                          "type": "object",
                          "properties": {
                            "eng": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              },
              "categories": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "uri": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "wgt": {
                      "type": "integer"
                    }
                  }
                }
              },
              "links": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "videos": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "image": {
                "type": "string"
              },
              "duplicateList": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "originalArticle": {
                "type": "string"
              },
              "eventUri": {
                "type": "string"
              },
              "location": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string"
                  },
                  "label": {
                    "type": "object",
                    "properties": {
                      "eng": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "extractedDates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "amb": {
                      "type": "boolean"
                    },
                    "imp": {
                      "type": "boolean"
                    },
                    "date": {
                      "type": "string"
                    },
                    "textStart": {
                      "type": "integer"
                    },
                    "textEnd": {
                      "type": "integer"
                    }
                  }
                }
              },
              "shares": {
                "type": "object",
                "properties": {
                  "facebook": {
                    "type": "integer"
                  }
                }
              },
              "wgt": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  }
}
```