# Local Falcon API — Complete Guide Content

> Local Falcon is an AI Visibility and local SEO platform. Track and improve business visibility across AI search platforms (ChatGPT, Gemini, Grok, Google AI Overviews, AI Mode) and in local search (Google Maps, Apple Maps).
> This file contains the full text of all Local Falcon API guides in a single document.
> Fetch this one file instead of scraping individual guide pages.
> Source: https://docs.localfalcon.com/guides/
> OpenAPI spec: https://docs.localfalcon.com/openapi.yaml
> MCP Connector: https://github.com/local-falcon/mcp

---

## Getting Started — Your First Scan in 5 Minutes

URL: https://docs.localfalcon.com/guides/getting-started

Go from zero to your first scan result. Find a business, save it, run a scan, and retrieve the report.

### Step 1: Get Your API Key

Log in to the Local Falcon dashboard and navigate to Settings → API to copy your API key.

https://www.localfalcon.com/settings/api

### Step 2: Search for a Business

Find the business you want to scan. Grab the `place_id` from the matching result.

```bash
curl -X POST "https://api.localfalcon.com/v2/locations/search" \
  -d "api_key=YOUR_API_KEY" \
  -d "term=Joe's Coffee Shop" \
  -d "platform=google" \
  -d "proximity=Austin, TX"
```

The response contains an array of matching businesses. Copy the `place_id` of the correct match.

### Step 3: Save the Location

A business must be saved to your account before you can scan it.

```bash
curl -X POST "https://api.localfalcon.com/v2/locations/add" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "platform=google"
```

The response confirms the location was saved and returns its details, including `lat` and `lng`.

### Step 4: Run a Scan

Submit a ranking scan for your saved location with a keyword, grid size, and radius.

```bash
curl -X POST "https://api.localfalcon.com/v2/run-scan/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "keyword=coffee shop" \
  -d "lat=30.2672" \
  -d "lng=-97.7431" \
  -d "gridSize=7" \
  -d "radius=3" \
  -d "measurement=mi" \
  -d "platform=google"
```

> WARNING: Running a scan costs credits. A 7×7 grid uses 49 scan points.

A `success: true` response means the scan was submitted. Scans take 30 seconds to several minutes to complete.

### Step 5: Check for the Completed Report

List your scan reports and filter by `placeId` to find the completed scan.

```bash
curl -X POST "https://api.localfalcon.com/v1/reports/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "fieldmask=report_key,date,keyword,location.name,arp,atrp,solv"
```

Poll this endpoint until your report appears. Copy the `report_key` from the result. **Never retry `run-scan`** — the scan is already queued and retrying would consume additional credits.

### Step 6: Retrieve the Full Report

Fetch the complete scan report using the `report_key` and a fieldmask for analysis data.

```bash
curl -X POST "https://api.localfalcon.com/v1/reports/YOUR_REPORT_KEY/" \
  -d "api_key=YOUR_API_KEY" \
  -d "fieldmask=report_key,date,place_id,keyword,location,arp,atrp,solv,found_in,total_competitors,competition_solv,max_solv,opportunity_solv,grid_size,radius,measurement,ai_analysis,image,heatmap"
```

The response includes ranking metrics (ARP, ATRP, SoLV), competitor data, grid images, and AI analysis text.

### Analysis Fieldmask

```
report_key,date,place_id,keyword,location,arp,atrp,solv,found_in,total_competitors,competition_solv,max_solv,opportunity_solv,grid_size,radius,measurement,ai_analysis,image,heatmap
```

> TIP: Use the `lat` and `lng` from the saved location as the center point of your scan grid. This ensures the grid is centered on the business.

---

## Metrics — Understanding Local Falcon Metrics

URL: https://docs.localfalcon.com/guides/metrics

What ARP, ATRP, SoLV, and other ranking metrics mean and how to interpret them.

### Quick Reference

| Metric | Full Name | Scale | What It Means |
|--------|-----------|-------|---------------|
| `arp` | Average Rank Position | 1–20+ | Average ranking across all grid points. Lower is better. 1.0 = #1 everywhere. |
| `atrp` | Average Top Rank Position | 1–20+ | Average of the best ranking at each grid point. Shows your peak performance. |
| `solv` | Share of Local Voice | 0–100% | Your share of visibility in local search results. Higher is better. |
| `saiv` | Share of AI Voice | 0–100% | Your visibility in AI platform results (ChatGPT, Gemini, etc.). AI equivalent of SoLV. |
| `found_in` | Found In | 0 to grid points | Number of grid points where your business appeared in results. |

### Core Metrics Explained

**ARP — Average Rank Position**: Calculated across all grid points in a scan. A score of 1 is the best possible (ranked #1 at every point); 20+ means not found. A score of 3.5 means you average position 3–4 across the grid. For local businesses, under 5.0 is strong.

**ATRP — Average Top Rank Position**: Similar to ARP but only considers the top (best) rank at each grid point. ATRP shows your ceiling — how well you perform in your strongest areas.

**SoLV — Share of Local Voice**: A percentage of local search visibility you own. 100% means you rank #1 at every grid point. 50% means you have half the possible visibility. Think of it as your market share of local search.

**SAIV — Share of AI Voice**: Same concept as SoLV but for AI platforms (Google AI Overviews, ChatGPT, Gemini, Grok, etc.). Measures how often AI recommends your business. Used in place of SoLV for AI-platform scans.

**`found_in`**: Raw count of grid points where your business appeared. On a 7×7 grid (49 points), `found_in=35` means you appeared in 71% of the scanned area.

### Competitive Metrics

These fields appear in scan reports and competitor reports.

| Metric | Description |
|--------|-------------|
| `competition_solv` | Aggregate SoLV held by all competitors combined. |
| `max_solv` | Theoretical maximum SoLV (the ceiling). |
| `opportunity_solv` | Gap between your current SoLV and `max_solv` — your growth potential. |
| `total_competitors` | Number of unique competitors found across all grid points. |

### Movement Metrics

Movement metrics track changes between consecutive scans.

| Metric | Description |
|--------|-------------|
| `arp_move` | Change in ARP since previous scan. Negative = improved (moved up). |
| `atrp_move` | Change in ATRP since previous scan. |
| `solv_move` | Change in SoLV since previous scan. Positive = improved (gained share). |

> TIP: Movement metrics appear in trend reports and campaign reports. They compare the latest scan to the previous one.

### Reviews Analysis Metrics

| Metric | Description |
|--------|-------------|
| `RVS` | Review Volume Score — quantitative measure of review volume. |
| `RQS` | Review Quality Score — qualitative measure of review quality. |

> WARNING: Reviews Analysis is a separate premium feature ($19/location) that evaluates up to 1M Google reviews for a target business plus up to 3 competitors.

### Recommended Fieldmask for Scan Report with All Metrics

```
report_key,date,keyword,location,arp,atrp,solv,found_in,total_competitors,competition_solv,max_solv,opportunity_solv
```

---

## Grid Configuration — Grid Size & Radius

URL: https://docs.localfalcon.com/guides/grid-configuration

Choose the right grid size and radius to match your business's service area.

### Grid Sizes

The `gridSize` parameter sets the number of scan points along each edge of the grid. A 7×7 grid creates a 7-row by 7-column pattern of 49 scan points.

| Grid Size | Grid Points | Typical Use Case |
|-----------|-------------|------------------|
| 3×3 | 9 | Quick spot-check. Minimal coverage, fast results. |
| 5×5 | 25 | Small service area or neighborhood business. |
| 7×7 | 49 | **Recommended default.** Good balance of coverage and cost. |
| 9×9 | 81 | Wider coverage for medium service areas. |
| 11×11 | 121 | Large service area or detailed competitive analysis. |
| 13×13 | 169 | Comprehensive city-level coverage. |
| 15×15 | 225 | Maximum detail. Best for enterprise-level analysis. |

> TIP: Start with a 7×7 grid. You can always increase the size later for more detailed analysis.

Campaigns support extended grid sizes up to 21×21 (441 points). Individual scans via the `run-scan` endpoint support up to 15×15.

### Radius

The `radius` parameter defines the distance from the center point to the outermost edge of the grid (north, east, south, and west). A larger radius spreads scan points farther apart; a smaller radius clusters them closer together.

#### Radius Guidance by Business Type

| Business Type | Suggested Radius | Reasoning |
|---------------|------------------|-----------|
| Neighborhood (restaurant, salon) | 1–3 mi / 2–5 km | Customers walk or drive short distances. |
| Local service (plumber, electrician) | 5–10 mi / 8–16 km | Service area covers several neighborhoods. |
| City-wide (law firm, hospital) | 10–20 mi / 16–32 km | Draws customers from across the metro area. |
| Regional (franchise, car dealer) | 20–50 mi / 32–80 km | Large coverage area, sparse population. |

Accepted range: `0.1` to `100` (miles or kilometers).

### Measurement Units

- `mi` — miles (used in the US, UK)
- `km` — kilometers (used everywhere else)

The measurement unit applies to the radius only. Grid point spacing is calculated automatically based on the radius and grid size.

### Parameter Reference

Where grid parameters are used across endpoints:

| Parameter | `run-scan` | `create campaign` | `get grid` |
|-----------|------------|-------------------|------------|
| `gridSize` | 3–15 | 3–21 | 3–15 |
| `radius` | 0.1–100 | 0.1–100 | 0.1–100 |
| `measurement` | `mi`, `km` | `mi`, `km` | `mi`, `km` |

> WARNING: Larger grids cost more credits. A 15×15 grid uses 225 scan points — over 9× more than a 5×5 grid (25 points). Choose the smallest grid that covers your business's service area.

---

## Platforms — Scan Platforms

URL: https://docs.localfalcon.com/guides/platforms

Compare the 7 platforms Local Falcon can scan — from Google Maps to AI assistants.

### Platform Overview

| Platform Code | Platform Name | What It Scans | Primary Metric | Sync Mode |
|---------------|---------------|---------------|----------------|-----------|
| `google` | Google Maps | Traditional local pack rankings | SoLV | Synchronous |
| `apple` | Apple Maps | Apple Maps business rankings | SoLV | Eager (async) |
| `gaio` | Google AI Overviews | AI Overview citations in Google | SAIV | Eager (async) |
| `chatgpt` | ChatGPT | ChatGPT business recommendations | SAIV | Eager (async) |
| `gemini` | Gemini | Gemini business recommendations | SAIV | Eager (async) |
| `grok` | Grok | Grok business recommendations | SAIV | Eager (async) |
| `aimode` | Google AI Mode | Google AI Mode results | SAIV | Eager (async) |

### Traditional vs AI Platforms

Traditional platforms (`google`, `apple`) measure local pack and map rankings using ARP, ATRP, and SoLV. AI platforms (`gaio`, `chatgpt`, `gemini`, `grok`, `aimode`) measure how often AI assistants recommend your business, using SAIV (Share of AI Voice). Running the same keyword across both platform types gives you a complete visibility picture.

### Platform-Specific Notes

**Google Maps (`google`)**: The default and most common platform. Scans run synchronously — the API waits for results before responding. Supports AI analysis (`ai_analysis=true`). Returns the full ranking grid with ARP, ATRP, and SoLV.

**Apple Maps (`apple`)**: Requires additional fields when saving a location: `name`, `lat`, `lng`. Runs in eager mode — the API returns immediately; poll for results.

**AI Platforms (`gaio`, `chatgpt`, `gemini`, `grok`, `aimode`)**: All run in eager mode — the API returns immediately. Use SAIV (Share of AI Voice) instead of SoLV.

> TIP: Run the same keyword on `google` and an AI platform to compare your traditional vs AI visibility.

### Platform Support by Endpoint

| Action | Supported Platforms |
|--------|---------------------|
| Run a scan (`POST /v2/run-scan/`) | `google`, `apple`, `gaio`, `chatgpt`, `gemini`, `grok`, `aimode` |
| Search for location (`POST /v2/locations/search`) | `google`, `apple` |
| Save a location (`POST /v2/locations/add`) | `google`, `apple` |
| Filter reports | `google`, `apple`, `gaio`, `chatgpt`, `gemini`, `grok`, `aimode` |
| On-Demand API | `google` only |

> WARNING: Non-Google platform scans run in eager mode — the API returns immediately with a success response. The scan continues processing in the background. Poll `POST /v1/reports/` to check for the completed report. Do NOT retry the scan — it would consume additional credits.

---

## Report Types — Report Types & How They Relate

URL: https://docs.localfalcon.com/guides/report-types

Every scan produces multiple report types automatically. Understand what each contains and when it appears.

### Report Hierarchy

A single `run-scan` call can generate up to five report types. Some are created immediately; others appear once enough data accumulates.

```
runLocalFalconScan
├── Scan Report          [always]
├── Competitor Report    [always]
├── Trend Report         [auto: 2+ identical scans]
├── Location Report      [auto: 2+ keywords, same location]*
└── Keyword Report       [auto: 2+ locations, same keyword]*
```

> TIP: Campaign scans consolidate all data into the Campaign Report. They do NOT generate separate Location, Keyword, or Trend reports.

### Report Types

| Report Type | Auto-Generated When | What It Contains | API Endpoint | Recommended Fieldmask |
|-------------|---------------------|------------------|--------------|----------------------|
| **Scan Report** | Every `run-scan` call | Core ranking data: ARP, ATRP, SoLV, found_in, grid visualization | `POST /v1/reports/{report_key}/` | `report_key,date,keyword,location,arp,atrp,solv,found_in,grid_size,ai_analysis,image,heatmap` |
| **Competitor Report** | Every scan (automatic) | Top-ranking businesses with ARP, ATRP, SoLV, reviews, ratings | `POST /v1/competitor-reports/{report_key}` | `date,keyword,businesses.*.name,businesses.*.arp,businesses.*.solv,businesses.*.reviews,businesses.*.rating` |
| **Trend Report** | 2+ scans with identical settings (same placeId, keyword, lat/lng, grid, radius, platform) | Historical ARP/ATRP/SoLV changes across scan dates | `POST /v1/trend-reports/{report_key}` | `report_key,last_date,keyword,location.name,scan_count,arp,arp_move,atrp,atrp_move,solv,solv_move` |
| **Location Report** | 2+ keywords scanned for same location (non-campaign only) | Aggregated performance across all keywords for one location | `POST /v1/location-reports/{report_key}` | (supports fieldmask) |
| **Keyword Report** | 2+ locations scanned for same keyword (non-campaign only) | Aggregated performance across all locations for one keyword | `POST /v1/keyword-reports/{report_key}` | (supports fieldmask) |
| **Campaign Report** | Campaign run (manual or scheduled) | Consolidated data across all locations and keywords in the campaign | `POST /v1/campaigns/{report_key}` | `report_key,name,status,locations,keywords,arp,atrp,solv,arp_move,atrp_move,solv_move,frequency,last_run,next_run` |

### Campaign vs Non-Campaign Scans

**Non-Campaign Scans**: Standalone `run-scan` calls generate reports independently:
- Scan + Competitor reports — created with every scan.
- Trend Report — auto-generated after 2+ scans with identical settings.
- Location Report — auto-generated after 2+ different keywords are scanned for the same location.
- Keyword Report — auto-generated after 2+ different locations are scanned for the same keyword.

**Campaign Scans**: Scans triggered through a campaign behave differently:
- Scan + Competitor reports — created per scan within the campaign.
- Campaign Report — consolidates all scan data across every location and keyword.
- No separate Location, Keyword, or Trend reports — that data lives in the Campaign Report.
- Scan reports from campaigns include a `campaign_key` field linking back to the parent campaign.

### Report URL Patterns

Direct links to reports on the Local Falcon dashboard:

| Report Type | URL Pattern |
|-------------|-------------|
| Scan | `/reports/view/{report_key}` |
| Competitor | `/reports/competitor/view/{report_key}` |
| Trend | `/reports/trend/view/{report_key}` |
| Location | `/reports/location/view/{report_key}` |
| Keyword | `/reports/keyword/view/{report_key}` |
| Campaign | `/campaigns/view/{report_key}` |

> WARNING: The `data_points` array is stripped by default from Scan, Competitor, and Trend reports. Only request it when you need per-grid-point ranking data. Use the `ai_analysis` field for human-readable insights instead.

---

## Fieldmasks — How Fieldmasks Work

URL: https://docs.localfalcon.com/guides/fieldmasks

Control exactly which fields the API returns. Reduce payload size and get only the data you need.

### What is a Fieldmask?

A fieldmask is a comma-separated list of field names passed as the `fieldmask` parameter in your API request. It tells the API to return only the fields you specify. Omitting the parameter returns all fields, which can result in very large responses. Use fieldmasks to reduce payload size and improve performance.

### Syntax

**Simple Fields**: List the top-level field names you need, separated by commas.

```
fieldmask=report_key,date,keyword,arp
```

**Dot Notation (Nested Fields)**: Access fields inside nested objects using dot notation.

```
fieldmask=location.name,location.address
```

**Wildcards (Arrays)**: Use `*` to select a field from every item in an array.

```
fieldmask=businesses.*.name,businesses.*.arp
```

### Per-Endpoint Recipes

Copy-paste these fieldmasks to get the right data from each endpoint without over-fetching.

| Endpoint | Use Case | Fieldmask Recipe |
|----------|----------|------------------|
| `POST /v1/reports/` | Browsing scan reports | `report_key,date,keyword,location.name,arp,atrp,solv,grid_size,platform` |
| `POST /v1/reports/{report_key}/` | Scan analysis | `report_key,date,place_id,keyword,location,arp,atrp,solv,found_in,total_competitors,competition_solv,max_solv,opportunity_solv,grid_size,radius,measurement,ai_analysis,image,heatmap` |
| `POST /v1/competitor-reports/` | Browsing competitors | `report_key,date,keyword,location.name,grid_size,platform` |
| `POST /v1/competitor-reports/{report_key}` | Competitor analysis | `date,keyword,grid_size,radius,businesses.*.name,businesses.*.place_id,businesses.*.arp,businesses.*.atrp,businesses.*.solv,businesses.*.reviews,businesses.*.rating,businesses.*.lat,businesses.*.lng` |
| `POST /v1/trend-reports/` | Browsing trends | `report_key,last_date,keyword,location.name,location.address,scan_count,arp,arp_move,atrp,atrp_move,solv,solv_move` |
| `POST /v1/campaigns/` | Browsing campaigns | `report_key,name,status,locations,keywords,frequency,last_run,next_run,arp,atrp,solv,arp_move,atrp_move,solv_move` |
| `POST /v1/campaigns/{report_key}` | Campaign overview | `report_key,name,status,locations,keywords,arp,atrp,solv,arp_move,atrp_move,solv_move,frequency,last_run,next_run` |
| `POST /v1/guard/` | Browsing Guard reports | `report_key,place_id,location.name,location.address,location.rating,location.reviews,status,date_added,date_last` |
| `POST /v1/reviews/` | Browsing Reviews | `reviews_key,name,date,locations,frequency,statistics.metrics.primaryBusiness` |

> WARNING: The `data_points` array contains ranking data for every grid coordinate and can be extremely large. It is stripped by default. Only include `data_points` in your fieldmask when you explicitly need per-grid-point data. For general analysis, use the `ai_analysis` field instead.

> TIP: Fieldmasks work alongside other request parameters like `placeId`, `keyword`, and date filters. Filter first to narrow the result set, then apply a fieldmask to trim each result down to only the fields you need.

---

## Campaigns — Campaigns vs Individual Scans

URL: https://docs.localfalcon.com/guides/campaigns

Campaigns schedule recurring scans across multiple locations and keywords. Individual scans are for one-off spot checks.

### When to Use Each

| | Individual Scan | Campaign |
|-|-----------------|----------|
| **Best for** | One-time spot checks, ad hoc analysis | Recurring monitoring, multi-location tracking |
| **Scheduling** | Manual only | One-time, daily, weekly, biweekly, monthly |
| **Locations** | One per scan | One or many |
| **Keywords** | One per scan | One or many |
| **Report output** | Separate Scan, Competitor, Trend, Location, Keyword reports | Consolidated Campaign Report (no separate Location/Keyword/Trend) |
| **Credits** | Per scan | Per scan within campaign (total checked against balance) |

### Campaign Lifecycle

#### Step 1: Verify Locations

Locations must be in your Saved Locations before they can be added to a campaign. List existing locations with:

```
POST /v1/locations/
```

If a location is not yet saved, add it with `POST /v2/locations/add` first.

#### Step 2: Create the Campaign

Endpoint: `POST /v2/campaigns/create`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Campaign name |
| `placeId` | string | Yes | Place ID(s), comma-separated for multiple |
| `keyword` | string | Yes | Keyword(s), comma-separated for multiple |
| `gridSize` | enum | Yes | 3–21 |
| `radius` | string | Yes | 0.1–100 |
| `measurement` | enum | Yes | `mi` or `km` |
| `frequency` | enum | Yes | `one-time`, `daily`, `weekly`, `biweekly`, `monthly` |
| `startDate` | string | Yes | MM/DD/YYYY |
| `startTime` | string | Yes | e.g., "9:00 AM" |

> TIP: Campaigns support grid sizes up to 21×21, larger than the 15×15 maximum for individual scans.

#### Step 3: Monitor and Manage

- **Run manually**: `POST /v2/campaigns/run` — trigger a campaign immediately
- **Pause**: `POST /v2/campaigns/pause` — stop scheduled runs
- **Resume**: `POST /v2/campaigns/resume` — restart after pause
- **Reactivate**: `POST /v2/campaigns/reactivate` — restart after credit deactivation

#### Step 4: Retrieve Results

List campaigns with a fieldmask to browse results:

```
POST /v1/campaigns/
```

Get a specific campaign report by its key:

```
POST /v1/campaigns/{report_key}
```

### Report Consolidation

Campaign scans consolidate all data into the Campaign Report. Unlike individual scans:
- No separate Location Reports are generated
- No separate Keyword Reports are generated
- No separate Trend Reports are generated
- Scan Reports and Competitor Reports are still created per scan within the campaign
- Scan reports include a `campaign_key` linking back to the parent campaign
- Historical data (trending) is available within the Campaign Report itself

### Fieldmask Recipes

**Browsing Campaigns**:
```
report_key,name,status,locations,keywords,frequency,last_run,next_run,arp,atrp,solv,arp_move,atrp_move,solv_move
```

**Campaign Report Detail**:
```
report_key,name,status,locations,keywords,arp,atrp,solv,arp_move,atrp_move,solv_move,frequency,last_run,next_run
```

> WARNING: Running a campaign manually costs credits for every scan in the campaign (locations × keywords). Check your credit balance with `POST /v2/account` before triggering large campaigns. Never retry `run-campaign` — the campaign is already queued.

---

## Errors & Async — Error Handling & Async Behavior

URL: https://docs.localfalcon.com/guides/errors-and-async

Scans and campaigns execute asynchronously. A success response means the job is queued, not completed. You must poll for results.

### The Async Scan Pattern

This is the most critical pattern in the API. When you submit a scan, the API queues it for processing and returns immediately. You then poll a separate endpoint until the results are ready.

#### Step 1: Submit the Scan

Call `POST /v2/run-scan/` with your scan parameters. A response with `"success": true` and the message "Scan submitted successfully" means the scan is **queued**, not completed. This is the expected response — it is not an error.

#### Step 2: Poll for Results

Call `POST /v1/reports/` filtered by `placeId` to check if the report has appeared. Use a lightweight fieldmask to keep polling fast:

```
fieldmask=report_key,date,keyword,location.name,arp,atrp,solv
```

Repeat every 10–15 seconds until your report appears in the response.

#### Step 3: Retrieve the Report

Once the report appears, call `POST /v1/reports/{report_key}/` with your full analysis fieldmask to get the complete scan data.

> WARNING: NEVER retry `run-scan` if you received `"success": true`. The scan is already queued and retrying would consume additional credits. If the report doesn't appear after 4–5 polling attempts, check localfalcon.com/reports directly.

### Campaign Async Pattern

Campaigns follow the same async pattern but with longer timeframes because they trigger multiple scans.

- `POST /v2/campaigns/run` returns success immediately once the campaign is submitted.
- Campaigns trigger multiple scans across locations and keywords — they can take minutes to hours to complete.
- Poll `POST /v1/campaigns/` or `POST /v1/reports/` to check for results.
- Never retry `run-campaign` after a success response — retrying would consume additional credits.
- After 4–5 polling attempts, stop polling and check the dashboard instead.

### Eager Mode (Non-Google Platforms)

The behavior of `POST /v2/run-scan/` depends on the platform:

- **Google scans** (`platform: "google"`) wait for results before responding, behaving more synchronously.
- **Non-Google platforms** (`apple`, `gaio`, `chatgpt`, `gemini`, `grok`, `aimode`) use **eager mode** — the API returns immediately and the scan processes in the background.

For eager-mode scans, poll `POST /v1/reports/` filtered by `placeId` to find the completed report.

### Rate Limiting

The API allows a maximum of 5 requests per second. If you exceed this limit, you will receive a `429` response.

Retry with exponential backoff:
1. Wait 1 second, then retry.
2. Wait 2 seconds, then retry.
3. Wait 4 seconds, then retry.

Stop after 3 retries. Retryable errors include network errors, timeouts, and `5xx` server responses.

### Response Format

All API responses follow this structure:

```json
{
  "code": 200,
  "success": true,
  "message": false,
  "data": { ... }
}
```

| Code | Success | Meaning |
|------|---------|---------|
| `200` | `true` | Request completed successfully |
| `200` | `true` | Scan/campaign submitted (async — poll for results) |
| `400` | `false` | Bad request — check parameters |
| `401` | `false` | Invalid or missing API key |
| `402` | `false` | Insufficient credits |
| `404` | `false` | Report or resource not found |
| `429` | `false` | Rate limited — wait and retry |
| `500` | `false` | Server error — retry with backoff |

### Common Gotchas

1. **`"success": true` doesn't mean the scan is done** — It means the scan was submitted. Poll for the report.
2. **Retrying costs credits** — Never retry `run-scan` or `run-campaign` after a success response.
3. **Campaign scans don't create separate trend/location/keyword reports** — All that data is consolidated in the Campaign Report.
4. **`data_points` is stripped by default** — Don't expect it unless you explicitly request it in the fieldmask.
5. **Date format is MM/DD/YYYY** — Not ISO 8601. All date parameters use this format.
6. **Omit unused parameters** — Don't pass `null` or empty strings for optional parameters you're not using.

### Timeouts

| Operation | Timeout |
|-----------|---------|
| Standard API calls | 30 seconds |
| Grid searches, campaign reports, keyword-at-coordinate | 60 seconds |
| Large campaign runs | Minutes to hours (poll, don't wait) |

---

## Examples — Worked Examples

URL: https://docs.localfalcon.com/guides/examples

Copy-paste API workflows for common tasks. Each example shows a complete multi-step workflow with cURL commands and recommended fieldmasks.

### Example 1: Competitive Analysis

#### Step 1: Run a Scan

```bash
curl -X POST "https://api.localfalcon.com/v2/run-scan/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "keyword=coffee shop" \
  -d "lat=30.2672" \
  -d "lng=-97.7431" \
  -d "gridSize=7" \
  -d "radius=3" \
  -d "measurement=mi" \
  -d "platform=google"
```

#### Step 2: Poll for the Completed Report

Wait 30–60 seconds, then list reports filtered by your Place ID.

```bash
curl -X POST "https://api.localfalcon.com/v1/reports/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "fieldmask=report_key,date,keyword,location.name,arp,atrp,solv"
```

#### Step 3: Get the Competitor Report

List competitor reports for the same Place ID, then fetch the full report by key.

```bash
curl -X POST "https://api.localfalcon.com/v1/competitor-reports/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "fieldmask=report_key,date,keyword,location.name,grid_size,platform"
```

```bash
curl -X POST "https://api.localfalcon.com/v1/competitor-reports/YOUR_REPORT_KEY/" \
  -d "api_key=YOUR_API_KEY" \
  -d "fieldmask=date,keyword,grid_size,radius,businesses.*.name,businesses.*.place_id,businesses.*.arp,businesses.*.atrp,businesses.*.solv,businesses.*.reviews,businesses.*.rating,businesses.*.lat,businesses.*.lng"
```

#### Step 4: Analyze the Results

The response ranks all competitors by SoLV. Compare review counts and ratings to identify why top-ranked businesses outperform you.

### Example 2: Multi-Location Campaign

#### Step 1: Verify Locations Are Saved

All locations must already exist in your account. Confirm with a list call.

```bash
curl -X POST "https://api.localfalcon.com/v1/locations/" \
  -d "api_key=YOUR_API_KEY"
```

#### Step 2: Create the Campaign

Schedule weekly scans for 3 locations across 2 keywords.

```bash
curl -X POST "https://api.localfalcon.com/v2/campaigns/create" \
  -d "api_key=YOUR_API_KEY" \
  -d "name=Weekly Monitoring" \
  -d "placeId=ChIJ...1,ChIJ...2,ChIJ...3" \
  -d "keyword=plumber,emergency plumber" \
  -d "gridSize=7" \
  -d "radius=5" \
  -d "measurement=mi" \
  -d "frequency=weekly" \
  -d "startDate=03/01/2026" \
  -d "startTime=9:00 AM"
```

#### Step 3: Retrieve Campaign Results

After the campaign runs, pull the consolidated report.

```bash
curl -X POST "https://api.localfalcon.com/v1/campaigns/" \
  -d "api_key=YOUR_API_KEY" \
  -d "fieldmask=report_key,name,status,locations,keywords,arp,atrp,solv,arp_move,atrp_move,solv_move,frequency,last_run,next_run"
```

#### Step 4: Compare Location Performance

Compare `arp_move` and `solv_move` across locations to identify which location is gaining or losing visibility.

### Example 3: AI Visibility Audit

#### Step 1: Run 3 Scans Across Platforms

Submit the same keyword on Google, ChatGPT, and Gemini.

```bash
# Scan 1: Google Maps
curl -X POST "https://api.localfalcon.com/v2/run-scan/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "keyword=best coffee shop" \
  -d "lat=30.2672" \
  -d "lng=-97.7431" \
  -d "gridSize=7" \
  -d "radius=3" \
  -d "measurement=mi" \
  -d "platform=google"
```

```bash
# Scan 2: ChatGPT
curl -X POST "https://api.localfalcon.com/v2/run-scan/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "keyword=best coffee shop" \
  -d "lat=30.2672" \
  -d "lng=-97.7431" \
  -d "gridSize=7" \
  -d "radius=3" \
  -d "measurement=mi" \
  -d "platform=chatgpt"
```

```bash
# Scan 3: Gemini
curl -X POST "https://api.localfalcon.com/v2/run-scan/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "keyword=best coffee shop" \
  -d "lat=30.2672" \
  -d "lng=-97.7431" \
  -d "gridSize=7" \
  -d "radius=3" \
  -d "measurement=mi" \
  -d "platform=gemini"
```

#### Step 2: Retrieve All 3 Reports

List reports filtered by Place ID. Each platform's scan produces its own report.

```bash
curl -X POST "https://api.localfalcon.com/v1/reports/" \
  -d "api_key=YOUR_API_KEY" \
  -d "placeId=ChIJ..." \
  -d "fieldmask=report_key,date,keyword,location.name,arp,atrp,solv,platform"
```

#### Step 3: Compare Results

Google scans return SoLV; AI platform scans return SAIV (displayed in the `solv` field). Compare visibility across traditional and AI search to find gaps.

> TIP: Non-Google platforms run in eager mode — the API returns immediately. Poll `POST /v1/reports/` for each platform's results separately.

---

## Manage Google Business Profile — Read & Write a Connected Profile

URL: https://docs.localfalcon.com/guides/google-business-profile

The `/v2/gbp/` endpoints act on the Google Business Profile itself, not on Local Falcon report data. They read and write live data at Google, so a call reflects the profile as it stands at that moment and a write takes effect on the public listing.

Every endpoint is keyed on `place_id` and works only for locations connected to a Google account. Use `POST /v1/locations/` with `gbp_linked` set to `true` to list eligible locations.

> WARNING: These are live writes against a real business listing. There is no sandbox.

### Endpoint Set

| Area | Read | Write |
|------|------|-------|
| Profile | `location`, `google-updated`, `verification` | `update-location`, `update-status` |
| Hours | `location` | `update-hours` |
| Posts | `posts` | `create-post`, `update-post`, `delete-post` |
| Media | `media`, `customer-media` | `create-media`, `update-media`, `delete-media` |
| Services | `services` | `add-services`, `remove-services`, `replace-services` |
| Attributes | `attributes`, `attribute-metadata` | `update-attributes` |
| Action links | `links`, `action-types` | `create-link`, `update-link`, `delete-link` |
| Reviews | `reviews` | `reply-review`, `delete-review-reply` |
| Reference | `categories`, `chains` | — |
| Performance | `metrics` | — |

All paths are prefixed `https://api.localfalcon.com/v2/gbp/` and take POST.

### Sending Parameters

Requests are form encoded. Array and object parameters are sent as indexed form fields, NOT as a JSON body. A JSON body is not read at all and the call fails as though the parameters were missing.

```bash
curl -X POST "https://api.localfalcon.com/v2/gbp/add-services/" \
  -d "api_key=YOUR_API_KEY" \
  -d "place_id=ChIJ..." \
  -d "services[0][name]=Drain cleaning" \
  -d "services[1][name]=Leak detection"
```

### Confirmation Tokens

Six endpoints will not act unless the caller echoes a confirmation token. Without it the request is rejected with `GBP_CONFIRMATION_REQUIRED` and nothing is changed, so a mistaken call is safe. Matching ignores case and surrounding whitespace.

| Endpoint | Send | Why |
|----------|------|-----|
| `delete-post` | `confirm=DELETE_POST` | Deleting a post cannot be undone |
| `delete-media` | `confirm=DELETE_MEDIA` | Deleting media cannot be undone |
| `delete-link` | `confirm=DELETE_LINK` | Deleting a link cannot be undone |
| `delete-review-reply` | `confirm=DELETE_REPLY` | The reply is removed from public view |
| `update-attributes` | `confirm=SET_ATTRIBUTES` | An attribute can be set but never removed |
| `replace-services` | `confirm=REPLACE_SERVICES` | Everything not listed is discarded |

`update-status` also requires `confirm=CLOSED_PERMANENTLY` when closing a business permanently.

> WARNING: `update-attributes` can set or change an attribute but cannot remove one. Sending `false` records an explicit negative rather than clearing it. On identity attributes such as `is_small_business`, a value you did not intend is a public claim this API cannot withdraw.

### Response Shape

Standard Local Falcon envelope with the payload in `data`. Field names are snake_case, with two deliberate exceptions: `location` and `google-updated` return Google's own resource unchanged, so their fields are camelCase.

A field with no value is returned as `false` rather than omitted. Times are objects: midnight is `{"hours": 0}` and a period running to the end of the day closes at `{"hours": 24}`.

List endpoints accept `limit` (1 to 100) and return `next_token` when more results exist. A `limit` outside the valid range is rejected rather than clamped.

### Worked Example: Publish a Post, Then Remove It

```bash
curl -X POST "https://api.localfalcon.com/v2/gbp/create-post/" \
  -d "api_key=YOUR_API_KEY" \
  -d "place_id=ChIJ..." \
  -d "topic_type=STANDARD" \
  -d "summary=Spring service checks are now open for booking."
```

The response returns a `post_id`. Deleting without the token is refused and the post stays live:

```bash
curl -X POST "https://api.localfalcon.com/v2/gbp/delete-post/" \
  -d "api_key=YOUR_API_KEY" \
  -d "place_id=ChIJ..." \
  -d "post_id=7421632958301234567"

# {"code":400,"code_desc":"GBP_CONFIRMATION_REQUIRED","success":false,
#  "message":"Deleting a post cannot be undone. Pass confirm=DELETE_POST to go ahead."}
```

Repeat with `-d "confirm=DELETE_POST"` to delete it.

### Gotchas

- Check `verification` first when a write is refused. `has_voice_of_merchant` is the practical signal: when false, the profile is not fully in the merchant's control and Google rejects some writes.
- Action link types are category dependent. Call `action-types` before `create-link`.
- Links Google sourced from a third party aggregator return `is_editable: false` and cannot be changed or removed.
- Services are free form (your label in `name`) or structured (a Google identifier in both `name` and `service_type_id`); `structured` tells them apart. The value in `name` is the matching key for add, remove and replace.
- Hours are independent: sending only `special` leaves regular hours untouched, and special hours are keyed by date.
- Writes merge by default. Fields not sent are left alone. Use `replace` to write wholesale and `clear` to empty.
- Metrics lag: Google holds roughly 18 months and the most recent few days are usually unavailable.

---

## Guide Index

URL: https://docs.localfalcon.com/guides/

All available guides:

1. [Getting Started](https://docs.localfalcon.com/guides/getting-started) — Go from zero to your first scan result in 5 minutes.
2. [Metrics](https://docs.localfalcon.com/guides/metrics) — What ARP, ATRP, SoLV, SAIV, and other ranking metrics mean.
3. [Grid Configuration](https://docs.localfalcon.com/guides/grid-configuration) — Choose the right grid size and radius for your scans.
4. [Platforms](https://docs.localfalcon.com/guides/platforms) — Compare all 7 scan platforms from Google Maps to AI assistants.
5. [Report Types](https://docs.localfalcon.com/guides/report-types) — How scan, competitor, trend, and campaign reports relate.
6. [Fieldmasks](https://docs.localfalcon.com/guides/fieldmasks) — Control which fields the API returns with per-endpoint recipes.
7. [Campaigns](https://docs.localfalcon.com/guides/campaigns) — Schedule recurring scans across multiple locations and keywords.
8. [Errors & Async](https://docs.localfalcon.com/guides/errors-and-async) — Handle async scan execution, polling, and rate limits.
9. [Examples](https://docs.localfalcon.com/guides/examples) — Copy-paste API workflows for competitive analysis and more.
10. [Manage Google Business Profile](https://docs.localfalcon.com/guides/google-business-profile) — Read and manage a connected Google Business Profile: hours, posts, media, services and reviews.

---

*Full API reference: https://docs.localfalcon.com*
*OpenAPI spec: https://docs.localfalcon.com/openapi.yaml*
*llms.txt: https://docs.localfalcon.com/llms.txt*