MPL-2.0 Licensed

Rover Documentation

Everything you need to integrate, contribute, and deploy Rover.

All Roversurf projects are licensed under the MPL-2.0 license.

Rover

Rover is the complete search engine platform. It contains all the core backend functionalities of RSEC, but it additionally includes the web frontend.

Rover Structure

text

rover/
├── api/            # FastAPI application & routers
├── crawler/        # Web spider & content extraction
├── indexer/        # Core indexing engine architecture
├── lib/            # Core libraries (DB, search engine, AI)
├── tools/          # Administrative & maintenance tools
├── web/            # Next.js web interface & frontend
└── requirements.txt

RSEC — Rover Search Engine Core

RSEC is the complete backend repository of Rover.

RSEC Structure

text

rsec/
├── api/            # FastAPI application & routers
├── crawler/        # Web spider & content extraction
├── indexer/        # Core indexing engine architecture
├── lib/            # Core libraries (DB, search engine, AI)
├── tools/          # Administrative & maintenance tools
└── requirements.txt

Rover-SCLI — Command Line Interface

Rover-SCLI is a fully-featured terminal search tool.

Installation

bash

# Clone the SCLI repository
git clone https://github.com/roversurf/rover-scli.git
cd rover-scli

# Install dependencies
pip install requests rich

Usage

bash

# Basic search
python rover_search.py "your search query"

# Search in a specific category
python rover_search.py "latest tech news" --tab news

# Interactive mode
python rover_search.py --interactive

# Specify region
python rover_search.py "weather" --region tr

Tip: In interactive mode, use Tab to cycle between categories.

R-Protocol (Common Parameters)

These parameters are used across all APIs in the Rover ecosystem (Search and Favicon) for identity and security verification.

r_src

Rover source identifier — indicates the page the request originates from (r_src). E.g.: hp (home page), srp (search results).

Example: r_src=hp

r_ua

Rover platform or action identifier — Specifies the device and interface type the request originates from (e.g., windows_web, android_app).

Example: r_ua=windows_web

r_cli

Rover client identifier — Indicates the interface making the request (e.g., r_sapi).

Example: r_cli=r_sapi

r_sv

Rover search validation parameter (r_sv).

Example: r_sv=R56789

r_csrf

For Rover security/CSRF compatibility (r_csrf).

Example: r_csrf=R_abc123_xyz

Search API

Provides programmatic access to web search results.

Web Search

bash

curl -X GET "https://roversurf.com/api/search?q=hello+world&region=global" \
  -H "Accept: application/json"

Response Format

json

{
  "results": [
    {
      "title": "Hello, World! - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Hello_World",
      "snippet": "A "Hello, World!" program is generally a simple...",
      "favicon_url": "https://en.wikipedia.org/favicon.ico"
    }
  ],
  "total": 150,
  "query": "hello world"
}

Image Search

bash

curl -X GET "https://roversurf.com/api/search/images?q=aurora+borealis&size=large"

Video Search

bash

curl -X GET "https://roversurf.com/api/search/videos?q=rust+programming"

News Search

bash

curl -X GET "https://roversurf.com/api/search/news?q=technology&region=us"

AI Search (Cortex)

bash

curl -X GET "https://roversurf.com/api/search/ai?q=explain+quantum+computing"

Query Parameters

qSearch query (required)

regionRegion code: global, us, gb, de, fr, tr, jp

langLanguage code (e.g. en, tr)

safeSafe search filter

Analytic Parameters (Automatic)

Used exclusively by /api/search for detailed user analysis:

r_eiEvent Identifier

r_sigDigital Signature

r_vidVisitor ID

r_oqOriginal Query

r_lpLocal Preference

Favicon API

Returns a high-resolution favicon for any website.

Usage

bash

# Get high-res favicon (returns redirect or direct bytes)
curl -L "https://roversurf.com/api/favicon?url=vertexishere.com"

# Get metadata with all Rover tracking parameters
curl "https://roversurf.com/api/favicon?url=vertexishere.com&metadata=true&r_sv=12345&r_csrf=abcde&r_src=hp&r_ua=windows_web&r_cli=r_sapi"

# Get only color & URL info
curl "https://roversurf.com/api/favicon/color?url=vertexishere.com"

Color Information Service (/color)

Exclusively used to retrieve the high-resolution icon URL and main color code of the target URL. Has only 1 parameter (url).

json

{
  "status": "success",
  "url": "https://github.com",
  "best_favicon_url": "https://github.githubassets.com/favicons/favicon.svg",
  "color": "#24292e"
}

Resolution Logic

api_favicon_priority_desc
SVG icons are always prioritized. For other formats, the one closest to 128x128 is preferred.

Color Extraction

Analyzes the icon's dominant color using PIL-based ColorFinder for dynamic use in the UI (shortcuts, etc.).

CORS & Byte Serving

Icons can be served as raw bytes directly through the server to bypass browser-based CORS and ORB restrictions.

Query Parameters

urlRequired

Target website address to fetch the icon from.

Example:

curl -L "https://roversurf.com/api/favicon?url=vertexishere.com"

metadataOptional

If set to true, returns JSON containing the icon URL and color info instead of an image.

Example:

curl "https://roversurf.com/api/favicon?url=vertexishere.com&metadata=true"

Note:: Favicon API also supports all R-Protocol (Common) parameters.

Note: Returns a 302 redirect to the best icon.

api_keys_title

api_keys_desc

How to Get an API Key

Navigate to the . Developer Portal.
Generation is reserved for the core team.
Your key will appear on the page once granted.

Using Your API Key

bash

# Include your API key in the request header
curl -X GET "https://roversurf.com/api/search?q=hello" \
  -H "Authorization: Bearer YOUR_API_KEY"

Security: Never expose your API key in client-side code.