SerpApi Superapp

SerpApi Superapp is a demo app with multiple tools that show what you can build with SerpApi across search, video, SEO, GEO, ASO, shopping, local, travel, hiring, finance, and research workflows. This is an initial subset of tools, and more will be added over time.

Live runs use your SerpApi API key and consume your SerpApi credits. Each tool displays an estimated credit usage count before you run it. You can enable Demo Mode to try pre-set examples with saved responses without consuming any credits.

Finance, Video, Hiring, and Research

Demo	Workflow	Maximum credits per live run
Finance Market Monitor	Scan green/red market cards, filter gainers or decliners, compare sections, inspect an instrument, switch to a table, and export results. Open Stock Tracker for price history.	1
Stock Tracker	Inspect a quote, explore dated price history, export observations, and read related news.	1
Video Intelligence Desk	Compare seven video engines, filter by engine, sort by reported views or engine overlap, and export a shortlist.	One per selected engine, plus optional video details and transcript
Video Transcript Desk	Paste a YouTube URL, inspect the selected caption track, search text, open timestamps, and export text or CSV.	1
Hiring Demand Tracker	Compare employers and sources in the returned jobs, filter listings, read descriptions, and open application links.	1
Patent Landscape Explorer	Filter patents by assignee and other criteria, inspect the source summary, export records, and open patent details.	1
Research Citation Lab	Search publications and patents, sort publications by citation count, and open author, patent, or case details using returned IDs.	One per selected engine

Result filters, sorting, and exports run in the browser and use no additional credits. Opening a related tool fills its inputs; press its run button to make a new request. Price changes use returned observations, and hiring counts describe the returned page rather than the entire market.

The home page includes searchable demos and a snapshot of 112 API references from SerpApi's catalog, checked September 9, 2026. The current Google Finance Markets reference supports only trend=indexes; the app uses gl for country selection and filters the returned sections locally.

All 32 tool pages and the AI Citation workflow have saved examples captured through the application routes and controllers. On September 10, 2026, 24 workflows received fuller examples, plus a second App Store country comparison for Google Play. MetaSearch compares five engines; GEO Country Visibility compares five countries across three AI engines; rank tracking uses three keywords across three engines; and AI brand comparisons use three prompts across four engines. Shopping, local, image, video, Trends, and ASO samples also exercise their comparison controls.

Each live-example.json includes the original inputs, normalized results, redacted API logs, and capture time. Demo Mode loads these examples first and restores their form inputs. Older saved runs remain available. Samples are snapshots; replaying them does not refresh prices, dates, rankings, or availability.

ASO comparisons include Google Play's highlighted app and label it "App highlight". Google Play positions follow the returned display order, with the highlighted app first and repeated app IDs removed. App matching uses the title or exact store ID; a shared developer name does not make Threads a match for Instagram. Use a package or bundle ID to distinguish apps with the same title.

Market Monitor uses green for gains, red for declines, and neutral styling for unchanged or unavailable movement. Arrows, signs, and text also indicate direction. Breadth counts and relative movement bars describe only the returned instruments in the current filter. The capture timestamp stays visible as filters change.

Market Monitor uses a local SVG subset of Lucide 1.43.0. Its ISC and MIT notices are included in the bundled license; package provenance is in source.json. Icons need no external font, script, or build step.

Trip Planner uses Google Search for event suggestions because live requests to google_events currently return an unsupported-engine error. Event suggestions link to web results; confirm dates on the source before adding them to an itinerary.

The transcript tool defaults to TED-Ed's English stock-market explainer. Its saved demo uses NASA's "What is a Black Hole?" narration, retrieved through SerpApi on September 9, 2026. Transcript requests prefer type=asr; videos can return an uploaded track instead. The UI identifies the returned track and reports language or type fallbacks. Unrequested tracks named as chat are kept in the raw call log and excluded from the speech reader and exports. A named track can be requested explicitly. The same checks apply to Video Intelligence's transcript enrichment. See the transcript parameters.

Run Locally

1. Install dependencies:

   uv sync

2. Start the app:

   uv run uvicorn app.main:app --reload

3. Open the app in your browser:

   http://127.0.0.1:8000
   

4. Add your SerpApi key:

   Open Settings in the app, paste your SerpApi API key, and click Save. Live tool runs use this browser-saved key and consume your SerpApi credits.

Development

The backend uses FastAPI and the SerpApi Python SDK (serpapi). Direct SDK calls are kept in app/serpapi_engines/, while demo workflow composition lives in app/controllers/.

Directory structure:

• app/ - FastAPI application, static frontend, routes, controllers, schemas, and SerpApi integrations.
• app/controllers/ - Tool workflow logic grouped by product area, with each tool implemented as a controller class.
• app/controllers/aso/ - App Store Optimization tool controllers.
• app/controllers/commerce/ - Shopping and marketplace tool controllers.
• app/controllers/finance/ - Finance market and ticker-tracking tool controllers.
• app/controllers/geo/ - Generative Engine Optimization and local visibility tool controllers.
• app/controllers/hiring/ - Hiring demand and labor market tool controllers.
• app/controllers/meta/ - Meta-search controller logic shared by search and AI search tools.
• app/controllers/research/ - Patent, scholar, and research landscape tool controllers.
• app/controllers/seo/ - Search Engine Optimization tool controllers.
• app/controllers/travel/ - Flights, hotels, destination, and local travel tool controllers.
• app/controllers/video/ - Video search and YouTube enrichment workflow controllers.
• app/core/ - Runtime configuration helpers.
• app/demo_cache/ - Saved demo responses used by Demo Mode.
• app/routes/ - FastAPI route modules under /api.
• app/schemas/ - Pydantic request models for API validation.
• app/serpapi_engines/ - Direct SerpApi SDK wrappers and engine helpers.
• app/static/ - Static HTML, CSS, and JavaScript frontend served by FastAPI.
• app/static/css/ - Shared frontend styles.
• app/static/js/ - Shared and tool-specific frontend JavaScript.
• app/static/tools/ - Individual static HTML pages for each demo tool.
• tests/ - Unit and live integration tests.

Request flow for a tool:

1. A user opens a static tool page such as app/static/tools/shopping-assistant.html.
2. Tool JavaScript reads the form configuration in app/static/js/analysis-tools.js and sends the request through apiJson() in app/static/js/api.js. The finance, video, hiring, and research result interactions live in app/static/js/discovery-tools.js.
3. apiJson() calls a backend route under /api, adds the browser-saved SerpApi key as the X-SerpApi-Key header, and returns JSON to the UI.
4. FastAPI receives the above request to /api and directs it to a route file such as app/routes/commerce_travel.py.
5. The route validates the request with a Pydantic schema from app/schemas/commerce_travel.py.
6. The route calls the matching controller class, for example ShoppingAssistantController in app/controllers/commerce/shopping_assistant.py.
7. The controller builds SerpApi engine parameters, runs one or more engine calls, normalizes the result for the UI, and returns results, calls, docs, and raw or near-raw SerpApi data for inspection.
8. Direct SerpApi requests go through helpers such as search() in app/serpapi_engines/client.py, which creates a serpapi.Client from the SerpApi Python SDK.
9. The JSON response flows back through the route to the frontend, where the tool renders results and the API call log.

Useful commands:

For testing, install the development dependencies, add TEST_SERPAPI_KEY env var and run:

uv run pytest

You can also put TEST_SERPAPI_KEY in the local .env file. It is used only by tests; browser live runs still require a key in Settings. Missing live credentials fail explicitly. The focused discovery tests are:

uv run pytest tests/test_market_dashboard.py tests/test_discovery_validation.py tests/test_hiring_finance_research_tools.py tests/test_video_research_tools.py

Live tests call controllers directly and require successful calls, redacted request parameters, exposed source responses, and populated UI fields. Saved responses do not substitute for live tool coverage. Market dashboard behaviour tests also require Node.js; the frontend itself has no build step.

Refresh saved examples

Showcase inputs live in app/demo_recipes.json. They exercise the comparisons each tool offers; live tests use smaller requests to keep test runs economical. Refresh selected examples with:

uv run python scripts/capture_demos.py meta-search geo-country-visibility

The command uses TEST_SERPAPI_KEY or prompts for a hidden key. It calls the application routes and controllers, checks every engine call and the normalized results, and saves only successful workflows. Failed or incomplete runs leave the previous sample intact. Credentials are redacted before saving. Use --all to refresh every recipe, including both ASO country samples. Refreshes consume SerpApi credits; Demo Mode replays do not.

To check that saved responses still match the recipes without making live requests:

uv run python scripts/capture_demos.py --all --check

The optional browser capture feature remains available with ENABLE_DEMO_CAPTURE=true.

The September 9, 2026 live check passed 101 tests. Four live checks still fail: Home Depot returns an engine error, Yandex video results omit source links, Scholar case details return no result for a freshly returned case ID, and the narrow destination query Reykjavík coffee has no Trends data. These failures remain in the test suite. Every tool has a working saved workflow, including a broader destination query with populated Trends results.