https://github.com/redredchen01/seoserper
Self-use Streamlit tool that analyzes Google + Bing SERP surfaces (Suggestions / PAA / Related Searches) via SerpAPI. 3-surface mode (key set) or Suggest-only (key unset). SQLite-backed history + compare view + MD/CSV export.
https://github.com/redredchen01/seoserper
autocomplete bing google-serp paa python seo serpapi sqlite streamlit
Last synced: 14 days ago
JSON representation
Self-use Streamlit tool that analyzes Google + Bing SERP surfaces (Suggestions / PAA / Related Searches) via SerpAPI. 3-surface mode (key set) or Suggest-only (key unset). SQLite-backed history + compare view + MD/CSV export.
- Host: GitHub
- URL: https://github.com/redredchen01/seoserper
- Owner: redredchen01
- License: mit
- Created: 2026-04-20T10:26:54.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-20T10:46:27.000Z (about 2 months ago)
- Last Synced: 2026-04-20T12:35:10.461Z (about 2 months ago)
- Topics: autocomplete, bing, google-serp, paa, python, seo, serpapi, sqlite, streamlit
- Language: Python
- Size: 300 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SEOSERPER
[](https://github.com/redredchen01/seoserper/actions/workflows/test.yml)
[](LICENSE)
[](pyproject.toml)
Local-first Google + Bing SERP analyzer. Pulls **Autocomplete Suggestions**, **People Also Ask**, and **Related Searches** for any query, saves history to SQLite, exports Markdown or CSV.
Solo-operator tool, self-use. No account, no cloud — bring your own SerpAPI key (optional, free tier works).
## Modes
| Mode | Trigger | Surfaces |
|------|---------|----------|
| **Full (Google)** | engine=Google + `SERPAPI_KEY` set | Suggestions (free) + PAA + Related (via SerpAPI) — 1 credit/submit |
| **Suggest-only (Google)** | engine=Google + `SERPAPI_KEY` unset | Suggestions only — 0 credits |
| **Bing** | engine=Bing + `SERPAPI_KEY` set | PAA + Related (via SerpAPI `engine=bing`) — 1 credit/submit. **No Suggest** — Bing has no public/free autocomplete endpoint. |
SerpAPI free tier is ~100-250 searches/month (depends on your plan — check https://serpapi.com/manage-api-key). No credit card. **Google and Bing share the same quota pool.** See `seoserper/config.py` module docstring for the full setup + locale + quota details.
**Note on Bing PAA**: Google returns PAA on ~80% of queries; Bing on ~20-40%. Don't be surprised when Bing's PAA surface is EMPTY — it's upstream behavior, not a tool error.
## Quick start
```bash
# 1. Clone + deps (Python 3.10+ required)
pip install -e .
# 2. Optional: configure SerpAPI for Full mode
cp .env.example .env # edit and paste your key
export $(grep -v '^#' .env | xargs)
# 3. Run
streamlit run app.py
```
Open http://localhost:8501. Pick a locale (English / 简体中文 / 繁體中文 / 日本語), submit a query.
## Screenshots
The default view shows Google + Bing side by side with `🟰` markers on items both engines returned, a quota progress bar at the top, and a filterable history sidebar.
## Export formats
| Format | Content |
|--------|---------|
| Markdown | H1 + frontmatter + sections — paste into Notion / 飞书 / VS Code |
| CSV | Flat `surface,rank,text,answer_preview` rows — open in Excel / LibreOffice (UTF-8 BOM for zh/ja compat) |
## Cache
Full-mode responses are cached by `(query, lang, country)` for 24 hours. Repeat queries don't burn SerpAPI quota. Reset / prune:
```bash
python3 scripts/reset_serp_cache.py # nuke all
python3 scripts/reset_serp_cache.py --prune-only # drop only expired
```
## Tests
```bash
pip install -e '.[dev]'
pytest tests/ -q
```
## Plans
Design history lives under `docs/plans/` — active plan is the highest-numbered `status: active` file. Completed plans stay for context.
## License
MIT — see [LICENSE](LICENSE).