World News
About 664 wordsAbout 2 min
Adds World News API headline and search capabilities — top news by country and full-text/semantic news search across 170,000+ articles/day from 210+ countries in 86+ languages — to Spora agents.
Installation
php bin/spora plugin:install spora-ai/spora-plugin-worldnewsFor local development against a sibling checkout, pass --path=/abs/path/to/checkout.
After install, the tool is exposed as worldnews:search.
Configuration
Settings → Tools → World News. The plugin needs a single API key, issued at https://worldnewsapi.com → Console. A free tier is available.
| Setting | Required | Default |
|---|---|---|
api_key | yes | — |
http_timeout | no | 30 (seconds; respects SPORA_TOOL_HTTP_TIMEOUT env) |
api_key is encrypted at rest by Spora’s ToolConfigService, masked in the UI, and never logged. Requests send it as the x-api-key header per the WorldNewsAPI contract.
Per-tool parameters
The plugin exposes one tool, worldnews:search, with two operations selected by the operation discriminator (search or top-news). Both return ToolResult::ok (formatted list of articles with title, source, publish date, summary, URL) or ToolResult::fail. The tool never throws — a single API failure cannot kill the agent loop.
search — /search-news
Searches news by text and optional filters. Returns news[] from the upstream response.
| Parameter | Type | Required | Notes |
|---|---|---|---|
q | string | yes | Keywords or phrases to search for |
source-country | string | no | ISO country code, e.g. us, de |
language | string | no | ISO 639-1 language code, e.g. en, de |
category | string | no | News category, e.g. politics, sports, technology |
earliest-publish-date | string | no | ISO 8601 date, e.g. 2026-04-01 |
latest-publish-date | string | no | ISO 8601 date, e.g. 2026-04-23 |
entities | array<string> | no | Semantic entities (people, organizations, locations) |
number | integer | no | Max results (1–100, default 10) |
offset | integer | no | Pagination offset |
top-news — /top-news
Returns top trending news for a specific country/language combination. The upstream response is grouped per country; the tool flattens the groups into a single article list.
| Parameter | Type | Required | Notes |
|---|---|---|---|
source-country | string | yes | ISO country code, e.g. us, de |
language | string | yes | ISO 639-1 language code, e.g. en, de |
Vendor links
- Signup + console: https://worldnewsapi.com
- API documentation: https://worldnewsapi.com/docs/
- Dashboard: https://console.worldnewsapi.com/
Translations
The plugin ships a German catalogue at locales/de.json, declared through WorldNewsPlugin::translationsPaths(). The catalogue key is the English source string:
{
"World News Search": "Weltnachrichten-Suche",
"API key for worldnewsapi.com": "API-Schlüssel für worldnewsapi.com"
}Only operator-facing copy is translated — the tool’s display name, every #[ToolSetting] description this plugin owns, and the plugin description. A description core already translates is core’s to keep: the host merges the plugin’s catalogue under core’s, and core wins a key collision, so the plugin does not repeat it. Strings the model reads (#[Tool].description, #[ToolParameter].description, #[ToolSetting].label and its option labels) stay English, in the operator’s view too: a German tool description degrades the model’s tool selection, and a translated label that also reaches the model puts German into its prompt.
Editing the English orphans the translation — the key changes and the old entry is dead — so re-translate in the same commit. The repository checks its catalogue against three rules: no translation is empty, none is identical to its key, and no key survives a copy edit. The gate is this repository’s own tests/Unit/LocaleCatalogTest.php.
Requires spora-core >= 0.31.0; on older cores the catalogue is ignored.
Development
composer install
./vendor/bin/pest # unit tests
./vendor/bin/phpstan analyse
./vendor/bin/php-cs-fixer fix --dry-run --diffCI: .github/workflows/ci.yml — Pest on PHP 8.4 + 8.5, PHPStan level per phpstan.neon, php-cs-fixer dry-run. A separate sonar job uploads coverage + JUnit to SonarCloud (project key spora-ai_spora-plugin-worldnews) so the new_coverage metric is measurable per PR. Requires the SONAR_TOKEN secret in the repo. MIT license.
Repo: spora-ai/spora-plugin-worldnews · MIT