# Brand News Monitor (`primeselectai/news-search-visibility-monitor`) Actor

Monitor brand, competitor, and topic news with repeatable queries. Receive normalized article records containing titles, URLs, publisher domains, timestamps, language, query labels, and stable IDs for SEO and PR reporting.

- **URL**: https://apify.com/primeselectai/news-search-visibility-monitor.md
- **Developed by:** [Simon Jessen](https://apify.com/primeselectai) (community)
- **Categories:** SEO tools
- **Stats:** 2 total users, 1 monthly users, 75.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Brand News Visibility Monitor

Brand News Visibility Monitor helps you find newly published coverage for a brand, competitor, or topic and turn it into a reusable monitoring feed. Each record includes the article title, source URL, publisher domain, timestamp, query, and stable deduplication ID; configure the search query and monitoring window afterward.

### Outcome

Track where and how often a brand, competitor, topic, or keyword appears across global news coverage using a commercially reusable open-data search feed.

### Use cases

- Use the Actor when you need track where and how often a brand, competitor, topic, or keyword appears across global news coverage using a commercially reusable open-data search feed.
- Build workflows around normalize GDELT news-search results into stable records with source domains, publication timestamps, language, country, article URLs, query labels, and repeat-run friendly deduplication keys for SEO visibility and digital-PR monitoring.
- Designed for SEO agencies, digital PR teams, content marketers, brand-monitoring teams, and publishers.
- Schedule repeat runs: Customers rerun saved brand, competitor, and topic queries daily or weekly to detect new coverage, emerging narratives, and changes in publisher visibility.
- Feed normalized dataset records into APIs, spreadsheets, databases, automations, or AI/agent workflows.

### Quick start

1. Open the Actor input form.
2. Set the filters or query relevant to your workflow.
3. Start with a small `maxResults` value.
4. Run the Actor and inspect the default dataset before scheduling larger or recurring jobs.

Example input:

```json
{
  "query": "renewable energy",
  "mode": "artlist",
  "maxrecords": 10,
  "sort": "datedesc",
  "timespan": "7d",
  "maxResults": 10
}
```

### Inputs

- **query** (string, required) — Keyword, exact phrase, or supported GDELT query expression such as a brand, competitor, topic, or site-restricted search.
- **mode** (string, optional) — Article-level results are enabled through the artlist mode.
- **timespan** (string, optional) — GDELT-supported relative time window such as 1d, 7d, 30d, or 90d.
- **maxResults** (integer, optional) — Maximum number of article records to return, from 1 to 250.
- **sort** (string, optional) — Use datedesc for newest-first monitoring or hybridrel for relevance-oriented discovery.
- **maxrecords** (integer, optional) — Maximum number of article records to return, capped conservatively for reliable operation.

### Output example

The example below is taken from the latest validated local live-source sample when available; otherwise it is derived from the bundled dataset schema.

```json
{
  "id": "https://www.vetogate.com/5725875",
  "title": "بتسهيلات غير مسبوقة .. الكهرباء تكافئ الملتزمين بقوانين التصالح .. تحويل 1 . 2 مليون عداد كودي للاستفادة من نظام الشرائح .. وتكشف حقيقة تطبيق الشريحة الموحدة كإجراء عقابي",
  "url": "https://www.vetogate.com/5725875",
  "domain": "vetogate.com",
  "seendate": "20260905T100000Z",
  "language": "Arabic",
  "query": "renewable energy",
  "source": "GDELT Project"
}
```

### Pricing

Store pricing is configured in Apify. The intended primary paid unit is **article record**. Start with a small result limit while validating your workflow, then scale only when the output and economics fit your use case. The README never hard-codes a price that could drift from the live Store configuration.

### Source and limitations

- Source: GDELT DOC 2.0 API.
- Licence/terms: GDELT Project unlimited and unrestricted use terms.
- Reuse condition: GDELT states that datasets may be used commercially and may be redistributed, rehosted, republished, or mirrored, provided every use or redistribution cites the GDELT Project and links to https://www.gdeltproject.org/. Article text, snippets, images, publisher trademarks, and other third-party material remain subject to their respective owners' rights; this Actor should return metadata and source links rather than republish article bodies or images. Do not imply GDELT, Google, or publisher endorsement.
- Automation condition: Use the documented GET API, limit request frequency and result volume, avoid abusive parallel polling, and handle HTTP errors and empty responses. Use maxrecords within documented limits and use the source's timespan parameter for bounded monitoring windows.
- This is adjacent to Google SERP intelligence rather than a Google-ranking replacement; it measures news visibility and article discovery, not general web rankings.
- GDELT coverage and ranking are not equivalent to Google or Bing results, so the product must not claim search-engine-position accuracy.
- Article titles, URLs, snippets, publisher names, and other third-party material may carry separate copyright, trademark, or publisher terms; limit output to metadata and links and preserve source attribution.
- GDELT's public API behavior, result limits, and availability may change; live schema and rate-limit checks are required before publication.
- The source response can contain low-quality, duplicate, syndicated, or inaccessible URLs; expose source metadata and avoid guaranteeing article availability.

This Actor does not bypass authentication, rate limits, robots/API policies, licensing conditions, or upstream access controls. Missing upstream values are not invented.

### FAQ

**Does this use the approved source contract?**\
Yes. Runtime requests are restricted to the source contract validated by Market Hunter before build.

**Can I schedule repeat runs?**\
Yes, when the source permits automated access. Use conservative schedules and result limits that respect upstream conditions.

**Why can some fields be empty or null?**\
The upstream source may omit fields for particular records. The Actor preserves missing values rather than fabricating data.

### Troubleshooting

- If a narrow query returns no rows, loosen filters and retry with a small result limit.
- If the upstream source returns a rate-limit or temporary server error, retry later instead of increasing request pressure.
- If authentication or source identity is required, verify the protected credential/identity configured for the Actor.
- If the upstream response schema changes, report the failed run so the deterministic mapping can be updated.

### Related Actors

- Domain Backlink Discovery from Common Crawl
- News Publisher Domain Monitor
- Brand Mention Change Detector
- Public Web Article Metadata Extractor

> Store publication remains an explicit manual action. This product is not affiliated with or endorsed by the upstream source unless the Store listing explicitly states otherwise.

# Actor input Schema

## `query` (type: `string`):

Keyword, exact phrase, or supported GDELT query expression such as a brand, competitor, topic, or site-restricted search.

## `mode` (type: `string`):

Article-level results are enabled through the artlist mode.

## `timespan` (type: `string`):

GDELT-supported relative time window such as 1d, 7d, 30d, or 90d.

## `maxResults` (type: `integer`):

Maximum number of article records to return, from 1 to 250.

## `sort` (type: `string`):

Use datedesc for newest-first monitoring or hybridrel for relevance-oriented discovery.

## `maxrecords` (type: `integer`):

Maximum number of article records to return, capped conservatively for reliable operation.

## Actor input object example

```json
{
  "query": "renewable energy",
  "mode": "artlist",
  "timespan": "7d",
  "maxResults": 25,
  "sort": "datedesc",
  "maxrecords": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runMeta` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "renewable energy",
    "mode": "artlist",
    "timespan": "7d",
    "maxResults": 25,
    "sort": "datedesc",
    "maxrecords": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("primeselectai/news-search-visibility-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "renewable energy",
    "mode": "artlist",
    "timespan": "7d",
    "maxResults": 25,
    "sort": "datedesc",
    "maxrecords": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("primeselectai/news-search-visibility-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "renewable energy",
  "mode": "artlist",
  "timespan": "7d",
  "maxResults": 25,
  "sort": "datedesc",
  "maxrecords": 10
}' |
apify call primeselectai/news-search-visibility-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,primeselectai/news-search-visibility-monitor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Oj1rx2C8RUX4CKwFm/builds/qQki3LmrcmLoI1Yq1/openapi.json