Novada Search

Novada Search v2.0

Multi-engine AI search — 9 engines, 13 Google types, 9 vertical scenes, smart agent modes. Powered by Novada Scraper API.

Get started in 30 seconds:

1. Get your free API key → novada.com
2. Set the key via environment or CLI: export NOVADA_API_KEY="your_key" (or pass --api-key $NOVADA_API_KEY)
3. Search: python3 {baseDir}/novada_search.py --query "coffee Berlin" --scene local

Agent-first + Human-friendly (Intelligent Distance)

This skill is optimized for agents first, then rendered for humans:

• Agent layer (machine logic)

  • Use --format agent-json.
  • Provides deterministic fields: engines_used, result_counts, duplicates_removed, unified_results, errors.
  • Best for planning, tool-chaining, re-ranking, and downstream automation.

• Human layer (readability)

  • Use --format enhanced or --format ranked.
  • Shows concise summaries, links, and ranked lists with less structural noise.

Recommended default contract for agent handoff:

python3 {baseDir}/novada_search.py --query "..." --scene news --format agent-json

If a human drags this skill to an agent, the agent should be able to clearly answer:

1. what this tool can do,
2. which mode to call (auto | multi | extract), and
3. which output format to consume (agent-json for logic).

SDK, MCP & Integrations (v1.0.8)

Python SDK

from novada_search import NovadaSearch

client = NovadaSearch(api_key="your_key")
result = client.search("coffee Berlin", scene="local")
result = client.search("buy shoes", mode="auto")
result = client.search("AI news", mode="multi", engines=["google", "bing"])
content = client.extract("https://example.com/article")

All SDK methods raise NovadaSearchError subclasses (not SystemExit), so agents can catch and recover.

MCP Server

python3 {baseDir}/novada_mcp_server.py

Tools: novada_search, novada_extract. Config example: mcp.json.

LangChain

from integrations.langchain_tool import NovadaSearchTool
tool = NovadaSearchTool(api_key="your_key")

Install via pip

pip install novada-search

agent-json enhanced fields

• response_time_ms
• search_metadata
• per-result domain
• per-result freshness

What’s New (P0) — Best-Answer First for Agents

• Unified Best Answer: agent-json now includes unified_results (top merged results across engines).
• Dedup that Agents Love: aggressive URL normalization + multi-engine merging; exposes duplicates_removed.
• Explainable Scoring: each unified result has score + agreement_count + domain + a short rationale.
• Regression Guardrail: added tests/ fixtures so ranking changes don’t silently degrade.

Troubleshooting (Read This)

• Novada may return HTTP 200 even on failure: the real error is in JSON data.code / data.msg. This CLI hard-checks it and will exit on non-success codes.
• Cloud/Vercel IPs may be blocked (402): validate from your production egress IP before shipping; request server-to-server allowlisting if needed.
• Local/Shopping default to fetch_mode=dynamic: slower, but higher hit rate for Maps/e-commerce pages.
• Debugging: add --verbose to see engine/type selection and execution path.

API Keys & Permissions

• NOVADA_API_KEY is required. Either export it (recommended for deployments) or pass --api-key per run.
• The CLI no longer scans home directories for secrets; it only checks CLI flag, NOVADA_API_KEY, or a local .env in the working folder.
• Declared permissions: filesystem (./*.py, ./*.md, ./samples/*) and network access to https://scraperapi.novada.com.

Real-World Example

Query: --query "dessert Düsseldorf" --scene local

Output:

🍰 Düsseldorf TOP 5 Dessert Shops

Click any shop name to open in Google Maps. This is the default enhanced output — actionable links, no extra flags needed.

Architecture

  Layer 3  │  AI Agent    │  auto · multi · extract
  Layer 2  │  Scenes      │  shopping · local · jobs · academic · video · news · travel · finance · images
  Layer 1  │  Engines     │  google · bing · yahoo · duckduckgo · yandex · youtube · ebay · walmart · yelp
           │              │  + Google: shopping · local · news · scholar · jobs · flights · finance · patents · videos · images · play · lens

Layer 1 — Engines

9 Engines

13 Google Sub-Types

Use --engine google --google-type <type>:

python3 {baseDir}/novada_search.py --query "MacBook Pro M4" --engine google --google-type shopping
python3 {baseDir}/novada_search.py --query "transformer attention" --engine google --google-type scholar
python3 {baseDir}/novada_search.py --query "python developer remote" --engine google --google-type jobs
python3 {baseDir}/novada_search.py --query "SFO to NRT" --engine google --google-type flights
python3 {baseDir}/novada_search.py --query "NVIDIA" --engine google --google-type finance

Layer 2 — Scenes

Scenes auto-combine the best engines for each use case. Use --scene <name>:

python3 {baseDir}/novada_search.py --query "MacBook Pro" --scene shopping
python3 {baseDir}/novada_search.py --query "ramen Tokyo" --scene local
python3 {baseDir}/novada_search.py --query "react hooks tutorial" --scene video
python3 {baseDir}/novada_search.py --query "AI startup funding" --scene news

Scene Output Example — Shopping

Query: --query "AirPods Pro" --scene shopping --format agent-json

{
  "query": "AirPods Pro",
  "scene": "shopping",
  "engines_used": ["google:shopping", "ebay", "walmart"],
  "result_counts": { "shopping": 15, "organic": 6 },
  "shopping_results": [
    { "title": "Apple AirPods Pro 2nd Gen", "price": "$189.99", "seller": "Walmart", "rating": 4.8 },
    { "title": "Apple AirPods Pro 2 - New", "price": "$179.00", "seller": "eBay", "rating": 4.9 },
    { "title": "AirPods Pro (2nd generation)", "price": "$249.00", "seller": "Apple", "rating": 4.7 }
  ]
}

Shopping Scene Enhanced Output (Coming in v1.1)

⚠️ Shopping price comparison requires engine-specific data parsing that is being finalized. The price_comparison, lowest_price, and price_range fields will be available in v1.1 when Walmart and eBay result parsing is complete.

Local Scene Enhanced Output (Coming in v1.1)

⚠️ Local business enrichment (phone, hours, open_now) depends on Google Maps and Yelp data parsing that is being finalized for v1.1.