How does the related articles algorithm work?

It analyzes content similarity, shared topics, named entities, and temporal proximity. Articles about the same story from different sources rank higher.

Can I filter related articles by country or language?

Yes. Apply the same filters available in `/search` to narrow related articles by country, language, political leaning, or source type.

How many related articles should I display?

3-5 related articles work well for sidebars. Use the `page_size` parameter to control results. Adjust based on your UI layout and user engagement.

Do related articles update in real-time?

Yes. As new articles are published on the same topic, they'll appear in related results. Poll periodically for evergreen content or breaking news.

Can I exclude the original article from results?

The API automatically excludes the source article used in the `article_id` parameter from related results.

How Do I Find Related or Similar News Articles? NewsDataHub Article Similarity API

intermediate 8 min read October 3, 2025

news api related articlesrelated articles apisimilar articles apiarticle similarity apinews recommendation endpointelasticsearch more like thishow to find related news articles via apinews api fields parameterreduce response size with fields parameterpython requests news api examplecurl example news api related

Learn how to use GET /v1/news/{article_id}/related to fetch articles similar to a given story, with parameters, code samples, and a trimmed response.

News has become an essential part of our daily lives, and the ability to find related news articles is a key feature for any news application or website. This feature can enhance the user experience by providing a comprehensive view of a news event or topic, ensuring readers won’t miss any important details or developments. In this article, we’ll explore how to use the GET /v1/news/{article_id}/related endpoint of the NewsDataHub API to find articles similar to a given article.

The NewsDataHub API uses a sophisticated algorithm to find similar articles by comparing multiple content elements. This algorithm analyzes the title, description, topics, and keywords of articles to identify meaningful connections between them. By examining these textual elements, the system can determine content similarity regardless of publication source. The results are limited to articles published within the last 60 days, ensuring their relevance and timeliness.

Here’s a quick overview of some key parameters you can use:

article_id:
- Type: String (path parameter)
- Purpose: The ID (UUID) of the article to find similar articles for
- Required: true
- Example: fa90d4bd-f901-4ea6-8b4d-e6f7a451d311
per_page:
- Type: Integer (query parameter)
- Purpose: Number of related articles to return (tier-dependent)
- Limits: Free: max 10, Starter: max 30, Basic: max 50, Pro: max 100
- Default: 5
- Example: ?per_page=5
fields:
- Type: String (query parameter)
- Purpose: Comma-separated list of fields to return
- Note: Returns all fields if not specified. ‘id’ is always included
- Example: ?fields=title,pub_date,source_title

To request related articles, you’ll need to make a GET request to the /v1/news/{article_id}/related endpoint. The article_id is a required parameter and should be the UUID of the article you want to find similar articles to.

Here’s a basic example of how to make a request:

import requests

API_KEY = "your-api-key"
article_id = "your-article-id"
url = f"https://api.newsdatahub.com/v1/news/{article_id}/related"
headers = {
    "x-api-key": API_KEY,
    "accept": "application/json",
    "User-Agent": "newsdatahub-related-articles-endpoint/1.0-py"
}
params = {
    'per_page': 5
}

try:
    response = requests.get(url, params=params, headers=headers, timeout=30)
    response.raise_for_status()  # Raise exception for 4XX/5XX status codes

    data = response.json()['data']
    for article in data:
        print(article['title'])
        print(f"By {article['source_title']}, published: {article['pub_date']}")
        print('----------------------------')

except requests.exceptions.HTTPError as err:
    status_code = err.response.status_code
    if status_code == 400:
        print("Error 400: Bad Request - Check your parameters")
    elif status_code == 401:
        print("Error 401: Unauthorized - Invalid API key")
    elif status_code == 429:
        print("Error 429: Too Many Requests - Rate limit exceeded")
    elif status_code == 500:
        print("Error 500: Internal Server Error - Try again later")
    else:
        print(f"HTTP Error: {err}")
except requests.exceptions.RequestException as err:
    print(f"Request Error: {err}")
except (KeyError, ValueError) as err:
    print(f"Response parsing error: {err}")

Example output:

Jeff Bezos Donates 520K Amazon Shares Worth Over $120M in Two Weeks
By International Business Times, published: 2025-09-21T02:44:22
----------------------------
Amazon.com, Inc. $AMZN Shares Bought by Sard Wealth Management Group LLC
By ETF Daily News, published: 2025-09-21T08:24:54
----------------------------
True Vision MN LLC Sells 61 Shares of Amazon.com, Inc. (NASDAQ:AMZN)
By ETF Daily News, published: 2025-08-06T07:55:05

Truncated example of the response:

{
  "related_to": {
      "id": "c4437db1-a8c5-4809-a00e-25e321bc2607",
      "title": "Jeff Bezos unloads over 3M Amazon shares worth $737M in June",
      "source_title": "New York Post",
      "article_link": "https://nypost.com/2025/07/01/business/jeff-bezos-unloads-over-3m-amazon-shares-worth-737m-in-june/",
      "pub_date": "2025-07-01T22:32:59"
    },
    "count": 1,
    "data": [
      {
        "id": "69120e42-23f8-4724-814a-38de8acda4ee",
        "title": "Jeff Bezos Donates 520K Amazon Shares Worth Over $120M in Two Weeks",
        "source_title": "International Business Times",
        "source_link": "https://ibtimes.co.uk",
        "article_link": "https://www.ibtimes.co.uk/jeff-bezos-donates-520k-amazon-shares-worth-over-120m-two-weeks-1744503",
        "keywords": [
          "Jeff Bezos Amazon shares donation",
          "non-profit organisations",
          "stock sale",
          "Blue Origin",
          "prenuptial agreement",
          "Florida mansion",
          "tax savings",
          "stock portfolio",
          "Amazon founder",
          "charity gifts"
        ],
        "topics": [
          "business",
          "philanthropy",
          "technology",
          "finance",
          "wealth management"
        ],
        "description": "Jeff Bezos continues to gift Amazon shares to non-profit organisations, and remains on track to match his 2024 record.",
        "pub_date": "2025-09-21T02:44:22",
        "creator": "Niloy Chakrabarti",
        "content": "Amazon founder and billionaire, Jeff Bezos, is known for frequently making donations to non-profit organisations. He himself runs non-profit funds, foundations, and preschools aimed at climate change and education. According to Form 4 filings with the US Securities and Exchange Commission, Bezos gifted over 5. 2 million shares of Amazon (Nasdaq: AMZN) to non-profit organisations between 14th August and 28th August. The total number of Amazon shares donated would be worth over $120. 8 million (88. 6 million) based on the latest closing price of $231. 62 (169. 94). Bezos owned over 883 million shares of the company after the donation, according to the filing. This year alone, Bezos has already gifted millions of Amazon shares to non-profits, with the first donation in early March. He remains on track to match last year's record. Apart from donations, Bezos sold billions of dollars' worth of Amazon shares around the time of his marriage to Lauren Sanchez earlier this year. The three-day extravaganza in Venice alone cost him an estimated $50 million (36. 6 million). The timing of the stock sale and Bezos' marriage got experts speculating that the financial move was related to a prenuptial agreement he reportedly signed with Sanchez before their marriage. The sale was under a March 10b5-1 plan, which notes that Bezos will offload $4. 7 billion (3. 4 billion) of the Amazon stock by May 2026. According to California attorney Alphonse Provinziano, the prenup would have likely included detailed documentation of Bezos' businesses, stock portfolio, and potential liabilities, ensuring there are no legal grey areas in case of a future dispute, thus minimising the chances of prolonged court battles. Last year, the Amazon founder sold an estimated $13. 6 billion (9. 9 billion) worth of Amazon shares. Reports emerged that he also uses the sales proceeds to fund his Blue Origin venture, which directly rivals Elon Musk's SpaceX. For instance, he sold over $3 billion (2. 2 billion) of the Amazon stock in November, ahead of Blue Origin's New Glenn launch. 'The only reason we are taking Blue Origin more seriously is because Bezos is bankrolling it,' Space Capital investor Chad Anderson had told The New York Times. Elsewhere, Bezos was also spending significantly on Florida mansions while saving taxes. He moved to Florida from Seattle, Washington, in early 2024. He announced his plans to move in 2023, citing personal and professional reasons: staying closer to his parents and Blue Origin in Cape Canaveral. He reportedly spent almost $250 million (183. 4 million) on three mansions in the billionaire bunker of Indian Creek village, which can be accessed only through a guarded bridge. That's not all. Financial experts believe Bezos saved over $1 billion (733. 6 million) in taxes this year by moving to Florida, as the state doesn't charge state income tax or capital gains tax compared to Washington, which imposed a 7% tax on long-term capital gains for selling assets over $250, 000 (183, 423). He will also avoid estate tax since Florida doesn't impose it, which will save his heirs more money in the future.",
        "media_url": "https://d.ibtimes.co.uk/en/full/1721966/jeff-bezos.jpg",
        "media_type": "image/jpeg",
        "media_description": null,
        "media_credit": null,
        "media_thumbnail": null,
        "language": "en",
        "sentiment": {
          "pos": 0.116,
          "neg": 0.035,
          "neu": 0.848
        },
        "source": {
          "id": "international-business-times",
          "country": "GB",
          "political_leaning": "center",
          "reliability_score": 7.0,
          "type": "digital_native"
        }
      },
    ]
}

Understanding the Response Structure

The response from the GET /v1/news/{article_id}/related endpoint returns a comprehensive JSON object with three main sections:

related_to object: Contains metadata about the original article you queried:

id: The unique identifier of the original article
title: The headline of the original article
source_title: The publication source (e.g., “New York Post”)
article_link: The URL to the original article
pub_date: Publication timestamp in ISO 8601 format

count field: Total number of related articles found that match your query parameters

data array: Contains the collection of related articles, each with extensive metadata:

Basic information: id, title, source_title, source_link, article_link, pub_date
Content details: description, content (full article text), creator (author)
Categorization: keywords array, topics array
Media: media_url, media_type, media_description, media_credit, media_thumbnail
Analysis: language, sentiment object (with pos, neg, neu values)
Source metadata: source object (with id, country, political_leaning, reliability_score, type)

You can customize the fields returned using the fields parameter and control the number of results with per_page parameter.

Here is another example using curl where we also utilize the fields parameter. We are using a real article ID in this example.

curl -G 'https://api.newsdatahub.com/v1/news/c4437db1-a8c5-4809-a00e-25e321bc2607/related' \
             -H 'x-api-key: YOUR_API_KEY' \
             -H 'User-Agent: newsdatahub-related-articles-endpoint/1.0-curl' \
             --data-urlencode 'per_page=3' \
             --data-urlencode 'fields=title,source_title,article_link,pub_date'

The response will only return fields specified in fields parameter. The fields parameter is set to title,source_title,article_link,pub_date, which instructs the API to return only these specific fields for each article in the response. Note that id is always included. The fields parameter in the NewsDataHub API allows you to customize which fields are included in the response. In this example, the response includes only the specific fields requested in the API call, which significantly reduces the size and complexity of the response.

{
  "related_to": {
      "id": "c4437db1-a8c5-4809-a00e-25e321bc2607",
      "title": "Jeff Bezos unloads over 3M Amazon shares worth $737M in June",
      "source_title": "New York Post",
      "article_link": "https://nypost.com/2025/07/01/business/jeff-bezos-unloads-over-3m-amazon-shares-worth-737m-in-june/",
      "pub_date": "2025-07-01T22:32:59"
    },
    "count": 3,
    "data": [
      {
        "id": "69120e42-23f8-4724-814a-38de8acda4ee",
        "title": "Jeff Bezos Donates 520K Amazon Shares Worth Over $120M in Two Weeks",
        "source_title": "International Business Times",
        "article_link": "https://www.ibtimes.co.uk/jeff-bezos-donates-520k-amazon-shares-worth-over-120m-two-weeks-1744503",
        "pub_date": "2025-09-21T02:44:22"
      },
      {
        "id": "e99bd052-482c-44a2-89d7-e8ff8bda0992",
        "title": "Amazon.com, Inc. $AMZN Shares Bought by Sard Wealth Management Group LLC",
        "source_title": "ETF Daily News",
        "article_link": "https://www.etfdailynews.com/2025/09/21/amazon-com-inc-amzn-shares-bought-by-sard-wealth-management-group-llc/",
        "pub_date": "2025-09-21T08:24:54"
      },
      {
        "id": "14a42102-481a-4432-8c62-8f0243b69835",
        "title": "True Vision MN LLC Sells 61 Shares of Amazon.com, Inc. (NASDAQ:AMZN)",
        "source_title": "ETF Daily News",
        "article_link": "https://www.etfdailynews.com/2025/08/06/true-vision-mn-llc-sells-61-shares-of-amazon-com-inc-nasdaqamzn/",
        "pub_date": "2025-08-06T07:55:05"
      }
    ]
}

Response Comparison

In the filtered response, each article in the data array contains only:

id (always included regardless of fields parameter)
title
source_title
article_link
pub_date

In a full response (without the fields parameter), each article would include many additional fields such as:

source_link
keywords
topics
description
content (full article text)
creator
media_url, media_type, etc.
language
sentiment data
source metadata with reliability scores and political leaning

Benefits of Using the Fields Parameter

Reduced data transfer: Only getting the data you need saves bandwidth
Improved performance: API responses are processed faster
Simplified data handling: Your application only needs to process relevant fields
Better user experience: Reduces load times by retrieving only necessary information

This approach is particularly useful in mobile applications or situations where bandwidth is limited or when you only need specific information from articles for display purposes.

Error Handling and Rate Limits

The NewsDataHub API returns standard HTTP status codes. It’s important to handle these error responses appropriately in your code and respect the rate limits. Below are a few common error responses and what they mean:

400 Bad Request: The request was unacceptable, often due to missing a required parameter.
401 Unauthorized: No valid API key provided.
429 Too Many Requests: You’ve exceeded the rate limits. Check the official documentation for current limits.
500 Internal Server Error: Something went wrong on NewsDataHub’s end.

Frequently Asked Questions (FAQ)

What is the NewsDataHub API?

The NewsDataHub API is a comprehensive news data service that provides access to breaking news articles from major publications worldwide. It offers powerful filtering capabilities by topic, country, language, source and more. Check out our official documentation here.
What is the NewsDataHub API’s related articles feature?

The NewsDataHub API’s related articles feature allows developers to find news articles that are similar to a given article using the GET /v1/news/{article_id}/related endpoint. This feature enhances user experience by providing articles that are related to news events or topics covered in the original article. This ensures readers don’t miss important details or developments.
How far back do related articles go?

The NewsDataHub API provides related articles that have been published within the last 60 days. This time limitation ensures that the results remain relevant and timely to the original article’s content, giving users access to recent developments on similar topics.
What are the key parameters for the related articles endpoint?

The key parameters include:
- article_id (required): The UUID of the article to find similar articles for
- per_page: Number of related articles to return, with tier-dependent limits (Free: max 10, Starter: max 30, Basic: max 50, Pro: max 100)
- fields: Comma-separated list of fields to return, allowing customization of the response
How can I optimize API responses for mobile applications?

You can optimize API responses for mobile applications by using the fields parameter to request only specific fields you need. This approach offers several benefits:
- Reduced data transfer, saving bandwidth
- Improved performance with faster API processing
- Simplified data handling in your application
- Better user experience with reduced load times
What information is included in a full API response?

A full response from the related articles endpoint contains three main sections:
- related_to object: Contains metadata about the original article (id, title, source, etc.)
- count field: Total number of related articles found
- data array: Collection of related articles with extensive metadata including basic information, content details, categorization, media, analysis, and source metadata
Can I try the NewsDataHub API without writing code?

Yes, we have an interactive API Testing Tool in our documentation that lets you make API requests directly from the browser. Just sign up for an account to get your API key (no credit card required) and start testing various endpoints and parameters right away in our docs.

FAQ

How does the related articles algorithm work?

It analyzes content similarity, shared topics, named entities, and temporal proximity. Articles about the same story from different sources rank higher.
Can I filter related articles by country or language?

Yes. Apply the same filters available in /search to narrow related articles by country, language, political leaning, or source type.
How many related articles should I display?

3-5 related articles work well for sidebars. Use the page_size parameter to control results. Adjust based on your UI layout and user engagement.
Do related articles update in real-time?

Yes. As new articles are published on the same topic, they’ll appear in related results. Poll periodically for evergreen content or breaking news.
Can I exclude the original article from results?

The API automatically excludes the source article used in the article_id parameter from related results.

Olga S.

Founder of NewsDataHub — Distributed Systems & Data Engineering

Connect on LinkedIn

How Do I Find Related or Similar News Articles? NewsDataHub Article Similarity API

Truncated example of the response:

Understanding the Response Structure

Response Comparison

Benefits of Using the Fields Parameter

Error Handling and Rate Limits

Frequently Asked Questions (FAQ)

Further Reading

Wrapping Up

FAQ

Olga S.

How Do I Find Related or Similar News Articles? NewsDataHub Article Similarity API

Understanding the Related Articles Algorithm

Requesting Related Articles

Truncated example of the response:

Understanding the Response Structure

Response Comparison

Benefits of Using the Fields Parameter

Error Handling and Rate Limits

Frequently Asked Questions (FAQ)

Further Reading

Wrapping Up

FAQ

Stay Updated

Olga S.