Newscatcher Local News API

openapi: 3.0.3
info:
  title: Local News API
  description: |
    The Local News API provides access to local news articles with location-specific filtering capabilities.

    ## Standard endpoints

    - `/search`: Search articles by keywords with simple location filtering ("City, State" format).
    - `/latest_headlines`: Retrieve recent articles for specified locations and time periods.
    - `/search_by`: Retrieve articles by URL, ID, or RSS GUID.
    - `/sources`: List available news sources.

    ## Advanced endpoints

    - `/search/advanced`: Search with structured GeoNames filtering.
    - `/latest_headlines/advanced`: Latest headlines with structured GeoNames filtering.

    ## Features

    - Multiple location detection methods including dedicated sources, proximity analysis, and AI extraction
    - Natural language processing for sentiment analysis and entity recognition on original content and English translations
    - Article clustering for topic analysis
    - English translations for non-English content

  termsOfService: https://newscatcherapi.com/terms-of-service
  contact:
    name: Maksym Sugonyaka
    email: [email protected]
    url: https://www.newscatcherapi.com/book-a-demo
  version: 1.2.0

externalDocs:
  description: Find out more about Local News API
  url: https://www.newscatcherapi.com/docs/local-news-api/get-started/introduction

servers:
  - url: https://local-news.newscatcherapi.com
    description: Local News API production server

security:
  - ApiKeyAuth: []

tags:
  - name: Search
    description:
      Operations to search for local news articles. Includes both standard
      location filtering and advanced GeoNames filtering.
  - name: LatestHeadlines
    description:
      Operations to retrieve local news latest headlines. Includes both standard
      location filtering and advanced GeoNames filtering.
  - name: SearchBy
    description: Operations to search local news by link, ID or RSS GUID.
  - name: Sources
    description: Operations to retrieve local news sources.

paths:
  /api/search:
    post:
      tags:
        - Search
      summary: Search articles
      description:
        Searches for local news based on specified criteria such as keywords,
        geographic locations, language, country, source, and more.
      operationId: Search_post
      requestBody:
        $ref: "#/components/requestBodies/SearchRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/SearchResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "408":
          $ref: "#/components/responses/RequestTimeoutError"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/latest_headlines:
    post:
      tags:
        - LatestHeadlines
      summary: Retrieve latest headlines
      description:
        Retrieves the most recent news headlines for the specific locations and
        times. You can filter results by language, source, theme, and more.
      operationId: LatestHeadlines_post
      requestBody:
        $ref: "#/components/requestBodies/LatestHeadlinesRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/LatestHeadlinesResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "408":
          $ref: "#/components/responses/RequestTimeoutError"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sources:
    post:
      tags:
        - Sources
      summary: Retrieve sources
      description:
        Retrieves the list of local news sources available in the database.
        Filterable by language, country, and theme.
      operationId: Sources_post
      requestBody:
        $ref: "#/components/requestBodies/SourceRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/SourcesResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "408":
          $ref: "#/components/responses/RequestTimeoutError"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/search_by:
    post:
      tags:
        - SearchBy
      summary: Search articles by identifiers
      description: Search for local news using article links, IDs, or RSS GUIDs.
      operationId: SearchBy_post
      requestBody:
        $ref: "#/components/requestBodies/SearchByRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/SearchByResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "408":
          $ref: "#/components/responses/RequestTimeoutError"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  # Advanced endpoints (new in v1.2.0)
  /api/search/advanced:
    post:
      tags:
        - Search
      summary: Search articles with GeoNames filtering
      description: |
        Searches for local news using structured GeoNames filtering with administrative hierarchy, coordinates, localization and confidence scores.
      operationId: SearchAdvanced_post
      requestBody:
        $ref: "#/components/requestBodies/SearchAdvancedRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/SearchAdvancedResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "408":
          $ref: "#/components/responses/RequestTimeoutError"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/latest_headlines/advanced:
    post:
      tags:
        - LatestHeadlines
      summary: Retrieve latest headlines with GeoNames filtering
      description: |
        Retrieves the most recent news headlines using structured GeoNames filtering with administrative hierarchy, coordinates, localization and confidence scores.
      operationId: LatestHeadlinesAdvanced_post
      requestBody:
        $ref: "#/components/requestBodies/LatestHeadlinesAdvancedRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/LatestHeadlinesAdvancedResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "408":
          $ref: "#/components/responses/RequestTimeoutError"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"

components:
  requestBodies:
    SearchRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchRequestDto"

    LatestHeadlinesRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/LatestHeadlinesRequestDto"

    SearchByRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchByRequestDto"

    SourceRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SourcesRequestDto"

    SearchAdvancedRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SearchAdvancedRequestDto"

    LatestHeadlinesAdvancedRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/LatestHeadlinesAdvancedRequestDto"

  responses:
    SearchResponse:
      description:
        A successful response containing articles that match the specified
        search criteria. The response may include clustering information if
        enabled.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/ArticleSearchResponseDto"
              - $ref: "#/components/schemas/ClusteringSearchResponseDto"

    LatestHeadlinesResponse:
      description:
        A successful response containing the latest headlines since the
        specified time. The response may include clustering information if
        enabled.
      content:
        application/json:
          schema:
            oneOf:
              - allOf:
                  - $ref: "#/components/schemas/ArticleSearchResponseDto"
                title: Latest Headlines Response
                description: |
                  The response model for the `Latest headlines` request.
              - allOf:
                  - $ref: "#/components/schemas/ClusteringSearchResponseDto"
                title: Clustered Latest Headlines Response

    SourcesResponse:
      description: Successful response containing the list of sources
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SourcesResponseDto"

    SearchByResponse:
      description: |
        A successful response containing articles that match the
        specified search criteria.
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ArticleSearchAdvancedResponseDto"
            title: Search By Response

    SearchAdvancedResponse:
      description: |
        A successful response containing articles that match the specified search criteria with GeoNames location data. The response may include clustering information if enabled.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/ArticleSearchAdvancedResponseDto"
              - $ref: "#/components/schemas/ClusteringSearchAdvancedResponseDto"

    LatestHeadlinesAdvancedResponse:
      description: |
        A successful response containing the latest headlines since the specified time with GeoNames location data. The response may include clustering information if enabled.
      content:
        application/json:
          schema:
            oneOf:
              - allOf:
                  - $ref: "#/components/schemas/ArticleSearchAdvancedResponseDto"
                title: Advanced Latest Headlines Response
              - allOf:
                  - $ref: "#/components/schemas/ClusteringSearchAdvancedResponseDto"
                title: Clustered Advanced Latest Headlines Response

    # Errors
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: "Invalid JSON in request body"
            status_code: 400
            status: "Bad request"

    UnauthorizedError:
      description: Unauthorized - Authentication failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: "Invalid api key: INVALID_API_KEY"
            status_code: 401
            status: "Unauthorized"

    ForbiddenError:
      description: Forbidden - Server refuses action
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message:
              "Your plan request date range cannot be greater than 400 days"
            status_code: 403
            status: "Forbidden"

    RequestTimeoutError:
      description: Request timeout
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: "Request timed out after 30 seconds"
            status_code: 408
            status: "Request timeout"

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: "Invalid date format"
            status_code: 422
            status: "Validation error"

    RateLimitError:
      description: Too many requests - Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: "Max API requests concurrency reached"
            status_code: 429
            status: "Too many requests"

    InternalServerError:
      description: Internal server error
      content:
        text/plain:
          schema:
            type: string
          example: "Internal Server Error"

  schemas:
    # Base schemas for composition
    BaseRequestDto:
      type: object
      description: Common parameters shared across standard endpoints.
      properties:
        locations:
          type: array
          items:
            type: string
          description: |
            The location(s) to search for in articles. Format should be "City, State".
            Example: `["San Francisco, California"]`
          example: ["New York City, New York", "Los Angeles, California"]
        detection_methods:
          $ref: "#/components/schemas/DetectionMethods"
        lang:
          $ref: "#/components/schemas/Lang"
        countries: # New in v1.2.0
          $ref: "#/components/schemas/Countries"
        sources:
          $ref: "#/components/schemas/Sources"
        not_sources:
          $ref: "#/components/schemas/NotSources"
        parent_url:
          $ref: "#/components/schemas/ParentUrl"
        is_paid_content:
          $ref: "#/components/schemas/IsPaidContent"
        page:
          $ref: "#/components/schemas/Page"
        page_size:
          $ref: "#/components/schemas/PageSize"
        word_count_min:
          $ref: "#/components/schemas/WordCountMin"
        word_count_max:
          $ref: "#/components/schemas/WordCountMax"
        clustering:
          $ref: "#/components/schemas/ClusteringEnabled"
        theme:
          $ref: "#/components/schemas/Theme"
        PER_entity_name:
          $ref: "#/components/schemas/PerEntityName"
        LOC_entity_name:
          $ref: "#/components/schemas/LocEntityName"
        MISC_entity_name:
          $ref: "#/components/schemas/MiscEntityName"
        ORG_entity_name:
          $ref: "#/components/schemas/OrgEntityName"
        title_sentiment_min:
          $ref: "#/components/schemas/TitleSentimentMin"
        title_sentiment_max:
          $ref: "#/components/schemas/TitleSentimentMax"
        content_sentiment_min:
          $ref: "#/components/schemas/ContentSentimentMin"
        content_sentiment_max:
          $ref: "#/components/schemas/ContentSentimentMax"
        include_translation_fields: # New in v1.2.0
          $ref: "#/components/schemas/IncludeTranslationFields"

    # v1.2.0 Updated BaseRequestDto
    BaseAdvancedRequestDto:
      type: object
      properties:
        geonames:
          $ref: "#/components/schemas/GeoNamesFilter"
        geonames_operator:
          $ref: "#/components/schemas/GeoNamesOperator"
        lang:
          $ref: "#/components/schemas/Lang"
        countries:
          $ref: "#/components/schemas/Countries"
        sources:
          $ref: "#/components/schemas/Sources"
        not_sources:
          $ref: "#/components/schemas/NotSources"
        parent_url:
          $ref: "#/components/schemas/ParentUrl"
        is_paid_content:
          $ref: "#/components/schemas/IsPaidContent"
        page:
          $ref: "#/components/schemas/Page"
        page_size:
          $ref: "#/components/schemas/PageSize"
        word_count_min:
          $ref: "#/components/schemas/WordCountMin"
        word_count_max:
          $ref: "#/components/schemas/WordCountMax"
        clustering:
          $ref: "#/components/schemas/ClusteringEnabled"
        theme:
          $ref: "#/components/schemas/Theme"
        PER_entity_name:
          $ref: "#/components/schemas/PerEntityName"
        LOC_entity_name:
          $ref: "#/components/schemas/LocEntityName"
        MISC_entity_name:
          $ref: "#/components/schemas/MiscEntityName"
        ORG_entity_name:
          $ref: "#/components/schemas/OrgEntityName"
        title_sentiment_min:
          $ref: "#/components/schemas/TitleSentimentMin"
        title_sentiment_max:
          $ref: "#/components/schemas/TitleSentimentMax"
        content_sentiment_min:
          $ref: "#/components/schemas/ContentSentimentMin"
        content_sentiment_max:
          $ref: "#/components/schemas/ContentSentimentMax"
        include_translation_fields:
          $ref: "#/components/schemas/IncludeTranslationFields"

    # Standard request DTOs (enhanced in v1.2.0)
    SearchRequestDto:
      allOf:
        - type: object
          properties:
            q:
              $ref: "#/components/schemas/Q"
            from_:
              $ref: "#/components/schemas/From"
            to_:
              $ref: "#/components/schemas/To"
            search_in: # Enhanced in v1.2.0
              $ref: "#/components/schemas/SearchIn"
            sort_by:
              $ref: "#/components/schemas/SortBy"
        - $ref: "#/components/schemas/BaseRequestDto"

    LatestHeadlinesRequestDto:
      allOf:
        - type: object
          properties:
            when:
              $ref: "#/components/schemas/When"
        - $ref: "#/components/schemas/BaseRequestDto"

    SourcesRequestDto:
      type: object
      properties:
        lang:
          $ref: "#/components/schemas/Lang"
        countries:
          $ref: "#/components/schemas/Countries"
        theme:
          $ref: "#/components/schemas/Theme"

    SearchByRequestDto:
      type: object
      properties:
        links:
          $ref: "#/components/schemas/Links"
        ids:
          $ref: "#/components/schemas/Ids"
        rss_guids:
          $ref: "#/components/schemas/RssGuids"
        from_:
          $ref: "#/components/schemas/From"
        to_:
          $ref: "#/components/schemas/To"
        page:
          $ref: "#/components/schemas/Page"
        page_size:
          $ref: "#/components/schemas/PageSize"

    # Advanced request DTOs (new in v1.2.0)
    SearchAdvancedRequestDto:
      allOf:
        - type: object
          properties:
            q:
              $ref: "#/components/schemas/Q"
            from_:
              $ref: "#/components/schemas/From"
            to_:
              $ref: "#/components/schemas/To"
            search_in:
              $ref: "#/components/schemas/SearchIn"
            sort_by:
              $ref: "#/components/schemas/SortBy"
        - $ref: "#/components/schemas/BaseAdvancedRequestDto"

    LatestHeadlinesAdvancedRequestDto:
      allOf:
        - type: object
          properties:
            when:
              $ref: "#/components/schemas/When"
        - $ref: "#/components/schemas/BaseAdvancedRequestDto"

    # Parameter schemas
    ## BaseRequestDto (mixin model) parameters
    ## v1.2.0 GeoNames schemas
    GeoNamesFilter:
      type: array
      items:
        $ref: "#/components/schemas/GeoNamesEntity"
      description: |
        Filters articles by geographic locations using structured GeoNames data. All location criteria within an object must be met (internal `AND`). Multiple objects are combined using the `geonames_operator` parameter.

        For detailed information, see [GeoNames filtering](/local-news-api/guides-and-concepts/geonames-filtering).
      example:
        - name: "New York City"
          country: "US"
          feature_class: "A"
        - name: "San Francisco"
          admin1:
            name: "California"
          localization_score:
            min: 7

    GeoNamesOperator:
      type: string
      enum:
        - AND
        - OR
      default: AND
      description: |
        The operator to combine multiple `geonames` objects. If `AND`, all geonames objects must match. If `OR`, at least one geonames object must match.
      example: AND

    GeoNamesEntity:
      type: object
      description: |
        A single geographic location filter using GeoNames structured data. All provided fields within this object are combined with `AND` logic.
      properties:
        geonames_id:
          type: string
          nullable: true
          description: |
            The unique GeoNames identifier for exact location matching.
          example: "5128581"
        name:
          type: string
          nullable: true
          description: |
            The location name to search in articles. Use leading minus `-` to exclude names (e.g., `-Boston`). Supports wildcard `*` for partial matching when `enable_wildcard` is `true`.

            When the `search_with_alt_names` parameter is `true`, search in both canonical and alternative names from GeoNames database.
          example: New York City
        country:
          type: string
          nullable: true
          description: |
            Two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.

            To learn more, see [Enumerated parameters > Country](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#country-country-and-not-country).
          example: "US"
        admin1:
          allOf:
            - $ref: "#/components/schemas/GeoNamesLocationAdminEntity"
          description: |
            First-order administrative division filter (e.g., states in US, provinces in Canada, regions in Italy).
          example:
            name: "California"
            code: "CA"
            geonames_id: "5332921"
        admin2:
          allOf:
            - $ref: "#/components/schemas/GeoNamesLocationAdminEntity"
          description: |
            Second-order administrative division filter (e.g., counties in the US, departments in France).
          example:
            name: "Los Angeles County"
            geonames_id: "5368361"
        admin3:
          allOf:
            - $ref: "#/components/schemas/GeoNamesLocationAdminEntity"
          description: |
            Third-order administrative division filter (e.g., townships, boroughs, smaller regional divisions).
          example:
            name: "Manhattan"
            geonames_id: "5125771"
        admin4:
          allOf:
            - $ref: "#/components/schemas/GeoNamesLocationAdminEntity"
          description: |
            Fourth-order administrative division filter (smallest administrative units).
          example:
            name: "Downtown"
        lat:
          type: object
          nullable: true
          description: The latitude range to filter by. Can be `null`.
          properties:
            min:
              type: number
              format: float
              minimum: -90
              maximum: 90
              description: Minimum latitude (inclusive).
            max:
              type: number
              format: float
              minimum: -90
              maximum: 90
              description: Maximum latitude (inclusive).
          example:
            min: 37.0
            max: 38.5
        lon:
          type: object
          nullable: true
          description: The longitude range to filter by. Can be `null`.
          properties:
            min:
              type: number
              format: float
              minimum: -180
              maximum: 180
              description: Minimum longitude (inclusive).
            max:
              type: number
              format: float
              minimum: -180
              maximum: 180
              description: Maximum longitude (inclusive).
          example:
            min: -123.0
            max: -121.5
        feature_class:
          type: string
          nullable: true
          description: |
            GeoNames feature class. Main classes: 
            - `A`: Administrative
            - `H`: Hydrographic
            - `L`: Area
            - `P`: Populated places
            - `R`: Roads/rail
            - `S`: Spots/buildings
            - `T`: Topography
            - `U`: Undersea
            - `V`: Vegetation
          example: "A"
        feature_code:
          type: string
          nullable: true
          description: |
            Specific GeoNames feature code (e.g., `PPL` for populated place, `PPLA` for administrative seat). Supports wildcards.
          example: "PPL"
        detection_methods:
          $ref: "#/components/schemas/DetectionMethods"
        localization_score:
          allOf:
            - $ref: "#/components/schemas/RangeModel"
          description: |
            Filter by geographic focus score (0-10):
            - 10: Hyper-local — specific town or neighborhood named with clear local impact
            - 7–9: Regional — nearby city, metro, or administrative region mentioned with some local detail
            - 4–6: Subnational — province/state-level reference; town may be named but with limited context
            - 1–3: National or broader — only national relevance; town appears only in passing
            - 0: None — no mention or not relevant to the location
        confidence_score:
          allOf:
            - $ref: "#/components/schemas/RangeModel"
          description: |
            Filter by model's confidence in location relevance (0-10):
            - 10: Certain — Clear, unambiguous match; location is definitely relevant
            - 7–9: High — Strong indications of relevance, but not absolute certainty
            - 4–6: Medium — Some evidence or indirect relevance, but inconclusive
            - 1–3: Low — Weak signal or unlikely relevance
            - 0: Certain Not — Confident the location is not mentioned or relevant
        search_with_alt_names:
          type: boolean
          default: false
          description: |
            If true, expands location search to alternative names, such as abbreviations, local language names, historical names, and other variants stored in the GeoNames database. For example, `"NYC"` finds articles about `"New York City"`. If false, searches only in canonical location names.

            **Note**: This setting affects all location names within the `geonames` object, including the `name` field and all administrative-level names (`admin1.name`, `admin2.name`, etc.).
          example: true
        enable_wildcard:
          type: boolean
          default: false
          description: |
            If true, enables wildcard matching using `*` for partial matching location names. If false, requires exact matching.

            **Note**: This setting affects all location names within the `geonames` object, including the `name` field and all administrative-level names (`admin1.name`, `admin2.name`, etc.).
          example: false

    GeoNamesLocationAdminEntity:
      type: object
      properties:
        geonames_id:
          type: string
          description: GeoNames ID for the administrative division.
        name:
          type: string
          description: |
            Administrative division name. Use leading minus `-` to exclude the name.
        code:
          type: string
          description: Administrative division code.

    RangeModel:
      type: object
      description:
        Numeric range filter with minimum and/or maximum values (inclusive).
      properties:
        min:
          type: number
          minimum: 0
          maximum: 10
          description: Minimum value (inclusive).
        max:
          type: number
          minimum: 0
          maximum: 10
          description: Maximum value (inclusive).
      example:
        min: 7
        max: 10

    Coordinates:
      type: object
      description: Geographic coordinates for a location.
      properties:
        lat:
          type: number
          format: float
          nullable: true
          minimum: -90
          maximum: 90
          description: The latitude coordinate.
        lon:
          type: number
          format: float
          nullable: true
          minimum: -180
          maximum: 180
          description: The longitude coordinate.
      example:
        lat: 40.71427
        lon: -74.00597

    IncludeTranslationFields:
      type: boolean
      default: false
      description: |
        If true, includes English translation fields in the response (`title_translated_en`, `content_translated_en`, and NLP translation fields). If false, excludes translation fields.
      example: true

    DetectionMethods:
      type: array
      items:
        type: string
        enum:
          - dedicated_source
          - local_section
          - regional_source
          - standard_format
          - proximity_mention
          - ai_extracted
      description: |
        The location detection methods to filter results by:
        - `dedicated_source`: Identifies locations based on sources exclusively covering a specific location.
        - `local_section`: Identifies locations through location-specific sections within larger publications.
        - `regional_source`: Identifies locations using regional context from state-level publications.
        - `standard_format`: Identifies locations written in standard formats like "City, State" or "City, County".
        - `proximity_mention`: Identifies cities and states mentioned within 15 words of each other.
        - `ai_extracted`: Identifies locations through AI-based content analysis. Requires AI Extraction plan.

        For detailed information, see [Location detection methods](/local-news-api/guides-and-concepts/location-detection-methods).
      example: ["dedicated_source", "proximity_mention", "ai_extracted"]

    Lang:
      oneOf:
        - type: string
        - type: array
          items:
            type: string
      description: |
        The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string or an array of strings.

        To learn more, see [Enumerated parameters > Language](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#language-lang-and-not-lang).
      example: ["en", "es"]

    Sources:
      oneOf:
        - type: string
        - type: array
          items:
            type: string
      description: |
        One or more news sources to narrow down the search. The format must be a domain URL. Subdomains, such as `finance.yahoo.com`, are also acceptable. To specify multiple sources, use a comma-separated string or an array of strings.
      example: ["nytimes.com", "theguardian.com"]

    NotSources:
      oneOf:
        - type: string
        - type: array
          items:
            type: string
      description: |
        The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string or an array of strings.
      example: ["cnn.com", "wsj.com"]

    ParentUrl:
      oneOf:
        - type: string
        - type: array
          items:
            type: string
      description: |
        The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string or an array of strings.
      example: ["

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newscatcher/refs/heads/main/openapi/newscatcher-local-news-api-openapi.yml