Stophy for Python

Web scraping API for AI agents, in Python. One API to search the web, read what people say, and look up products, places, jobs and homes. Pay only for answers. Every method and result is typed.

Install

pip install stophy

Try it without a key

from stophy import Stophy

result = Stophy().google.search(query="bun runtime")
print(result["data"]["results"])

Some searches and lookups work without a key, within a small free allowance. The endpoint list marks them with keyless: true. Every other method raises a StophyError with the code unauthorized.

Use an API key

Get a key from the dashboard. Keys start with st_. Set it as STOPHY_API_KEY, or pass it in:

stophy = Stophy(api_key="st_...")

videos = stophy.youtube.search(query="bun runtime")
print(videos["data"]["results"])

Methods follow the source and the command: stophy.google.maps.search(...), stophy.reddit.subreddit(...), stophy.meta.ads.search(...).

To point at one thing, send its link or its id, never both: stophy.youtube.video(video_url=...) or stophy.youtube.video(video_id=...). Methods that take a person send user_url or username.

Every response is a dict with success, data, creditsUsed, and requestId. data is one flat dict. Lists are in data["results"].

Arguments are keyword-only and snake_case.

For async code, use AsyncStophy. It has the same methods, and you await each call.

More data

A YouTube transcript, Reddit posts, Google Maps reviews, a TikTok profile and Meta ads:

stophy = Stophy(api_key="st_...")

transcript = stophy.youtube.transcript(video_url="https://youtu.be/dQw4w9WgXcQ", include_timestamps=True)
print(transcript["data"].get("text"), transcript["data"].get("segments"))

posts = stophy.reddit.search(query="bun runtime", sort="top", within="month")
print(posts["data"]["results"])

places = stophy.google.maps.search(query="coffee", location="Austin, TX")
place_id = places["data"]["results"][0].get("placeId")
if place_id:
    reviews = stophy.google.maps.reviews(place_id=place_id)
    print(reviews["data"]["results"])

profile = stophy.tiktok.profile(username="tiktok")
print(profile["data"].get("followers"), profile["data"].get("results"))

ads = stophy.meta.ads.search(query="running shoes")
print(ads["data"]["results"])

Get the next page

Each call returns one page of results, as the site shows it. List methods page in one of two ways.

Some take a page number. They return data["page"]. Ask for the next number to continue, and stop when results comes back empty:

first = stophy.google.search(query="bun runtime")
second = stophy.google.search(query="bun runtime", page=first["data"]["page"] + 1)

Others return data["cursor"] when there is more. Pass it back as is:

first = stophy.youtube.search(query="bun runtime")
if first["data"].get("cursor"):
    next_page = stophy.youtube.search(query="bun runtime", cursor=first["data"]["cursor"])

Handle errors

from stophy import StophyError

try:
    stophy.reddit.search(query="bun")
except StophyError as error:
    print(error.code, error.retryable, error.retry_after_seconds)

StophyError has code, retryable, retry_after_seconds, status, and request_id. The message is str(error).

The SDK retries network errors and the HTTP statuses 429, 500, 502, 503, and 504, and it waits as long as the API asks. If the API asks for a wait longer than 60 seconds, the SDK raises right away with retry_after_seconds set.

Options

Check your account

usage = stophy.usage()
logs = stophy.logs(days=7, page=0)

usage returns your balance and your all-time usage. logs returns your recent requests. Both need an API key.

License

MIT