> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> API reference for World News API: every `worldnewsapi.api.*` operation with input and output types.

Every `worldnewsapi.api.*` operation is listed below with parameter shapes and return types from the plugin Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## News

### extractNews

`news.extractNews`

Extract a news article from a website to a well-structured JSON object, including title, text, images, videos, publish date, authors, language, and sentiment.

**Risk:** `read`

```ts theme={null}
await corsair.worldnewsapi.api.news.extractNews({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | The URL of the news article to extract into structured data. |
| `analyze` | `boolean` | No | Whether to analyze the extracted news (extract named entities, detect sentiment, etc.). Defaults to false. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `title` | `string` | No | — |
| `text` | `string` | No | — |
| `url` | `string` | No | — |
| `image` | `string \| null` | No | — |
| `images` | `object[]` | No | — |
| `video` | `string \| null` | No | — |
| `videos` | `object[]` | No | — |
| `publish_date` | `string` | No | — |
| `author` | `string \| null` | No | — |
| `authors` | `(string \| null)[]` | No | — |
| `language` | `string` | No | — |
| `source_country` | `string` | No | — |
| `sentiment` | `number` | No | — |
| `entities` | `object[]` | No | — |

> [accordion] images full type
>
> ```ts theme={null}
> {
>   title?: string,
>   url: string,
>   width?: number,
>   height?: number
> }[]
> ```

> [accordion] videos full type
>
> ```ts theme={null}
> {
>   title?: string,
>   url: string,
>   summary?: string,
>   duration?: number,
>   thumbnail?: string
> }[]
> ```

> [accordion] entities full type
>
> ```ts theme={null}
> {
>   name: string,
>   type: string,
>   sentiment?: number
> }[]
> ```

***

### extractNewsLinks

`news.extractNewsLinks`

Extract news article links from a website or webpage, with optional filtering by URL prefix and subdomain inclusion.

**Risk:** `read`

```ts theme={null}
await corsair.worldnewsapi.api.news.extractNewsLinks({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | The webpage or site URL from which news article links should be extracted. |
| `analyze` | `boolean` | No | Whether to analyze extracted links. Defaults to false. |
| `prefix` | `string` | No | The prefix that discovered news links must start with. |
| `subDomain` | `boolean` | No | Whether to include links to news articles on sub-domains. Defaults to true. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `string` | No | — |
| `news_links` | `string[]` | Yes | — |

***

### getGeoCoordinates

`news.getGeoCoordinates`

Retrieve latitude and longitude of a location name to fill the location-filter parameter in news search operations.

**Risk:** `read`

```ts theme={null}
await corsair.worldnewsapi.api.news.getGeoCoordinates({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `location` | `string` | Yes | The address or location name to geocode (e.g., "Tokyo, Japan" or "Mumbai, India"). |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `latitude` | `number` | Yes | — |
| `longitude` | `number` | Yes | — |
| `city` | `string` | No | — |

***

### newsWebsiteToRssFeed

`news.newsWebsiteToRssFeed`

Convert any news website page into an RSS feed with the latest news from that page.

**Risk:** `read`

```ts theme={null}
await corsair.worldnewsapi.api.news.newsWebsiteToRssFeed({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | The URL of the news website/page to convert into an RSS 2.0 feed. |
| `extractNews` | `boolean` | No | Whether to extract full article text/data for each item in the feed (costs additional quota). Defaults to false. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `title` | `string` | No | — |
| `link` | `string` | No | — |
| `description` | `string` | No | — |
| `pubDate` | `string` | No | — |
| `lastBuildDate` | `string` | No | — |
| `language` | `string` | No | — |
| `items` | `object[]` | Yes | — |
| `rawXml` | `string` | No | — |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   title?: string,
>   link?: string,
>   guid?: string,
>   pubDate?: string,
>   description?: string,
>   author?: string,
>   category?: string,
>   enclosureUrl?: string
> }[]
> ```

***

### searchNews

`news.searchNews`

Search and filter news by text, date, location, category, language, and more.

**Risk:** `read`

```ts theme={null}
await corsair.worldnewsapi.api.news.searchNews({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `text` | `string` | No | Search query text. Supports implicit AND, OR, negation with -, parentheses, and quotes for exact phrases. |
| `textMatchIndexes` | `string` | No | Where to search for text: "title", "content", or "title,content". |
| `sourceCountry` | `string` | No | Filter by 2-letter ISO 3166 country code. |
| `language` | `string` | No | Filter by 2-letter ISO 639-1 language code. |
| `minSentiment` | `number` | No | Minimum sentiment score between -1.0 (very negative) and 1.0 (very positive). |
| `maxSentiment` | `number` | No | Maximum sentiment score between -1.0 and 1.0. |
| `earliestPublishDate` | `string` | No | Filter for news published on or after this timestamp (YYYY-MM-DD HH:MM:SS or YYYY-MM-DD). |
| `latestPublishDate` | `string` | No | Filter for news published on or before this timestamp (YYYY-MM-DD HH:MM:SS or YYYY-MM-DD). |
| `newsSources` | `string` | No | Comma-separated list of up to 10 news sources (e.g., "bbc.co.uk,nytimes.com"). |
| `authors` | `string` | No | Comma-separated list of author names. |
| `categories` | `string` | No | Comma-separated categories (politics, sports, business, technology, entertainment, health, science, etc.). |
| `entities` | `string` | No | Filter by semantic entities (e.g., "ORG:Tesla,PER:Elon Musk"). |
| `locationFilter` | `string` | No | Filter by geographic radius in the format "latitude,longitude,radius in km" (radius: 1-100). |
| `sort` | `string` | No | Sort criteria, typically "publish-time". |
| `sortDirection` | `ASC \| DESC` | No | Sort direction: "ASC" or "DESC". Defaults to DESC for publish-time. |
| `offset` | `number` | No | Number of results to skip for pagination. |
| `number` | `number` | No | Number of results to return (1-100). Defaults to 10. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `offset` | `number` | Yes | — |
| `number` | `number` | Yes | — |
| `available` | `number` | Yes | — |
| `news` | `object[]` | Yes | — |

> [accordion] news full type
>
> ```ts theme={null}
> {
>   id: number,
>   title: string,
>   text?: string,
>   summary?: string | null,
>   url: string,
>   image?: string | null,
>   video?: string | null,
>   publish_date?: string,
>   author?: string | null,
>   authors?: (string | null)[],
>   category?: string,
>   language?: string,
>   source_country?: string,
>   sentiment?: number
> }[]
> ```

***

### searchNewsSources

`news.searchNewsSources`

Search whether a news source is being monitored by the World News API.

**Risk:** `read`

```ts theme={null}
await corsair.worldnewsapi.api.news.searchNewsSources({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | The (partial) name of the news source to search for (e.g. "bbc", "reuters", "times"). |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `available` | `number` | Yes | — |
| `sources` | `object[]` | Yes | — |

> [accordion] sources full type
>
> ```ts theme={null}
> {
>   name: string,
>   url: string,
>   language?: string,
>   country?: string
> }[]
> ```

***

### topNews

`news.topNews`

Get the top news from a country in a specific language for a given date. The top news are clustered from multiple sources in the specified country.

**Risk:** `read`

```ts theme={null}
await corsair.worldnewsapi.api.news.topNews({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `sourceCountry` | `string` | Yes | The 2-letter ISO 3166 country code for which top news should be retrieved (e.g., "us", "in", "gb"). |
| `language` | `string` | Yes | The 2-letter ISO 639-1 language code of the top news (e.g., "en", "es", "fr"). |
| `date` | `string` | No | The date for which the top news should be retrieved (YYYY-MM-DD). Defaults to today. |
| `headlinesOnly` | `boolean` | No | Whether to only return basic headline fields (id, title, url). Defaults to false. |
| `maxNewsPerCluster` | `number` | No | How many news articles to return per story cluster. Default is 1. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `top_news` | `object[]` | Yes | — |
| `language` | `string` | No | — |
| `country` | `string` | No | — |

> [accordion] top\_news full type
>
> ```ts theme={null}
> {
>   news: {
>     id: number,
>     title: string,
>     text?: string,
>     summary?: string | null,
>     url: string,
>     image?: string | null,
>     video?: string | null,
>     publish_date?: string,
>     author?: string | null,
>     authors?: (string | null)[],
>     category?: string,
>     language?: string,
>     source_country?: string,
>     sentiment?: number
>   }[]
> }[]
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.