Searxng Web Search

SearXNG Web Search

Search the web using a self-hosted SearXNG instance. This skill provides access to web search results through the SearXNG JSON API, with built-in rate limiting, error handling, and result formatting.

When to Use

Use this skill when you need to:

• -Find current information or recent news
• -Research topics beyond your knowledge cutoff
• -Look up documentation or technical references
• -Verify facts or check current status
• -Find URLs or resources on specific topics
• -Search for code examples or solutions

Configuration

Set the SEARXNG_URL environment variable to your SearXNG instance:

export SEARXNG_URL="http://localhost:8888"

Or use the default (http://localhost:8888) if not set.

Usage

Execute the search script with your query:

bb scripts/search.clj "your search query"

Advanced Options

Pass additional parameters as JSON:

bb scripts/search.clj "your query" '{"category": "news", "time_range": "day", "num_results": 10}'

Available options:

• -category - Filter by category: general, news, images, videos, it, science
• -time_range - Time filter: day, week, month, year
• -language - Language code (default: en)
• -num_results - Number of results to return (default: 5)

Output Format

The script returns formatted search results as text:

Search Results for "your query"
Found 42 total results

1. Result Title [Score: 1.85]
   URL: https://example.com/page
   Description snippet from the page...
   Engines: google, bing

2. Another Result [Score: 1.62]
   ...

Error Handling

The script handles common errors gracefully:

• -Network timeouts (30s timeout)
• -SearXNG unavailable (clear error message)
• -Invalid queries (error details)
• -Rate limiting (429 responses)
• -Empty results (informative message)

Rate Limiting

The script implements basic rate limiting:

• -Minimum 1 second between requests
• -Uses filesystem-based state (.searxng-last-request)
• -Prevents accidental spam

Examples

Basic Search

bb scripts/search.clj "NixOS configuration"

News Search

bb scripts/search.clj "AI developments" '{"category": "news", "time_range": "week"}'

Technical Search

bb scripts/search.clj "babashka http client" '{"category": "it", "num_results": 3}'

Recent Results Only

bb scripts/search.clj "product launch" '{"time_range": "day"}'

Troubleshooting

"SEARXNG_URL not set"

• -Set the environment variable: export SEARXNG_URL="http://localhost:8888"

Connection timeout

• -Check that SearXNG is running: curl $SEARXNG_URL/search?q=test&format=json
• -Verify firewall settings
• -Check service status: systemctl status searx

Empty results

• -Try a broader query
• -Remove filters and try again
• -Check SearXNG logs: journalctl -u searx -n 50

Rate limit errors

• -Wait a few seconds between searches
• -The script enforces minimum 1s delay automatically

Implementation Notes

The search script (scripts/search.clj) uses:

• -babashka.http-client for HTTP requests
• -Clojure's cheshire.core for JSON parsing
• -Filesystem-based rate limiting
• -30-second timeout with proper error messages
• -Result scoring and sorting for best results first

For detailed API documentation, see references/api-guide.md.