Skip to main content
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

1

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
2

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"
  }'
Replace YOUR_API_KEY_HERE with your actual API key.
3

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
      }
    }
  ]
}
4

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"
  }'
5

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:
  1. Explore Location detection methods for better location matching.
  2. Read about GeoNames filtering for advanced geographic targeting.
  3. Learn about Search in translations to find articles across languages using English keywords.
  4. Read about NLP features to extract insights from articles.
Need help? Contact our support team at support@newscatcherapi.com