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.