https://github.com/mumblebaj/mmm-newsapi
MagicMirror² module - displaying news articles from Newsapi.org API V2
https://github.com/mumblebaj/mmm-newsapi
magicmirror2
Last synced: 2 months ago
JSON representation
MagicMirror² module - displaying news articles from Newsapi.org API V2
- Host: GitHub
- URL: https://github.com/mumblebaj/mmm-newsapi
- Owner: mumblebaj
- License: mit
- Created: 2021-08-04T19:05:38.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-10T08:23:03.000Z (about 1 year ago)
- Last Synced: 2025-05-10T09:28:00.076Z (about 1 year ago)
- Topics: magicmirror2
- Language: JavaScript
- Homepage:
- Size: 135 KB
- Stars: 11
- Watchers: 2
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MMM-NewsAPI
A [MagicMirror²](https://magicmirror.builders) module to to get news from [NewsAPi.org](https://newsapi.org/).
[](https://MagicMirror.builders)
[](LICENSE)
## Support
If you like my module you can support my work by giving me a star ir buy me a coffee.
## Updates
- [x] Issue raise that null's were displayed for certain information. Update to rather return a blank string.
- [X] Make sortBy an optional parameter for both `headlines` and `everything`
- [X] Add DEBUG Handling.
- - [X] Only add `debug: true` to the config section if you are experiencing issues and require more information to find issues.
- [X] Replaced moment with luxon
- [X] Replaced request with internal fetch
- [X] Remove the following line from your config `className: "NEWS",`. It is no longer required and module will stop working if not removed.
- [X] Optional QR code via QRious
- [X] Remove QRCode element when option is not selected. This was causing display issues in vertical mode. When selected will display
## Dependencies
- luxon@3.5.0
## Installation
In your terminal, go to your MagicMirror's Module folder:
```bash
cd ~/MagicMirror/modules
```
Clone this repository:
```bash
git clone https://github.com/mumblebaj/MMM-NewsAPI
```
Add the module to the modules array in the `config/config.js` file:
```javascript
{
module: "MMM-NewsAPI",
header: "NEWS",
position: "bottom_bar",
},
```
## Configuration options
The following properties can be configured:
| Option | Description
| ---------------------------- | -----------
| `header` | The header text
**Default value:** `'NEWS'`
| `choice` | Type of query to be instantiated
**Possible values:** `headlines` or `everything`
**Default value:** `headlines`
| `type` | Orientation
**Possible values:** `horizontal` or `vertical`
**Default value:** `horizontal`. Module does currently not cater for vertical
| `pageSize` | The number of articles to be returned. Max = 100
**Default value:** `20`
| `sortBy` | The order to sort the articles in.
**Possible values:** `relevancy`, `popularity`, `publishedAt`
only available for `choice: "everything"`
| `drawInterval` | The amount of time each article is displayed
**Default value:** `30` seconds
| `templateFile` | The template file to use. You can create your own template file and reference here. For now use `template.html`
| `fetchInterval` | The time interval between fetching new articles. There is a daily limit of 100 calls per apiKey. Best to set this to `100 * 60 * 60`
| `apiKey` | You can obtain an API Key from [NewsAPi.org](https://newsapi.org/)
| `QRCode` | Boolean true/false value to display QR code for article URL. Default is false.
## Query Options
**The following query options can be defined:**
When specifying the query options take note of the following:
When using `headlines`, `country` and `sources` cannot be used together.
The `domains` option cannot be used on it's own, you have to specify any of the following parameters with it: `sources`, `q`, `language`, `country`, `category`.
When using `everything`, you cannot use the `country` option.
To try more combinations you can visit [NewsAPi.org](https://newsapi.org/)
| Option | Description
| ---------------------------- | -----------
| `country` | The 2-letter ISO 3166-1 code of the country you want to get headlines for.
Possible options:
`ae` `ar` `at` `au` `be` `bg` `br` `ca` `ch` `cn`
`co` `cu` `cz` `de` `eg` `fr` `gb` `gr` `hk` `hu` `id` `ie` `ve` `za`
`il` `in` `it` `jp` `kr` `lt` `lv` `ma` `mx` `my` `ng` `nl`
`no` `nz` `ph` `pl` `pt` `ro` `rs` `ru` `sa` `se` `sg` `si`
`sk` `th` `tr` `tw` `ua` `us`.
**Note: you can't mix this param with the sources param**
| `category` | The category you want to get headlines for.
Possible options: `business` `entertainment` `general` `health` `science` `sports` `technology`.
**Note: you can't mix this param with the sources param.**
| `q` | Keywords or phrases to search for in the article title and body
| `qInTitle` | Keywords or phrases to search for in the article title only
| `sources` | A comma-seperated string of identifiers (maximum 20) for the news sources or blogs you want headlines from
TO obtain a list of sources or sources for your country you can put the following in your browser. `https://newsapi.org/v2/top-headlines/sources?apiKey=your-api-key-here&country=your-country-code-here`
| `domains` | A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to.
| `excludeDomains` | A comma-seperated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results.
| `language` | The 2-letter ISO-639-1 code of the language you want to get headlines for. Possible options:
`ar` `de` `en` `es` `fr` `he` `it` `nl` `no` `pt` `ru` `se` `ud` `zh`
## Config Example
**everything** Example
```javascript
{
module: "MMM-NewsAPI",
header: "news",
position: "bottom_bar",
config: {
apiKey: "",
type: "horizontal",
choice: "everything",
pageSize: 10,
sortBy: "publishedAt",
drawInterval: 1000*30,
templateFile: "template.html",
fetchInterval: 1000*60*60,
QRCode: true,
query: {
country: "",
category: "",
q: "",
qInTitle: "",
sources: "",
domains: "cnn.com,nytimes.com,news24.com",
excludeDomains: "",
language: ""
}
}
},
```
**headlines** Example
```javascript
{
module: "MMM-NewsAPI",
header: "news",
position: "bottom_bar",
config: {
apiKey: "",
type: "horizontal",
choice: "headlines",
pageSize: 10,
sortBy: "relevance",
drawInterval: 1000*30,
templateFile: "template.html",
fetchInterval: 1000*60*60,
query: {
country: "us",
category: "",
q: "covid",
qInTitle: "",
sources: "",
domains: "nytimes.com",
excludeDomains: "",
language: ""
}
}
},
```
**Notes**
- `apiKey` is **required**. You should first create an account on
## Updating
To update the module to the latest version, use your terminal to go to your MMM-NewsAPI module folder and type the following command:
```bash
cd ~/MagicMirror/modules/MMM-NewsAPI
git pull
npm install
```