Your First Scan in 5 Minutes

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

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

Search for a Business

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

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.

Save the Location

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

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.

Run a Scan

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

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"

Running a scan costs credits. A 7x7 grid uses 49 scan points.

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

Check for the Completed Report

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

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.

Retrieve the Full Report

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

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

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.

Next Steps