> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to Local News API

> Access location-specific news with advanced geographic relevance detection and structured filtering capabilities.

## What is Local News API?

Local News provides location-specific news content with
[GeoNames filtering](/local-news-api/guides-and-concepts/geonames-filtering) and
[Location detection methods](/local-news-api/guides-and-concepts/location-detection-methods)
optimized for city, county, and regional news coverage. In addition, the service
offers exclusive access to thousands of unique local news sources, including
small city publishers, regional outlets, university newspapers, and local
government news portals.

Supported news sources by country:

<div
  style={{
display: "grid",
gridTemplateColumns: "1fr 1fr",
gap: "0.5rem",
marginLeft: "1.5rem",
}}
>
  <div>• United States</div>
  <div>• Germany</div>
  <div>• Canada</div>
  <div>• France</div>
  <div>• Great Britain</div>
  <div>• Italy</div>
  <div>• China</div>
  <div>• Thailand</div>
  <div>• Switzerland</div>
</div>

## Features

<Tabs>
  <Tab title="Location">
    * Six distinct location detection methods - Content from thousands of local
      news sources across multiple countries - Advanced GeoNames filtering with
      administrative hierarchy, localization and confidence scores -
      Cross-language search using English keywords
  </Tab>

  <Tab title="Content">
    * NLP analysis including summary, sentiment, theme, and entity recognition -
      Article clustering for related content grouping - English translations for
      non-English content with search and NLP support
  </Tab>

  <Tab title="Technical">
    * Advanced query syntax with logical operators, wildcards, and proximity
      search capabilities - High-volume retrieval with up to 1000 articles per
      page - Comprehensive API with standard and advanced endpoints
  </Tab>
</Tabs>

## Key differences from News API

For users familiar with our core News API, Local News API offers these key
enhancements:

| Feature           | Local News API                                                               | News API                                  |
| ----------------- | ---------------------------------------------------------------------------- | ----------------------------------------- |
| Geographic focus  | Local coverage across multiple countries with specialized location detection | Global news coverage                      |
| Location handling | Simple location names plus structured GeoNames filtering                     | Basic geographic filtering                |
| Historical data   | 30 days of history                                                           | Up to 5 years of history                  |
| Source types      | Local newspapers, government sites, university outlets                       | Major publications, international sources |

## Location detection methods

The system uses six distinct methods to detect and validate locations in news
articles:

<CardGroup cols={2}>
  <Card title="Dedicated Source" icon="building-columns">
    Identifies articles from news sources exclusively covering a specific
    location (highest confidence)
  </Card>

  <Card title="Local Section" icon="newspaper">
    Identifies locations through dedicated sections in larger publications
  </Card>

  <Card title="Regional Source" icon="map">
    Uses regional context to properly interpret and disambiguate location
    mentions
  </Card>

  <Card title="Standard Format" icon="font">
    Identifies locations written in standard formats like "City, State"
  </Card>

  <Card title="Proximity Mention" icon="arrow-right-arrow-left">
    Detects cities and states mentioned within 15 words of each other
  </Card>

  <Card title="AI Extraction" icon="brain">
    Uses AI-based content analysis to identify locations (requires AI Extraction
    plan)
  </Card>
</CardGroup>

For detailed information on each method, see
[Location detection methods](/local-news-api/guides-and-concepts/location-detection-methods).

## Base URL

For API requests use the following base URL:

```bash theme={null}
https://local-news.newscatcherapi.com
```

## Endpoints

### Standard endpoints

| Endpoint                | Method | Description                                     | Use Case                                                                  |
| ----------------------- | ------ | ----------------------------------------------- | ------------------------------------------------------------------------- |
| `/api/search`           | POST   | Full-text search with simple location filtering | Find articles using "City, State" or "City, Country" format for locations |
| `/api/latest_headlines` | POST   | Recent articles by location                     | Monitor latest news for specific towns or regions                         |
| `/api/search_by`        | POST   | Direct article lookup                           | Retrieve specific articles using URLs, IDs, or RSS GUIDs                  |
| `/api/sources`          | POST   | Available news sources                          | Discover local news providers by region                                   |

### Advanced endpoints

| Endpoint                         | Method | Description                              | Use Case                                                                     |
| -------------------------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------------------- |
| `/api/search/advanced`           | POST   | Full-text search with GeoNames filtering | Find articles using structured geographic data with administrative hierarchy |
| `/api/latest_headlines/advanced` | POST   | Recent articles with GeoNames filtering  | Monitor latest news with precise geographic targeting and confidence scores  |

## Request format

Include your API key in the `x-api-token` header for each request. All requests
must use HTTPS.

### Standard endpoint example

<CodeGroup>
  ```json JSON theme={null}
  {
    "q": "venture capital",
    "locations": ["San Francisco, California"],
    "detection_methods": ["dedicated_source", "standard_format"],
    "lang": "en",
    "from_": "7 days ago",
    "include_translation_fields": true
  }
  ```

  ```python Python theme={null}
  import requests
  import json

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

  PAYLOAD = {
      "q": "venture capital",
      "locations": ["San Francisco, California"],
      "detection_methods": ["dedicated_source", "local_section"],
      "lang": "en",
      "from_": "7 days ago",
      "include_translation_fields": True
  }

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

  ```bash cURL theme={null}
  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": "venture capital",
      "locations": ["San Francisco, California"],
      "detection_methods": ["dedicated_source", "local_section"],
      "lang": "en",
      "from_": "7 days ago",
      "include_translation_fields": true
    }'
  ```
</CodeGroup>

### Advanced endpoint example

<CodeGroup>
  ```json JSON theme={null}
  {
    "q": "venture capital",
    "geonames": [
      {
        "name": "San Francisco",
        "country": "US",
        "admin1": {
          "name": "California"
        },
        "localization_score": {
          "min": 7
        }
      }
    ],
    "lang": "en",
    "from_": "7 days ago",
    "include_translation_fields": true
  }
  ```

  ```python Python theme={null}
  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
          }
      }],
      "lang": "en",
      "from_": "7 days ago",
      "include_translation_fields": True
  }

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

  ```bash cURL theme={null}
  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
        }
      }],
      "lang": "en",
      "from_": "7 days ago",
      "include_translation_fields": true
    }'
  ```
</CodeGroup>

## Response differences

Both endpoint types include basic article information with metadata, NLP and
translation fields (`title_translated_en`, `content_translated_en`). The main
difference between standard and advanced endpoints is the location data
structure.

### Standard endpoints

Return simple location data:

```json theme={null}
"locations": [
  {
    "name": "San Francisco, California",
    "detection_methods": ["dedicated_source"]
  }
]
```

### Advanced endpoints

Return structured GeoNames data:

```json theme={null}
"geonames": [
  {
    "geonames_id": "5391959",
    "name": "San Francisco",
    "country": "US",
    "admin1": {"name": "California", "code": "CA"},
    "coordinates": {"lat": 37.77493, "lon": -122.41942},
    "localization_score": 8.5,
    "confidence_score": 9.2,
    "detection_methods": ["dedicated_source"]
  }
]
```

<Note>
  For detailed information on all available response fields, see [API
  Reference](/local-news-api/api-reference/search/search-articles-post).
</Note>

## Use cases

Local News API is designed for applications requiring location-specific news
intelligence:

* **Local news applications**: Deliver geographically relevant content to users.
* **Regional business monitoring**: Track company activities in specific
  markets.
* **Real estate intelligence**: Monitor development news, policy changes, and
  market trends.
* **Media analysis**: Examine coverage patterns across geographic regions.
* **Government affairs**: Track policy issues at local and regional levels.
* **Crisis monitoring**: Follow emergencies and public health issues by
  location.
* **University research**: Analyze local media coverage of regional issues.

## Getting started

1. [Book a demo](https://www.newscatcherapi.com/book-a-demo) to get your API
   key.
2. Follow the [Quickstart guide](/local-news-api/get-started/quickstart) to make
   your first request and comprehend the basic workflow.
3. Review the
   [Location detection methods](/local-news-api/guides-and-concepts/location-detection-methods)
   documentation to understand how the system identifies and validates location
   mentions.
4. Learn about [GeoNames filtering](/local-news-api/guides-and-concepts/geonames-filtering)
   for advanced geographic targeting.
5. Dive into the [API reference](/local-news-api/api-reference/search/search-articles-post) for detailed endpoint
   documentation and advanced query options.