SerpApi Superapp

SerpApi Superapp is a demo app with multiple tools that show what you can build with SerpApi across search, SEO, GEO, ASO, shopping, local, and travel 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.

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/geo/ - Generative Engine Optimization and local visibility tool controllers.
• app/controllers/meta/ - Meta-search controller logic shared by search and AI search tools.
• app/controllers/seo/ - Search Engine Optimization tool controllers.
• app/controllers/travel/ - Flights, hotels, destination, and local travel tool 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.
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