# Google News

Search Google News to retrieve news articles from thousands of sources in JSON format.

## Endpoint

```
GET /v1/news/{query}
```

## Description

The Google News Search endpoint allows you to search for news articles from Google News. The query parameter should be a URL-encoded query string. News can be filtered by country and language using the `ceid` parameter.

## Authentication

All requests require authentication using the `X-Api-Key` header. See the [Authentication guide](/docs/guides/authentication) for more details.

## Path Parameters

### `query` (required)

**Type:** `string`

A URL-encoded query string for Google News search. You can use simple queries or include country/language filters.

**Examples:**
- Simple query: `q=president`
- Multiple keywords: `q=news+about+president+trump`
- Filtered by country and language:
  - US news in English: `q=trump&ceid=US:en`
  - Great Britain news in English: `q=trump&ceid=GB:en`

## Request Headers

### `X-Proxy-Location` (optional)

**Type:** `string`

Specify the proxy location for the search. Available options:

- `EU` - European Union
- `CA` - Canada
- `US` - United States
- `IE` - Ireland
- `GB` - United Kingdom
- `FR` - France
- `DE` - Germany
- `SE` - Sweden
- `IN` - India
- `JP` - Japan
- `KR` - South Korea
- `SG` - Singapore
- `AU` - Australia
- `BR` - Brazil

### `X-User-Agent` (optional)

**Type:** `string`

Specify the user agent type. Available options:

- `desktop` - Desktop user agent (default)
- `mobile` - Mobile user agent

## Request Example

### Using cURL

```bash
curl --request GET \
  --url 'https://api.serply.io/v1/news/q=stock+market' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

### Using JavaScript/Node.js

```javascript
const response = await fetch('https://api.serply.io/v1/news/q=stock+market', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);
```

### Using Python

```python
import requests

headers = {
    'X-Api-Key': 'YOUR_API_KEY'
}

response = requests.get(
    'https://api.serply.io/v1/news/q=stock+market',
    headers=headers
)
data = response.json()
print(data)
```

## Response

The API returns a JSON object containing a `feed` object with news feed metadata and an `entries` array of news articles.

### Response Structure

```json
{
  "feed": {
    "title": "News Feed Title",
    "generator": "Google News",
    "generator_detail": {},
    "link": "https://news.google.com/...",
    "links": {},
    "language": "en",
    "publisher": "Google News",
    "publisher_detail": "...",
    "rights": "...",
    "rights_detail": "...",
    "updated": "2024-01-01T00:00:00Z",
    "updated_parsed": "...",
    "subtitle": "...",
    "subtitle_detail": "...",
    "entries": [
      {
        "title": "Article Title",
        "title_detail": {},
        "links": [{"link": "https://example.com/article"}],
        "link": "https://example.com/article",
        "id": "article-id",
        "guidislink": false,
        "published": "2024-01-01T00:00:00Z",
        "published_parsed": "...",
        "summary": "Article summary...",
        "summary_detail": {},
        "source": "Source Name",
        "sub_articles": "..."
      }
    ]
  },
  "entities": [
    {
      "title": "Article Title",
      "links": []
    }
  ]
}
```

### Response Fields

- **`feed`** (object): News feed metadata and entries
  - **`title`** (string): Feed title
  - **`generator`** (string): Feed generator name
  - **`link`** (string): Feed URL
  - **`language`** (string): Feed language
  - **`publisher`** (string): Publisher name
  - **`updated`** (string): Last update timestamp
  - **`entries`** (array): Array of news article objects
    - **`title`** (string): Article title
    - **`link`** (string): Article URL
    - **`summary`** (string): Article summary/description
    - **`published`** (string): Publication date
    - **`source`** (string): News source name
- **`entities`** (array): Array of entity objects with titles and links

### Example Response

```json
{
  "feed": {
    "title": "stock market - Google News",
    "generator": "Google News",
    "link": "https://news.google.com/rss/search?q=stock+market",
    "language": "en",
    "publisher": "Google News",
    "updated": "2024-01-15T12:00:00Z",
    "entries": [
      {
        "title": "Stock Market Reaches New High",
        "link": "https://example.com/news/stock-market-high",
        "summary": "The stock market reached a new all-time high today...",
        "published": "2024-01-15T10:00:00Z",
        "source": "Financial Times"
      }
    ]
  },
  "entities": [
    {
      "title": "Stock Market Reaches New High",
      "links": []
    }
  ]
}
```

## Status Codes

- **200 OK** - Successful response
- **404 Not Found** - The requested resource was not found
- **422 Unprocessable Entity** - The request was well-formed but contains semantic errors
- **429 Too Many Requests** - Rate limit exceeded

## Error Responses

See the [Errors guide](/docs/guides/errors) for information on error response formats.