DEV Community

coreclaw
coreclaw

Posted on

Google Maps Scraper API: How to Run a Local SEO Audit for Multi-Location Brands

A local SEO audit for a multi-location brand is a comparison problem, not a content problem. Before you rewrite service pages, you need to know whether each location looks weaker than the three businesses sitting beside it on the map — fewer reviews, a thinner category set, missing hours, a lower rating. All of that is public listing data, and you can turn it into a scored audit with one script. This guide is for agencies running local SEO retainers, franchise operators, and in-house marketers who need the same answer for 5 locations or 500.

TL;DR

  • Pull the top 15–20 listings for one keyword in one market, per location you audit.
  • Score five things: share of local voice, rating position, category match, listing completeness, hygiene flags.
  • Weight the score so review volume and rating drive it, because those move rankings and calls most.
  • Sort locations by score, then fix the lowest dimension first — usually completeness, because it is cheap.
  • Store every run with a scraped_at date. An audit without a timestamp is an opinion.

Why the manual audit breaks

The first version of this audit is always a spreadsheet. Someone opens Google Maps, searches "dentist near me", copies the top ten names, ratings, and review counts for each of twelve locations, and pastes them into tabs. It takes a day and it is wrong by Friday, because review counts move and ratings shift by a tenth of a star.

There are three structural problems with the manual version:

  1. The comparison is inconsistent. One analyst includes the map pack, another includes organic results, a third filters out closed businesses. The numbers no longer describe the same market.
  2. Categories get ignored. A competitor ranking for "emergency dentist" may carry that category while your client does not. Ratings alone will not explain the gap.
  3. There is no history. You cannot show a client that review share went from 12% to 19% in three months if each audit overwrites the last one.

A script fixes all three by pulling the same fields, for the same query, in the same market, and writing a timestamped record.

The five metrics that make the audit defensible

Google Maps listing data supports more metrics than most audits use. These five are enough to explain most visibility gaps, and each maps to a documented field rather than a guess.

1. Share of local voice. Total reviews your client has, divided by total reviews across the audited set. A business with 400 reviews in a market where the leader has 1,800 is not competitive on social proof, even if its rating is higher. This is the single most useful number in the audit.

2. Rating position, not rating. A 4.4 looks fine until the market average is 4.6. Store the gap (review_rating minus market average) so the client sees position, not an isolated score.

3. Category match. Google Maps listings carry a primary_category and an all_categories list. If the target query is "cosmetic dentist" and that phrase is absent from every category on the listing, the listing is competing on the wrong terms.

4. Listing completeness. Count which of these are present: phone, website, opening hours, price range, attributes, images. Six fields, scored as a percentage. This is the part of the audit the client can fix this week.

5. Hygiene flags. Permanently closed status, missing hours on a location that serves customers, duplicated place_id values across two listings for the same address, ratings below the market floor. Flags are not scored; they are work items.

CoreClaw's Google Maps scraper documents the fields these metrics need — review_count, review_rating, rating_distribution, primary_category, all_categories, opening_hours, price_range, attributes, place_id and status. If you already have a data source, map your field names to these before scoring; the metric definitions matter more than the vendor.

The workflow

Step 1 — Define the market. One keyword, one location string, one radius of competitors. "Dentist" in "Austin, TX" is a market. "Dentist in Texas" is not; it returns a different set of businesses than a customer two miles away sees.

Step 2 — Pull the top N listings. N of 15–20 is enough. Positions 1–5 explain who wins; positions 6–20 explain how crowded the middle is. Keep the raw JSON.

Step 3 — Normalize into one table. One row per place, one column per metric input. Do this before scoring so a missing field fails loudly instead of silently scoring zero.

Step 4 — Score and rank. Weighted score, 0–100, per location.

Step 5 — Write the fix list. For each location, three actions tied to its weakest dimension.

Step 6 — Re-run monthly. Append, do not overwrite. Compare against the previous run.

The fetch step is the only part that touches the network. Keep it isolated so the scoring logic stays testable offline.

Runnable Python

The example below separates fetching from scoring. The scoring function runs on bundled sample data with no credentials, so you can verify the output before connecting a live endpoint. When you do connect one, set CORECLAW_MAPS_ENDPOINT and CORECLAW_API_KEY as environment variables — the request URL is account-specific, so copy it from the console rather than hardcoding a path you found in a blog post.

"""Score local search visibility from public Google Maps listing data."""
import json
import os
import time

import requests  # pip install requests

API_KEY = os.environ.get("CORECLAW_API_KEY", "")
# Account-specific request URL. Copy it from the CoreClaw console for the
# Google Maps worker you call; do not guess a path.
ENDPOINT = os.environ.get("CORECLAW_MAPS_ENDPOINT", "")

COMPLETENESS_FIELDS = ["phone", "website", "opening_hours", "price_range", "attributes", "images"]


def build_payload(keyword: str, location: str, limit: int) -> dict:
    # Key names must match the request example shown for your worker.
    return {"keyword": keyword, "location": location, "limit": limit}


def fetch_places(keyword: str, location: str, limit: int = 20, retries: int = 3):
    if not ENDPOINT or not API_KEY:
        raise RuntimeError("Set CORECLAW_MAPS_ENDPOINT and CORECLAW_API_KEY first")
    headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
    for attempt in range(retries):
        try:
            resp = requests.post(
                ENDPOINT,
                json=build_payload(keyword, location, limit),
                headers=headers,
                timeout=90,
            )
            resp.raise_for_status()
            data = resp.json()
            return data.get("places") or data.get("results") or []
        except (requests.RequestException, ValueError):
            if attempt == retries - 1:
                raise
            time.sleep(2 ** attempt)  # 1s, then 2s
    return []


def _value(place: dict, *keys, default=None):
    for key in keys:
        value = place.get(key)
        if value not in (None, "", [], {}):
            return value
    return default


def score_market(places: list, target_category: str) -> list:
    total_reviews = sum(int(_value(p, "review_count", default=0)) for p in places) or 1
    ratings = [float(_value(p, "review_rating", default=0)) for p in places]
    market_avg = sum(ratings) / len(ratings) if ratings else 0.0
    shares = [100 * int(_value(p, "review_count", default=0)) / total_reviews for p in places]
    top_share = max(shares) if shares else 0

    rows = []
    for place, share, rating in zip(places, shares, ratings):
        categories = [str(c).lower() for c in _value(place, "all_categories", default=[])]
        present = sum(1 for field in COMPLETENESS_FIELDS if _value(place, field) is not None)

        share_index = 100 * share / top_share if top_share else 0
        rating_index = max(0.0, min(100.0, (rating - 3.0) / 2.0 * 100))
        completeness = 100 * present / len(COMPLETENESS_FIELDS)
        category_index = 100 if target_category.lower() in categories else 0

        score = (
            0.4 * share_index
            + 0.3 * rating_index
            + 0.2 * completeness
            + 0.1 * category_index
        )
        rows.append(
            {
                "name": _value(place, "title", default="unknown"),
                "review_count": int(_value(place, "review_count", default=0)),
                "review_rating": rating,
                "share_pct": round(share, 1),
                "rating_gap": round(rating - market_avg, 2),
                "completeness_pct": round(completeness),
                "category_match": bool(category_index),
                "score": round(score, 1),
            }
        )

    return sorted(rows, key=lambda row: row["score"], reverse=True)


SAMPLE = [
    {"title": "Lakeside Dental Studio", "review_count": 412, "review_rating": 4.7,
     "all_categories": ["Dentist", "Cosmetic dentist"], "phone": "+1-512-555-0110",
     "website": "https://example.com/lakeside", "opening_hours": {"mon": "8-17"},
     "price_range": "$$", "attributes": ["Wheelchair accessible"], "images": ["a.jpg"]},
    {"title": "Northgate Family Dental", "review_count": 1180, "review_rating": 4.4,
     "all_categories": ["Dentist", "Emergency dental clinic"], "phone": "+1-512-555-0142",
     "website": "https://example.com/northgate", "opening_hours": {"mon": "7-19"},
     "price_range": "$$", "attributes": ["Accepts new patients"], "images": ["b.jpg"]},
    {"title": "Bright Smile Clinic", "review_count": 86, "review_rating": 4.9,
     "all_categories": ["Dentist"], "phone": "+1-512-555-0177",
     "website": "https://example.com/bright", "opening_hours": {"mon": "9-16"},
     "images": ["c.jpg"]},
    {"title": "Riverbend Dental Care", "review_count": 640, "review_rating": 4.1,
     "all_categories": ["Dentist", "Teeth whitening service"], "phone": "+1-512-555-0193",
     "opening_hours": {"mon": "8-16"}, "attributes": ["Walk-ins welcome"], "images": ["d.jpg"]},
    {"title": "Emergency Dentist 24h", "review_count": 205, "review_rating": 3.8,
     "all_categories": ["Emergency dental clinic"], "phone": "+1-512-555-0166",
     "attributes": ["Open 24 hours"]},
]

if __name__ == "__main__":
    use_sample = os.environ.get("USE_SAMPLE", "1") == "1"
    market = SAMPLE if use_sample else fetch_places("dentist", "Austin, TX")
    for row in score_market(market, "Dentist"):
        print(json.dumps(row))
Enter fullscreen mode Exit fullscreen mode

Two behaviours are worth keeping when you adapt this. The retry loop backs off instead of hammering a failing endpoint, and _value treats empty strings, empty lists, and nulls the same way — because a scraper that returns "" for a missing website will otherwise inflate the completeness score.

What the output looks like

Running the sample prints one JSON object per location, already ranked:

{"name": "Northgate Family Dental", "review_count": 1180, "review_rating": 4.4, "share_pct": 46.8, "rating_gap": 0.02, "completeness_pct": 100, "category_match": true, "score": 91.0}
{"name": "Lakeside Dental Studio", "review_count": 412, "review_rating": 4.7, "share_pct": 16.3, "rating_gap": 0.32, "completeness_pct": 100, "category_match": true, "score": 69.5}
{"name": "Riverbend Dental Care", "review_count": 640, "review_rating": 4.1, "share_pct": 25.4, "rating_gap": -0.28, "completeness_pct": 67, "category_match": true, "score": 61.5}
{"name": "Bright Smile Clinic", "review_count": 86, "review_rating": 4.9, "share_pct": 3.4, "rating_gap": 0.52, "completeness_pct": 67, "category_match": true, "score": 54.7}
{"name": "Emergency Dentist 24h", "review_count": 205, "review_rating": 3.8, "share_pct": 8.1, "rating_gap": -0.58, "completeness_pct": 33, "category_match": false, "score": 25.6}
Enter fullscreen mode Exit fullscreen mode

Read in a client meeting, that table says something specific. Northgate wins on volume, not quality — its rating is barely above market average. Bright Smile has the best rating in the market and almost no share of voice, which makes review generation the fix, not reputation repair. Emergency Dentist 24h is invisible for the "Dentist" query because its categories never include that term.

Metric What it answers Typical fix
Share of local voice Are we outnumbered on social proof? Review request campaign, post-visit QR, email follow-up
Rating gap Are we below market expectation? Service recovery, response to negative reviews
Category match Are we eligible for the query? Add the service category the query implies
Listing completeness Does the profile look trustworthy? Fill hours, price range, attributes, photos
Hygiene flags Is the listing healthy at all? Merge duplicates, remove closed locations, fix hours

Where this fits in an agency workflow

Monthly retainer reporting. Run the audit on the first business day, diff against last month, and lead the report with share-of-voice movement. It is the one local metric clients understand without a glossary.

Franchise operations. Score every location on the same query and compare. Corporate can see which franchisees are behind on photos and hours without asking them to fill in a form.

Pre-sales. Audit a prospect's market before the pitch. Naming the exact competitor holding 46% of review share is a stronger opening than a generic deck.

Multi-market expansion. Run the same keyword across candidate cities. Markets where the top listing has 90 reviews are cheaper to enter than markets where the leader has 2,000.

Manual, scripted, or platform

Approach Setup Cost driver Best for Weak point
Manual copy-paste None Analyst hours One location, one-off Not repeatable, drifts within days
Script + API API key, ~1 hour Per-result requests Agencies, 10–500 locations You own retries, storage, schema
Ready-made worker Account, no code Per-run or per-result Teams without engineers Less control over field selection
Full SEO platform Subscription Seat-based Enterprise reporting suites Local listing fields are summarised, not raw

For teams that want the script without maintaining the fetch layer, the ready-made Google Maps workers in the CoreClaw store cover listing and lead data, and the same fields feed the scoring function above unchanged.

Limits and compliance

Review data is not available for every merchant. Google Maps coverage varies by region, category, and how recently a listing was claimed, so a review_count of zero may mean "no reviews" or "not exposed in this response" — check fetch_reviews settings and coverage notes before drawing conclusions.

Rankings are personal and unstable. Google tailors results by location, device, language, and history. Treat search_rank from a single query as a snapshot of one market view, not an absolute position.

Keep the scope to public business listings. Do not collect reviewer personal data you do not need, do not republish review text with names attached, and do not build profiles of individuals from review activity. Respect the target site's terms, applicable privacy law, and robots directives where they apply. This workflow does not involve bypassing access controls, evading CAPTCHAs, or accessing non-public data, and it should not be extended to do so.

Finally, the score is a prioritisation tool, not a ranking predictor. A high score correlates with visibility; it does not guarantee it, and Google's local algorithm weighs signals this audit cannot see.

FAQ

Is there an official Google Maps API for this data?
Google publishes the Places API, which returns place details under Google's own terms, quotas, and pricing. Verify current limits on Google's documentation before designing around them. A managed scraper is a different trade-off: less contractual control over coverage, but no per-field API negotiation and no Google Cloud billing setup.

Which fields matter most if I can only collect a few?
review_count, review_rating, primary_category, and all_categories. Those four drive three of the five metrics. Add opening_hours and website for completeness scoring.

How often should the audit run?
Monthly for client reporting, weekly only if you are actively testing listing changes. Review counts move slowly; running daily adds noise and cost without adding insight.

Can this handle 200 locations?
Yes, with queueing. One request per location-keyword pair, a bounded worker pool, and raw JSON written to storage before scoring. Cap concurrency so a single endpoint failure does not cascade, and log the request parameters with each run.

Should I pull review text too?
Only if you need qualitative themes, and only when review coverage is documented for that merchant. Review fetching is typically off by default and costs more. If you do store text, strip reviewer names and keep only rating, date, and the content you need.

How do I present the score to a non-technical client?
Show the table, then three actions. Clients do not need the weighting formula; they need to know that adding the missing service category and 40 reviews moves them above the business currently sitting third.

Does a higher score mean higher rankings?
No. It means the listing is better positioned on the signals the audit measures. Rankings also depend on proximity, relevance, prominence, and behaviour the audit does not observe.

Next step

Pick one market, run the sample to confirm the output shape, then point CORECLAW_MAPS_ENDPOINT at the Google Maps worker in your account. If you would rather build a custom scoring worker with your own weighting and output schema, start from CoreClaw Workers and keep the fetch and score steps separate. For the field-level reference behind these metrics, see the CoreClaw Google Maps scraper documentation.

Related reading: ready-made scrapers for local business data and the Google Maps lead-generation workflow.

Top comments (0)