​
Overview

Proximity search is a powerful technique that lets you find articles where specific terms appear close to each other. This method is particularly useful to ensure that related concepts are discussed in the same context within an article.

News API v3 supports proximity search through the NEAR operator. This operator lets you specify two or more terms and the maximum number of words that can appear between them.

By using the NEAR operator, you can significantly improve the relevance of your search results, finding articles where related terms are discussed in close proximity to each other.

​
Before you start

Before you begin, ensure you have:

  • An active API key for NewsCatcher News API v3
  • Basic knowledge of making API requests
  • Python or another tool for making HTTP requests (cURL, Postman, or a programming language with HTTP capabilities)

​
Steps

1

Understand NEAR syntax

The NEAR operator uses the following format:

NEAR("phrase_A", "phrase_B", distance, in_order);
  • phrase_A and phrase_B: The terms or phrases you want to find near each other (max 4 words per phrase).
  • distance: The maximum number of words that can appear between the phrases (max 100).
  • in_order: Optional boolean parameter. If true, phrase_B must appear after phrase_A. Defaults to false.
2

Construct your query

Here are some examples of NEAR queries:

  • NEAR("climate change", "renewable energy", 15)
  • NEAR("artificial intelligence", "healthcare", 20, true)

Note the following limitations:

  • Maximum 4 words per phrase
  • Maximum 3 phrases per NEAR operation
  • Maximum distance of 100 words
3

Make an API request

Use the /search endpoint with your constructed query in the q parameter. Here’s a Python code example:

import requests
import json

API_KEY = "YOUR_API_KEY_HERE"
URL = "https://v3-api.newscatcherapi.com/api/search"
HEADERS = {"x-api-token": API_KEY}

PAYLOAD = {
    "q": 'NEAR("climate change", "renewable energy", 15)',
    "lang": "en",
}

try:
    response = requests.post(URL, headers=HEADERS, json=PAYLOAD)
    response.raise_for_status()
    print(json.dumps(response.json(), indent=2))
except requests.exceptions.RequestException as e:
    print(f"Failed to fetch articles: {e}")
4

Analyze the results

The API returns a JSON response similar to other search queries. Here’s an example of what you might see:

{
  "status": "ok",
  "total_hits": 635,
  "page": 1,
  "total_pages": 7,
  "page_size": 100,
  "articles": [
    {
      "title": "We Must Adopt Renewable Energy To Combat Climate Change",
      "author": null,
      "published_date": "2024-09-01",
      "link": "https://ournaijanews.com/we-must-adopt-renewable-energy-to-combat-climate-change-sanusi",
      "domain_url": "ournaijanews.com",
      "description": "Emir Sanusi II advocates for renewable energy adoption to combat climate change, emphasizing its importance for environmental and human health.",
      "word_count": 453
      // ... other article fields
    }
    // ... other articles
  ],
  "user_input": {
    "q": "NEAR(\"climate change\", \"renewable energy\", 15)",
    "lang": ["en"],
    "from_": "2024-08-26T00:00:00",
    "to_": "2024-09-02T10:32:59.545085",
    "sort_by": "relevancy",
    "page": 1,
    "page_size": 100
    // ... other input parameters
  }
}
5

Refine your query as needed

If you’re not getting the desired results, try adjusting your query:

  • Change the distance parameter to narrow or broaden your search
  • Add more terms to the NEAR operator (up to 3 phrases)
  • Combine NEAR with boolean operators for more complex queries. For example:
NEAR("electric vehicles", "battery technology", 20) AND NOT "Tesla"

​
See also

Was this page helpful?

Use boolean operatorsSearch by entity