openserp 0.1.0

Python SDK for the OpenSERP self-hosted server and OpenSERP Cloud.

OpenSERP Python SDK

Alpha: API may change before 1.0.

Python SDK for the OpenSERP self-hosted server and OpenSERP Cloud. The same client works against both backends.

Install

pip install openserp

For DataFrame export:

pip install "openserp[pandas]"

OSS Mode

OSS mode is the default. Run the open source server locally, then point the SDK at it:

from openserp import OpenSERP

client = OpenSERP(base_url="http://localhost:7000")

resp = client.search(
    engine="google",
    text="openserp",
    limit=10,
    region="US",
)

print(resp.results[0].title, resp.results[0].url)

If you omit every option, the client uses http://localhost:7000.

Cloud Mode

Pass an API key and the client defaults to https://api.openserp.org/v1.

import os

from openserp import OpenSERP

client = OpenSERP(api_key=os.environ["OPENSERP_API_KEY"])
resp = client.search(engine="google", text="openserp")

print(resp.results[0].title)
print(client.last_response.credits)

Async

import asyncio
import os

from openserp import AsyncOpenSERP


async def main() -> None:
    async with AsyncOpenSERP(api_key=os.environ["OPENSERP_API_KEY"]) as client:
        resp = await client.search(engine="google", text="openserp")
        print(resp.results[0].title)


asyncio.run(main())

Mega Search

from openserp import OpenSERP

client = OpenSERP()

mega = client.mega_search(
    text="openserp",
    engines=["google", "bing", "yandex"],
    mode="balanced",
)

df = mega.to_pandas()
print(df[["rank", "title", "url", "engine"]])

Convenience helpers are also available:

client.fast_search(text="openserp", engines=["google", "bing"])
client.any_search(text="openserp", engines=["google", "bing"])
client.mega_image(text="golang logo", engines=["google", "bing"])

AI / RAG

from openserp import OpenSERP

client = OpenSERP()
resp = client.search(engine="google", text="latest postgres indexing guide", limit=5)

context = "\n\n".join(
    f"{item.title}\n{item.url}\n{item.snippet}"
    for item in resp.results
)

prompt = f"Use these web results as grounding:\n\n{context}\n\nSummarize the key points."

SEO Keyword Tracker

from openserp import OpenSERP

client = OpenSERP()
keywords = ["openserp", "serp api", "google search api"]
frames = []

for keyword in keywords:
    resp = client.search(engine="google", text=keyword, region="US", limit=10)
    frame = resp.to_pandas()
    frame["keyword"] = keyword
    frames.append(frame)

report = __import__("pandas").concat(frames, ignore_index=True)
report.to_csv("rank-report.csv", index=False)

Async Batch

import asyncio

from openserp import AsyncOpenSERP


async def main() -> None:
    sem = asyncio.Semaphore(20)
    queries = [f"keyword {i}" for i in range(500)]

    async with AsyncOpenSERP() as client:
        async def run(query: str):
            async with sem:
                return await client.search(engine="google", text=query, limit=10)

        responses = await asyncio.gather(*(run(query) for query in queries))
        print(len(responses))


asyncio.run(main())

Endpoint Availability

Search endpoints work in both modes. Operational OSS endpoints such as health(), stats(), parse_google(), and parse_bing() require a self-hosted server and raise OssOnlyError in Cloud mode.

Cloud account endpoints such as me(), pricing(), engines_status(), and engines_capabilities() require Cloud mode and raise CloudOnlyError in OSS mode.

Development

python -m pip install -e ".[dev,pandas]"
pytest
ruff check .
mypy src
python -m build

The project is scaffolded for uv too:

uv build