OpenSERP (Search Engine Results)

OpenSERP is an API and CLI for accessing search engine results from Google, Yandex, Baidu, Bing, and DuckDuckGo. A developer-friendly alternative to paid SERP API services!

Official website: openserp.org

💡 OpenSerp is free and open-source. Only links listed in this repository and on the official website are associated with the project.

Features

• 🔍 Multi-engine - search with dedicated endpoints for each engine
• 🌐 Megasearch - cross-engine aggregation with deduplication
• 🖼 Images - image search is also available
• 🎯 Advanced filters - language, date range, file type, and site queries
• 🌍 Configurable - proxy, cache, and resilient mode support
• 🐳 Docker-ready - local and container deployment
• 📝 Data Formats - JSON, Markdown, Text, NdJSON response format types are supported

Quick Start⚡️

Docker

# Run the API server via prebuilt image
docker run -p 127.0.0.1:7000:7000 -it karust/openserp serve -a 0.0.0.0 -p 7000

# Or use docker-compose
docker compose up --build

From Source

git clone https://github.com/karust/openserp.git
cd openserp
go build -o openserp .
./openserp serve

API Docs

• Swagger UI: http://127.0.0.1:7000/docs
• OpenAPI YAML: http://127.0.0.1:7000/openapi.yaml

Search Endpoints

Available engine names: google, yandex, baidu, bing, duckduckgo.

Dedicated engine endpoints:

curl "http://127.0.0.1:7000/google/search?text=golang&limit=10"

Image search:

curl "http://127.0.0.1:7000/bing/image?text=golang+logo&limit=10"

Megasearch:

# Search all configured engines
curl "http://127.0.0.1:7000/mega/search?text=golang&limit=10"

# Search selected engines
curl "http://127.0.0.1:7000/mega/search?text=golang&engines=duckduckgo,bing&limit=15"

# Advanced filtering
curl "http://127.0.0.1:7000/mega/search?text=golang&engines=google,bing&limit=20&date=20250101..20251231&lang=EN"

# Image megasearch
curl "http://127.0.0.1:7000/mega/image?text=golang+logo&limit=20"

List engines:

curl "http://127.0.0.1:7000/mega/engines"

🔍 Query Parameters

Common parameters:

Parameter	Description	Example
text	Search query	golang programming
lang	Language code	EN, DE, RU, ES
date	Date range	20250101..20251231
file	File extension	pdf, doc, xls
site	Site-specific search	github.com
limit	Number of results, max 100	10, 25, 50
start	Pagination offset	0, 10, 20
format	Output format	json, markdown, text, ndjson

Engine-specific parameters:

Parameter	Supported engines	Notes
filter	google	Duplicate filter: true hides similar results, false includes them.
answers	google	Include Google answer boxes in output.

Search Response Example

{
  "query": {
    "text": "golang",
    "engines_requested": ["google"]
  },
  "meta": {
    "request_id": "019dc6c1-da45-706e-a57c-d671fa2862ee",
    "requested_at": "2026-04-25T22:27:52Z",
    "took_ms": 6410,
    "engines_failed": [],
    "version": "1.0"
  },
  "results": [
    {
      "id": "s_78341aa47c336101",
      "rank": 1,
      "type": "organic",
      "title": "Documentation - The Go Programming Language",
      "url": "https://go.dev/doc/",
      "display_url": "go.dev > doc",
      "snippet": "Official Go documentation, tutorials, references, and release notes.",
      "domain": "go.dev",
      "favicon": "https://go.dev/favicon.ico",
      "is_ad": false,
      "position": {
        "absolute": 1,
        "page": 1,
        "on_page": 1
      },
      "engine": "google",
      "domain_info": {
        "tld": "dev",
        "sld": "go",
        "is_gov": false,
        "is_edu": false,
        "is_social": false
      },
      "classification": {
        "content_type": "webpage"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "has_more": true,
    "next_start": 25
  }
}

Mega Response Notes

/mega/search returns the same envelope plus clusters. Results are deduplicated by normalized URL; clusters keep the per-engine occurrences:

{
  "id": "c_a1b2c3d4e5f6a1b2",
  "canonical_url": "https://go.dev/",
  "domain": "go.dev",
  "title": "The Go Programming Language",
  "occurrences": [
    { "engine": "google", "rank": 1, "result_id": "s_78341aa47c336101" },
    { "engine": "bing", "rank": 2, "result_id": "s_20f9f15f0c3d9f6d" }
  ],
  "engines_count": 2,
  "best_rank": 1,
  "score": 0.75
}

Image Response Example

{
  "id": "i_a1b2c3d4e5f6a1b2",
  "rank": 1,
  "type": "image",
  "title": "Go Gopher Logo",
  "image": {
    "url": "https://example.com/images/go-logo.png",
    "thumbnail": "https://example.com/images/go-logo-thumb.png",
    "width": 1200,
    "height": 800
  },
  "source": {
    "page_url": "https://go.dev/brand/",
    "domain": "go.dev"
  },
  "engine": "bing"
}

Error Responses

400 Bad Request:

{
  "error": "bad_request",
  "code": 400,
  "message": "EMPTY_QUERY: query cannot be empty: provide text, site, or file parameter",
  "reason": "EMPTY_QUERY"
}

503 Service Unavailable:

{
  "error": "service_unavailable",
  "code": 503,
  "message": "captcha found, please stop sending requests for a while: captcha detected"
}

🌍 Proxy Support

OpenSERP supports HTTP and SOCKS5 proxies.

Simple global proxy:

./openserp serve --proxy socks5://127.0.0.1:1080
./openserp search bing "query" --proxy http://user:pass@127.0.0.1:8080

Advanced proxy configuration is available in config.yaml. You can enable tagged proxy pools and per-request override via X-Use-Proxy: <tag> or X-Use-Proxy: direct.

Health & Stats

curl -i "http://127.0.0.1:7000/health"
curl "http://127.0.0.1:7000/ready"
curl "http://127.0.0.1:7000/stats"
curl "http://127.0.0.1:7000/stats/cache"
curl "http://127.0.0.1:7000/stats/proxy"
curl "http://127.0.0.1:7000/stats/cb"

License

This project is licensed under the MIT License. See LICENSE.

🤝 Contributing

Contributions are welcome. See docs/CONTRIBUTING.md.

"OpenSERP" is the name of this open-source project. Use of the name in a way that implies affiliation, endorsement, or official status is not permitted.