# ddgs

`ddgs` is an async Rust search client inspired by the Python [`ddgs`](https://github.com/deedy5/ddgs) package.

The crate focuses on three search categories:

- `text`
- `news`
- `books`

It implements Python-style multi-backend search for `text` and `news`, with `auto` as the default backend strategy.

## Installation

From crates.io:

```toml
[dependencies]
ddgs = "0.1.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

From Git:

```toml
[dependencies]
ddgs = { git = "https://github.com/YuanBLQ/ddgs.git", tag = "v0.1.0" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

## Quick Start

```rust,no_run
use ddgs::{Ddgs, TextOptions};

#[tokio::main]
async fn main() -> ddgs::Result<()> {
    let ddgs = Ddgs::new()?;

    let results = ddgs
        .text_with_options("openai realtime", TextOptions::default().max_results(5))
        .await?;

    for result in results {
        println!("{} -> {}", result.title, result.href);
    }

    Ok(())
}
```

Convenience methods are also available:

```rust,no_run
# async fn run() -> ddgs::Result<()> {
# let ddgs = ddgs::Ddgs::new()?;
let text = ddgs.text("rust language").await?;
let news = ddgs.news("duckduckgo").await?;
let books = ddgs.books("rust programming").await?;
# Ok(())
# }
```

## Backends

### Text

`text` defaults to `TextBackend::Auto`, which tries multiple backends and deduplicates results.

Available text backends:

- `auto`
- `all`
- `yahoo`
- `startpage`
- `brave`
- `google`
- `mojeek`
- `yandex`
- `wikipedia`
- `grokipedia`
- `html`
- `lite`
- `api`

Example:

```rust,no_run
use ddgs::{Ddgs, TextBackend, TextOptions};

# async fn run() -> ddgs::Result<()> {
# let ddgs = Ddgs::new()?;
let results = ddgs
    .text_with_options(
        "openai realtime",
        TextOptions::default()
            .backend(TextBackend::Yahoo)
            .max_results(5),
    )
    .await?;
# Ok(())
# }
```

### News

`news` defaults to `NewsBackend::Auto`.

Available news backends:

- `auto`
- `all`
- `bing`
- `duckduckgo`
- `yahoo`

### Books

`books` currently uses Anna's Archive search result extraction.

## CLI

After installing the binary:

```bash
cargo install ddgs
```

Run searches from the command line:

```bash
ddgs text "rust programming" --max-results 5
ddgs text "rust programming" --backend yahoo --max-results 5
ddgs text "rust programming" --backend all --max-results 5

ddgs news "rust programming" --max-results 5
ddgs news "rust programming" --backend bing --max-results 5

ddgs books "rust programming" --max-results 5
```

## Notes

Search engines may rate-limit, block, or change their HTML structure at any
time. `auto` backends are intended to improve availability by trying multiple
providers, but they cannot guarantee stable results from third-party services.

## Current Scope

This project currently implements `text`, `news`, and `books`. Other verticals
from the Python package, such as images and videos, are intentionally out of
scope for now.
