SerpAPI Review Tracker

A Java CLI for small businesses and developers who want to fetch, cache, and analyze Google Maps and Yelp reviews through SerpAPI. Export CSV history, track rating trends, and project how many reviews you need to reach a target average.

Badges

CLI Reference

Fetch Google Maps reviews

$mvn exec:java -Dexec.args="google"

Variable	Type	Description
SERPAPI_API_KEY	string	Required. Your SerpAPI API key
SERPAPI_PLACE_ID	string	Required. Google Maps place ID
QUERY	string	Optional text filter inside reviews
FORCE_FULL_BACKFILL	boolean	Rebuild cache from scratch (true / false)

Fetch Yelp reviews

$mvn exec:java -Dexec.args="yelp"

Variable	Type	Description
SERPAPI_API_KEY	string	Required. Your SerpAPI API key
SERPAPI_YELP_PLACE_ID	string	Required. Yelp business place ID
YELP_RATING	string	Optional rating filter, e.g. 5 or 5,4,3

Run tests

$mvn test

SerpAPI Endpoints Used

This project calls SerpAPI over HTTP — it does not expose its own REST server.

Google Maps reviews

GET https://serpapi.com/search?engine=google_maps_reviews

Parameter	Type	Description
api_key	string	Required. SerpAPI key
place_id	string	Required. Google place ID
next_page_token	string	Pagination token from previous response

Yelp reviews

GET https://serpapi.com/search.json?engine=yelp_reviews

Parameter	Type	Description
api_key	string	Required. SerpAPI key
place_id	string	Required. Yelp place ID
start	number	Pagination offset
num	number	Page size

Environment Variables

To run this project, add the following environment variables to your .env file (see .env.example):

SERPAPI_API_KEY

SERPAPI_PLACE_ID

SERPAPI_YELP_PLACE_ID

TARGET_AVG

PROJECTION_STAR

QUERY

FORCE_FULL_BACKFILL

YELP_RATING

Variable	Required	Default	Description
SERPAPI_API_KEY	Yes	—	SerpAPI API key
SERPAPI_PLACE_ID	Google	—	Google Maps place ID
SERPAPI_YELP_PLACE_ID	Yelp	—	Yelp business place ID
TARGET_AVG	No	4.60	Target average for projections
PROJECTION_STAR	No	5	Star rating assumed for future reviews
QUERY	No	—	Optional text filter inside reviews
FORCE_FULL_BACKFILL	No	false	Rebuild Google cache and reset Google CSV
YELP_RATING	No	—	Rating filter, e.g. 5 or 5,4,3

Prerequisites

• Java 17+ — Download
• Maven 3.8+ — Download
• SerpAPI account — Sign up (free tier available)

Verify your setup:

java -version   # should print 17 or higher
mvn -version    # should print 3.8 or higher

Run Locally

Clone the project

$git clone https://github.com/afaqahmadijaz/serpapi-review-tracker.git

Go to the project directory

$cd serpapi-review-tracker

Copy the environment template

$cp .env.example .env

Export your variables (or load .env in your shell / IDE)

export SERPAPI_API_KEY=your_key
export SERPAPI_PLACE_ID=your_google_place_id

Run the tracker

$mvn exec:java -Dexec.args="google"

Usage / Examples

First run (full backfill) — empty cache triggers a full paginated fetch:

export SERPAPI_API_KEY=your_key
export SERPAPI_PLACE_ID=ChIJxxxxxxxxxxxx
mvn exec:java -Dexec.args="google"

Incremental run — fetches only new reviews since the last run:

$mvn exec:java -Dexec.args="google"

Yelp with rating filter:

export SERPAPI_YELP_PLACE_ID=your_yelp_place_id
export YELP_RATING=5,4
mvn exec:java -Dexec.args="yelp"

Force a full Google cache rebuild:

export FORCE_FULL_BACKFILL=true
mvn exec:java -Dexec.args="google"

Output (local only, gitignored)

Path	Description
.cache/	JSON review caches for deduplication
history/	CSV exports appended on each run
summaries/	Timestamped summary text files

Disclaimer

This tool is provided as-is. You are responsible for complying with SerpAPI's terms, Google and Yelp platform policies, and applicable privacy laws when fetching, storing, or using review data.

Contributing

Contributions are welcome! See CONTRIBUTING.md.

For security issues, see SECURITY.md.

License

MIT