Locations Metrics & Local SEO Geo-Grid API

Use these endpoints to feed store-level local search visibility, customer actions, and Geo-Grid competitor rankings into PowerBI, Looker Studio, Snowflake, or BigQuery.

1. Store & Location Performance Metrics (GET /api/v1/reports/locations/metrics)

Endpoint: GET https://profilepilotapp.com/api/v1/reports/locations/metrics Required Scope: reports:read or locations:read Required Product Subscription: Locations & Reputation + Developer API Access

Query Parameters:

• startDate (YYYY-MM-DD, optional) — Start of reporting window (defaults to 30 days ago UTC).
• endDate (YYYY-MM-DD, optional) — End of reporting window (defaults to today UTC; clamped to 366 days max).
• storeCode or store_code (string, optional) — Filter Google, Facebook, and Instagram location records to a single branch store_code.
• platform ("all" | "google" | "meta", optional, default "all") — Restrict daily metric aggregation to Google Business Profile ("google"), Meta Facebook/Instagram ("meta"), or both ("all").

Performance Metrics & Response Fields:

• period — { startDate, endDate } UTC date range evaluated.
• footprint — Connected location counts across channels: google_locations, meta_locations, instagram_locations, bing_locations, and enterprise_store_locations (submitted master stores).
• google_totals — Organisation-wide Google Business Profile sums across the period:
• impressions (number) — Total listing views across Search and Maps (desktop + mobile).
• maps_impressions (number) — Combined BUSINESS_IMPRESSIONS_DESKTOP_MAPS + BUSINESS_IMPRESSIONS_MOBILE_MAPS.
• search_impressions (number) — Combined BUSINESS_IMPRESSIONS_DESKTOP_SEARCH + BUSINESS_IMPRESSIONS_MOBILE_SEARCH.
• website_clicks (number), call_clicks (number), direction_requests (number), booking_clicks (number), messages (number).
• engagement (number) — website_clicks + call_clicks + direction_requests.
• leads (number) — call_clicks + booking_clicks + messages.
• total_interactions (number) — engagement + booking_clicks + messages.
• meta_totals — Organisation-wide Meta location sums:
• facebook: { reach, post_engagements, page_views, total_fans }.
• instagram: { impressions, reach, followers }.
• stores[] — Per-location breakdown sorted by impressions descending:
• store_code (string | null), name (string humanized display name), google_location_id (string), account_id (string | null), status ("open" | "temporarily_closed" | "closed").
• impressions, maps_impressions, search_impressions, website_clicks, call_clicks, direction_requests, booking_clicks, messages, engagement, leads, total_interactions (number).
• peak_days (string) — Top weekday(s) for customer direction requests (e.g. "Sat & Fri" or "—" when no direction requests occurred).
• meta — { org_id, api_usage: { month, used, limit, remaining } }.

2. Local SEO Geo-Grid & Share of Voice (GET /api/v1/reports/seo-grid)

Endpoint: GET https://profilepilotapp.com/api/v1/reports/seo-grid Required Scope: reports:read Required Product Subscription: Locations & Reputation + Developer API Access

Query Parameters:

• gridId or grid_id (UUID, optional) — Inspect a specific Geo-Grid configuration (defaults to the organisation’s most recently scanned grid).
• scanId or scan_id (UUID, optional) — Inspect a specific historical scan snapshot (defaults to the latest successful scan).
• leaderboardLimit (number, optional, 5–40, default 20) — Maximum competitors returned in leaderboard[].

Performance Metrics & Response Fields:

• grids[] — List of configured Geo-Grids in the organisation (id, name, location_id, center_lat, center_lng, rows, cols, spacing_m, keyword, schedule_frequency, schedule_next_run_at, created_at).
• empty (boolean) & empty_reason (string | null) — true if no completed Geo-Grid scan exists yet.
• scan — Metadata for the evaluated scan: { scanId, gridId, gridName, keyword, scannedAt, pointsBilled, totalPoints, pointsWithResults }.
• tracked_place_id (string | null) — Google place_id matched to your tracked store.
• your_avg_rank (number | null) — Your average SERP pack position across all grid pins where your store appeared (1.0 is #1 on every pin).
• your_best_rank (number | null) — Highest rank achieved across any pin in the scan.
• your_pin_visibility_pct (number | null) — Percentage of grid coordinate pins where your business appeared in the local pack (appearances / pointsWithResults × 100).
• sov_pct (number | null) — Your rank-weighted Share of Voice % across the grid (Rank 1 carries weight 20, Rank 20 carries weight 1, matching Mission Control and Executive Reports).
• leaderboard[] — Top competitors ranked by Share of Voice ({ placeId, name, appearances, pinVisibilityPct, shareOfVoicePct, avgRank, bestRank, avgRating, maxReviews, isYou }).
• benchmark[] — Normalized 0–100 multi-axis competitor benchmark comparison for the top 5 pack leaders + your tracked listing.

3. Troubleshooting & Common Scenarios

• `peak_days` returns `"—"`: Peak days are computed from daily BUSINESS_DIRECTION_REQUESTS buckets across the selected startDate..endDate. If a store had zero direction requests in that window, "—" is returned.
• Difference between `your_pin_visibility_pct` and `sov_pct`: Pin visibility measures presence anywhere in the top 20 results on a coordinate pin, whereas sov_pct weights each pin by rank (21 - rank) against all competitors in the grid.
• `empty: true` on `/api/v1/reports/seo-grid`: Either no Geo-Grid has been created under Competitor Analysis → Local SEO Grid or the first scan has not completed yet (empty_reason explains which).