> ## 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.

# Local News API quickstart guide

> Get started with location-specific news data using Local News API.

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](https://www.newscatcherapi.com/book-a-demo) page)
* Basic understanding of REST APIs
* Your preferred programming language and HTTP client
* Basic knowledge of JSON data format

## Steps

<Steps>
  <Step title="Set up your environment">
    Make sure you have the necessary HTTP client library installed for your programming language:

    <CodeGroup>
      ```bash curl theme={null}
      # cURL is typically included in your system
      # To check, open the terminal and type the following:
      curl --version
      ```

      ```bash Python theme={null}
      pip install requests
      ```

      ```bash TypeScript theme={null}
      npm install axios
      ```
    </CodeGroup>
  </Step>

  <Step title="Make your first request">
    Search for local news articles using standard location filtering:

    <CodeGroup>
      ```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": "*",
          "locations": ["San Francisco, California"],
          "detection_methods": ["local_section", "ai_extracted"],
          "theme": "Tech",
          "lang": "en",
          "from_": "7 days ago"
        }'
      ```

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

      ```python Python theme={null}
      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}")
      ```

      ```typescript TypeScript theme={null}
      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();
      ```
    </CodeGroup>

    <Note>
      Replace `YOUR_API_KEY_HERE` with your actual API key.
    </Note>
  </Step>

  <Step title="Review the response">
    The API returns a JSON response containing articles with location data:

    ```json JSON {10-15} theme={null}
    {
      "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
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Try advanced GeoNames filtering">
    Use the advanced endpoint for structured geographic filtering with additional metadata:

    <CodeGroup>
      ```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
            }
          }],
          "from_": "7 days ago"
        }'
      ```

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

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

      ```typescript TypeScript theme={null}
      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();
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the advanced response">
    The advanced endpoint returns structured GeoNames data:

    ```json JSON {10-30} theme={null}
    {
      "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.
  </Step>
</Steps>

## What's next

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

1. Explore
   [Location detection methods](/local-news-api/guides-and-concepts/location-detection-methods)
   for better location matching.
2. Read about [GeoNames filtering](/local-news-api/guides-and-concepts/geonames-filtering)
   for advanced geographic targeting.
3. Learn about
   [Search in translations](/news-api/how-to/search-in-translations) to
   find articles across languages using English keywords.
4. Read about [NLP features](/news-api/guides-and-concepts/nlp-features)
   to extract insights from articles.

<Note>Need help? Contact our support team at [support@newscatcherapi.com](mailto:support@newscatcherapi.com)</Note>