Search Examples

Real-world examples for the Search API

Basic Search

Search the web and get structured results:

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(query="web automation tools", location="US")

for r in response.results:
    print(f"{r.position}. {r.title}")
    print(f"   {r.url}\n")

Output:

{
  "query": "web automation tools",
  "results": [
    {
      "position": 1,
      "site_name": "www.firecrawl.dev",
      "title": "Top 9 Browser Automation Tools for Web Testing and Scraping in ...",
      "snippet": "This guide covers 9 of the best tools across testing, scraping, and workflow automation...",
      "url": "https://www.firecrawl.dev/blog/browser-automation-tools-comparison"
    },
    {
      "position": 2,
      "site_name": "www.skyvern.com",
      "title": "Best Free Open Source Browser Automation Tools in 2025 - Skyvern",
      "snippet": "Developed by Microsoft, Playwright is the next generation of web automation tools...",
      "url": "https://www.skyvern.com/blog/best-free-open-source-browser-automation-tools-in-2025/"
    }
  ],
  "total_results": 10,
  "page": 0
}

Search with Intent

Pass the optional purpose parameter to state why you are searching — the goal the results will be used for. It is always optional, but supplying it gives the search additional intent signal beyond the raw keywords, helping deliver better-quality results.

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(
    query="pdf invoice parser",
    purpose="Find an open-source library for parsing PDF invoices in Python",
)

for r in response.results:
    print(f"{r.position}. {r.title}")

Include or Exclude Sites

Use include_domains to restrict results to specific domains, and exclude_domains to remove domains from the results. Both take a comma-separated list of domains.

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(
    query="python tutorial",
    include_domains="docs.python.org",
    location="US",
)

for r in response.results:
    print(f"{r.position}. {r.title} ({r.site_name})")

To exclude specific sites, use exclude_domains:

cURL

curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=recipe ideas" \
  --data-urlencode "exclude_domains=facebook.com,youtube.com" \
  --data-urlencode "location=US" \
  -H "X-API-Key: $TINYFISH_API_KEY"

Deprecated: domain filtering via site:/-site: operators inside the query string still works, but prefer include_domains / exclude_domains above.

cURL

curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=python tutorial site:docs.python.org" \
  --data-urlencode "location=US" \
  -H "X-API-Key: $TINYFISH_API_KEY"

cURL

curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=recipe ideas -site:facebook.com -site:youtube.com" \
  --data-urlencode "location=US" \
  -H "X-API-Key: $TINYFISH_API_KEY"

Geo-Targeted Search

Get results localized to a specific country and language:

Python

from tinyfish import TinyFish

client = TinyFish()

# Search in French — location auto-resolves to FR
response = client.search.query(query="meilleurs restaurants", language="fr")

for r in response.results:
    print(f"{r.position}. {r.title} ({r.site_name})")

When only language is provided, location auto-resolves to the most common pairing (e.g. fr → FR, ja → JP). See the Reference for details.

Search + Fetch Pipeline

Combine Search with Fetch to get full page content from top results:

Python

from tinyfish import TinyFish

client = TinyFish()

# Step 1: Search
results = client.search.query(query="TinyFish web agent", location="US")
top_urls = [r.url for r in results.results[:3]]

# Step 2: Fetch full content
pages = client.fetch.get_contents(urls=top_urls, format="markdown")
for page in pages.results:
    print(f"## {page.title}")
    print(page.text[:200], "\n")

---

Freshness Filter

Use recency_minutes when you want a freshness window relative to now.

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(query="FIFA", recency_minutes=60)

for r in response.results:
    print(f"{r.position}. {r.title}")

Date Window Search

Use after_date and before_date when you want a calendar date range.

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(
    query="FIFA",
    after_date="2026-06-01",
    before_date="2026-06-18",
)

News Search

Use domain_type=news to retrieve recent news articles. Results include publisher and date fields.

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(query="AI regulation", domain_type="news", location="US")

for r in response.results:
    print(f"{r.position}. {r.title}")
    print(f"   {getattr(r, 'publisher', '')} — {getattr(r, 'date', '')}")
    print(f"   {r.url}\n")

Research Paper Search

Use domain_type=research_paper to search academic papers. Results include authors, venue, year, and cited_by_count fields.

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(query="attention is all you need", domain_type="research_paper")

for r in response.results:
    print(f"{r.position}. {r.title}")
    authors = getattr(r, 'authors', None) or []
    print(f"   Authors: {', '.join(authors)}")
    print(f"   Venue: {getattr(r, 'venue', '')}  Year: {getattr(r, 'year', '')}")
    print(f"   Citations: {getattr(r, 'cited_by_count', '')}")
    print(f"   {r.url}\n")

Research Paper Search by Publication Year

Use pub_year_min / pub_year_max with domain_type=research_paper to scope results to a publication-year range (inclusive integers, 0-9999, with pub_year_min <= pub_year_max when both are set). These replace after_date / before_date / recency_minutes, which are not supported for domain_type=research_paper.

Python

from tinyfish import TinyFish

client = TinyFish()
response = client.search.query(
    query="transformer architecture",
    domain_type="research_paper",
    pub_year_min=2019,
    pub_year_max=2022,
)

for r in response.results:
    print(f"{r.position}. {r.title} ({getattr(r, 'year', '')})")

---

Related

Search Reference

Full parameter and response docs

Fetch Examples

Extract page content from URLs