*** title: Get live news subtitle: Retrieve real-time news results from the You.com Search API. Filter by recency, country, language, and more. og:title: Get Live News | You.com Search API og:description: Retrieve real-time news results from the You.com Search API. Filter by recency, country, language, and more. --------------------- For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://you.com/docs/search/llms.txt. For full documentation content, see https://you.com/docs/search/llms-full.txt. ## Overview The Search API automatically returns news articles alongside web results whenever your query has news intent — breaking events, recent announcements, trending topics. You don't need a separate endpoint or special configuration: just send your query and our classification system determines if news results are relevant. When news results are returned, they appear in the `results.news` array alongside `results.web`. ## News-specific fields Each news result includes: | Field | Description | | --------------- | ---------------------------------------------------------- | | `title` | Article headline | | `description` | Article summary | | `url` | Link to the article | | `page_age` | Publication timestamp (ISO 8601) | | `thumbnail_url` | Associated image | | `contents` | Full article content (when `livecrawl` is `news` or `all`) | ## Parameters that improve news results These parameters tune your news queries for relevance, recency, and safety: | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------------------------------------------- | | `count` | integer | Max results per section (default 10, max 100) | | `freshness` | string | `day`, `week`, `month`, `year`, or a date range `YYYY-MM-DDtoYYYY-MM-DD` | | `country` | string | ISO 3166-2 country code — focuses results geographically (e.g., `US`, `GB`, `DE`) | | `language` | string | BCP 47 language code — filters by article language (e.g., `EN`, `FR`, `JP`) | | `safesearch` | string | Content moderation: `off`, `moderate` (default), or `strict` | ### `freshness` — control recency `freshness` is the most important parameter for news use cases. Breaking news requires `day`; trend analysis might use `week` or `month`. You can also specify an exact date range. ```python from youdotcom.models import Freshness freshness=Freshness.DAY # Last 24 hours freshness=Freshness.WEEK # Last 7 days freshness=Freshness.MONTH # Last 30 days freshness=Freshness.YEAR # Last 365 days freshness="2025-01-01to2025-03-01" # Custom range ``` ## Basic news query ```python from youdotcom import You from youdotcom.models import Freshness with You(api_key_auth="api_key") as you: res = you.search.unified( query="AI regulation news", freshness=Freshness.DAY, count=10, ) if res.results and res.results.news: for article in res.results.news: print(f"{article.title}") print(f" {article.url}") print(f" Published: {article.page_age}\n") else: print("No news results returned for this query.") ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { Freshness } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { const result = await you.search({ query: "AI regulation news", freshness: Freshness.Day, count: 10, }); result.results?.news?.forEach((article) => { console.log(article.title); console.log(` ${article.url}`); console.log(` Published: ${article.pageAge}\n`); }); } run(); ``` ```curl curl -G https://ydc-index.io/v1/search \ -H "X-API-Key: api_key" \ --data-urlencode "query=AI regulation news" \ -d freshness=day \ -d count=10 ``` ## Filter by country and language Use `country` and `language` together to narrow results to a specific region and language. This is useful for monitoring local news, international media, or non-English markets. ```python from youdotcom import You from youdotcom.models import Freshness, Country with You(api_key_auth="api_key") as you: # Get French-language news from France, published this week res = you.search.unified( query="élections", freshness=Freshness.WEEK, country=Country.FR, language="FR", count=10, ) if res.results and res.results.news: for article in res.results.news: print(f"{article.title} — {article.page_age}") ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { Freshness, Country } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { // Get French-language news from France, published this week const result = await you.search({ query: "élections", freshness: Freshness.Week, country: Country.Fr, language: "FR", count: 10, }); result.results?.news?.forEach((article) => { console.log(`${article.title} — ${article.pageAge}`); }); } run(); ``` ```curl # Get French-language news from France, published this week curl -G https://ydc-index.io/v1/search \ -H "X-API-Key: api_key" \ --data-urlencode "query=élections" \ -d freshness=week \ -d country=FR \ -d language=FR \ -d count=10 ``` ## Custom date range Use a date range string in `YYYY-MM-DDtoYYYY-MM-DD` format to target a specific window — useful for historical monitoring or scheduled digests. ```python from youdotcom import You with You(api_key_auth="api_key") as you: res = you.search.unified( query="federal reserve interest rates", freshness="2025-01-01to2025-03-01", count=20, ) if res.results and res.results.news: for article in res.results.news: print(f"{article.page_age} {article.title}") ``` ```typescript import { You } from "@youdotcom-oss/sdk"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { const result = await you.search({ query: "federal reserve interest rates", freshness: "2025-01-01to2025-03-01", count: 20, }); result.results?.news?.forEach((article) => { console.log(`${article.pageAge} ${article.title}`); }); } run(); ``` ```curl curl -G https://ydc-index.io/v1/search \ -H "X-API-Key: api_key" \ --data-urlencode "query=federal reserve interest rates" \ -d freshness=2025-01-01to2025-03-01 \ -d count=20 ``` ## Get full article content The `livecrawl` parameter allows you to retrieve the full page content of every search result. You can choose to retrieve only news articles, web pages or all search results, using `news`, `web` or `all` respectively. Then, set `livecrawl_formats` to either `markdown` or `html` based on your needs. Since we're focused on news, set it `news` or `all` to retrieve the full article text for every search result. Set `livecrawl_formats=markdown` for LLM-ready output. ```python from youdotcom import You from youdotcom.models import Freshness, LiveCrawl, LiveCrawlFormats with You(api_key_auth="api_key") as you: res = you.search.unified( query="climate policy summit", freshness=Freshness.DAY, count=5, livecrawl=LiveCrawl.NEWS, livecrawl_formats=LiveCrawlFormats.MARKDOWN, ) if res.results and res.results.news: for article in res.results.news: print(f"{article.title}") if article.contents: print(article.contents.markdown[:300]) print() ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { Freshness, LiveCrawl, LiveCrawlFormats } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { const result = await you.search({ query: "climate policy summit", freshness: Freshness.Day, count: 5, livecrawl: LiveCrawl.News, livecrawlFormats: LiveCrawlFormats.Markdown, }); result.results?.news?.forEach((article) => { console.log(article.title); if (article.contents?.markdown) { console.log(article.contents.markdown.slice(0, 300)); } console.log(); }); } run(); ``` ```curl curl -G https://ydc-index.io/v1/search \ -H "X-API-Key: api_key" \ --data-urlencode "query=climate policy summit" \ -d freshness=day \ -d count=5 \ -d livecrawl=news \ -d livecrawl_formats=markdown ``` For news monitoring pipelines that need full article bodies, combine `livecrawl=news` with `freshness=day` and schedule recurring calls. See [Retrieve page content](/docs/search/retrieve-page-content) for more on live crawling. *** ## Next steps Get full HTML or Markdown from any result with live crawling View all parameters and response schemas