SearXNG Search

Open Source: https://github.com/searxng/searxng

Public Instances: https://searx.space/

Overview

SearXNG is a free, open-source metasearch engine that aggregates results from multiple search engines while protecting user privacy. It can be self-hosted or used via public instances.

Note: SearXNG returns a fixed number of results per page (~20 by default) and does not support limiting results via the API. The max_results parameter is not directly supported by SearXNG.

LiteLLM Python SDK

from litellm import search

# Set your SearXNG instance URL (REQUIRED)
os.environ["SEARXNG_API_BASE"] = "https://serxng-deployment-production.up.railway.app"

response = search(
    query="latest AI developments",
    search_provider="searxng",
    max_results=10
)

LiteLLM AI Gateway

1. Setup config.yaml

model_list:
  - model_name: gpt-4
    litellm_params:
      model: gpt-4
      api_key: os.environ/OPENAI_API_KEY

search_tools:
  - search_tool_name: searxng-search
    litellm_params:
      search_provider: searxng
      api_base: https://serxng-deployment-production.up.railway.app

2. Start the proxy

litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

3. Test the search endpoint

curl http://0.0.0.0:4000/v1/search/searxng-search \\
  -H "Authorization: Bearer sk-1234" \\
  -H "Content-Type: application/json" \\
  -d '{
    "query": "latest AI developments",
    "max_results": 10
  }'

Provider-specific Parameters

from litellm import search

# REQUIRED: Set your SearXNG instance URL
os.environ["SEARXNG_API_BASE"] = "https://serxng-deployment-production.up.railway.app"

response = search(
    query="machine learning research",
    search_provider="searxng",
    max_results=10,
    # SearXNG-specific parameters
    categories="general,science",      # Comma-separated categories
    engines="google,duckduckgo,bing",  # Comma-separated engines
    language="en",                      # Language code
    pageno=1,                           # Page number
    time_range="month"                  # Time filter: day, month, year
)

Features

SearXNG provides powerful metasearch capabilities:

Multiple Search Engines

Aggregate results from multiple search engines simultaneously:

• Google, DuckDuckGo, Bing, Brave
• Wikipedia, Startpage
• And many more

Categories

Search within specific categories:

• general - General web search
• science - Scientific articles and papers
• images - Image search
• news - News articles
• videos - Video content
• music - Music and audio
• files - File search
• it - IT and technology
• map - Maps and location

Time-Based Filtering

Filter results by time range:

• day - Past day
• month - Past month
• year - Past year

Privacy-Focused

• No user tracking
• No cookies required
• No profiling
• No ads

Language Support

Support for 60+ languages with the language parameter.

Self-Hosting

SearXNG can be self-hosted for complete control.

Quick Deploy

Use our pre-configured deployment repository for easy setup:

Fork and Deploy: github.com/BerriAI/serxng-deployment

This repository includes:

• Docker and Docker Compose setup
• JSON API format pre-configured
• Ready to deploy

Manual Installation

See the official SearXNG installation instructions for detailed setup.

Important: When you install SearXNG, the only active output format by default is the HTML format. You need to activate the JSON format to use the API.

Add the following to your settings.yml file:

search:
  formats:
    - html
    - json

Then restart SearXNG:

# Using Docker
docker run -d -p 8080:8080 \\
  -v $(pwd)/settings.yml:/etc/searxng/settings.yml:ro \\
  -e SEARXNG_BASE_URL=http://localhost:8080 \\
  searxng/searxng

# Then configure LiteLLM to use your instance

Configuration

Setting API Base URL (Required)

You must specify a SearXNG instance URL either via environment variable or in the search call:

# Option 1: Environment variable (Recommended)

os.environ["SEARXNG_API_BASE"] = "https://your-instance.com"

response = search(
    query="AI developments",
    search_provider="searxng"
)

# Option 2: Pass directly in search call
response = search(
    query="AI developments",
    search_provider="searxng",
    api_base="https://your-instance.com"
)

Note: There is no default instance URL. You must choose either a public instance or self-host your own.

Optional Authentication

Some SearXNG instances may require authentication:

# Set API key if required
os.environ["SEARXNG_API_KEY"] = "your-api-key"

response = search(
    query="AI developments",
    search_provider="searxng"
)

Cost

SearXNG is completely free:

• Open source - No licensing costs
• Self-hosted - Only infrastructure costs
• Public instances - Usually free, check instance policies

Advanced Usage

Custom Engine Selection

response = search(
    query="Python tutorials",
    search_provider="searxng",
    engines="stackoverflow,github,reddit",  # Only search these engines
    categories="it"
)

Multi-Category Search

response = search(
    query="climate change",
    search_provider="searxng",
    categories="general,science,news",  # Search multiple categories
    time_range="month"
)

Pagination

# Get page 1
page1 = search(
    query="AI research",
    search_provider="searxng",
    pageno=1
)

# Get page 2
page2 = search(
    query="AI research",
    search_provider="searxng",
    pageno=2
)

Response Format

SearXNG returns results in the standard LiteLLM search format:

{
  "object": "search",
  "results": [
    {
      "title": "Example Result",
      "url": "https://example.com",
      "snippet": "This is the content snippet from the search result...",
      "date": "2024-01-15",
      "last_updated": null
    }
  ]
}

Troubleshooting

Test Your Instance First

If LiteLLM with searxng search provider is not working, test your SearXNG instance directly with curl:

# Test if JSON API is working
curl -s "https://your-searxng-instance.com/search?q=test&format=json" | head -50

# Example with specific instance
curl -s "https://serxng-deployment-production.up.railway.app/search?q=test&format=json" | head -50

Expected response: JSON with search results
If you get HTML: JSON format is not enabled in the instance's settings.yml

No Results

If you get no results:

1. Try different engines: Specify engines parameter
2. Broaden categories: Use multiple categories
3. Adjust language: Set appropriate language parameter

JSON Format Not Enabled

If you get HTML instead of JSON:

1. Test with curl: Use the curl command above to verify JSON output
2. Self-host your own instance: Use our deployment repo with JSON pre-configured
3. Check instance configuration: Not all public instances have JSON enabled
4. Enable JSON manually: Add to settings.yml:

   search:
     formats:
       - html
       - json