README.md

metadata

title: DDGS Search API
short_description: DuckDuckGo search API with UI, auth, and markdown output.
emoji: 👁
colorFrom: indigo
colorTo: red
sdk: docker
app_port: 7860
pinned: false

DDGS Search API

Public DuckDuckGo Search API and CLI built with FastAPI, packaged for local development and Hugging Face Spaces.

Highlights

• src/ package layout with compatibility wrappers for app.py and ddgs_cli.py
• FastAPI app with bearer-token protection on /search
• Built-in browser UI at / for manual API testing
• CLI for local search workflows
• .env-driven configuration with .env.example
• pytest, ruff, Makefile, and GitHub Actions CI

Repository Layout

.
├── app.py                  # HF/local ASGI entrypoint
├── ddgs_cli.py             # Local CLI wrapper
├── src/ddgs_api/           # Application package
├── tests/                  # Unit tests
├── test_scripts/           # Integration and deployment helpers
├── .env.example            # Safe environment template
└── Dockerfile              # Hugging Face Spaces runtime image

Quick Start

cp .env.example .env
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Update .env with a real API_BEARER_TOKEN before running the API.

Local Development

Install dependencies:

make install-dev

Run the API:

make run

Open the UI:

open http://127.0.0.1:7860

Run the CLI:

ddgs-search "openai"

Run checks:

make check

API Usage

Local request example:

curl -X POST http://127.0.0.1:7860/search \
  -H "Authorization: Bearer $API_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"openai","max_results":1,"region":"us-en","safesearch":"moderate","timelimit":"m","backend":"auto","timeout":30,"verify":true}'

Endpoints:

• GET / browser UI for interactive testing
• GET /health
• POST /search

Environment Variables

Required:

• API_BEARER_TOKEN

Required only for Hugging Face secret upload helpers:

• HF_TOKEN
• HF_SPACE_ID

Optional DDGS defaults:

• DDGS_REGION
• DDGS_SAFESEARCH
• DDGS_TIMELIMIT
• DDGS_MAX_RESULTS
• DDGS_BACKEND
• DDGS_PROXY
• DDGS_TIMEOUT
• DDGS_OUTPUT
• DDGS_VERIFY

Optional local certificate settings:

• USE_LOCAL_ZSCALER_CERT
• CERT_ZSCALER_PEM

Hugging Face Spaces

Upload the API bearer token to your Docker Space:

test_scripts/hf_upload_secrets.sh

Build locally:

docker build -t ddgs-api .
docker run -p 7860:7860 --env-file .env ddgs-api

Remote smoke test:

test_scripts/test_remote_api.sh https://your-space.hf.space "$API_BEARER_TOKEN"

Inspect runtime state:

curl -s "https://huggingface.co/api/spaces/$HF_SPACE_ID"

Read Space logs:

source .env

curl -N \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/$HF_SPACE_ID/logs/build"

curl -N \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/spaces/$HF_SPACE_ID/logs/run"

If the runtime is stuck in RUNTIME_ERROR without a code change, restart it:

python - <<'PY'
import os
from dotenv import load_dotenv
from huggingface_hub import HfApi

load_dotenv(".env")
api = HfApi(token=os.environ["HF_TOKEN"])
api.restart_space(repo_id=os.environ["HF_SPACE_ID"])
PY

Testing

Fast local verification:

pytest -q
ruff check .

The test_scripts/ directory contains integration helpers for live API checks and Hugging Face secret management.

Contributing

1. Start from .env.example.
2. Use make install-dev.
3. Run make check before pushing.
4. Keep secrets in the local .env only.