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"

proxyOptional

Bypasses CORS by proxying the image through the server. Useful when direct favicon URLs have CORS restrictions.

Example:

curl -L "https://roversurf.com/api/favicon?url=https://example.com/favicon.ico&proxy=true"

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

Note: Returns a 302 redirect to the best icon.

Fetch API

Universal CORS bypass proxy. Fetches any external resource and serves it with proper headers. Supports JSON, HTML, images, videos, and any content type.

Usage

bash

# Fetch JSON data
curl "https://roversurf.com/api/fetch?url=https://api.github.com/users/octocat"

# Fetch HTML page
curl "https://roversurf.com/api/fetch?url=https://example.com"

# Fetch image (save to file)
curl "https://roversurf.com/api/fetch?url=https://httpbin.org/image/png" -o image.png

# With tracking parameters
curl "https://roversurf.com/api/fetch?url=https://api.github.com/users/octocat&r_src=hp&r_ua=linux_web"

Features

Bypasses CORS restrictions for client-side requests
Supports all content types (JSON, HTML, images, videos, etc.)
Automatic redirect following
Analytics logging for tracking

Query Parameters

urlRequired

Target URL to fetch. Must be a valid HTTP/HTTPS URL.

Example:

curl "https://roversurf.com/api/fetch?url=https://api.github.com/users/octocat"

Note:: Fetch API also supports all R-Protocol (Common) parameters for tracking.

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.