Local Falcon

Retrieves Google's own performance metrics for a connected profile: impressions, calls, website clicks, direction requests and similar, per day. This is Google-reported engagement data, distinct from Local Falcon scan rankings (ARP/ATRP/SoLV) — use it to connect visibility changes to real customer actions.

getLocalFalconGbpPerformanceMetrics

Retrieves the live Google Business Profile for a connected location as Local Falcon holds it: name, address, phone, categories, hours, website and open status. Reads from Google at request time, so it reflects the profile right now rather than the last scan. NOTE: this endpoint returns Google's own resource, so its field names are camelCase, unlike the snake_case used by other Local Falcon endpoints. Only works for OAuth-connected locations.

getLocalFalconGbpProfile

Retrieves the Google verification state of a connected business profile. Unverified or suspended profiles rank poorly or not at all, so check this first when a location has unexpectedly high ARP or has disappeared from results.

getLocalFalconGbpVerificationStatus

Retrieves a specific keyword report aggregating scan data across multiple locations for one keyword. Shows which locations perform best/worst for that keyword. STRONGLY RECOMMEND fieldmask — keyword reports aggregating many locations can grow large. Recommended fieldmask: 'report_key,last_date,keyword,location_count,locations.*.place_id,locations.*.name,locations.*.arp,locations.*.atrp,locations.*.solv'. Get the report_key from listLocalFalconKeywordReports.

getLocalFalconKeywordReport

Retrieves the complete content of a specific Local Falcon Knowledge Base article, including full step-by-step instructions in markdown format. Use this AFTER searchLocalFalconKnowledgeBase to get the full guide for a specific article. If the user references an article by number (e.g. 'KB70', 'article 70', '#70'), strip any prefix and pass just the numeric ID. This is the tool that gives you the actual detailed instructions, walkthroughs, and explanations — the search tool only returns summaries.

getLocalFalconKnowledgeBaseArticle

Retrieves a specific location report aggregating scan data across multiple keywords for one business location. Shows which keywords perform best/worst for that location. STRONGLY RECOMMEND fieldmask — location reports aggregating many keywords can grow large. Recommended fieldmask: 'report_key,last_date,place_id,location.name,location.address,keyword_count,keywords.*.keyword,keywords.*.arp,keywords.*.atrp,keywords.*.solv'. Get the report_key from listLocalFalconLocationReports.

getLocalFalconLocationReport

Retrieves a specific Reviews Analysis report with full metrics: Review Volume Score (RVS), Review Quality Score (RQS), review velocity, freshness, total reviews, rating analysis, response rates, Local Guide reviews, photo reviews, and sentiment/topic analysis. Includes competitor comparison data if competitors were configured. STRONGLY RECOMMEND fieldmask — review reports can exceed 100KB given sentiment/topic breakdowns across up to 1M reviews. Recommended fieldmask for overview: 'reviews_key,name,review_date,locations,frequency,statistics.metrics.primaryBusiness'. For competitor comparison add 'statistics.metrics.competitors'; for sentiment detail add 'statistics.sentiment'. Get the report key from listLocalFalconReviewsAnalysisReports.

getLocalFalconReviewsAnalysisReport

Retrieves a specific scan report by report_key. Returns full ranking data, competitor summary, grid visualization images, and AI analysis. **STRONGLY RECOMMEND** passing a fieldmask on every call. Without one, a single scan report is typically 100-300KB (grid-3 ~112KB, denser markets up to ~300KB), which can overflow LLM context windows. Size hints: `places` is the largest single field (~50KB on competitive verticals, 100+ entries each); `sources` on AI scans is ~5-15KB (citation list); `ai_analysis.summary` alone is ~2KB of HTML-bearing prose and is almost always the right surgical fieldmask for narrative-only analysis. Always strip `data_points` (stripped by default) unless per-grid-point data is specifically requested. **Response shape is platform-specific — pick the recipe that matches your scan's platform:** - Maps scans (`platform: google` or `apple`) return top-level `solv` plus an `insights` object containing: - `insights.solv_competitors.{total, active}` — total competitors considered vs how many are actually in the grid - `insights.osolv.{yours, top}` — your SoLV vs the top competitor's SoLV (opportunity-gap signal) - `insights.solv_distance.{yours, average}` — distance metric around top-3 rankings - Per-place metadata includes rating, reviews, phone, url, categories, store_code - AI scans (`platform: chatgpt`, `gemini`, `aimode`, `gaio`, `grok`) return top-level `saiv` instead of `solv`, a `sources` array (AI-platform citations), `ai_place_id`, and `bps`. No `insights` object on AI. Per-place metadata is leaner (no rating/reviews/phone). - `unique_competitors` is universal on both platform groups. - `rankings` keys mirror the top-level metric: `by_solv` on Maps, `by_saiv` on AI; `by_arp` and `by_atrp` on both. **Recommended fieldmask for Maps analysis:** `report_key,date,place_id,platform,keyword,location,lat,lng,grid_size,radius,measurement,arp,atrp,solv,found_in,unique_competitors,insights.solv_competitors.total,insights.solv_competitors.active,ai_analysis.summary,image,heatmap` **Recommended fieldmask for AI analysis:** `report_key,date,place_id,ai_place_id,platform,keyword,location,arp,atrp,saiv,found_in,unique_competitors,sources,ai_analysis.summary,image,heatmap` **About `ai_analysis`:** this is a STRUCTURED OBJECT, not an HTML string. Shape: `{summary, problem: {major[], minor[]}, success: {major[], minor[]}, vulnerable[], competitors, citations[]}`. The `summary` field is a string (HTML-bearing). If you only need the narrative, fieldmask `ai_analysis.summary`; if you need the structured breakdown, fieldmask the whole `ai_analysis` object. **Note on list-vs-get asymmetry:** `listLocalFalconScanReports` returns the visibility metric polymorphically as `solv` regardless of platform (listing convenience). `getLocalFalconReport` is platform-explicit — request `solv` on Maps or `saiv` on AI; the wrong field will simply be absent from the response. Requires a report_key from listLocalFalconScanReports. Cannot create new reports — use runLocalFalconScan for that.

getLocalFalconReport

Retrieves a specific trend report showing historical ARP, ATRP, and SoLV changes across multiple scan dates for one location + one keyword. Returns: scans array (historical snapshots with date, ARP, ATRP, SoLV, grid images per scan), locations array (competitor leaderboard with aggregated metrics across all scans), location object (full GBP profile of the target business), and top-level metadata (keyword, grid config, PDF link). Heavy nested data (data_points, per-scan locations) is automatically stripped to save context. **STRONGLY RECOMMEND** fieldmask — trend reports with many historical scans can grow large (scans[] array scales with snapshot count). **Recommended fieldmask (Maps-platform trend reports):** "last_date,keyword,location.name,scan_count,scans.*.date,scans.*.arp,scans.*.atrp,scans.*.solv" **Recommended fieldmask (AI-platform trend reports):** swap `scans.*.solv` for `scans.*.saiv`. Get the report_key from listLocalFalconTrendReports.

getLocalFalconTrendReport

Lists campaign reports in the account. Campaigns are the primary method for scheduled, recurring scans across multiple locations and/or keywords. Can be configured as: single location + single keyword, multiple locations + single keyword, single location + multiple keywords, or multiple locations + multiple keywords. Campaign scans consolidate all data in the campaign report — no separate location/keyword/trend reports are generated. Use fieldmask to control returned fields. Recommended fieldmask: "report_key,name,status,locations,keywords,frequency,last_run,next_run,arp,atrp,solv,arp_move,atrp_move,solv_move".

listLocalFalconCampaignReports

Lists competitor analysis reports. One is AUTO-GENERATED with every scan, showing top-ranking businesses in the scanned area. Filter by placeId, keyword, date range, or grid size. Use fieldmask to control returned fields. Recommended fieldmask: "report_key,date,keyword,location.name,grid_size,platform".

getLocalFalconCompetitorReports

Lists locations monitored by Falcon Guard. Guard monitors Google Business Profiles for unwanted changes, checking twice daily. Availability depends on existing account entitlements. OAuth-connected locations include enhanced metrics: calls, website clicks, directions, impressions (up to 18 months historical). Non-OAuth locations only show GBP change history. Use fieldmask to control returned fields. Recommended fieldmask: "report_key,place_id,location.name,location.address,location.rating,location.reviews,status,date_added,date_last". Filter by date range or status (protected/paused).

listLocalFalconGuardReports

Lists the action links (booking, ordering, appointment buttons) on a connected business profile. Use getLocalFalconGbpAvailableActionTypes to see which link types the profile supports.

listLocalFalconGbpActionLinks

Lists photos and videos uploaded by CUSTOMERS to a connected Google Business Profile, as opposed to the owner's own uploads. Customer media cannot be deleted through the API — only reported to Google directly.

listLocalFalconGbpCustomerMedia

Lists photos and videos the business has uploaded to its connected Google Business Profile. Filter by category (e.g. INTERIOR, EXTERIOR, LOGO, COVER) or pass mediaId for a single item. For photos uploaded by customers, use listLocalFalconGbpCustomerMedia instead.

listLocalFalconGbpMedia

Lists Google Business Profile posts (updates, events, offers, alerts) for a connected location. Pass postId to fetch a single post.

listLocalFalconGbpPosts

Lists Google reviews for one or more connected locations, including any owner replies. Set unanswered to true to find reviews still needing a response, or filter by star rating. Distinct from the Reviews Analysis report tools, which return Local Falcon's AI analysis rather than the live review list.

listLocalFalconGbpReviews

Lists the services listed on a connected business profile, with descriptions and prices. Services influence which queries a profile surfaces for, so review these when diagnosing weak keyword coverage.

listLocalFalconGbpServices

Lists keyword reports that aggregate scan data across multiple locations for a specific keyword. AUTO-GENERATED after a keyword has been scanned for 2+ different locations outside of campaigns. NOT generated for campaign scans. Useful for comparing how different locations perform for the same keyword. Use fieldmask to control returned fields.

listLocalFalconKeywordReports

Lists all location groups in the Local Falcon account, including the number of locations and the Place IDs contained in each group. Groups may be nested: a group with type 'child' includes a 'parent' object identifying its containing group by key and name, while top-level groups have type 'parent'. Use this to discover how saved locations are organized into groups (e.g. by region or brand) and to pull the Place IDs belonging to a group.

listLocalFalconLocationGroups

Lists location reports that aggregate scan data across multiple keywords for a specific business location. AUTO-GENERATED after a location has been scanned for 2+ different keywords outside of campaigns. NOT generated for campaign scans. Useful for seeing how a location performs across its keyword portfolio. Use fieldmask to control returned fields.

listLocalFalconLocationReports

Lists Reviews Analysis reports in the account. These are existing AI-powered review analyses that evaluate up to 1M Google reviews for a target business plus up to 3 competitors. Separate from ranking scan reports. Filter by placeId, frequency, or reviewsKey. Use fieldmask to control returned fields. Recommended fieldmask: "reviews_key,name,review_date,locations,frequency,statistics.metrics.primaryBusiness". Use getLocalFalconReviewsAnalysisReport with a report key to see full results.

listLocalFalconReviewsAnalysisReports

Lists all business locations already configured in the Local Falcon account. Check here BEFORE searching for a business - if the business is already in the account, you'll get the Place ID instantly without needing to search Google. Saves time and ensures consistency with previous scans.

listAllLocalFalconLocations

Lists existing scan reports. ALWAYS check here before running new scans to avoid duplicates and save credits. Returns report metadata including date, keyword, location, ARP, ATRP, SoLV, grid size, and platform. Use filters to narrow results. If a report has a campaign_key, its data is consolidated in the campaign report — no separate trend/location/keyword reports exist for campaign scans. Use fieldmask to control returned fields. Recommended fieldmask for browsing: "report_key,date,keyword,location.name,arp,atrp,solv,grid_size,platform". Returns limited results per page; use nextToken for pagination.

listLocalFalconScanReports

Lists ONLY individually scheduled automatic scans. NOTE: This does NOT include campaign-scheduled scans, which are the more common way to schedule recurring scans. To see campaign schedules, use listLocalFalconCampaignReports instead. Most users schedule scans through campaigns for better organization and reporting.

listLocalFalconAutoScans

Lists trend reports showing ranking changes over time. These are AUTO-GENERATED when 2+ scans are run with IDENTICAL settings (same Place ID, keyword, coordinates, grid size, radius, platform). Each trend report tracks one location + one keyword combination. Requires at least 2 matching scans to exist. NOT generated for campaign scans — that historical data is in the campaign report. Use fieldmask to control returned fields. Recommended fieldmask: "report_key,last_date,keyword,location.name,location.address,scan_count,arp,arp_move,atrp,atrp_move,solv,solv_move". Filter by placeId, keyword, platform, or date range.

listLocalFalconTrendReports

Adds, updates or removes action links (booking, ordering, appointment buttons) on a connected Google Business Profile. WRITES LIVE TO GOOGLE — always confirm with the user first. action='create' needs actionType; action='update' and action='delete' need linkId. Call getLocalFalconGbpAvailableActionTypes first to get a valid actionType, and listLocalFalconGbpActionLinks for linkId values.

manageLocalFalconGbpActionLinks

Adds, recategorises or deletes owner media on a connected Google Business Profile. WRITES LIVE TO GOOGLE — always confirm with the user first. action='create' needs mediaFormat, sourceUrl and category; action='update' needs mediaId and category (and cannot set COVER or PROFILE); action='delete' needs mediaId and permanently removes the item. Customer-uploaded media cannot be modified — see listLocalFalconGbpCustomerMedia.

manageLocalFalconGbpMedia

Creates, updates or deletes a post on a connected Google Business Profile. WRITES LIVE TO GOOGLE — always confirm with the user first. action='create' needs summary (and event/offer when topicType is EVENT/OFFER); action='update' needs postId; action='delete' needs postId and permanently removes the post. Use listLocalFalconGbpPosts to find postId values.

manageLocalFalconGbpPosts

Publishes or deletes owner replies to Google reviews on connected locations. WRITES LIVE TO GOOGLE and replies are publicly visible — always confirm the exact wording with the user first. action='reply' either replies to one review (reviewId + reply) or to up to 50 at once (replies array); action='delete' removes an existing reply from reviewId. Use listLocalFalconGbpReviews with unanswered=true to find reviews needing a response.

manageLocalFalconGbpReviewReplies

Adds, removes or wholesale-replaces the services on a connected Google Business Profile. WRITES LIVE TO GOOGLE — always confirm with the user first. action='add' appends services; action='remove' deletes the named services; action='replace' overwrites the ENTIRE service list, so anything omitted is removed — read listLocalFalconGbpServices first and only use 'replace' when the user explicitly wants a full rewrite.

manageLocalFalconGbpServices

Pauses a campaign to stop it from running on its scheduled frequency. Use listLocalFalconCampaignReports to find the campaign_key for the campaign you want to pause.

pauseLocalFalconCampaign

Pauses protection for one or multiple locations in Falcon Guard. You must provide either guardKey or placeId (or both). Use listLocalFalconGuardReports to find guard_key values for protected locations.

pauseFalconGuardProtection

Reactivates a campaign that was deactivated due to insufficient credits. Use listLocalFalconCampaignReports to find the campaign_key for the campaign you want to reactivate.

reactivateLocalFalconCampaign

Removes protection for one or multiple locations from Falcon Guard entirely. This deletes the Guard monitoring for the specified locations. You must provide either guardKey or placeId (or both). Use listLocalFalconGuardReports to find guard_key values.

removeFalconGuardProtection

Resumes a campaign from a deactivated or paused status. Use listLocalFalconCampaignReports to find the campaign_key for the campaign you want to resume.

resumeLocalFalconCampaign

Resumes protection for one or multiple locations in Falcon Guard that were previously paused. You must provide either guardKey or placeId (or both). Use listLocalFalconGuardReports to find guard_key values for paused locations.

resumeFalconGuardProtection

Manually triggers a campaign to run immediately. COSTS CREDITS — the total credits required will be checked against your available credits. Use listLocalFalconCampaignReports to find the campaign_key for the campaign you want to run. IMPORTANT: Campaign runs trigger multiple scans and can take minutes to hours to complete depending on the number of locations and keywords. If the response says 'success: true' with a 'Campaign run submitted successfully' message, this is EXPECTED — the campaign is processing normally. Do NOT treat this as an error. Follow up with listLocalFalconCampaignReports or listLocalFalconScanReports to check for completed results. NEVER retry runLocalFalconCampaign — retrying would consume additional credits. If results are not found after 4-5 polling attempts, stop polling and tell the user: their campaign is still processing (large campaigns can take hours) and they can check https://www.localfalcon.com/reports for results, or come back and ask again later.

runLocalFalconCampaign

Runs a new ranking scan for a business. USES EXISTING CREDITS — make settings and credit use clear before execution. Obtain confirmation only if the user has not already explicitly approved this operation and settings; do not require a redundant second confirmation. Requires: Place ID (business must be saved first), keyword, center coordinates (lat/lng), grid size, radius, measurement unit, and platform. Available platforms: google (Maps), apple (Apple Maps), gaio (Google AI Overviews), chatgpt (ChatGPT), gemini (Gemini), aimode (Google AI Mode). Enable aiAnalysis for AI-generated insights on the results (Google Maps only). Grid size and radius should match the business type and service area. IMPORTANT: Scans take 30 seconds to several minutes to complete depending on grid size and queue load. If the response says 'success: true' with a 'Scan submitted successfully' message, this is EXPECTED — the scan is processing normally. Do NOT treat this as an error or timeout. Immediately follow up with listLocalFalconScanReports (filter by the same placeId) to find the completed report. NEVER retry runLocalFalconScan — the scan is already queued and retrying would consume additional credits. If the report is not found after 4-5 polling attempts, stop polling and tell the user: their scan is still processing and they can check https://www.localfalcon.com/reports for results, or ask again in a few minutes.

runLocalFalconScan

Saves a business location to your Local Falcon account. This is required to run a scan if it doesn't exist in your account.

saveLocalFalconBusinessLocationToAccount