Local News API quickstart guide

This guide helps you make your first API call to access local news articles with location detection and filtering capabilities.

Before you start

Before you begin, make sure you meet these prerequisites:

An API key (obtain one through Book a demo page)
Basic understanding of REST APIs
Your preferred programming language and HTTP client
Basic knowledge of JSON data format

Steps

Set up your environment

Make sure you have the necessary HTTP client library installed for your programming language:

# cURL is typically included in your system
# To check, open the terminal and type the following:
curl --version

pip install requests

npm install axios

Make your first request

Search for local news articles using standard location filtering:

curl -X POST https://local-news.newscatcherapi.com/api/search \
  -H "x-api-token: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "locations": ["San Francisco, California"],
    "detection_methods": ["local_section", "ai_extracted"],
    "theme": "Tech",
    "lang": "en",
    "from_": "7 days ago"
  }'

{
  "q": "*",
  "locations": ["San Francisco, California"],
  "detection_methods": ["local_section", "ai_extracted"],
  "theme": "Tech",
  "lang": "en",
  "from_": "7 days ago"
}

import requests
import json

# Configuration
API_KEY = "YOUR_API_KEY_HERE"  # Replace with your actual API key
URL = "https://local-news.newscatcherapi.com/api/search"
HEADERS = {"x-api-token": API_KEY, "Content-Type": "application/json"}

# Define the search parameters
PAYLOAD = {
    "q": "*",  # Search for all articles
    "locations": ["San Francisco, California"],  # City to search for
    "detection_methods": [
        "local_section",
        "ai_extracted",
    ],  # How to detect location mentions
    "theme": "Tech",  # Filter for tech news
    "lang": "en",  # English language articles
    "from_": "7 days ago",  # Articles from the last week
}

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}")

async function fetchLocalNews() {
  const API_KEY = "YOUR_API_KEY_HERE";
  const URL = "https://local-news.newscatcherapi.com/api/search";

  const payload = {
    q: "*",
    locations: ["San Francisco, California"],
    detection_methods: ["local_section", "ai_extracted"],
    theme: "Tech",
    lang: "en",
    from_: "7 days ago"
  };

  try {
    const response = await fetch(URL, {
      method: 'POST',
      headers: {
        'x-api-token': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log(JSON.stringify(data, null, 2));
  } catch (error) {
    console.error('Failed to fetch articles:', error);
  }
}

fetchLocalNews();

Replace YOUR_API_KEY_HERE with your actual API key.

Review the response

The API returns a JSON response containing articles with location data:

JSON

{
  "status": "ok",
  "total_hits": 51,
  "page": 1,
  "total_pages": 1,
  "page_size": 100,
  "articles": [
    {
      "id": "d156bb26af2b39ed33bd96b8428b4b21",
      "locations": [
        {
          "name": "San Francisco, California",
          "detection_methods": ["local_section"]
        }
      ],
      "title": "Researchers say an AI-powered transcription tool used in hospitals invents things no one ever said",
      "link": "https://www.sfchronicle.com/business/article/researchers-say-an-ai-powered-transcription-tool-19864411.php",
      "published_date": "2024-10-26 04:15:41",
      "domain_url": "sfchronicle.com",
      // ... other fields
      "nlp": {
        "theme": ["Tech", "Science"],
        "summary": "Whisper, an AI-powered transcription tool, is prone to making up chunks of text or entire sentences.",
        "sentiment": {
          "title": 0.8877,
          "content": -0.9958
        }
        // ... other nlp fields
      }
    }
  ]
}

Try advanced GeoNames filtering

Use the advanced endpoint for structured geographic filtering with additional metadata:

curl -X POST https://local-news.newscatcherapi.com/api/search/advanced \
  -H "x-api-token: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "venture capital",
    "geonames": [{
      "name": "San Francisco",
      "country": "US",
      "admin1": {
        "name": "California"
      },
      "localization_score": {
        "min": 7
      }
    }],
    "from_": "7 days ago"
  }'

{
  "q": "venture capital",
  "geonames": [{
    "name": "San Francisco",
    "country": "US",
    "admin1": {
      "name": "California"
    },
    "localization_score": {
      "min": 7
    }
  }],
  "from_": "7 days ago"
}

import requests
import json

API_KEY = "YOUR_API_KEY_HERE"
URL = "https://local-news.newscatcherapi.com/api/search/advanced"
HEADERS = {"x-api-token": API_KEY, "Content-Type": "application/json"}

PAYLOAD = {
    "q": "venture capital",
    "geonames": [{
        "name": "San Francisco",
        "country": "US",
        "admin1": {
            "name": "California"
        },
        "localization_score": {
            "min": 7  # Only articles with high local relevance
        }
    }],
    "from_": "7 days ago"
}

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}")

async function fetchAdvancedLocalNews() {
  const API_KEY = "YOUR_API_KEY_HERE";
  const URL = "https://local-news.newscatcherapi.com/api/search/advanced";

  const payload = {
    q: "venture capital",
    geonames: [{
      name: "San Francisco",
      country: "US",
      admin1: {
        name: "California"
      },
      localization_score: {
        min: 7
      }
    }],
    from_: "7 days ago"
  };

  try {
    const response = await fetch(URL, {
      method: 'POST',
      headers: {
        'x-api-token': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log(JSON.stringify(data, null, 2));
  } catch (error) {
    console.error('Failed to fetch articles:', error);
  }
}

fetchAdvancedLocalNews();

Review the advanced response

The advanced endpoint returns structured GeoNames data:

JSON

{
  "status": "ok",
  "total_hits": 23,
  "page": 1,
  "total_pages": 1,
  "page_size": 100,
  "articles": [
    {
      "id": "249f0551574a6042ca375d0a9d64bae9",
      "geonames": [
        {
          "geonames_id": "5391959",
          "name": "San Francisco",
          "country": "US",
          "admin1": {
            "geonames_id": "5332921",
            "name": "California",
            "code": "CA"
          },
          "coordinates": {
            "lat": 37.77493,
            "lon": -122.41942
          },
          "feature_class": "P",
          "feature_code": "PPL",
          "detection_methods": ["ai_extracted"],
          "reason": "San Francisco mentioned as the location of venture capital activity",
          "localization_score": 8.5,
          "confidence_score": 9.2
        }
      ],
      "title": "Bay Area startup raises $50M in Series B funding",
      // ... other fields
    }
  ]
}

The advanced response includes coordinates, administrative hierarchy, confidence scores, and detailed detection information.

What’s next

Now that you’ve made your first calls to the Local News API:

Explore Location detection methods for better location matching.
Read about GeoNames filtering for advanced geographic targeting.
Learn about Search in translations to find articles across languages using English keywords.
Read about NLP Enrichments to extract insights from articles.

Need help? Contact our support team at support@newscatcherapi.com

Get started

Guides and concepts

API Reference

Local News API quickstart guide

Before you start

Steps

What’s next

​Before you start

​Steps

​What’s next

Before you start

Steps

What’s next