> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Examples

> Real-world examples for TinySearch

## Basic Search

Search the web and get structured results:

```python Python theme={null}
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")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "web automation tools",
  location: "US",
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title}`);
  console.log(`   ${r.url}\n`);
}
```

```bash cURL theme={null}
curl -s "https://api.search.tinyfish.ai?query=web+automation+tools&location=US" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

**Output:**

```json theme={null}
{
  "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 Python theme={null}
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}")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "pdf invoice parser",
  purpose: "Find an open-source library for parsing PDF invoices in Python",
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title}`);
}
```

```bash cURL theme={null}
curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=pdf invoice parser" \
  --data-urlencode "purpose=Find an open-source library for parsing PDF invoices in Python" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## 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 Python theme={null}
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})")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "python tutorial",
  include_domains: "docs.python.org",
  location: "US",
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title} (${r.site_name})`);
}
```

```bash cURL theme={null}
curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=python tutorial" \
  --data-urlencode "include_domains=docs.python.org" \
  --data-urlencode "location=US" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

To exclude specific sites, use `exclude_domains`:

```bash cURL theme={null}
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"
```

> [!NOTE]
>
> **Deprecated:** domain filtering via `site:`/`-site:` operators inside the `query`
> string still works, but prefer `include_domains` / `exclude_domains` above.
>
> ```bash cURL theme={null}
> 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"
> ```
>
> ```bash cURL theme={null}
> 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 Python theme={null}
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})")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();

// Search in French — location auto-resolves to FR
const response = await client.search.query({
  query: "meilleurs restaurants",
  language: "fr",
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title} (${r.site_name})`);
}
```

```bash cURL theme={null}
curl -s "https://api.search.tinyfish.ai?query=meilleurs+restaurants&language=fr" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

> [!NOTE]
>
> When only `language` is provided, `location` auto-resolves to the most common pairing (e.g. `fr` → `FR`, `ja` → `JP`). See the [Reference](https://docs.tinyfish.ai/tinysearch/reference.md) for details.

## Search + Fetch Pipeline

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

```python Python theme={null}
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")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();

// Step 1: Search
const results = await client.search.query({
  query: "TinyFish web agent",
  location: "US",
});
const topUrls = results.results.slice(0, 3).map((r) => r.url);

// Step 2: Fetch full content
const pages = await client.fetch.getContents({
  urls: topUrls,
  format: "markdown",
});
for (const page of pages.results) {
  console.log(`## ${page.title}`);
  console.log(page.text.slice(0, 200), "\n");
}
```

***

## Freshness Filter

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

```python Python theme={null}
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}")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "FIFA",
  recency_minutes: 60,
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title}`);
}
```

```bash cURL theme={null}
curl "https://api.search.tinyfish.ai?query=FIFA&recency_minutes=60" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## Date Window Search

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

```python Python theme={null}
from tinyfish import TinyFish

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

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "FIFA",
  after_date: "2026-06-01",
  before_date: "2026-06-18",
});
```

```bash cURL theme={null}
curl "https://api.search.tinyfish.ai?query=FIFA&after_date=2026-06-01&before_date=2026-06-18" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## News Search

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

```python Python theme={null}
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")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "AI regulation",
  domain_type: "news",
  location: "US",
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title}`);
  console.log(`   ${r.publisher ?? ""} — ${r.date ?? ""}`);
  console.log(`   ${r.url}\n`);
}
```

```bash cURL theme={null}
curl "https://api.search.tinyfish.ai?query=AI+regulation&domain_type=news&location=US" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## Research Paper Search

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

```python Python theme={null}
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")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "attention is all you need",
  domain_type: "research_paper",
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title}`);
  console.log(`   Authors: ${(r.authors ?? []).join(", ")}`);
  console.log(`   Venue: ${r.venue ?? ""}  Year: ${r.year ?? ""}`);
  console.log(`   Citations: ${r.cited_by_count ?? ""}`);
  console.log(`   ${r.url}\n`);
}
```

```bash cURL theme={null}
curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=attention is all you need" \
  --data-urlencode "domain_type=research_paper" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## 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 Python theme={null}
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', '')})")
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const response = await client.search.query({
  query: "transformer architecture",
  domain_type: "research_paper",
  pub_year_min: 2019,
  pub_year_max: 2022,
});

for (const r of response.results) {
  console.log(`${r.position}. ${r.title} (${r.year ?? ""})`);
}
```

```bash cURL theme={null}
curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=transformer architecture" \
  --data-urlencode "domain_type=research_paper" \
  --data-urlencode "pub_year_min=2019" \
  --data-urlencode "pub_year_max=2022" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

***

## Related

> [card] [Search Reference](https://docs.tinyfish.ai/tinysearch/reference.md)
>
> Full parameter and response docs

> [card] [Fetch Examples](https://docs.tinyfish.ai/tinyfetch/examples.md)
>
> Extract page content from URLs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.