News Search Results via Custom Search API Reference

To retrieve news results from the Custom Search JSON API, combine the standard web search endpoint with sort=date to rank by recency and dateRestrict to bound results to a specific time window. When Google indexes a news article, it often embeds schema.org NewsArticle structured data in the page — surfaced in the pagemap.newsarticle field — giving you the headline, author, publisher, and publication date without scraping. You can also fall back to pagemap.metatags for Open Graph or Twitter Card metadata if newsarticle is absent.

Endpoint

GET https://www.googleapis.com/customsearch/v1

How News Search Works

Configure your Programmable Search Engine to include news sources, then scope requests with date-based parameters. The API returns results ordered by freshness when you pass sort=date, making it straightforward to power a “latest news” feed.

For best results, configure your Programmable Search Engine to search across established news domains such as reuters.com, apnews.com, bbc.com, or a curated list of your preferred sources. A general-purpose engine without site restrictions may surface blogs and forums alongside news articles.

Request Parameters

Required Parameters

string

required

Your Google API key.

string

required

Your Programmable Search Engine ID, configured to include news sources.

string

required

The news search query. Use natural-language topic descriptions, person names, or event names. Supports all standard query operators such as "exact phrase", -exclude, and OR.

Date and Recency Parameters

string

Sort order for results. Pass date to rank results by publication/index date, newest first. Without this parameter, results are ranked by relevance.You can also use the extended form to filter by a date range:

date:r:YYYYMMDD:YYYYMMDD — restricts to articles published between two dates, e.g. sort=date:r:20240101:20240131.

string

Restricts results to pages indexed within a rolling time window relative to now. Format: [d|w|m|y][number].

Value	Meaning
`d1`	Last 24 hours
`d7`	Last 7 days
`w2`	Last 2 weeks
`m1`	Last month
`m6`	Last 6 months
`y1`	Last year

Content Filtering Parameters

integer

default:"10"

Number of results per page. Accepted values are 1 through 10.

integer

default:"1"

Index of the first result. Use to paginate up to 100 results total (maximum start value is 91).

string

Restrict news results to a specific publication’s domain, e.g. siteSearch=reuters.com. Combine with siteSearchFilter=i to include only that domain.

string

Controls the behavior of siteSearch. Pass i to include only results from the specified site, or e to exclude them.

string

Requires all results to contain this exact phrase. Useful for tracking specific named entities or verbatim quotes in news coverage.

string

Excludes results that contain this word or phrase. Useful for narrowing a broad topic — for example, searching "jaguar" with excludeTerms=car to filter out automotive news.

string

Broadens the query with alternative terms. Results must match the main query OR at least one of these terms.

Language and Region Parameters

string

Restricts results to news articles written in a specific language. Example: lang_en for English, lang_es for Spanish.

string

Biases results toward news relevant to a specific country. Accepts a two-letter ISO 3166-1 alpha-2 code such as us, gb, or au.

string

Hard-filters results to news originating from a specific country. Uses Google country codes such as countryUS or countryGB.

string

default:"off"

SafeSearch filter. Pass active to suppress explicit content.

Example Requests

Breaking news (last 24h)
Date range search
Single publication

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=artificial+intelligence+regulation\
&sort=date\
&dateRestrict=d1\
&lr=lang_en\
&num=10"

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=federal+reserve+interest+rates\
&sort=date%3Ar%3A20240101%3A20240331\
&num=10"

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=climate+summit\
&siteSearch=reuters.com\
&siteSearchFilter=i\
&sort=date\
&dateRestrict=w2\
&num=5"

import requests

params = {
    "key": "YOUR_API_KEY",
    "cx": "YOUR_SEARCH_ENGINE_ID",
    "q": "artificial intelligence regulation",
    "sort": "date",
    "dateRestrict": "d1",
    "lr": "lang_en",
    "num": 10,
}

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    params=params
)
data = response.json()

for item in data.get("items", []):
    pagemap = item.get("pagemap", {})

    # Prefer schema.org NewsArticle, fall back to metatags
    news_article = pagemap.get("newsarticle", [{}])[0]
    metatags = pagemap.get("metatags", [{}])[0]

    headline = (
        news_article.get("headline")
        or metatags.get("og:title")
        or item["title"]
    )
    published = (
        news_article.get("datepublished")
        or metatags.get("article:published_time")
        or "Unknown"
    )
    author = news_article.get("author", "Unknown")

    print(f"{published}  {headline}  ({author})")
    print(f"  {item['link']}")

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  cx: "YOUR_SEARCH_ENGINE_ID",
  q: "artificial intelligence regulation",
  sort: "date",
  dateRestrict: "d1",
  lr: "lang_en",
  num: "10",
});

const response = await fetch(
  `https://www.googleapis.com/customsearch/v1?${params}`
);
const data = await response.json();

for (const item of data.items ?? []) {
  const pagemap = item.pagemap ?? {};

  // Prefer schema.org NewsArticle, fall back to metatags
  const newsArticle = pagemap.newsarticle?.[0] ?? {};
  const metatags = pagemap.metatags?.[0] ?? {};

  const headline =
    newsArticle.headline ?? metatags["og:title"] ?? item.title;
  const published =
    newsArticle.datepublished ??
    metatags["article:published_time"] ??
    "Unknown";
  const author = newsArticle.author ?? "Unknown";

  console.log(`${published}  ${headline}  (${author})`);
  console.log(`  ${item.link}`);
}

Example Response

{
  "kind": "customsearch#search",
  "searchInformation": {
    "searchTime": 0.391204,
    "totalResults": "182000000",
    "formattedTotalResults": "182,000,000"
  },
  "queries": {
    "request": [
      {
        "title": "Google Custom Search - artificial intelligence regulation",
        "searchTerms": "artificial intelligence regulation",
        "count": 10,
        "startIndex": 1,
        "language": "lang_en",
        "cx": "YOUR_SEARCH_ENGINE_ID"
      }
    ],
    "nextPage": [
      {
        "searchTerms": "artificial intelligence regulation",
        "count": 10,
        "startIndex": 11
      }
    ]
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "EU Adopts Landmark AI Act, Setting Global Standard for AI Regulation",
      "htmlTitle": "EU Adopts Landmark <b>AI</b> Act, Setting Global Standard for <b>AI Regulation</b>",
      "link": "https://www.example-news.com/tech/eu-ai-act-2024",
      "displayLink": "www.example-news.com",
      "snippet": "The European Parliament voted today to adopt the AI Act, the world's first comprehensive legal framework governing artificial intelligence systems.",
      "htmlSnippet": "The European Parliament voted today to adopt the <b>AI</b> Act...",
      "formattedUrl": "https://www.example-news.com/tech/eu-ai-act-2024",
      "pagemap": {
        "newsarticle": [
          {
            "headline": "EU Adopts Landmark AI Act, Setting Global Standard for AI Regulation",
            "description": "The European Parliament voted today to adopt the AI Act.",
            "datepublished": "2024-03-13T14:22:00Z",
            "datemodified": "2024-03-13T16:45:00Z",
            "author": "Jane Doe",
            "articlebody": "The European Parliament has formally adopted...",
            "publisher": "Example News",
            "url": "https://www.example-news.com/tech/eu-ai-act-2024"
          }
        ],
        "metatags": [
          {
            "og:title": "EU Adopts Landmark AI Act",
            "og:description": "The European Parliament voted today to adopt the AI Act.",
            "og:type": "article",
            "og:url": "https://www.example-news.com/tech/eu-ai-act-2024",
            "article:published_time": "2024-03-13T14:22:00Z",
            "article:author": "Jane Doe",
            "article:section": "Technology"
          }
        ]
      }
    }
  ]
}

Response Fields

News results share the standard response structure. Article metadata is embedded in items[].pagemap.newsarticle and items[].pagemap.metatags.

string

The plain-text headline of the article as indexed by Google.

string

The canonical URL of the news article.

string

The publication’s hostname, e.g. "www.reuters.com".

string

A short excerpt from the article body or meta description.

array

An array of schema.org NewsArticle objects extracted from the page’s structured data. Usually contains a single entry. Present only when the publisher includes NewsArticle JSON-LD or microdata markup.

Show newsarticle[] fields

string

The article headline from structured data. Often more precise than items[].title.

string

A short summary of the article content.

string

ISO 8601 datetime string for when the article was first published, e.g. "2024-03-13T14:22:00Z".

string

ISO 8601 datetime string for when the article was last updated.

string

The name of the article’s author or authors.

string

A truncated portion of the article body text as extracted by Google.

string

The name of the publishing organization.

string

The canonical URL as declared in the article’s structured data.

array

Open Graph, Twitter Card, and other HTML <meta> tags from the article page. A reliable fallback when newsarticle is absent.

Show metatags[] fields (news-relevant)

string

Open Graph title, typically the article headline.

string

Open Graph description, typically the article summary or lede.

string

Open Graph type. A value of "article" indicates a news article page.

string

Canonical URL declared via Open Graph.

string

ISO 8601 publication timestamp from the Open Graph article namespace.

string

ISO 8601 modification timestamp from the Open Graph article namespace.

string

Author name or profile URL from Open Graph metadata.

string

The editorial section or category of the article, e.g. "Technology" or "Politics".

string

Twitter Card title, often identical to og:title.

string

Twitter Card description.

Extracting Article Metadata: Decision Tree

Use the following priority order when extracting article metadata from a result item:

pagemap.newsarticle[0].headline         → article title
pagemap.metatags[0]["og:title"]         → fallback title
items[].title                           → last resort title

pagemap.newsarticle[0].datepublished    → publication date
pagemap.metatags[0]["article:published_time"]  → fallback date
(absent — date not available)

pagemap.newsarticle[0].author           → author name
pagemap.metatags[0]["article:author"]   → fallback author

pagemap.newsarticle[0].publisher        → publisher name
items[].displayLink                     → fallback publisher

When building a news feed, store items[].link as the unique identifier for each article and use it for deduplication — the same article may appear across different start pages if the result set is volatile over time.

Monitoring a topic in real time

Schedule a request every 15–30 minutes with sort=date&dateRestrict=d1 and track items[].link values you have already seen. Persist new links to a database and trigger notifications for genuinely new articles. Stay within your quota by batching with num=10 and caching results.

Building a breaking news alert

Use exactTerms to track a specific named entity or event title, combined with dateRestrict=d1 and sort=date. For example, tracking "Federal Reserve rate decision" with dateRestrict=d1 will surface same-day coverage as soon as Google indexes it.

Error Codes

HTTP Status	Meaning
`400`	Bad request — a parameter value is invalid, e.g. malformed `dateRestrict` or `sort` format.
`401`	Invalid API key.
`403`	Daily quota exceeded. The free tier allows 100 queries per day.
`429`	Too many requests — apply exponential backoff and retry.
`500`	Internal server error — retry after a short delay.

The sort=date parameter sorts by index date, not necessarily by the article’s declared publication date. An article published weeks ago that was recently re-indexed or updated may rank at the top. Always read pagemap.newsarticle[0].datepublished or pagemap.metatags[0]["article:published_time"] for the true publication date.

​Endpoint

​How News Search Works

​Request Parameters

​Required Parameters

​Date and Recency Parameters

​Content Filtering Parameters

​Language and Region Parameters

​Example Requests

​Example Response

​Response Fields

​Extracting Article Metadata: Decision Tree

​Error Codes

Endpoint

How News Search Works

Request Parameters

Required Parameters

Date and Recency Parameters

Content Filtering Parameters

Language and Region Parameters

Example Requests

Example Response

Response Fields

Extracting Article Metadata: Decision Tree

Error Codes