# World News API — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orthogonal.com/v1/run` · [llms.txt](https://orthogonal.com/llms.txt) · [browse all APIs](https://orthogonal.com/discover)

Comprehensive news aggregation API with access to thousands of news sources in 86+ languages from 210+ countries. Search, filter, extract, and analyze news articles with sentiment analysis, entity recognition, and geo-search capabilities.

**Verified:** no

## Access

**Run API:** `POST https://api.orthogonal.com/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://orthogonal.com/dashboard/settings/api-keys

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "price": "<usd>", "data": { ... } }`.

## Endpoints

### Retrieve News by IDs

Retrieve full news articles by ID (IDs come from Search News or Top News). Returns title, full text, summary, URL, image, video, publish date, authors, language, category, source country, and sentiment, plus optional named entities. Price: $0.0008 per ID requested, including entity extraction.

`GET /retrieve-news`

**Estimated cost:** Dynamic — use `"dryRun": true` in the Run API request to check the exact cost before calling.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ids` | string | Yes | Comma-separated list of news article IDs. |
| `add-entities` | boolean | No | Set to true to include named entities (people, organizations, locations) for each article. Included in the price. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"world-news-api","path":"/retrieve-news","method":"GET","query":{"ids":"<string>","add-entities":"<boolean>"}}'
```

### Search News

Search and filter news articles by text, language, source country, news sources, authors, category, sentiment, entities, publish date range, and geographic radius. Returns 1 to 100 articles per request (default 10) with full text, summary, URL, image, authors, publish date, language, category, and sentiment, plus optional named entities (add-entities=true). Price is based on results actually returned: $0.004 per request plus $0.00004 per returned result, or $0.00044 per returned result with entities. Maximum $0.048. Prepaid agent payments (x402, MPP) are charged before the call at $0.004 + $0.00044 per requested result.

`GET /search-news`

**Estimated cost:** Dynamic — use `"dryRun": true` in the Run API request to check the exact cost before calling.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | No | Text to match in news content (3-100 chars). Supports AND, OR, quotes for exact match, minus for exclusion. |
| `text-match-indexes` | string | No | Where to search: title, content, or both (comma-separated). Default: both. |
| `source-country` | string | No | ISO 3166 country code for news origin. |
| `language` | string | No | ISO 6391 language code. |
| `min-sentiment` | number | No | Minimum sentiment score [-1, 1]. |
| `max-sentiment` | number | No | Maximum sentiment score [-1, 1]. |
| `earliest-publish-date` | string | No | Articles published after this date. |
| `latest-publish-date` | string | No | Articles published before this date. |
| `news-sources` | string | No | Comma-separated list of up to 10 news sources. |
| `authors` | string | No | Comma-separated author names. |
| `categories` | string | No | Comma-separated categories: politics, sports, business, technology, entertainment, health, science, lifestyle, travel, culture, education, environment, other. |
| `entities` | string | No | Filter by entities with semantic types (e.g., ORG:Tesla, PER:Elon Musk). |
| `location-filter` | string | No | Filter by radius: latitude,longitude,radius_km (1-100km). |
| `sort` | string | No | Sort criteria. Only publish-time is supported. |
| `sort-direction` | string | No | ASC or DESC. |
| `offset` | number | No | Number of results to skip (0-10000). |
| `number` | number | No | Number of results to return (1-100). Default 10. Each requested result adds $0.00004. |
| `add-entities` | boolean | No | Set to true to include named entities (people, organizations, locations) for each article. Included in the price. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"world-news-api","path":"/search-news","method":"GET","query":{"text":"<string>","text-match-indexes":"<string>","source-country":"<string>","language":"<string>","min-sentiment":"<number>","max-sentiment":"<number>","earliest-publish-date":"<string>","latest-publish-date":"<string>","news-sources":"<string>","authors":"<string>","categories":"<string>","entities":"<string>","location-filter":"<string>","sort":"<string>","sort-direction":"<string>","offset":"<number>","number":"<number>","add-entities":"<boolean>"}}'
```

### Top News

Get the top news stories for a country and language on a given date, clustered across multiple sources and ranked by coverage. Set headlines-only=true to return just id, title, and url. Price: $0.004 per request.

`GET /top-news`

**Estimated cost:** $0.004

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `source-country` | string | Yes | ISO 3166 country code. |
| `language` | string | Yes | ISO 6391 language code (must be spoken in source-country). |
| `date` | string | No | Date for top news (YYYY-MM-DD). Defaults to today. |
| `headlines-only` | boolean | No | Return only id, title, and url. |
| `max-news-per-cluster` | number | No | How many news items per cluster (1-100). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"world-news-api","path":"/top-news","method":"GET","query":{"source-country":"<string>","language":"<string>","date":"<string>","headlines-only":"<boolean>","max-news-per-cluster":"<number>"}}'
```

### Get Geo Coordinates

Convert a place name or address to latitude and longitude. Use the result in Search News location-filter as latitude,longitude,radius_km. Price: $0.004 per request.

`GET /geo-coordinates`

**Estimated cost:** $0.004

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `location` | string | Yes | The address or name of the location. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"world-news-api","path":"/geo-coordinates","method":"GET","query":{"location":"<string>"}}'
```

### Extract News

Extract structured data from a news article URL: title, full text, authors, publish date, image, and language. Set analyze=true to also extract entities and sentiment. Price: $0.008 per request, or $0.016 with analyze=true.

`GET /extract-news`

**Estimated cost:** Dynamic — use `"dryRun": true` in the Run API request to check the exact cost before calling.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | The URL of the news article to extract. |
| `analyze` | boolean | No | Whether to also extract entities and detect sentiment. Raises the price from $0.008 to $0.016. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"world-news-api","path":"/extract-news","method":"GET","query":{"url":"<string>","analyze":"<boolean>"}}'
```

### Extract News Links

Extract news article links from a news site page such as a homepage or section page. Works best with major publisher sites; some heavily scripted or bot-protected pages return no links. Price: $0.004 per request.

`GET /extract-news-links`

**Estimated cost:** $0.004

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | The URL to extract news links from. |
| `prefix` | string | No | Only return links that start with this prefix. |
| `sub-domain` | boolean | No | Whether to include links on sub-domains of the site. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"world-news-api","path":"/extract-news-links","method":"GET","query":{"url":"<string>","prefix":"<string>","sub-domain":"<boolean>"}}'
```

### Search News Sources

Search the news sources indexed by World News API by (partial) name. Returns each source's name, URL, and language. Price: $0.004 per request.

`GET /search-news-sources`

**Estimated cost:** $0.004

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | The (partial) name of the source, at least 3 characters. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"world-news-api","path":"/search-news-sources","method":"GET","query":{"name":"<string>"}}'
```

---

Full details and an interactive quickstart: https://orthogonal.com/discover/world-news-api