# News250 — Full Technical Documentation for AI Crawlers

> News250 is a real-time news API that ingests articles from 4,500+ global sources, deduplicates redundant coverage into unified event clusters, and delivers ultra-concise AI-generated summaries via a single REST API call. It is an alternative to newsdata.io, newsapi.org, gnews.io, and mediastack.

## What News250 Does

News250 monitors ~4,500 global news sources. Articles are ingested via RSS, sitemaps, and HTML parsing, then processed through an AI pipeline that:

1. **Deduplicates** articles using advanced vector similarity search and centroid matching
2. **Clusters** related articles into unified event groups (one event = one cluster)
3. **Summarizes** each cluster into a fact-dense summary using Groq Llama 3.1 8B
4. **Extracts entities** (Person, Organization, Location, Country, City, Event, Product, Law) using GLiNER2
5. **Ranks** clusters by importance using a rule-based scoring system (freshness, source count, source diversity, entity richness)

## API Base URL

```
https://news250.com/api/v1
```

## Authentication

Include your API key as a Bearer token:

```
Authorization: Bearer n250_YOUR_API_KEY
```

## Endpoints

### GET /api/v1/clusters
Returns deduplicated news clusters sorted by importance.

**Parameters:**
- `limit` (int, default 25, max 100): Number of clusters to return
- `offset` (int, default 0): Pagination offset
- `language` (string): Filter by language code (en, es, it, fr)
- `country` (string): Filter by country code
- `from_date` (string, ISO 8601): Start date filter
- `to_date` (string, ISO 8601): End date filter

**Example Response:**
```json
{
  "data": [
    {
      "cluster_id": "clst_abc123",
      "headline": "Federal Reserve Holds Interest Rates Steady at 5.25-5.50%",
      "summary": "Fed holds rates at 5.25-5.50% citing persistent inflation. Powell signals possible cuts later in 2026 if data improves. Markets react positively with S&P 500 up 0.8%.",
      "language": "en",
      "entities": {
        "persons": ["Jerome Powell"],
        "orgs": ["Federal Reserve", "S&P 500"],
        "locations": ["United States"],
        "countries": ["US"],
        "events": ["FOMC Meeting"]
      },
      "dedup": {
        "source_count": 47,
        "similarity_score": 0.89
      },
      "sources": [
        {
          "url": "https://reuters.com/article/...",
          "domain": "reuters.com",
          "title": "Fed keeps rates steady, signals patience",
          "published_at": "2026-03-15T14:30:00Z"
        }
      ],
      "timestamps": {
        "first_seen": "2026-03-15T14:32:00Z",
        "last_updated": "2026-03-15T16:45:00Z"
      },
      "importance_score": 0.95,
      "category": "economy"
    }
  ],
  "meta": {
    "total_count": 1250,
    "offset": 0,
    "limit": 25
  }
}
```

### GET /api/v1/public/clusters
Public endpoint (no auth required). Same schema as `/clusters` but limited to 50 results.

### GET /api/v1/search
Full-text search across cluster headlines and summaries.

**Parameters:**
- `q` (string, required): Search query
- `limit` (int, default 25): Number of results
- `language` (string): Language filter
- `from_date` / `to_date`: Date range

### GET /api/v1/entities/trending
Returns trending named entities across recent clusters.

**Parameters:**
- `limit` (int, default 20): Number of entities
- `type` (string): Entity type filter (person, org, location)

### GET /api/v1/sources
Returns metadata about indexed news sources.

## Pricing

| Plan | Price | Requests/Month | Features |
|------|-------|-----------------|----------|
| Starter | Free | 1,000 | Full cluster payloads, AI summaries, entities |
| Pro | $39/mo | 50,000 | Priority support, higher rate limits |
| Enterprise | Custom | Unlimited | Custom SLAs, dedicated support, raw data access |

## Languages Served
- Included in payload metadata

## Languages Collected
- Global language coverage

## Countries Covered
- Global news source coverage

## Use Cases
- **LLM & RAG Pipelines**: Feed structured, deduplicated news into AI models
- **Trading Signals**: React to events, not duplicate noise
- **Media Monitoring**: Track entities across publishers and languages
- **News Dashboards**: Embed live news into your product

## Competitor Comparison
News250 is an alternative to newsdata.io, newsapi.org, gnews.io, and mediastack. Key differentiators:
- Deduplication (competitors return raw article lists with duplicates)
- AI-generated summaries per cluster (competitors provide raw content only)
- Structured entity extraction (8 NER types per cluster)
- Event-level clustering (one event = one API object)

## Links
- Website: https://news250.com
- API Docs: https://news250.com/docs
- API Reference: https://news250.com/api
- Pricing: https://news250.com/pricing
- FAQ: https://news250.com/faq
- Alternatives: https://news250.com/alternatives
- Contact: https://news250.com/contact
- Privacy: https://news250.com/privacy
- Terms: https://news250.com/terms