How to Get Search Results Programmatically with the You.com Web Search API

TLDR: Getting search results programmatically means calling a search API from code instead of reading a results page: one POST with a query and API key, ranked results back as JSON, then parsing, shaping, and citing them. This guide covers the full four-step pattern with working Python, the fields you actually use from the response, how to turn results into LLM context and citations, and the failure modes, empty results, truncated snippets, stale pages, that break naive integrations.

Programmatic search is the foundation layer of nearly everything agentic: research pipelines, enrichment jobs, answer engines, and monitoring loops all begin with the same act, getting current web results into code as structured data. You.com ships the Web Search API for exactly that step. This guide is the full pattern, the same four moves our web search API overview introduces at the product level, here at the level a developer copies into a repo.

How Do You Make the Call?

The API is a POST endpoint at https://ydc-index.io/v1/search with the API key in the X-API-Key header, taking a query and a result count, and returning ranked results as JSON. The standard library is enough for the first version:

import json
import os
import urllib.request

def search(query: str, count: int = 5) -> dict:
    key = os.environ["YOUCOM_API_KEY"]
    req = urllib.request.Request(
        "https://ydc-index.io/v1/search",
        data=json.dumps({"query": query, "count": count}).encode(),
        headers={"Content-Type": "application/json", "X-API-Key": key},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.load(resp)

payload = search("what is a web search api", count=5)

The key reads from an environment variable rather than a literal, so it never lands in source control or logs. The timeout exists because a search call without one will outwait the patience of whatever called it, and error handling lives in the caller, where the right retry policy is knowable.

How Do You Parse the Response?

The response carries results in typed buckets, web and news, and each result carries the fields a downstream integration needs: URL, snippet text, and page age. The parsing step maps those into your own shape, because relying on the raw response shape everywhere couples your code to a schema you do not control:

def to_hits(payload: dict) -> list:
    results = payload.get("results", {})
    hits = []
    for bucket in ("web", "news"):
        for hit in results.get(bucket, []) or []:
            hits.append({
                "kind": bucket,
                "url": hit["url"],
                "snippet": hit.get("snippet", ""),
                "page_age": hit.get("page_age", ""),
            })
    return hits

hits = to_hits(payload)
for hit in hits:
    print(hit["kind"], "|", hit["page_age"] or "no age", "|", hit["url"])

The defensive defaults exist for a reason: a missing snippet or page age is a data condition your code will meet in production, not an exception, and treating it as one turns a partial result into a crash. The full field surface is documented in What Is in a Web Search API JSON Response?

How Do You Turn Results into LLM Context and Citations?

The two output shapes cover most uses. Context block: a numbered list of snippets with URLs inline, so a model reads fresh evidence in its prompt instead of guessing from training data. Citation list: the same URLs in a sources section under the generated answer, so every reader can check the machine's work. The shaping rule that keeps both honest: the model only sees what you fetched, and the citations only name what the model saw, no laundering of unsourced claims through the middle of an answer. That discipline, and what to do when the search comes back empty, is the core of our guide to reducing LLM hallucinations.

Why an API Instead of Scraping a Results Page?

The decision framework is three questions. Reliability: a search results page is an interface that changes without notice, while an API response schema is a contract, and code built on contracts survives redesigns. Throughput: parsing scraped HTML at scale means fighting rate limits and bot detection, while API usage is metered and documented. Legality: scraping a results page may violate the engine's terms of service, while API usage operates under a license you agreed to explicitly. For anything past a one-off script, the API wins all three, and the pattern in this guide is the standard shape.

What Failure Modes Break Naive Integrations?

Each failure mode has a detection. Empty results: the query is too specific or mispelled and the API returns a normal response with nothing in it, which naive code then feeds to a model as zero evidence, the setup for confident hallucination. Detection: check result count before generation and refuse or rephrase on empty, never generate on a void. Snippet truncation: the snippet cuts a sentence in half and the model cites a claim the snippet never made. Detection: when a snippet must carry load-bearing facts, fetch the full page with the Contents API, documented in What Is a Web Content Extraction API?, and cite against the extracted text. Stale pages: the result ranked well but the page moved, changed, or was pulled, and a citation to it embarrasses you. Detection: spot-check a random sample of cited URLs per day and watch the failure rate, because stale citations are the failure mode users notice first. Key rotation: the API key expires and every call starts returning auth errors, which surfaces as an integration outage with an obvious signature once anyone reads the error body. Detection: monitor error responses by type, and alert on the auth category specifically, so rotation is a five-minute fix instead of a morning of debugging.

Related Guides

• What Is in a Web Search API JSON Response? Fields, Parsing, and Pitfalls
• Web Search API in Python: A Practical Guide With the You.com SDK
• How to Reduce LLM Hallucinations
• How to Call the You.com Web Search API With cURL

FAQ

How do I get search results programmatically? Call a search API from your language of choice, passing a query and API key, and parse the JSON response. This guide's Python example is the whole core: one POST, one parse, and you have ranked results with URLs and snippets as data instead of a page you would have to scrape.

What fields come back for each result? The ones you will build on are the URL, the snippet text, and the page age. Treat everything else as engine-specific detail that your parsing layer should normalize away, so your code depends on your own schema rather than the response shape.

Do I need an SDK? No. The API is a plain POST with JSON in and JSON out, so the standard library handles it, and the SDK is a convenience rather than a requirement. Reach for the SDK when you want retries, typed responses, and language-native ergonomics for free.

How many results should I request per call? Request what you will actually use. Five covers most context-building uses, and larger counts serve ranking research and dashboards. Count is an API volume knob, so size it from your downstream need rather than defaulting to the maximum.

What do I do when search returns no results? Refuse rather than improvise. An empty result set means the query needs rephrasing or the topic has nothing current to cite, and either answer is safer than generating text with zero evidence behind it. Log the empty query too, since it is a signal about what your users expect to exist.