Name: News Headlines API: World News by Country as JSON
Brand: martindata
SKU: api-martindata-newsheadlines-api
Availability: InStock
Author: API Market

# News Headlines API

## Overview

The News Headlines API collects the latest headlines from news outlets around the world and returns them as clean JSON. A single endpoint takes filters for country, topic, language, keywords and outlet, and returns up to 100 headlines per request, newest first. Each headline has its title, summary, link, source, publication time and image URL when one exists. The same endpoint can also return the catalog of feeds it reads.

It is built for developers of news apps, media monitoring tools, market research dashboards and AI agents that need current headlines in one format. Results are read live from publisher RSS and Atom feeds, and you can add your own feed URLs to the same request.

## Features

*   **1 endpoint**: headlines and the feed catalog from the same call.
*   **Filters**: country, topic, language, keywords, excluded keywords and outlet.
*   **Custom feeds**: add any RSS or Atom feed URL through `extraFeeds`.
*   **Result size**: up to 100 headlines per request, newest first.
*   **Billing**: 1 API unit per result returned, so a call that returns 5 results uses 5 units.
*   **Deduplication**: the same story across sections of one outlet is returned once.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **News apps**: build country or topic feeds from one source.
*   **Media monitoring teams**: track a brand, person or ticker with keyword filters.
*   **Market researchers**: follow business and technology headlines by region.
*   **AI agents**: give a model current headlines with source links.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/martindata/newsheadlines-api
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. News headlines

Returns the latest headlines for your filters. Requests read live feeds and can take up to about 60 seconds, so set your client timeout to 150 seconds.

**Method:** `POST`

**Endpoint:** `/m/news-headlines-scraper`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| countries | body | Two-letter country codes of the outlets (us, gb, ca, au, in, de, fr, es, it, nl, br, jp, bg, ... and 'int' for international outlets like Al Jazeera, DW, France 24, UN News). 'uk' and 'usa' also work. Empty = all 44 countries. Run with listSources=true to see every feed. | array of strings | No | - | - |
| topics | body | Feed sections: top, world, business, technology, science, health, sports, entertainment, politics. Empty = all topics. Many countries only have 'top' (main headlines) feeds. | array of strings | No | - | - |
| keywords | body | Keep only headlines whose title or summary contains at least one of these words or phrases (whole-word, case-insensitive), e.g. a brand, person, ticker or topic. Empty = all headlines. | array of strings | No | - | - |
| excludeKeywords | body | Drop headlines that contain any of these words or phrases. | array of strings | No | - | - |
| languages | body | Two-letter language codes (en, de, fr, es, it, pt, nl, pl, sv, bg, ja, ...). Empty = all languages. | array of strings | No | - | - |
| sources | body | Only these outlets: part of the name or domain, e.g. 'BBC', 'nytimes', 'Al Jazeera'. Empty = all outlets that match the other filters. | array of strings | No | - | - |
| extraFeeds | body | Any other RSS or Atom feed URLs to read in the same run (your trade press, a company newsroom, a local paper). They get topic 'custom'. | array of strings | No | - | - |
| hoursBack | body | Only headlines published in the last N hours. Feeds usually hold the last 1-3 days. Default 24. | integer | No | - | - |
| maxItems | body | Most headlines saved (newest first) and the most you pay for. Default 100. | integer | No | 20 | 100 |
| dedupe | body | The same story in several feeds of one outlet (top + world + politics) is saved once; its sections are listed in 'topics'. | boolean | No | - | - |
| requireImage | body | Keep only headlines that come with an image URL. | boolean | No | - | - |
| listSources | body | Instead of headlines, output the feed catalog (country, language, topic, outlet, feed URL) for the filters above. Free of headlines, one row per feed. | boolean | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/newsheadlines-api/m/news-headlines-scraper' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "countries": [
    "us",
    "gb"
  ],
  "hoursBack": 24,
  "maxItems": 5,
  "dedupe": true,
  "requireImage": false,
  "listSources": false
}'
```

**Example Response (200 OK):**

```json
{
  "count": 5,
  "items": [
    {
      "ageMinutes": 2,
      "author": null,
      "categories": [
        "sports",
        "college"
      ],
      "country": "us",
      "feedUrl": "https://sports.yahoo.com/rss/",
      "fetchedAt": "2026-11-08T11:18:26Z",
      "imageUrl": "https://media.zenfs.com/en/the-oklahoman/365c87e83ad2cffb69f1b81b991ff99e.jpg",
      "language": "en",
      "matchedKeywords": null,
      "publishedAt": "2026-11-08T11:16:08Z",
      "source": "Yahoo Sports",
      "sourceDomain": "sports.yahoo.com",
      "summary": "David Taylor wants his Oklahoma State wrestlers to know that last Sunday's invitational results are just a starting point. Not an ending point.",
      "title": "Oklahoma State wrestling roster 'hungry' and deep. Here are four weight classes to watch.",
      "topic": "sports",
      "topics": [
        "sports"
      ],
      "url": "https://sports.yahoo.com/articles/oklahoma-state-wrestling-roster-hungry-111608505.html"
    },
    {
      "ageMinutes": 2,
      "author": null,
      "categories": [],
      "country": "gb",
      "feedUrl": "https://www.dailymail.co.uk/articles.rss",
      "fetchedAt": "2026-11-08T11:18:26Z",
      "imageUrl": "https://i.dailymail.com/1s/2026/11/08/10/112376955-0-image-m-42_1794134593289.jpg",
      "language": "en",
      "matchedKeywords": null,
      "publishedAt": "2026-11-08T11:15:56Z",
      "source": "Daily Mail",
      "sourceDomain": "dailymail.com",
      "summary": "Ernest Cruz, 38, abused the 'barely conscious' victim in a private room at Bournemouth Hospital - going in to see her 12 times over a two-hour period.",
      "title": "Nurse who sexually assaulted woman in A&E after she was admitted when her drink was spiked is jailed seven years",
      "topic": "top",
      "topics": [
        "top"
      ],
      "url": "https://www.dailymail.com/news/article-16275855/nurse-sexually-assaulted-woman-drink-spiked-jailed-seven-years.html?ns_mchannel=rss&ito=1490&ns_campaign=1490"
    }
  ]
}
```

#### 2. Feed catalog

Set `listSources` to `true` to get the feeds that match your filters instead of headlines. The parameters are the same as above.

**Method:** `POST`

**Endpoint:** `/m/news-headlines-scraper`

**Parameters:** None.

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/newsheadlines-api/m/news-headlines-scraper' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "countries": [
    "int"
  ],
  "listSources": true,
  "maxItems": 3
}'
```

**Example Response (200 OK):**

```json
{
  "count": 7,
  "items": [
    {
      "country": "int",
      "feedUrl": "https://www.aljazeera.com/xml/rss/all.xml",
      "language": "en",
      "source": "Al Jazeera",
      "topic": "world",
      "type": "source"
    },
    {
      "country": "int",
      "feedUrl": "https://rss.dw.com/rdf/rss-en-all",
      "language": "en",
      "source": "DW",
      "topic": "world",
      "type": "source"
    },
    {
      "country": "int",
      "feedUrl": "https://rss.dw.com/rdf/rss-en-bus",
      "language": "en",
      "source": "DW",
      "topic": "business",
      "type": "source"
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

Every plan allows up to 10 requests per second. Subscription plans also have a monthly call quota shown on the pricing page. Sending more than 10 requests per second returns `429 Too Many Requests`. Throttle your client to stay under 10 requests per second, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **How is usage counted?**

    One API unit per result returned. The feed catalog also counts one unit per row.

*   **How far back do results go?**

    Use `hoursBack` to limit by age. Feeds usually hold the last 1 to 3 days.

*   **Which countries are supported?**

    Call the endpoint with `listSources` set to `true` to see the feeds for a country. Use `int` for international outlets such as Al Jazeera and DW.

*   **Why did a request take a long time?**

    Results are read live from many feeds, so a broad request can take up to about 60 seconds.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Get the latest news headlines by country, topic, language, keyword or outlet as clean JSON, with summaries, images and source links.

News Headlines API: World News by Country as JSON