Request Controls

These parameters target which results come back. They sit on the request alongside query and count. For query syntax inside query itself, see Search operators.

Send parameters as a JSON body on POST /v1/search. Array fields are plain JSON arrays.

Domain Filtering

Restrict results to, exclude results from, or boost specific domains. Use include_domains for a strict allowlist, exclude_domains to filter out unwanted domains, and boost_domains to prefer matching domains without filtering out other results. Each list supports up to 500 domains. For large domain lists, POST is strongly recommended.

from youdotcom import You
with You() as you:
  # Only return results from trusted news sources
  res = you.search(
    query="federal reserve interest rate decision",
    include_domains=["reuters.com", "apnews.com", "ft.com", "bloomberg.com"],
  )
  if res.results and res.results.web:
      for result in res.results.web:
          print(f"{result.title} — {result.url}")

Use boost_domains when you want to prefer sources without making them mandatory. Matching results from boosted domains receive a relative ranking boost, but the boost is not quantified. If boosted domains do not have matching results, results from other domains can still appear. boost_domains can be used with exclude_domains, but not with include_domains.

Freshness

Filter results by recency:

• day — Last 24 hours
• week — Last 7 days
• month — Last 30 days
• year — Last 365 days
• YYYY-MM-DDtoYYYY-MM-DD — Custom date range

When your search query includes a temporal keyword and you also set a freshness parameter, the search uses the broader (less restrictive) of the two timeframes. For example, query=news this week with freshness=month uses a freshness of month.

Pagination

Use offset to retrieve additional pages of results. The offset value (0–9) skips that many pages, so offset=1 with count=10 returns results 11–20. count is the max results per section (default 10, max 100).

from youdotcom import You
with You() as you:
  # Get the second page of results
  res = you.search(
    query="machine learning",
    count=10,
    offset=1,
  )
  print(res.results.web)

Geographic Targeting

Target results by geographic region using the country parameter (ISO 3166-1 alpha-2 country codes) and filter by language using the language parameter (BCP 47 language codes).

from youdotcom import You
from youdotcom.models import Country
# Get Swiss results
with You() as you:
  res = you.search(
    query="best restaurants in geneva",
    country=Country.CH,
  )
  # Print restaurant results with descriptions
  if res.results and res.results.web:
      for result in res.results.web:
          print(f"{result.title}")
          if result.description:
              print(f"  {result.description}\n")

Refer to the ISO 3166-1 alpha-2 standard for a list of country codes.

Safesearch

safesearch controls explicit-content filtering: off, moderate (default), or strict.

View full API reference

Next Steps