openapi: 3.1.0
info:
  title: Google News RSS Headlines API
  description: Google News provides RSS feeds that deliver news headlines organized by topic, location, and search query. While not an officially documented REST API, Google News exposes structured RSS/XML feeds that can be consumed programmatically to retrieve top stories, topic-based headlines, location-specific news, and search results across multiple languages and regions.
  version: 1.0.0
  contact:
    name: Google News
    url: https://news.google.com
  license:
    name: Google Terms of Service
    url: https://policies.google.com/terms
servers:
- url: https://news.google.com
  description: Google News RSS Server
tags:
- name: Headlines
  description: Retrieve top news headlines
paths:
  /rss:
    get:
      operationId: getTopHeadlines
      summary: Google News RSS Get Top Headlines
      description: Retrieves the top news headlines as an RSS feed.
      tags:
      - Headlines
      parameters:
      - name: hl
        in: query
        description: Host language (e.g., en-US).
        schema:
          type: string
          default: en-US
      - name: gl
        in: query
        description: Geographic location (e.g., US).
        schema:
          type: string
          default: US
      - name: ceid
        in: query
        description: Country and language edition identifier (e.g., US:en).
        schema:
          type: string
          default: US:en
      responses:
        '200':
          description: RSS feed of top headlines.
          content:
            application/rss+xml:
              schema:
                $ref: '#/components/schemas/RSSFeed'
  /rss/headlines/section/geo/{location}:
    get:
      operationId: getLocationHeadlines
      summary: Google News RSS Get Headlines by Location
      description: Retrieves news headlines for a specific geographic location.
      tags:
      - Headlines
      parameters:
      - name: location
        in: path
        required: true
        description: The location name or code.
        schema:
          type: string
      - name: hl
        in: query
        description: Host language.
        schema:
          type: string
      - name: gl
        in: query
        description: Geographic location.
        schema:
          type: string
      - name: ceid
        in: query
        description: Country and language edition identifier.
        schema:
          type: string
      responses:
        '200':
          description: RSS feed of location-based headlines.
          content:
            application/rss+xml:
              schema:
                $ref: '#/components/schemas/RSSFeed'
components:
  schemas:
    NewsItem:
      type: object
      properties:
        title:
          type: string
          description: The headline of the news article.
        link:
          type: string
          format: uri
          description: The URL of the news article.
        pubDate:
          type: string
          description: Publication date of the article.
        description:
          type: string
          description: A brief summary of the article.
        source:
          type: string
          description: The news source name.
    RSSFeed:
      type: object
      description: An RSS 2.0 feed containing news items.
      properties:
        channel:
          type: object
          properties:
            title:
              type: string
              description: The title of the RSS channel.
            link:
              type: string
              format: uri
              description: The URL of the channel.
            description:
              type: string
              description: Description of the channel.
            language:
              type: string
              description: The language of the channel.
            lastBuildDate:
              type: string
              description: The last build date of the feed.
            items:
              type: array
              items:
                $ref: '#/components/schemas/NewsItem'
externalDocs:
  description: Google News
  url: https://news.google.com