{ "openapi": "3.0.3", "info": { "title": "Local Falcon API", "version": "1.0.0", "x-logo": { "url": "https://www.localfalcon.com/uploads/icon-light.png", "altText": "Local Falcon" }, "description": "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). Use this API to manage locations, run scans, retrieve reports, manage campaigns, and more.\n\n**Download OpenAPI Spec:** [JSON](https://docs.localfalcon.com/openapi.json) ยท [YAML](https://docs.localfalcon.com/openapi.yaml)\n\n๐Ÿ“š **API Guides:** [Getting Started, Tutorials & Best Practices]( https://docs.localfalcon.com/guides/ )\n\n## Quick Start\n\n### Option A: OAuth 2.1 via MCP Server (Recommended for AI Agents & Integrations)\n\n1. **Connect to the MCP server** at `https://mcp.localfalcon.com` โ€” all API capabilities are exposed as structured tools with full OAuth session management.\n\nThis is the recommended path for AI platforms, connector directories, and any third-party integration.\n\n### Option B: API Key for Direct REST API Access\n\n1. **Get your API key** from the [API Credentials](https://www.localfalcon.com/api/credentials/) page in your dashboard.\n2. **Make your first request** โ€” try listing your saved locations with a simple POST to `/v1/locations/`.\n3. **Explore the endpoints** below, organized by feature area.\n\nBase URL: `https://api.localfalcon.com`\n\n## API Versions\n\nThe Local Falcon API has two endpoint versions:\n\n- **v1 endpoints** โ€” The original API. Primarily used for retrieving reports, listing resources, and the On-Demand API.\n- **v2 endpoints** โ€” The current API. Used for running scans, managing locations, campaigns, Falcon Guard, and more.\n\nBoth versions are fully supported. Use whichever version provides the endpoint you need โ€” many features have endpoints in both versions.\n\n## Authentication\n\nLocal Falcon supports multiple authentication methods. **OAuth 2.1 via the MCP server is the recommended integration path** for AI agents, connector platforms, and third-party applications. Direct REST API access is available using API key authentication.\n\n### OAuth 2.1 (Recommended for Integrations)\n\nFor AI platforms, connector directories, and third-party integrations, authenticate through the Local Falcon MCP server at `https://mcp.localfalcon.com`. The MCP server implements OAuth 2.1 Authorization Code flow with PKCE (mandatory S256) and exposes all API capabilities as structured tools with built-in session management.\n\nSee **[AI Agent & Connector Integration](#section/AI-Agent-Connector-Integration)** below for full OAuth details.\n\n### API Key (Direct REST API Access)\n\nFor direct REST API calls, pass your `api_key` with each request:\n\n- **POST requests** โ€” Send `api_key` as a form data field in the request body (`application/x-www-form-urlencoded`).\n- **GET requests** โ€” Send `api_key` as a query parameter.\n\nAlternatively, you can pass the same API key value as a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nBoth methods authenticate identically โ€” the Bearer header is a convenience for clients that prefer header-based authentication.\n\nYou may have up to **5 active API keys** at any given time, each with optional **IP whitelisting** for security. Get your keys from the [API Credentials](https://www.localfalcon.com/api/credentials/) page in your dashboard.\n\n**Local Falcon assumes no liability for any failure to adequately protect your API credentials.** It is your responsibility to keep your keys secure and to rotate or revoke them if you suspect unauthorized access.\n\n## Standard Response Format\n\nEvery endpoint returns a JSON envelope with this structure:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `code` | integer | HTTP status code |\n| `code_desc` | string or false | Status description (e.g., `\"OK\"`, `\"Bad Request\"`) |\n| `success` | boolean | Whether the request succeeded |\n| `message` | string or false | Error message if failed, `false` if successful |\n| `parameters` | object | Parameters received by the endpoint |\n| `data` | object | Response payload (varies by endpoint) |\n\n## Error Codes\n\n| Code | Description |\n|------|-------------|\n| 200 | OK โ€” Request successful |\n| 400 | Bad Request โ€” Missing or invalid parameters |\n| 401 | Unauthorized โ€” Invalid or missing API key |\n| 404 | Not Found โ€” Resource not found |\n| 429 | Too Many Requests โ€” Rate limit exceeded |\n| 500 | Server Error โ€” Unexpected server error |\n\n## Field Masks\n\nMany endpoints support a `fieldmask` parameter to control which fields are returned, reducing payload size.\n\n- **Multiple fields**: `fieldmask=report_key,arp,atrp,solv`\n- **Nested fields**: Use dot notation โ€” `fieldmask=reports.*.report_key,reports.*.date`\n- **Wildcards**: Use `*` to select a field from every item in an array\n\n## AI Agent & Connector Integration\n\nThe Local Falcon [MCP server](https://mcp.localfalcon.com) is the recommended integration layer for AI agents, connector platforms, and third-party applications. It provides a structured, OAuth-secured interface to all Local Falcon API capabilities โ€” purpose-built for machine-to-machine communication.\n\n### Why Use the MCP Server?\n\n- **OAuth 2.1 with PKCE** โ€” Industry-standard authorization for secure, user-consented access. No API keys to manage or rotate.\n- **Structured tool interface** โ€” All API operations are exposed as typed, validated tools with built-in parameter validation and error handling.\n- **Session management** โ€” The MCP server handles token lifecycle, rate limiting, and request orchestration.\n- **Platform-ready** โ€” Designed for direct registration with AI connector directories (Anthropic, OpenAI, and others).\n\n### OAuth 2.1 Flow Details\n\n| Parameter | Value |\n|-----------|-------|\n| **Grant type** | Authorization Code with PKCE (S256, mandatory) |\n| **Authorization URL** | `https://www.localfalcon.com/oauth-v2/authorize` |\n| **Token URL** | `https://www.localfalcon.com/oauth-v2/token` |\n| **Revocation URL** | `https://www.localfalcon.com/oauth-v2/revoke` |\n| **MCP Server** | `https://mcp.localfalcon.com` |\n| **npm package** | [`@local-falcon/mcp`](https://www.npmjs.com/package/@local-falcon/mcp) |\n\n### Architecture\n\nThe MCP server operates as an integration layer by design. Users authorize via OAuth 2.1, and the MCP server manages authenticated sessions and routes requests to the Local Falcon REST API on their behalf. This architecture provides a clean separation between the integration interface (OAuth + structured tools) and the underlying REST API (direct key-based access), following the same pattern used by many modern platforms.\n\nFor direct REST API access without the MCP layer, use API key authentication as described in the [Authentication](#section/Authentication) section above.\n\n## Also See\n\n- [API Guides](https://docs.localfalcon.com/guides/) โ€” Getting started tutorials, metric definitions, grid configuration, fieldmask recipes, and worked examples\n- [OpenAPI Spec (YAML)](https://docs.localfalcon.com/openapi.yaml) ยท [OpenAPI Spec (JSON)](https://docs.localfalcon.com/openapi.json)\n- [llms.txt](https://docs.localfalcon.com/llms.txt) โ€” Machine-readable site index for AI agents\n- [Local Falcon Platform](https://www.localfalcon.com) ยท [Register Free](https://www.localfalcon.com/register)\n- [MCP Server](https://mcp.localfalcon.com) (OAuth 2.1) ยท [npm: @local-falcon/mcp](https://www.npmjs.com/package/@local-falcon/mcp) ยท [GitHub](https://github.com/local-falcon/mcp)\n", "contact": { "name": "Local Falcon Support", "url": "https://www.localfalcon.com" } }, "servers": [ { "url": "https://api.localfalcon.com", "description": "Local Falcon API Production Server" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "api_key", "in": "query", "description": "Pass your API key as a query parameter (`api_key`) on GET requests, or as a form data field on POST requests. Get your key from the [API Credentials](https://www.localfalcon.com/api/credentials/) dashboard page.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Pass your API key as a Bearer token in the Authorization header. The token value is the same as your API key โ€” this is an alternative transport method for clients that prefer header-based authentication.\n" } }, "schemas": { "StandardResponse": { "type": "object", "description": "The standard envelope returned by all API endpoints. Every response follows this structure regardless of the specific endpoint called.\n", "properties": { "code": { "type": "integer", "description": "The HTTP status code of the response.", "example": 200 }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean", "enum": [ false ] } ], "description": "A string identifier describing the status code (e.g., \"OK\", \"Bad Request\"). Returns false if not applicable.\n", "example": "OK" }, "success": { "type": "boolean", "description": "Indicates whether the request was successful.", "example": true }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean", "enum": [ false ] } ], "description": "A human-readable error message if the request failed. Returns false if the request was successful.\n", "example": false }, "parameters": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "maxItems": 0 } ], "description": "An associative array of the parameters received by the endpoint. May be an empty array if no parameters were provided.\n" }, "data": { "type": "object", "additionalProperties": true, "description": "The returned data payload. Contents vary by endpoint.\n" } }, "required": [ "code", "code_desc", "success", "message", "parameters", "data" ] }, "LocationBasic": { "type": "object", "description": "Basic location information returned in list endpoints such as listing all saved locations.\n", "properties": { "place_id": { "type": "string", "description": "The platform-specific Place ID for the location.", "example": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "name": { "type": "string", "description": "The business name of the location.", "example": "Local Falcon" }, "address": { "type": "string", "description": "The full street address of the location.", "example": "123 Main St, Anytown, USA" }, "lat": { "type": "string", "description": "The latitude coordinate of the location.", "example": "40.7128" }, "lng": { "type": "string", "description": "The longitude coordinate of the location.", "example": "-74.0060" }, "rating": { "type": "string", "description": "The current star rating of the location.", "example": "4.5" }, "reviews": { "type": "string", "description": "The number of reviews for the location.", "example": "127" }, "store_code": { "oneOf": [ { "type": "string" }, { "type": "boolean", "enum": [ false ] } ], "description": "The store code associated with the location, if any. Returns false if no store code is set.\n", "example": "STORE-001" } } }, "LocationDetailed": { "allOf": [ { "$ref": "#/components/schemas/LocationBasic" }, { "type": "object", "description": "Full location information including all basic fields plus additional detail fields.\n", "properties": { "platform": { "type": "string", "description": "The platform this location is associated with (e.g., google, apple).", "example": "google" }, "rating_pct": { "type": "string", "description": "The rating expressed as a percentage.", "example": "90" }, "phone": { "type": "string", "description": "The phone number of the location.", "example": "+1-555-123-4567" }, "url": { "type": "string", "description": "The full URL to the location's listing on the platform.", "example": "https://www.google.com/maps/place/?q=place_id:ChIJN1t_tDeuEmsRUsoyG83frY4" }, "display_url": { "type": "string", "description": "The website URL displayed on the location's listing.", "example": "https://www.example.com" }, "claimed": { "type": "boolean", "description": "Whether the location listing has been claimed by the owner.", "example": true }, "categories": { "type": "object", "additionalProperties": true, "description": "The categories assigned to the location on the platform." }, "store_code": { "oneOf": [ { "type": "string" }, { "type": "boolean", "enum": [ false ] } ], "description": "The store code associated with the location, if any. Returns false if no store code is set.\n", "example": "STORE-001" } } } ] }, "ErrorResponse": { "type": "object", "description": "Error response returned when a request fails. Follows the standard response structure with success set to false and an error message.\n", "properties": { "code": { "type": "integer", "description": "The HTTP status code of the error." }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean", "enum": [ false ] } ], "description": "A string identifier describing the error status code." }, "success": { "type": "boolean", "description": "Always false for error responses.", "example": false }, "message": { "type": "string", "description": "A human-readable error message describing what went wrong." }, "parameters": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "maxItems": 0 } ], "description": "The parameters that were received by the endpoint." }, "data": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "maxItems": 0 } ], "description": "May contain additional error detail or be empty." } }, "required": [ "code", "code_desc", "success", "message", "parameters", "data" ] } }, "parameters": { "ApiKeyFormData": { "name": "api_key", "in": "query", "description": "Your Local Falcon API key. For POST requests, this should be sent as a form data field in the request body. This query parameter definition serves as a reference; actual POST endpoints will define api_key in the request body schema.\n", "required": true, "schema": { "type": "string" }, "example": "your-api-key-here" }, "ApiKeyQuery": { "name": "api_key", "in": "query", "description": "Your Local Falcon API key, passed as a query parameter. Used for GET requests.\n", "required": true, "schema": { "type": "string" }, "example": "your-api-key-here" }, "LimitParam": { "name": "limit", "in": "query", "description": "The maximum number of results to return per page. Accepts values between 1 and 100. Defaults to 10 if not specified.\n", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "example": 10 }, "StartDateParam": { "name": "start_date", "in": "query", "description": "A lower limit (oldest) date for filtering results. Expects date formatted as MM/DD/YYYY.\n", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}/\\d{2}/\\d{4}$" }, "example": "01/01/2025" }, "EndDateParam": { "name": "end_date", "in": "query", "description": "An upper limit (newest) date for filtering results. Expects date formatted as MM/DD/YYYY.\n", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}/\\d{2}/\\d{4}$" }, "example": "12/31/2025" }, "PlaceIdFilterParam": { "name": "place_id", "in": "query", "description": "Filter results by a specific Google Place ID. Supports multiple Place IDs separated by commas.\n", "required": false, "schema": { "type": "string" }, "example": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "KeywordFilterParam": { "name": "keyword", "in": "query", "description": "Filter results by keyword. Uses a loose match, so partial keyword matches will be included in the results.\n", "required": false, "schema": { "type": "string" }, "example": "pizza delivery" }, "GridSizeFilterParam": { "name": "grid_size", "in": "query", "description": "Filter results by a specific grid size.", "required": false, "schema": { "type": "string", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ] }, "example": "7" }, "PlatformFilterParam": { "name": "platform", "in": "query", "description": "Filter results by a specific platform.", "required": false, "schema": { "type": "string", "enum": [ "aimode", "apple", "chatgpt", "gaio", "gemini", "google", "grok" ] }, "example": "google" }, "NextTokenParam": { "name": "next_token", "in": "query", "description": "Pagination token for retrieving the next page of results. Use the value provided in the previous response to fetch subsequent pages.\n", "required": false, "schema": { "type": "string" } }, "FieldmaskParam": { "name": "fieldmask", "in": "query", "description": "A comma-separated list of fields to include in the response. Use dot notation for nested fields and asterisk (*) as a wildcard within arrays. For example: \"report_key,arp,atrp,solv\" or \"reports.*.report_key,reports.*.date\".\n", "required": false, "schema": { "type": "string" }, "example": "report_key,arp,atrp,solv" }, "ReportKeyPath": { "name": "report_key", "in": "path", "description": "The unique key identifying the report.", "required": true, "schema": { "type": "string" }, "example": "0ee3c5869f3fa13" } }, "responses": { "BadRequest": { "description": "The request was malformed or missing required parameters.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "code": { "example": 400 }, "code_desc": { "example": "Bad Request" }, "success": { "example": false }, "message": { "example": "Missing required parameter." } } } ] } } } }, "Unauthorized": { "description": "The API key is missing, invalid, or does not have permission for the requested resource.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "code": { "example": 401 }, "code_desc": { "example": "Unauthorized" }, "success": { "example": false }, "message": { "example": "Invalid API key." } } } ] } } } }, "NotFound": { "description": "The requested resource could not be found.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "code": { "example": 404 }, "code_desc": { "example": "Not Found" }, "success": { "example": false }, "message": { "example": "The requested resource was not found." } } } ] } } } }, "TooManyRequests": { "description": "You have exceeded the rate limit. Please wait before making additional requests.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "code": { "example": 429 }, "code_desc": { "example": "Too Many Requests" }, "success": { "example": false }, "message": { "example": "Rate limit exceeded. Please try again later." } } } ] } } } }, "ServerError": { "description": "An unexpected error occurred on the server. Please try again later.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "code": { "example": 500 }, "code_desc": { "example": "Server Error" }, "success": { "example": false }, "message": { "example": "An unexpected server error occurred." } } } ] } } } } } }, "tags": [ { "name": "Scans & Reports", "description": "Run scans and retrieve all report types โ€” scan reports, competitor reports, trend reports, keyword reports, location reports, and scheduled auto-scans.\n\nUse **POST /v2/run-scan/** to run new scans, and the **/v1/** endpoints to list and retrieve report data.\n" }, { "name": "Locations", "description": "Search for business locations, save them to your account, and list all connected locations.\n\nLocations must be saved to your account before they can be used in scans.\n" }, { "name": "Campaigns", "description": "Create, run, pause, resume, and reactivate campaigns. Campaigns allow you to schedule recurring scans for one or more locations with one or more keywords.\n\nUse **/v2/campaigns/** endpoints to manage campaigns and **/v1/campaigns/** to retrieve campaign reports.\n" }, { "name": "Falcon Guard", "description": "Monitor and protect your Google Business Profile listings. Add locations to Falcon Guard, pause or resume protection, and retrieve Guard reports.\n" }, { "name": "Reviews Analysis", "description": "Retrieve AI-powered analysis reports for your business reviews.\n" }, { "name": "Account", "description": "View your Local Falcon account information including subscription details, credit balance, and usage.\n" }, { "name": "Knowledge Base", "description": "Search and retrieve articles from the Local Falcon Knowledge Base. These endpoints use **GET** requests with the API key passed as a query parameter.\n" }, { "name": "On-Demand API", "description": "**Advanced endpoints with separate per-request costs.** The On-Demand API charges a separate fee for each request, independent of your Local Falcon credit balance.\n\nFor most use cases, the **v2 endpoints** (such as Run a Scan) are recommended instead, as they use your standard Local Falcon credits. The On-Demand API remains available for specialized use cases requiring direct coordinate-level queries without saving locations to your account.\n" } ], "x-tagGroups": [ { "name": "Core", "tags": [ "Scans & Reports", "Locations", "Campaigns" ] }, { "name": "Features", "tags": [ "Falcon Guard", "Reviews Analysis", "Account", "Knowledge Base" ] }, { "name": "Advanced", "tags": [ "On-Demand API" ] } ], "paths": { "/v1/autoscans/": { "post": { "tags": [ "Scans & Reports" ], "summary": "List all Scheduled Scans", "operationId": "listScheduledScans", "description": "Allows you to retrieve a list of all Auto Scans associated with your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "start_date": { "type": "string", "description": "A lower limit (oldest) next run date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit (newest) next run date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "place_id": { "type": "string", "description": "Filter only results for specific platform place ID." }, "keyword": { "type": "string", "description": "Filter only results similar to specified keyword (loose match)." }, "grid_size": { "type": "string", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ], "description": "Filter only for specific grid sizes." }, "frequency": { "type": "string", "enum": [ "one-time", "daily", "weekly", "biweekly", "monthly" ], "description": "Filter only records with a specific run frequency." }, "status": { "type": "string", "enum": [ "scheduled", "paused" ], "description": "Filter only records with a specific status." }, "platform": { "type": "string", "description": "Filter only records for specified Platforms. Expects either one or multiple values of aimode, apple, chatgpt, gaio, gemini, google, grok; separated by commas." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "autoscans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "autoscan_key": { "type": "string" }, "nickname": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "place_id": { "type": "string" }, "location": { "type": "object", "properties": { "place_id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "rating": { "type": "string" }, "reviews": { "type": "string" }, "store_code": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] } } }, "keyword": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "data_points": { "type": "string" }, "frequency": { "type": "string" }, "last_run_timestamp": { "type": "string" }, "last_run_date": { "type": "string" }, "next_run_timestamp": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "next_run_date": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "status": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "", "start_date": "", "end_date": "", "place_id": "", "keyword": "", "grid_size": "", "frequency": "", "status": "", "next_token": "" }, "data": { "count": 10, "next_token": "VFhwTmVVMXFUVE09", "autoscans": [ { "id": "86cc4e9347f9e0a", "autoscan_key": "86cc4e9347f9e0a", "nickname": false, "place_id": "ChIJHWcru6OBwokRVgGRpXenAQY", "location": { "place_id": "ChIJHWcru6OBwokRVgGRpXenAQY", "name": "Two Maids", "address": "114 New South Rd, Hicksville, NY 11801", "lat": "40.759686", "lng": "-73.506616", "rating": "5.000", "reviews": "41", "store_code": false }, "keyword": "Cleaning Service", "lat": "40.759686", "lng": "-73.506616", "grid_size": "7", "radius": "3.0", "measurement": "mi", "data_points": "49", "frequency": "monthly", "last_run_timestamp": "1677265200", "last_run_date": "2/24/2023 2:00 PM", "next_run_timestamp": false, "next_run_date": false, "looker_last_run_datetime": "20230224", "looker_next_run_datetime": false, "status": "paused" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/locations/": { "post": { "tags": [ "Locations" ], "summary": "List All Connected Locations", "operationId": "listConnectedLocations", "description": "Get a full list of all locations connected to your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "query": { "type": "string", "description": "Search query. Matches against location name, address, Place ID, or store code." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "place_id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "rating": { "type": "string" }, "reviews": { "type": "string" }, "store_code": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "url": { "type": "string" }, "phone": { "type": "string" }, "categories": { "type": "object", "additionalProperties": { "type": "string" } }, "groups": { "type": "array", "items": { "type": "string" } } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "query": "" }, "data": { "count": 10, "next_token": "VFhwUk1rNTZZM2c9", "locations": [ { "id": "ChIJ2VRoeR_YcEgRwPypNJIvj8A", "platform": "google", "place_id": "ChIJ2VRoeR_YcEgRwPypNJIvj8A", "name": "JWS COTSWOLD BUILDERS Ltd.", "address": "Weston House, Weston Rd, Bretforton, Evesham WR11 7HW, United Kingdom", "lat": "52.0865272", "lng": "-1.8584223", "rating": "0.000", "reviews": "0", "store_code": false, "url": "http://jwscotswold.co.uk/", "phone": "", "categories": { "construction_company": "Construction company" }, "groups": [] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/location-groups/": { "post": { "tags": [ "Locations" ], "summary": "List All Location Groups", "operationId": "listLocationGroups", "description": "Get a full list of all location groups in your Local Falcon account, including the number of locations and the Place IDs contained in each group.\n\nGroups may be nested. A group with a parent is returned with `type` set to `child`, and its `parent` object identifies the containing group by `key` and `name`. Top-level groups are returned with `type` set to `parent`.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "query": { "type": "string", "description": "Search query. Matches against the group key or name." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10, "description": "The number of results you wish to retrieve." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "total": { "type": "integer" }, "count": { "type": "integer" }, "next_token": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "parent", "child" ], "description": "`parent` for a top-level group, `child` for a nested group." }, "parent": { "type": "object", "description": "Present only when `type` is `child`. Identifies the containing group.", "properties": { "key": { "type": "string" }, "name": { "type": "string" } } }, "location_count": { "type": "integer", "description": "The number of locations contained in the group." }, "place_ids": { "type": "array", "description": "The Place IDs of the locations contained in the group.", "items": { "type": "string" } }, "date_created": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "query": "" }, "data": { "total": 2, "count": 2, "next_token": false, "groups": [ { "key": "VFhwQk1rNTZRWGc9", "name": "West Coast", "type": "parent", "location_count": 12, "place_ids": [ "ChIJ2VRoeR_YcEgRwPypNJIvj8A", "ChIJN1t_tDeuEmsRUsoyG83frY4" ], "date_created": "Jan 4, 2024, 9:14 am" }, { "key": "VFhwQ01rNTZTWGc9", "name": "San Francisco", "type": "child", "parent": { "key": "VFhwQk1rNTZRWGc9", "name": "West Coast" }, "location_count": 4, "place_ids": [ "ChIJ2VRoeR_YcEgRwPypNJIvj8A" ], "date_created": "Jan 6, 2024, 11:02 am" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/reports/": { "post": { "tags": [ "Scans & Reports" ], "summary": "List of All Scan Reports", "operationId": "listScanReports", "description": "Allows you to retrieve a list of all Scan Reports performed by your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "start_date": { "type": "string", "description": "A lower limit (oldest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit (newest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "place_id": { "type": "string", "description": "Filter only results for specific Place IDs. Supports multiple Platform Place IDs, separated by commas." }, "keyword": { "type": "string", "description": "Filter only results similar to specified keyword (loose match)." }, "grid_size": { "type": "string", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ], "description": "Filter only for specific grid sizes." }, "campaign_key": { "type": "string", "description": "Filter only for scans from a specific Campaign." }, "platform": { "type": "string", "description": "Filter only results for specific Platforms. Expects either one or multiple values of aimode, apple, chatgpt, gaio, gemini, google, grok; separated by commas." }, "fields": { "type": "string", "description": "This parameter is used to target specific fields for the API to return. Expects single or comma delimited values of available data that the endpoint normally returns." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "checksum": { "type": "string" }, "report_key": { "type": "string" }, "timestamp": { "type": "string" }, "date": { "type": "string" }, "looker_date": { "type": "string" }, "type": { "type": "string" }, "platform": { "type": "string" }, "place_id": { "type": "string" }, "location": { "type": "object" }, "keyword": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "data_points": { "type": "string" }, "found_in": { "type": "string" }, "arp": { "type": "string" }, "atrp": { "type": "string" }, "solv": { "type": "string" }, "image": { "type": "string" }, "heatmap": { "type": "string" }, "pdf": { "type": "string" }, "public_url": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "", "start_date": "", "end_date": "", "place_id": "", "keyword": "", "grid_size": "", "next_token": "" }, "data": { "count": 10, "next_token": "VGtSTmVrOUVRVFZPZHowOQ==", "reports": [ { "id": "33ec21769d25069d353b241fb2fe5f35", "checksum": "38be34e80decbc79be975bc2b0fd39b235c5b0726947acb280573159fb9da103", "report_key": "4df21b0fe569354", "timestamp": "1752850980", "date": "7/18/2025 11:03 AM", "looker_date": "20250718", "type": "manual", "platform": "google", "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "location": { "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "name": "Walmart Supercenter", "address": "3501 NJ-42, Turnersville, NJ 08012", "lat": "39.7294642", "lng": "-75.0357578", "rating": "4.000", "reviews": "4582", "store_code": false, "phone": "+18566293888", "url": "https://www.walmart.com/store/1742-turnersville-nj/?veh=seo_loc", "primary_category": "Electronics Store", "secondary_category": [ "Bakery", "Clothing Store", "Department Store" ] }, "keyword": "home supply store near me", "lat": "39.7292366", "lng": "-75.0357437", "grid_size": "3", "radius": "0.5", "measurement": "mi", "data_points": "9", "found_in": "0", "arp": "21.00", "atrp": "21.00", "solv": "0.00", "image": "https://lf-static-v2.localfalcon.com/image/4df21b0fe569354/018aeaee55712f6", "heatmap": "https://lf-static-v2.localfalcon.com/heatmap-img/4df21b0fe569354/018aeaee55712f6", "pdf": "https://lf-pdf-ecs.localfalcon.com/scan-report/4df21b0fe569354/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/scan-report/4df21b0fe569354/018aeaee55712f6/" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/reports/{report_key}/": { "post": { "tags": [ "Scans & Reports" ], "summary": "Get Specific Scan Report", "operationId": "getScanReport", "description": "Allows you to retrieve the full result of a Scan Report within your Local Falcon account.\n", "parameters": [ { "name": "report_key", "in": "path", "required": true, "description": "The key of the report you wish to retrieve. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "report_key": { "type": "string", "description": "The key of the report you wish to retrieve. Required if not included in URL." }, "ai_analysis": { "type": "boolean", "description": "When set to true, the endpoint will not return the report until the AI analysis (if enabled) for the report has been completed." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "checksum": { "type": "string" }, "report_key": { "type": "string" }, "campaign_report_key": { "type": "string" }, "timestamp": { "type": "string" }, "date": { "type": "string" }, "looker_date": { "type": "string" }, "platform": { "type": "string" }, "place_id": { "type": "string" }, "location": { "type": "object" }, "keyword": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "points": { "type": "string" }, "found_in": { "type": "string" }, "arp": { "type": "string" }, "atrp": { "type": "string" }, "solv": { "type": "string" }, "unique_competitors": { "type": "integer" }, "image": { "type": "string" }, "heatmap": { "type": "string" }, "pdf": { "type": "string" }, "public_url": { "type": "string" }, "data_points": { "type": "array", "items": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" }, "found": { "type": "boolean" }, "rank": { "oneOf": [ { "type": "integer" }, { "type": "boolean" } ] }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "place_id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "", "start_date": "", "end_date": "", "place_id": "", "keyword": "", "grid_size": "", "next_token": "" }, "data": { "id": "8043fd66e75eb73d7f896d9e901995bf", "checksum": "66f869ccbf5235d7ae4e0d0eb28909c36e46e07653172a083647691772d69d0a", "report_key": "8033268405f23ac", "campaign_report_key": "742e9e6e76f24a2", "timestamp": "1687870863", "date": "6/27/2023 9:01 AM", "looker_date": "20230627", "platform": "google", "place_id": "ChIJ6ULSRklQwYkR_V5GGobrWTc", "location": { "platform": "google", "place_id": "ChIJ6ULSRklQwYkR_V5GGobrWTc", "lat": "40.1420759", "lng": "-74.8225698", "name": "Walmart Supercenter", "address": "180 Levittown Center, Levittown, PA 19055", "rating": "3.700", "rating_pct": "0.740", "reviews": "6123", "phone": "+12159496600", "url": "https://www.walmart.com/store/2068-levittown-pa/", "display_url": "walmart.com", "claimed": true, "categories": { "electronics_store": "Electronics store", "department_store": "Department store" }, "store_code": false }, "keyword": "home supply store near me", "lat": "40.1419777", "lng": "-74.8225408", "grid_size": "7", "radius": "5", "measurement": "mi", "points": "49", "found_in": "0", "arp": "21.00", "atrp": "21.00", "solv": "0.00", "unique_competitors": 87, "image": "https://lf-static-v2.localfalcon.com/image/8033268405f23ac", "heatmap": "https://lf-static-v2.localfalcon.com/heatmap-img/8033268405f23ac", "pdf": "https://lf-pdf-ecs.localfalcon.com/scan-report/8033268405f23ac/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/scan-report/8033268405f23ac/018aeaee55712f6/", "data_points": [ { "lat": "40.0696930", "lng": "-74.9170987", "found": false, "rank": false, "count": 20, "results": [ { "rank": 1, "place_id": "ChIJde7TDrVMwYkR5V9kpj_KiP0", "name": "The Home Depot" } ] } ] } } } } }, "202": { "description": "Scan is still processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "report_key": { "type": "string" }, "status": { "type": "string" } } } } }, "example": { "code": 202, "success": true, "message": "Scan is still processing", "data": { "report_key": "19c96a00485ef96", "status": "processing" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/competitor-reports/": { "post": { "tags": [ "Scans & Reports" ], "summary": "List of All Competitor Reports", "operationId": "listCompetitorReports", "description": "Allows you to retrieve a list of all Competitor Reports within your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "start_date": { "type": "string", "description": "A lower limit (oldest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit (newest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "place_id": { "type": "string", "description": "Filter only results for specific Platform Place ID. Supports multiple platform Place IDs, separated by commas." }, "keyword": { "type": "string", "description": "Filter only results similar to specified keyword (loose match)." }, "grid_size": { "type": "string", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ], "description": "Filter only for specific grid sizes." }, "platform": { "type": "string", "description": "Filter only results for specific Platform. Expects either one or multiple values of aimode, apple, chatgpt, gaio, gemini, google, grok; separated by commas." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "checksum": { "type": "string" }, "report_key": { "type": "string" }, "timestamp": { "type": "string" }, "date": { "type": "string" }, "looker_date": { "type": "string" }, "type": { "type": "string" }, "place_id": { "type": "string" }, "location": { "type": "object" }, "keyword": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "data_points": { "type": "string" }, "found_in": { "type": "string" }, "arp": { "type": "string" }, "atrp": { "type": "string" }, "solv": { "type": "string" }, "image": { "type": "string" }, "pdf": { "type": "string" }, "public_url": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "", "start_date": "", "end_date": "", "place_id": "", "keyword": "", "grid_size": "", "next_token": "" }, "data": { "count": 10, "next_token": "VGtSTmVrOUVRVFZPUVQwOQ==", "reports": [ { "id": "8043fd66e75eb73d7f896d9e901995bf", "checksum": "66f869ccbf5235d7ae4e0d0eb28909c36e46e07653172a083647691772d69d0a", "report_key": "8033268405f23ac", "timestamp": "1687870863", "date": "6/27/2023 9:01 AM", "looker_date": "20230627", "type": "campaign", "place_id": "ChIJ6ULSRklQwYkR_V5GGobrWTc", "location": { "place_id": "ChIJ6ULSRklQwYkR_V5GGobrWTc", "name": "Walmart Supercenter", "address": "180 Levittown Center, Levittown, PA 19055", "lat": "40.1420759", "lng": "-74.8225698", "rating": "3.700", "reviews": "6391", "store_code": false }, "keyword": "home supply store near me", "lat": "40.1419777", "lng": "-74.8225408", "grid_size": "7", "radius": "5", "measurement": "mi", "data_points": "49", "found_in": "0", "arp": "21.00", "atrp": "21.00", "solv": "0.00", "image": "https://lf-static-v2.localfalcon.com/image/8033268405f23ac/018aeaee55712f6", "pdf": "https://lf-pdf-ecs.localfalcon.com/scan-report/8033268405f23ac/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/scan-report/8033268405f23ac/018aeaee55712f6/" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/competitor-reports/{report_key}": { "post": { "tags": [ "Scans & Reports" ], "summary": "Get Specific Competitor Report", "operationId": "getCompetitorReport", "description": "Allows you to retrieve the full result of a Competitor Report within your Local Falcon account.\n", "parameters": [ { "name": "report_key", "in": "path", "required": true, "description": "The key of the report you wish to retrieve. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "report_key": { "type": "string", "description": "The key of the report you wish to retrieve. Required if not included in URL." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "checksum": { "type": "string" }, "report_key": { "type": "string" }, "timestamp": { "type": "string" }, "date": { "type": "string" }, "looker_date": { "type": "string" }, "platform": { "type": "string" }, "keyword": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "points": { "type": "string" }, "businesses": { "type": "array", "items": { "type": "object", "properties": { "place_id": { "type": "string" }, "platform": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "rating": { "type": "string" }, "reviews": { "type": "string" }, "categories": { "type": "object", "additionalProperties": { "type": "string" } }, "phone": { "type": "string" }, "url": { "type": "string" }, "display_url": { "type": "string" }, "claimed": { "type": "boolean" }, "arp": { "type": "string" }, "atrp": { "type": "string" }, "solv": { "type": "string" }, "data_points": { "type": "array", "items": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" }, "rank": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } } } } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "fields": "" }, "data": { "id": "8043fd66e75eb73d7f896d9e901995bf", "checksum": "66f869ccbf5235d7ae4e0d0eb28909c36e46e07653172a083647691772d69d0a", "report_key": "8033268405f23ac", "timestamp": "1687870863", "date": "6/27/2023 9:01 AM", "looker_date": "20230627", "platform": "", "keyword": "home supply store near me", "lat": "40.1419777", "lng": "-74.8225408", "grid_size": "7", "radius": "5", "measurement": "mi", "points": "49", "businesses": [ { "place_id": "ChIJqbLkjkBYwYkRzXf-90vsD5A", "platform": "google", "name": "Home Building Center", "address": "1580 N Olden Ave, Ewing Township, NJ 08638", "lat": "40.2430417", "lng": "-74.7561746", "rating": "5.000", "reviews": "1", "categories": { "hardware_store": "Hardware store" }, "phone": "", "url": "", "display_url": "", "claimed": false, "arp": "5.92", "atrp": "9.00", "solv": "38.78", "data_points": [ { "lat": "40.0696930", "lng": "-74.9170987", "rank": "20+" }, { "lat": "40.1901675", "lng": "-74.9170987", "rank": 5 } ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/trend-reports/": { "post": { "tags": [ "Scans & Reports" ], "summary": "List of All Trend Reports", "operationId": "listTrendReports", "description": "Allows you to retrieve a list of all Trend Reports within your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "place_id": { "type": "string", "description": "Filter only results for specific platform Place ID. Supports multiple platform Place IDs, separated by commas." }, "keyword": { "type": "string", "description": "Filter only results similar to specified keyword (loose match)." }, "start_date": { "type": "string", "description": "A lower limit (oldest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit (newest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "platform": { "type": "string", "description": "Filter only results for specific Platforms. Expects either one or multiple values of aimode, apple, chatgpt, gaio, gemini, google, grok; separated by commas." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "last_timestamp": { "type": "string" }, "last_date": { "type": "string" }, "looker_last_date": { "type": "string" }, "location": { "type": "object" }, "keyword": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "points": { "type": "string" }, "scan_count": { "type": "string" }, "arp": { "type": "string" }, "arp_move": { "type": "string" }, "atrp": { "type": "string" }, "atrp_move": { "type": "string" }, "solv": { "type": "string" }, "solv_move": { "type": "string" }, "pdf": { "type": "string" }, "csv": { "type": "string" }, "public_url": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "", "place_id": "", "keyword": "", "next_token": "" }, "data": { "count": 10, "next_token": "VFZSQ09FNVVXVEJQUkZVeA==", "reports": [ { "id": "3ec2071a1504810a9cee38e03874a0c7", "report_key": "15660c271e19dad", "last_timestamp": "1687870863", "last_date": "6/27/2023 9:01 AM", "looker_last_date": "20230627", "location": { "place_id": "ChIJ6ULSRklQwYkR_V5GGobrWTc", "name": "Walmart Supercenter", "address": "180 Levittown Center, Levittown, PA 19055", "lat": "40.1420759", "lng": "-74.8225698", "rating": "3.700", "reviews": "6391", "store_code": false }, "keyword": "home supply store near me", "lat": "40.1419777", "lng": "-74.8225408", "grid_size": "7", "radius": "5", "measurement": "mi", "points": "49", "scan_count": "3", "arp": "20+", "arp_move": "0.00", "atrp": "20+", "atrp_move": "0.00", "solv": "0.00", "solv_move": "0.00", "pdf": "https://lf-pdf-ecs.localfalcon.com/trend-report/15660c271e19dad/018aeaee55712f6/", "csv": "https://lf-export-v2.localfalcon.com/trend/csv/15660c271e19dad/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/trend-report/15660c271e19dad/018aeaee55712f6/" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/trend-reports/{report_key}": { "post": { "tags": [ "Scans & Reports" ], "summary": "Get Specific Trend Report", "operationId": "getTrendReport", "description": "Allows you to retrieve the full result of a Trend Report from the Local Falcon.\n", "parameters": [ { "name": "report_key", "in": "path", "required": true, "description": "The key of the report you wish to retrieve. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "report_key": { "type": "string", "description": "The key of the report you wish to retrieve. Required if not included in URL." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "last_timestamp": { "type": "string" }, "last_date": { "type": "string" }, "looker_last_date": { "type": "string" }, "location": { "type": "object" }, "keyword": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "points": { "type": "string" }, "scan_count": { "type": "integer" }, "arp": { "type": "string" }, "arp_move": { "type": "string" }, "atrp": { "type": "string" }, "atrp_move": { "type": "string" }, "solv": { "type": "string" }, "solv_move": { "type": "string" }, "pdf": { "type": "string" }, "csv": { "type": "string" }, "public_url": { "type": "string" }, "scans": { "type": "array", "items": { "type": "object", "properties": { "report_key": { "type": "string" }, "timestamp": { "type": "string" }, "date": { "type": "string" }, "arp": { "type": "string" }, "atrp": { "type": "string" }, "solv": { "type": "string" }, "image": { "type": "string" }, "heatmap": { "type": "string" }, "public_url": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object" } } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": [], "data": { "id": "3ec2071a1504810a9cee38e03874a0c7", "report_key": "15660c271e19dad", "last_timestamp": "1687870863", "last_date": "6/27/2023 9:01 AM", "looker_last_date": "20230627", "location": { "platform": "google", "place_id": "ChIJ6ULSRklQwYkR_V5GGobrWTc", "lat": "40.1420759", "lng": "-74.8225698", "name": "Walmart Supercenter", "address": "180 Levittown Center, Levittown, PA 19055", "rating": "3.700", "rating_pct": "0.740", "reviews": "6123", "phone": "+12159496600", "url": "https://www.walmart.com/store/2068-levittown-pa/", "display_url": "walmart.com", "claimed": true, "categories": { "electronics_store": "Electronics store", "department_store": "Department store" }, "store_code": false }, "keyword": "home supply store near me", "lat": "40.1419777", "lng": "-74.8225408", "grid_size": "7", "radius": "5", "measurement": "mi", "points": "49", "scan_count": 3, "arp": "21.00", "arp_move": "0.00", "atrp": "21.00", "atrp_move": "0.00", "solv": "0.00", "solv_move": "0.00", "pdf": "https://lf-pdf-ecs.localfalcon.com/trend-report/15660c271e19dad/018aeaee55712f6/", "csv": "https://lf-export-v2.localfalcon.com/trend/csv/15660c271e19dad/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/trend-report/15660c271e19dad/018aeaee55712f6/", "scans": [ { "report_key": "8033268405f23ac", "timestamp": "1687870863", "date": "6/27/2023 9:01 AM", "arp": "21.00", "atrp": "21.00", "solv": "0.00", "image": "https://lf-static-v2.localfalcon.com/image/8033268405f23ac", "heatmap": "https://lf-static-v2.localfalcon.com/heatmap/8033268405f23ac", "public_url": "https://localrankingtracker.com/scan-report/8033268405f23ac/018aeaee55712f6/" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/keyword-reports/": { "post": { "tags": [ "Scans & Reports" ], "summary": "List of All Keyword Reports", "operationId": "listKeywordReports", "description": "Allows you to retrieve a list of all Keyword Reports within your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "keyword": { "type": "string", "description": "Filter only results similar to specified keyword (loose match)." }, "start_date": { "type": "string", "description": "A lower limit (oldest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit (newest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "last_timestamp": { "type": "string" }, "last_date": { "type": "string" }, "looker_last_date": { "type": "string" }, "keyword": { "type": "string" }, "location_count": { "type": "string" }, "scan_count": { "type": "string" }, "avg_arp": { "type": "string" }, "avg_atrp": { "type": "string" }, "avg_solv": { "type": "string" }, "pdf": { "type": "string" }, "public_url": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "3", "keyword": "", "next_token": "" }, "data": { "count": 3, "next_token": "VFROM2VVMUVTVE5OYWtFOQ==", "reports": [ { "id": "34627d4274a24cfd2db970eebcf2666a", "report_key": "efb0c0ca0382449", "last_timestamp": "1752850980", "last_date": "7/18/2025 11:03 AM", "looker_last_date": "20250718", "keyword": "home supply store near me", "location_count": "1", "scan_count": "1", "avg_arp": "20+", "avg_atrp": "20+", "avg_solv": "0.00", "pdf": "https://lf-pdf-ecs.localfalcon.com/keyword-report/efb0c0ca0382449/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/keyword-report/efb0c0ca0382449/018aeaee55712f6/" }, { "id": "2aeb4b2e7c85ebfaa7c8c700f5ccad23", "report_key": "675c340e3891a6e", "last_timestamp": "0", "last_date": "12/31/1969 7:00 PM", "looker_last_date": "19691231", "keyword": "housekeeping service", "location_count": "1", "scan_count": "0", "avg_arp": "20+", "avg_atrp": "20+", "avg_solv": "0.00", "pdf": "https://lf-pdf-ecs.localfalcon.com/keyword-report/675c340e3891a6e/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/keyword-report/675c340e3891a6e/018aeaee55712f6/" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/keyword-reports/{report_key}": { "post": { "tags": [ "Scans & Reports" ], "summary": "Get Specific Keyword Report", "operationId": "getKeywordReport", "description": "Allows you to retrieve the full result of a Keyword Report from the Local Falcon.\n", "parameters": [ { "name": "report_key", "in": "path", "required": true, "description": "The key of the report you wish to retrieve. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "report_key": { "type": "string", "description": "The key of the report you wish to retrieve. Required if not included in URL." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "last_timestamp": { "type": "integer" }, "last_date": { "type": "string" }, "looker_last_date": { "type": "string" }, "keyword": { "type": "string" }, "location_count": { "type": "integer" }, "scan_count": { "type": "integer" }, "avg_arp": { "type": "string" }, "avg_atrp": { "type": "string" }, "avg_solv": { "type": "string" }, "pdf": { "type": "string" }, "public_url": { "type": "string" }, "scans": { "type": "array", "items": { "type": "object" } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": [], "data": { "id": "44d4293351c9f751f0ad4c8c8c025487", "report_key": "efb0c0ca0382449", "last_timestamp": 0, "last_date": "12/31/1969 7:00 PM", "looker_last_date": "19691231", "keyword": "home supply store near me", "location_count": 1, "scan_count": 0, "avg_arp": "0.00", "avg_atrp": "0.00", "avg_solv": "0.00", "pdf": "https://lf-pdf-ecs.localfalcon.com/keyword-report/efb0c0ca0382449/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/keyword-report/efb0c0ca0382449/018aeaee55712f6/", "scans": [] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/location-reports/": { "post": { "tags": [ "Scans & Reports" ], "summary": "List of All Location Reports", "operationId": "listLocationReports", "description": "Allows you to retrieve a list of all Location Reports within your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "place_id": { "type": "string", "description": "Filter only results for specific platform Place ID. Supports multiple platform Place IDs, separated by commas." }, "keyword": { "type": "string", "description": "Filter only results similar to specified keyword (loose match)." }, "start_date": { "type": "string", "description": "A lower limit (oldest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit (newest) date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "last_timestamp": { "type": "string" }, "last_date": { "type": "string" }, "looker_last_date": { "type": "string" }, "place_id": { "type": "string" }, "location": { "type": "object" }, "keyword_count": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "scan_count": { "type": "string" }, "avg_arp": { "type": "string" }, "avg_atrp": { "type": "string" }, "avg_solv": { "type": "string" }, "pdf": { "type": "string" }, "public_url": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "", "place_id": "", "keyword": "", "next_token": "" }, "data": { "count": 10, "next_token": "VFZSQ09FMVVRVE5PVkVreg==", "reports": [ { "id": "985eb941def161e987f0c9db1a526508", "report_key": "615dbd40e9af3a1", "last_timestamp": "1687870863", "last_date": "6/27/2023 9:01 AM", "looker_last_date": "20230627", "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "location": { "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "name": "Walmart Supercenter", "address": "3501 NJ-42, Turnersville, NJ 08012", "lat": "39.7294642", "lng": "-75.0357578", "rating": "4.000", "reviews": "4442", "store_code": false }, "keyword_count": "3", "keywords": [ "groceries near me", "chips", "home supply store near me" ], "scan_count": "9", "avg_arp": "11.83", "avg_atrp": "20+", "avg_solv": "0.68", "pdf": "https://lf-pdf-ecs.localfalcon.com/location-report/615dbd40e9af3a1/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/location-report/615dbd40e9af3a1/018aeaee55712f6/" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/location-reports/{report_key}": { "post": { "tags": [ "Scans & Reports" ], "summary": "Get Specific Location Report", "operationId": "getLocationReport", "description": "Allows you to retrieve the full result of a Location Report from the Local Falcon.\n", "parameters": [ { "name": "report_key", "in": "path", "required": true, "description": "The key of the report you wish to retrieve. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "report_key": { "type": "string", "description": "The key of the report you wish to retrieve. Required if not included in URL." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "timestamp": { "type": "string" }, "date": { "type": "string" }, "looker_last_date": { "type": "string" }, "place_id": { "type": "string" }, "location": { "type": "object" }, "keyword_count": { "type": "integer" }, "scan_count": { "type": "integer" }, "avg_arp": { "type": "string" }, "avg_atrp": { "type": "string" }, "avg_solv": { "type": "string" }, "pdf": { "type": "string" }, "public_url": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "scan_count": { "type": "integer" }, "arp": { "type": "string" }, "arp_move": { "type": "string" }, "atrp": { "type": "string" }, "atrp_move": { "type": "string" }, "solv": { "type": "string" }, "solv_move": { "type": "string" }, "last_timestamp": { "type": "string" }, "last_date": { "type": "string" }, "last_scan_report_key": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": [], "data": { "id": "985eb941def161e987f0c9db1a526508", "report_key": "615dbd40e9af3a1", "timestamp": "1687870863", "date": "6/27/2023 9:01 AM", "looker_last_date": "20230627", "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "location": { "platform": "google", "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "lat": "39.7294642", "lng": "-75.0357578", "name": "Walmart Supercenter", "address": "3501 NJ-42, Turnersville, NJ 08012", "rating": "4.000", "rating_pct": "0.800", "reviews": "4228", "phone": "+18566293888", "url": "https://www.walmart.com/store/1742-turnersville-nj/", "display_url": "walmart.com", "claimed": true, "categories": { "department_store": "Department store", "grocery_store": "Grocery store" }, "store_code": false }, "keyword_count": 3, "scan_count": 9, "avg_arp": "11.83", "avg_atrp": "20.73", "avg_solv": "0.68", "pdf": "https://lf-pdf-ecs.localfalcon.com/location-report/615dbd40e9af3a1/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/location-report/615dbd40e9af3a1/018aeaee55712f6/", "keywords": [ { "keyword": "groceries near me", "scan_count": 3, "arp": "9.50", "arp_move": "-0.50", "atrp": "20.53", "atrp_move": "-0.02", "solv": "2.04", "solv_move": "0.00", "last_timestamp": "1687870863", "last_date": "6/27/2023 9:01 AM", "last_scan_report_key": "a4214eac691a566" }, { "keyword": "chips", "scan_count": 3, "arp": "5.00", "arp_move": "7.00", "atrp": "20.67", "atrp_move": "0.15", "solv": "0.00", "solv_move": "0.00", "last_timestamp": "1687870863", "last_date": "6/27/2023 9:01 AM", "last_scan_report_key": "5937e81e35699cd" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/campaigns/": { "post": { "tags": [ "Campaigns" ], "summary": "List of All Campaign Reports", "operationId": "listCampaignReports", "description": "Allows you to retrieve a list of all Campaign Reports within your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "start_date": { "type": "string", "description": "A lower limit date of a Campaign run you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit date of a Campaign run or schedule you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "place_id": { "type": "string", "description": "Filter only results for specific platform Place ID. Supports multiple platform Place IDs, separated by commas." }, "run": { "type": "string", "description": "Filter for the results of a specific Run Date. Expects a date value contained within the \"runs\" response. Defaults to the last report run." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "name": { "type": "string" }, "locations": { "type": "string" }, "keywords": { "type": "string" }, "scans": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "frequency": { "type": "string" }, "last_run": { "type": "string" }, "last_run_date": { "type": "string" }, "next_run": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "next_run_date": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "arp": { "type": "string" }, "arp_move": { "type": "string" }, "atrp": { "type": "string" }, "atrp_move": { "type": "string" }, "solv": { "type": "string" }, "solv_move": { "type": "string" }, "public_url": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "limit": "", "start_date": "", "end_date": "", "place_id": "", "next_token": "" }, "data": { "count": 1, "next_token": false, "reports": [ { "id": "106a19450c2485fd1ee8cbefa2d4f144", "report_key": "742e9e6e76f24a2", "name": "Local Falcon Campaigns Demo", "locations": "20", "keywords": "3", "scans": "60", "grid_size": "7", "radius": "5", "measurement": "mi", "frequency": "every two weeks", "last_run": "1687870863", "last_run_date": "6/27/2023 9:01 AM", "next_run": false, "next_run_date": false, "arp": "11.35", "arp_move": "0.59", "atrp": "20.58", "atrp_move": "0.02", "solv": "0.85", "solv_move": "0.07", "public_url": "https://localrankingtracker.com/campaign-report/742e9e6e76f24a2/018aeaee55712f6/", "status": "paused" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/campaigns/{report_key}": { "post": { "tags": [ "Campaigns" ], "summary": "Get Specific Campaign Report", "operationId": "getCampaignReport", "description": "Allows you to retrieve the full result of a Campaign Report from the Local Falcon.\n", "parameters": [ { "name": "report_key", "in": "path", "required": true, "description": "The key of the report you wish to retrieve. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "report_key": { "type": "string", "description": "The key of the report you wish to retrieve. Required if not included in URL." }, "run": { "type": "string", "description": "Load a specific run date's campaign data. Expects run date formatted as YYYY-MM-DD. Defaults to the latest run date." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "name": { "type": "string" }, "created": { "type": "string" }, "date_created": { "type": "string" }, "updated": { "type": "string" }, "date_updated": { "type": "string" }, "last_run": { "type": "string" }, "date_last_run": { "type": "string" }, "next_run": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "date_next_run": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "frequency": { "type": "string" }, "locations": { "type": "string" }, "keywords": { "type": "string" }, "scans": { "type": "string" }, "arp": { "type": "string" }, "arp_change": { "type": "string" }, "atrp": { "type": "string" }, "atrp_change": { "type": "string" }, "solv": { "type": "string" }, "solv_change": { "type": "string" }, "public_url": { "type": "string" }, "status": { "type": "string" }, "runs": { "type": "array", "items": { "type": "string" } }, "run_data": { "type": "object", "properties": { "run": { "type": "string" }, "metrics": { "type": "object" }, "breakdown": { "type": "object" } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": [], "data": { "id": "336d5ebc5436534e61d16e63ddfca327", "report_key": "742e9e6e76f24a2", "name": "Local Falcon Campaigns Demo", "created": "1686679756", "date_created": "6/13/2023 2:09 PM", "updated": "1686679756", "date_updated": "6/13/2023 2:09 PM", "last_run": "1687870863", "date_last_run": "6/27/2023 9:01 AM", "next_run": false, "date_next_run": false, "grid_size": "7", "radius": "5", "measurement": "mi", "frequency": "every two weeks", "locations": "20", "keywords": "3", "scans": "60", "arp": "11.35", "arp_change": "0.59", "atrp": "20.58", "atrp_change": "0.02", "solv": "0.85", "solv_change": "0.07", "public_url": "https://localrankingtracker.com/campaign-report/742e9e6e76f24a2/018aeaee55712f6/", "status": "paused", "runs": [ "2023-06-13", "2023-06-23", "2023-06-27" ], "run_data": { "run": "2023-06-27", "metrics": { "arp": "11.35", "arp_move": "0.59", "atrp": "20.58", "atrp_move": "0.02", "solv": "0.85", "solv_move": "0.07" }, "breakdown": { "arp": [ { "label": "1st", "value": 10 }, { "label": "Top 3", "value": 8 }, { "label": "Top 10", "value": 10 }, { "label": "Top 20", "value": 12 }, { "label": "20+", "value": 20 } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/guard/": { "post": { "tags": [ "Falcon Guard" ], "summary": "List of All Falcon Guard Reports", "operationId": "listGuardReports", "description": "Allows you to retrieve the full list of all Falcon Guard Reports within your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "start_date": { "type": "string", "description": "A lower limit date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit date you wish to retrieve. Expects date formatted as MM/DD/YYYY." }, "status": { "type": "string", "enum": [ "protected", "paused" ], "description": "Filter results based on location's protection status." }, "limit": { "type": "integer", "minimum": 3, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "report_key": { "type": "string" }, "date_added": { "type": "string" }, "date_last": { "type": "string" }, "date_next": { "type": "string" }, "place_id": { "type": "string" }, "location": { "type": "object", "properties": { "place_id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "rating": { "type": "string" }, "reviews": { "type": "string" }, "store_code": { "type": "string" }, "phone": { "type": "string" }, "url": { "type": "string" }, "primary_category": { "type": "string" }, "secondary_category": { "type": "array", "items": { "type": "string" } } } }, "public_url": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "start_date": "", "end_date": "" }, "data": { "count": 1, "next_token": false, "reports": [ { "id": "9e48adeba87d5ebee077370140e97496", "report_key": "f67cac38fc34d79", "date_added": "5/5/2025 10:28 AM", "date_last": "5/5/2025 10:28 AM", "date_next": "5/5/2025 10:28 PM", "place_id": "ChIJVWL9HOV_LYgRSRR2NVoYcMw", "location": { "place_id": "ChIJVWL9HOV_LYgRSRR2NVoYcMw", "name": "D Thomas Masonry Inc", "address": "Erie County, PA, USA", "lat": "42.0830849", "lng": "-79.7894638", "rating": "4.700", "reviews": "12", "store_code": "15248406827968068040", "phone": "+18148738213", "url": "https://www.dthomasmasonry.com/", "primary_category": "Masonry Contractor", "secondary_category": [ "Bricklayer", "Chimney Services", "Service Establishment" ] }, "public_url": "https://localrankingtracker.com/guard-report/f67cac38fc34d79/018aeaee55712f6/", "status": "Protected" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/guard/{place_id}": { "post": { "tags": [ "Falcon Guard" ], "summary": "Get Specific Falcon Guard Report", "operationId": "getGuardReport", "description": "Allows you to retrieve the full result of the Falcon Guard Report of an active/protected location from the Local Falcon.\n", "parameters": [ { "name": "place_id", "in": "path", "required": true, "description": "The Place ID of the location you wish to retrieve. Also accepts the report_key. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of the location you wish to retrieve. Also accepts the report_key. Required if not included in URL." }, "start_date": { "type": "string", "description": "A lower limit date you wish to retrieve changes and metrics for. Expects date formatted as MM/DD/YYYY." }, "end_date": { "type": "string", "description": "Upper limit date you wish to retrieve changes and metrics for. Expects date formatted as MM/DD/YYYY." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "place_id": { "type": "string" }, "location": { "type": "object", "properties": { "place_id": { "type": "string" }, "fid": { "type": "string" }, "cid": { "type": "string" }, "name": { "type": "string" }, "address": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "full_address": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "is_sab": { "type": "boolean" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "plus_code": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "store_code": { "type": "string" }, "description": { "type": "string" }, "phone": { "type": "string" }, "url": { "type": "string" }, "display_url": { "type": "string" }, "hours": { "type": "object" }, "rating": { "type": "string" }, "reviews": { "type": "string" }, "primary_category": { "type": "string" }, "secondary_categories": { "type": "array", "items": { "type": "string" } } } }, "changes": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "object" } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": [], "data": { "id": "9e48adeba87d5ebee077370140e97496", "place_id": "ChIJVWL9HOV_LYgRSRR2NVoYcMw", "location": { "place_id": "ChIJVWL9HOV_LYgRSRR2NVoYcMw", "fid": "0x882d7fe51cfd6255:0xcc70185a35761449", "cid": "14731301156851946569", "name": "D Thomas Masonry Inc", "address": false, "full_address": false, "is_sab": true, "lat": "42.0830849", "lng": "-79.7894638", "plus_code": false, "store_code": "15248406827968068040", "description": "D Thomas Masonry Inc. is your go-to expert for all masonry repair needs.", "phone": "+18148738213", "url": "https://www.dthomasmasonry.com/", "display_url": "dthomasmasonry.com", "hours": { "monday": { "formatted": "7:00 AM - 6:00 PM", "opens": "7:00 AM", "closes": "6:00 PM", "all_day": false, "closed": false }, "saturday": { "formatted": "Closed", "opens": false, "closes": false, "all_day": false, "closed": true } }, "rating": "4.700", "reviews": "12", "primary_category": "Masonry Contractor", "secondary_categories": [ "Bricklayer", "Chimney Services", "Service Establishment" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/reviews/": { "post": { "tags": [ "Reviews Analysis" ], "summary": "List of All Reviews Analysis Reports", "operationId": "listReviewsReports", "description": "Allows you to retrieve the full list of all Reviews Analysis Reports within your Local Falcon account.\n\nIf more records exist than is allowed within the set `limit`, a value will be returned under `next_token` that can be used as a parameter to request the next page of results.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "reviews_key": { "type": "string", "description": "Used to filter the list of reports by their source. Provide the unique identifier (key) of the parent Reviews Analysis record to retrieve only the reports generated by that specific configuration." }, "place_id": { "type": "string", "description": "Filter only results for specific platform Place ID. Supports multiple platform Place IDs, separated by commas." }, "frequency": { "type": "string", "enum": [ "one_time", "daily", "weekly", "two_weeks", "three_weeks", "four_weeks", "monthly" ], "description": "Filter results based on the frequency of the analysis frequency." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The number of results you wish to retrieve." }, "next_token": { "type": "string", "description": "This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "next_token": { "type": "string" }, "reports": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reviews_key": { "type": "string" }, "review_date": { "type": "string" }, "name": { "type": "string" }, "locations": { "type": "string" }, "frequency": { "type": "string" }, "price": { "type": "integer" }, "report_url": { "type": "string" } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": [], "data": { "count": 10, "next_token": "VFZSamVVOUJQVDA9", "reports": [ { "key": "cbe487c635bca4f", "reviews_key": "5d4c2d2200e1a18", "review_date": "9/7/2025, 9:23 AM", "name": "Reviews of Dahlkemper Custom Jewelers", "locations": "1 location", "frequency": "Every Week", "price": 19, "report_url": "https://localrankingtracker.com/reviews-analysis-report/cbe487c635bca4f/" }, { "key": "c9011ed64d3a630", "reviews_key": "958b13cef787859", "review_date": "9/3/2025, 1:30 PM", "name": "Jessica Hunter Photography", "locations": "1 location", "frequency": "Every Week", "price": 19, "report_url": "https://localrankingtracker.com/reviews-analysis-report/c9011ed64d3a630/" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/reviews/{report_key}": { "post": { "tags": [ "Reviews Analysis" ], "summary": "Get Specific Reviews Analysis Report", "operationId": "getReviewsReport", "description": "Allows you to retrieve the full result of a Reviews Analysis Report from the Local Falcon.\n", "parameters": [ { "name": "report_key", "in": "path", "required": true, "description": "The key of the report you wish to retrieve. Required if not included in parameters.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "report_key": { "type": "string", "description": "The key of the report you wish to retrieve. Required if not included in URL." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "type": "boolean" }, "success": { "type": "boolean" }, "message": { "type": "boolean" }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "type": { "type": "string" }, "report": { "type": "object", "properties": { "date": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "message": { "type": "string" }, "statistics": { "type": "object", "properties": { "bestPerformingBusiness": { "type": "string" }, "worstPerformingBusiness": { "type": "string" }, "rollupHistoricalVelocityValues": { "type": "object", "additionalProperties": { "type": "object", "properties": { "month": { "type": "string" }, "review_count": { "type": "integer" }, "average_star_rating": { "type": "number" } } } } } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "fields": "" }, "data": { "type": "single", "report": { "date": "2025-09-07T13:23:49.139Z", "status": "complete", "progress": 100, "message": "", "statistics": { "bestPerformingBusiness": "ChIJr6qrgkB_MogRzeO1EIeguQU", "worstPerformingBusiness": "ChIJr6qrgkB_MogRzeO1EIeguQU", "rollupHistoricalVelocityValues": { "2022-09": { "month": "2022-09", "review_count": 1, "average_star_rating": 5 }, "2022-10": { "month": "2022-10", "review_count": 2, "average_star_rating": 5 }, "2023-01": { "month": "2023-01", "review_count": 4, "average_star_rating": 5 } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/run-scan/": { "post": { "operationId": "runScan", "tags": [ "Scans & Reports" ], "summary": "Run a Scan", "description": "Run a scan at the specified coordinate point and get ranking data for the specified business using your Local Falcon Credits.\n\nBusinesses used in the scans must already exist inside your Saved Locations in the Local Falcon Dashboard. Use the Save a Business Location to Account endpoint to add new locations before running a scan.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "keyword", "lat", "lng", "grid_size", "radius", "measurement", "platform" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The platform Place ID of the business to match against in results." }, "keyword": { "type": "string", "description": "The desired search term or keyword." }, "lat": { "type": "string", "description": "The data point latitude value." }, "lng": { "type": "string", "description": "The data point longitude value." }, "grid_size": { "type": "string", "description": "The size of your desired grid.", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ] }, "radius": { "type": "string", "description": "The radius of your grid from center point to outer most north/east/south/west point. Expects 0.1 to 100." }, "measurement": { "type": "string", "description": "The measurement unit of your radius.", "enum": [ "mi", "km" ] }, "ai_analysis": { "type": "string", "description": "Whether AI analysis should be generated for this scan. Defaults to false.", "enum": [ "true", "false" ], "default": "false" }, "platform": { "type": "string", "description": "The platform to run the scan against.", "enum": [ "aimode", "apple", "chatgpt", "gaio", "gemini", "google", "grok" ] }, "eager": { "type": "string", "description": "Whether to return a response eagerly within 20 seconds. When true, the API will respond within 20 seconds. When false, the API will wait as long as needed for the scan to complete. Defaults to false.", "enum": [ "true", "false" ], "default": "false" } } } } } }, "responses": { "200": { "description": "Scan completed successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "code_desc": { "example": false }, "success": { "type": "boolean", "example": true }, "message": { "example": false }, "parameters": { "type": "object", "properties": { "type": { "type": "integer", "example": 1 }, "place_id": { "type": "string", "example": "ChIJzdUMEvHTxokRaBwKyttKwlw" }, "keyword": { "type": "string", "example": "home supply store near me" }, "lat": { "type": "string", "example": "39.7292366" }, "lng": { "type": "string", "example": "-75.0357437" }, "grid_size": { "type": "string", "example": "3" }, "distance": { "type": "string", "example": "0.5" }, "measurement": { "type": "string", "example": "mi" }, "platform": { "type": "string", "example": "google" }, "ai_analysis": { "type": "boolean", "example": true } } }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "33ec21769d25069d353b241fb2fe5f35" }, "checksum": { "type": "string", "example": "38be34e80decbc79be975bc2b0fd39b235c5b0726947acb280573159fb9da103" }, "report_key": { "type": "string", "example": "4df21b0fe569354" }, "campaign_report_key": { "example": false }, "timestamp": { "type": "string", "example": "1752850980" }, "date": { "type": "string", "example": "7/18/2025 11:03 AM" }, "looker_date": { "type": "string", "example": "20250718" }, "platform": { "type": "string", "example": "google" }, "place_id": { "type": "string", "example": "ChIJzdUMEvHTxokRaBwKyttKwlw" }, "location": { "type": "object", "properties": { "platform": { "type": "string" }, "place_id": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "rating": { "type": "string" }, "rating_pct": { "type": "string" }, "reviews": { "type": "string" }, "phone": { "type": "string" }, "url": { "type": "string" }, "display_url": { "type": "string" }, "claimed": { "type": "boolean" }, "categories": { "type": "object", "additionalProperties": { "type": "string" } }, "store_code": { "example": false } } }, "keyword": { "type": "string", "example": "home supply store near me" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "grid_size": { "type": "string" }, "radius": { "type": "string" }, "measurement": { "type": "string" }, "points": { "type": "string" }, "found_in": { "type": "string" }, "arp": { "type": "string", "description": "Average Rank Position" }, "atrp": { "type": "string", "description": "Average Top Rank Position" }, "solv": { "type": "string", "description": "Share of Local Voice" }, "unique_competitors": { "type": "integer" }, "image": { "type": "string", "format": "uri" }, "heatmap": { "type": "string", "format": "uri" }, "pdf": { "type": "string", "format": "uri" }, "public_url": { "type": "string", "format": "uri" }, "data_points": { "type": "array", "items": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" }, "found": { "type": "boolean" }, "rank": { "example": false }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object" } } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "type": 1, "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "keyword": "home supply store near me", "lat": "39.7292366", "lng": "-75.0357437", "grid_size": "3", "distance": "0.5", "measurement": "mi", "platform": "google", "ai_analysis": true }, "data": { "id": "33ec21769d25069d353b241fb2fe5f35", "checksum": "38be34e80decbc79be975bc2b0fd39b235c5b0726947acb280573159fb9da103", "report_key": "4df21b0fe569354", "campaign_report_key": false, "timestamp": "1752850980", "date": "7/18/2025 11:03 AM", "looker_date": "20250718", "platform": "google", "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "location": { "platform": "google", "place_id": "ChIJzdUMEvHTxokRaBwKyttKwlw", "lat": "39.7294642", "lng": "-75.0357578", "name": "Walmart Supercenter", "address": "3501 NJ-42, Turnersville, NJ 08012", "rating": "4.000", "rating_pct": "0.800", "reviews": "4509", "phone": "+18566293888", "url": "https://www.walmart.com/store/1742-turnersville-nj/?veh=seo_loc", "display_url": "walmart.com", "claimed": true, "categories": { "electronics_store": "Electronics store", "department_store": "Department store" }, "store_code": false }, "keyword": "home supply store near me", "lat": "39.7292366", "lng": "-75.0357437", "grid_size": "3", "radius": "0.5", "measurement": "mi", "points": "9", "found_in": "0", "arp": "21.00", "atrp": "21.00", "solv": "0.00", "unique_competitors": 34, "image": "https://lf-static-v2.localfalcon.com/image/4df21b0fe569354", "heatmap": "https://lf-static-v2.localfalcon.com/heatmap-img/4df21b0fe569354", "pdf": "https://lf-pdf-ecs.localfalcon.com/scan-report/4df21b0fe569354/018aeaee55712f6/", "public_url": "https://localrankingtracker.com/scan-report/4df21b0fe569354/018aeaee55712f6/", "data_points": [ { "lat": "39.7220081", "lng": "-75.0451426", "found": false, "rank": false, "count": 20, "results": [] } ] } } } } }, "202": { "description": "Scan is still processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "report_key": { "type": "string" }, "status": { "type": "string" } } } } }, "example": { "code": 202, "success": true, "message": "Scan is still processing", "data": { "report_key": "19c96a00485ef96", "status": "processing" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/locations/search": { "post": { "operationId": "searchBusinessLocation", "tags": [ "Locations" ], "summary": "Search for a Business Location", "description": "Returns a list of found Google My Business locations based on search query, including Service Area Businesses (SAB).\n\nThis endpoint runs searches only against Google Maps.\n\nEvery successful location search is charged two (2) credits.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "name" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "name": { "type": "string", "description": "The Business Location Name you want to search for." }, "proximity": { "type": "string", "description": "To narrow your results, you can enter a city, state, country, etc." }, "platform": { "type": "string", "description": "The platform to run the search against. Defaults to 'google'.", "enum": [ "google", "apple" ], "default": "google" } } } } } }, "responses": { "200": { "description": "Business location search results returned successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "", "parameters": { "term": "Walmart", "proximity": "", "platform": "google" }, "data": { "count": 20, "true_count": 20, "results": [ { "platform": "google", "place_id": "ChIJw4zdDvPuMIgRBmtyW-1vnYU", "lat": 41.4202665, "lng": -81.7538936, "name": "Walmart Supercenter", "address": "10000 Brookpark Rd, Cleveland, OH 44130", "sab": false, "rating": "3.700", "rating_pct": 0.74, "reviews": 9687, "categories": { "department_store": "Department store", "grocery_store": "Grocery store" }, "phone": "+12167417340", "url": "https://www.walmart.com/store/2073-cleveland-oh/?veh=seo_loc", "display_url": "walmart.com", "map_link": "https://www.google.com/maps/search/?api=1&query=Walmart+Supercenter&query_place_id=ChIJw4zdDvPuMIgRBmtyW-1vnYU" }, { "platform": "google", "place_id": "ChIJC54X4Lf4W4gRY-GW20plShU", "lat": 35.8380991, "lng": -83.57445659999999, "name": "Walmart Supercenter", "address": "1414 Parkway, Sevierville, TN 37862", "sab": false, "rating": "3.900", "rating_pct": 0.78, "reviews": 17083, "categories": { "department_store": "Department store", "grocery_store": "Grocery store" }, "phone": "+18654290029", "url": "https://www.walmart.com/store/578-sevierville-tn/?veh=seo_loc", "display_url": "walmart.com", "map_link": "https://www.google.com/maps/search/?api=1&query=Walmart+Supercenter&query_place_id=ChIJC54X4Lf4W4gRY-GW20plShU" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/locations/add": { "post": { "operationId": "saveBusinessLocation", "tags": [ "Locations" ], "summary": "Save a Business Location to Account", "description": "Add a Business Location into your Local Falcon Dashboard's Saved Locations.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "platform", "place_id" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "platform": { "type": "string", "description": "The platform to add the location from.", "enum": [ "google", "apple" ] }, "place_id": { "type": "string", "description": "The Business Location ID you want to add." }, "name": { "type": "string", "description": "The Business Location Name. Required if platform is set to 'apple'." }, "lat": { "type": "string", "description": "The center point latitude value. Required if platform is set to 'apple'." }, "lng": { "type": "string", "description": "The center point longitude value. Required if platform is set to 'apple'." } } } } } }, "responses": { "200": { "description": "Location saved successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Your location has been successfully added", "parameters": { "platform": "google", "place_id": "ChIJg9jFhfejz4kRkk0U2WghtAE" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/account": { "post": { "operationId": "viewAccountInformation", "tags": [ "Account" ], "summary": "View Account Information", "description": "Retrieves detailed information about your Local Falcon account including user information, permissions, subscription details, and available credits.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." } } } } } }, "responses": { "200": { "description": "Account information returned successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "", "parameters": [], "data": { "key": "018aeaee55712f6", "email": "success@localfalcon.com", "first_name": "Local", "last_name": "Falcon", "phone": "8147466987", "meta": { "business_name": "Local Falcon", "business_type": "Small / Medium Business", "company_domain": "", "location_count": "1000+", "registration_ip": "", "timezone": "America/New_York", "website": "", "last_login_ip": "49.145.105.233", "user_country": "PH" }, "company": "", "date_registered": "1677159525", "permissions": { "ai_chat_access": false, "ai_scan_reports": true, "api_access": true, "on_demand_api_access": false, "white_label_reports": true }, "api": [], "package": [], "preferences": { "agency_email": "", "agency_logo": "", "agency_url": "", "ai_report_emails": "0", "ai_report_notification": "1", "autoscan_completion_emails": "1", "auto_ai_reports": "1", "date_format_short": "n/j/Y", "map_style": "high", "measurement": "mi", "per_page": "10", "public_domain": "localrankingtracker.com", "scan_completion_emails": "1", "time_format": "g:i A" }, "falcon_guard_subscriber": true, "falcon_guard_seats": "10", "credits": { "credit_package_total": 0, "credit_package_remaining": 0, "total_usable_credits": 4620 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/guard/add": { "post": { "operationId": "addFalconGuard", "tags": [ "Falcon Guard" ], "summary": "Add location(s) to Falcon Guard", "description": "Add one or multiple locations to be protected by Falcon Guard.\n\nWhen protecting locations, each business location needs to have already been added to your Saved Locations in your Local Falcon dashboard.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "Protect one or multiple locations in Falcon Guard. Supports multiple platform Place IDs, separated by commas." } } } } } }, "responses": { "200": { "description": "Location(s) added to Falcon Guard successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Business Location(s) added to Falcon Guard.", "parameters": { "place_id": "ChIJg9jFhfejz4kRkk0U2WghtAE" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/guard/pause": { "post": { "operationId": "pauseFalconGuard", "tags": [ "Falcon Guard" ], "summary": "Pause Location Protection", "description": "Pause protection for one or multiple locations in Falcon Guard.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "guard_key": { "type": "string", "description": "Pause protection for one or multiple locations in Falcon Guard. Supports multiple Falcon Guard report keys, separated by commas." }, "place_id": { "type": "string", "description": "Pause protection for one or multiple locations in Falcon Guard. Supports multiple Google Place IDs, separated by commas. Required if guard_key is blank." } } } } } }, "responses": { "200": { "description": "Falcon Guard protection paused successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Falcon Guard protection paused.", "parameters": { "guard_key": "f285ee441a78abc" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/guard/resume": { "post": { "operationId": "resumeFalconGuard", "tags": [ "Falcon Guard" ], "summary": "Resume Location Protection", "description": "Resume protection for one or multiple locations in Falcon Guard.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "guard_key": { "type": "string", "description": "Resume protection for one or multiple locations in Falcon Guard. Supports multiple Falcon Guard report keys, separated by commas." }, "place_id": { "type": "string", "description": "Resume protection for one or multiple locations in Falcon Guard. Supports multiple Google Place IDs, separated by commas. Required if guard_key is blank." } } } } } }, "responses": { "200": { "description": "Falcon Guard protection resumed successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Falcon Guard protection resumed.", "parameters": { "guard_key": "f67cac38fc34d79" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/guard/delete": { "post": { "operationId": "removeFalconGuard", "tags": [ "Falcon Guard" ], "summary": "Remove Location Protection", "description": "Remove protection for one or multiple locations in Falcon Guard.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "guard_key": { "type": "string", "description": "Remove protection for one or multiple locations in Falcon Guard. Supports multiple Falcon Guard report keys, separated by commas." }, "place_id": { "type": "string", "description": "Remove protection for one or multiple locations in Falcon Guard. Supports multiple Google Place IDs, separated by commas. Required if guard_key is blank." } } } } } }, "responses": { "200": { "description": "Location removed from Falcon Guard successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Location removed from Falcon Guard.", "parameters": { "guard_key": "f285ee441a78abc" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/campaigns/create": { "post": { "operationId": "createCampaign", "tags": [ "Campaigns" ], "summary": "Create a Campaign", "description": "Create a new campaign in Local Falcon. Campaigns allow you to schedule recurring scans for one or multiple locations with one or multiple keywords.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "name", "measurement", "grid_size", "radius", "frequency", "place_id", "keyword", "start_date", "start_time" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "name": { "type": "string", "description": "A name to give the campaign." }, "measurement": { "type": "string", "description": "The measurement unit of your radius.", "enum": [ "mi", "km" ] }, "grid_size": { "type": "string", "description": "The size of your desired grid.", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ] }, "radius": { "type": "string", "description": "The radius of your grid from center point to outer most north/east/south/west point. Expects 0.1 to 100." }, "frequency": { "type": "string", "description": "The specific run frequency for the campaign.", "enum": [ "one-time", "daily", "weekly", "biweekly", "monthly" ] }, "place_id": { "type": "string", "description": "The location(s) to include in the campaign. Supports multiple Google Place IDs, separated by commas." }, "keyword": { "type": "string", "description": "The keyword(s) to run against the campaign locations. Supports multiple keywords, separated by commas." }, "start_date": { "type": "string", "description": "The date when your campaign runs the first time. Expects date formatted as MM/DD/YYYY." }, "start_time": { "type": "string", "description": "The time of day your campaign should run. Expects friendly time formatted like \"9:00 AM\"." }, "ai_analysis": { "type": "string", "description": "Whether campaign scans should include AI analysis.", "enum": [ "0", "1" ] }, "notify": { "type": "string", "description": "Whether email notification should be enabled for the campaign.", "enum": [ "0", "1" ] }, "email_recipients": { "type": "string", "description": "Recipients of email notification. Required if notify is set to 1. Supports multiple email addresses, separated by commas." }, "email_subject": { "type": "string", "description": "Email subject of the email notification. Required if notify is set to 1." }, "email_body": { "type": "string", "description": "Email body of the email notification if notify is set to 1." } } } } } }, "responses": { "200": { "description": "Campaign created successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Campaign successfully created", "parameters": { "name": "Test Campaign", "measurement": "mi", "grid_size": "5", "radius": "10", "frequency": "one-time", "place_id": "ChIJg9jFhfejz4kRkk0U2WghtAE,ChIJUW__IQikz4kRMzHhVYurBuo", "keyword": "groceries near me,home supply store near me", "start_date": "11/05/2025", "start_time": "9:00 AM", "ai_analysis": "0", "notify": "0" }, "data": { "campaign_key": "ceb2085a2c2561a", "campaign_details": { "name": "Test Campaign", "size": "5", "radius": "10.0", "measurement": "mi", "frequency": "0", "ai_analysis": false, "locations": "2", "keywords": "1", "scans": "2", "date": "12/19/2025", "time": "1:21 PM", "next_date": "12/19/2025", "notify": false, "email": { "name": false, "subject": false, "body": false, "replyto": false, "recipients": [ "success@localfalcon.com" ] }, "future_date": "12/19/2025, 1:21 PM", "last_run": false, "readable": { "frequency": "One Time" }, "groups": [] } }, "str_date": "November 05, 2025", "step": "Campaign Details" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/campaigns/update": { "post": { "operationId": "updateCampaign", "tags": [ "Campaigns" ], "summary": "Edit a Campaign", "description": "Edit an existing campaign. The fields required depend on the value of the `action` parameter:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ActionRequired Additional FieldsOptional Additional Fields
update-settings(none)name, size, radius, measurement, ai_analysis, keyword_type, date, time, frequency, notify, email_name, email_replyto, email_subject, email_body, recipients, email_send_ai
add-locationplace_idsize, radius, measurement, platforms
modify-locationplace_idsize, radius, measurement, platforms
remove-locationplace_id(none)
add-keywordkeywordplace_id, keyword_type
update-keywordkeywordplace_id, keyword_type
remove-keywordkeyword(none)
\n\nMany fields accept either a single value or a comma-delimited list of values (for example `place_id`, `keyword`, `platforms`).\n\nA campaign cannot be modified while it is currently running โ€” wait until the run finishes before calling this endpoint.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "campaign_key", "action" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "campaign_key": { "type": "string", "description": "The key of the campaign you wish to edit." }, "action": { "type": "string", "description": "The edit action to perform on the campaign.", "enum": [ "update-settings", "add-location", "modify-location", "remove-location", "add-keyword", "update-keyword", "remove-keyword" ] }, "place_id": { "type": "string", "description": "Google Place ID(s) of the campaign location(s) to act on. Supports a single value or multiple values separated by commas.\n\n- **Required** when `action` is `add-location`, `modify-location`, or `remove-location`.\n- **Optional** when `action` is `add-keyword` or `update-keyword` to scope the keyword(s) to specific location(s) already in the campaign.\n" }, "keyword": { "type": "string", "description": "The keyword(s) to act on. Supports a single value or multiple values separated by commas.\n\n**Required** when `action` is `add-keyword`, `update-keyword`, or `remove-keyword`.\n" }, "size": { "type": "string", "description": "Grid size for the campaign or location. Used with `update-settings`, `add-location`, or `modify-location`.", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ] }, "radius": { "type": "string", "description": "Grid radius from center point to the outermost point. Expects 0.1 to 100. Used with `update-settings`, `add-location`, or `modify-location`." }, "measurement": { "type": "string", "description": "The measurement unit of the radius. Used with `update-settings`, `add-location`, or `modify-location`.", "enum": [ "mi", "km" ] }, "platforms": { "type": "string", "description": "Platforms to enable for the location. Supports a single value or multiple values separated by commas. Used with `add-location` or `modify-location`.\n", "enum": [ "google", "gaio", "gemini", "aimode", "chatgpt", "grok" ] }, "keyword_type": { "type": "string", "description": "The type of keyword(s) being added or modified. Used with `update-settings`, `add-keyword`, or `update-keyword`.\n", "enum": [ "traditional", "ai", "both" ] }, "name": { "type": "string", "description": "Updated name for the campaign. Used with `update-settings`." }, "ai_analysis": { "type": "string", "description": "Whether campaign scans should include AI analysis. Used with `update-settings`.", "enum": [ "0", "1" ] }, "date": { "type": "string", "description": "Next run date for the campaign. Expects `MM/DD/YYYY`. Used with `update-settings`. Must be provided together with `time`." }, "time": { "type": "string", "description": "Next run time for the campaign. Expects friendly time like `\"9:00 AM\"`. Used with `update-settings`. Must be provided together with `date`." }, "frequency": { "type": "string", "description": "Updated run frequency for the campaign. Used with `update-settings`.", "enum": [ "one-time", "daily", "weekly", "biweekly", "monthly" ] }, "notify": { "type": "string", "description": "Whether email notification should be enabled for the campaign. Used with `update-settings`.", "enum": [ "0", "1" ] }, "recipients": { "type": "string", "description": "Recipients of email notifications. Supports multiple email addresses separated by commas. Used with `update-settings`." }, "email_name": { "type": "string", "description": "From-name used on email notifications. Pass `|empty|` to clear the value. Used with `update-settings`." }, "email_replyto": { "type": "string", "description": "Reply-to address used on email notifications. Pass `|empty|` to clear the value. Used with `update-settings`." }, "email_subject": { "type": "string", "description": "Subject line used on email notifications. Pass `|empty|` to clear the value. Used with `update-settings`." }, "email_body": { "type": "string", "description": "Body content used on email notifications. Pass `|empty|` to clear the value. Used with `update-settings`." }, "email_send_ai": { "type": "string", "description": "Whether AI analysis should be included in email notifications. Used with `update-settings`.", "enum": [ "0", "1" ] } } } } } }, "responses": { "200": { "description": "Campaign updated successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Campaign settings updated successfully.", "parameters": { "campaign_key": "742e9e6e76f24a2", "action": "update-settings", "name": "Renamed Campaign" }, "data": { "campaign_key": "742e9e6e76f24a2", "campaign_details": { "name": "Renamed Campaign", "size": "5", "radius": "10.0", "measurement": "mi", "frequency": "0", "ai_analysis": false, "locations": "2", "keywords": "1", "scans": "2", "date": "12/19/2025", "time": "1:21 PM", "next_date": "12/19/2025", "notify": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden โ€” campaign is currently running, or a referenced `place_id` has not been saved to the user's account." }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/campaigns/run": { "post": { "operationId": "runCampaign", "tags": [ "Campaigns" ], "summary": "Manually Run a Campaign", "description": "Manually trigger a Campaign to run immediately.\n\nThe total amount of credits that will be used by calling this endpoint and running the campaign will be checked against your available credits in the Local Falcon Dashboard.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "campaign_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "campaign_key": { "type": "string", "description": "The key of the campaign you wish to run." } } } } } }, "responses": { "200": { "description": "Campaign scans queued successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "60 scans queued successfully.", "parameters": { "campaign_key": "742e9e6e76f24a2" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/campaigns/pause": { "post": { "operationId": "pauseCampaign", "tags": [ "Campaigns" ], "summary": "Pause a Campaign", "description": "Pause a Campaign to stop it from running on its scheduled frequency.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "campaign_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "campaign_key": { "type": "string", "description": "The key of the campaign you wish to pause." } } } } } }, "responses": { "200": { "description": "Campaign paused successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Campaign paused successfully.", "parameters": { "campaign_key": "742e9e6e76f24a2" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/campaigns/resume": { "post": { "operationId": "resumeCampaign", "tags": [ "Campaigns" ], "summary": "Resume a Campaign", "description": "Resume a Campaign from a deactivated or paused status.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "campaign_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "campaign_key": { "type": "string", "description": "The key of the campaign you wish to resume." }, "start_date": { "type": "string", "description": "Resume a campaign and trigger it to run on a specific date. Expects format MM/DD/YYYY." }, "start_time": { "type": "string", "description": "The time of day your campaign should next run. Expects friendly time formatted like \"9:00 AM\"." } } } } } }, "responses": { "200": { "description": "Campaign resumed successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Campaign resumed successfully.", "parameters": { "campaign_key": "742e9e6e76f24a2" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/campaigns/reactivate": { "post": { "operationId": "reactivateCampaign", "tags": [ "Campaigns" ], "summary": "Reactivate a Campaign", "description": "Reactivate a Campaign when it has been deactivated due to insufficient credits.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "campaign_key" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "campaign_key": { "type": "string", "description": "The key of the campaign you wish to reactivate." } } } } } }, "responses": { "200": { "description": "Campaign reactivated successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": "Campaign reactivated successfully.", "parameters": { "campaign_key": "742e9e6e76f24a2" }, "data": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/knowledge-base/{id}": { "get": { "operationId": "getKnowledgeBaseArticle", "tags": [ "Knowledge Base" ], "summary": "Get Single Article", "description": "Returns the full content of a single Knowledge Base article with HTML converted to markdown.\n\nNotes:\n- Content is returned as markdown (converted from HTML on the server).\n- Preserves headings, links, images, lists, bold/italic, and other formatting.\n- Image URLs are fully qualified.\n- The `id` field returns with \"KB\" prefix (e.g., \"KB70\") but the URL path accepts just the number.\n", "parameters": [ { "name": "api_key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Your Local Falcon API key." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The numeric ID of the Knowledge Base article (e.g., 70)." } ], "responses": { "200": { "description": "Article returned successfully.", "content": { "application/json": { "example": { "code": 200, "success": true, "data": { "id": "KB70", "title": "How To Use Local Falcon's AI Reviews Analysis Tool", "summary": "", "content": "Traditional sentiment analysis... [full markdown content]", "categories": [ "Reviews" ], "tags": [ "reviews analysis" ], "views": 82417, "up_votes": 0, "down_votes": 0, "date_created": "1718823798", "date_updated": "1751567728", "date_updated_formatted": "2025-07-03 14:35:28", "date_created_formatted": "2024-06-19 15:03:18" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/knowledge-base/": { "get": { "operationId": "searchKnowledgeBase", "tags": [ "Knowledge Base" ], "summary": "Search / List Articles", "description": "Returns a paginated list of active Knowledge Base articles. Supports keyword search and category filtering.\n\nNotes:\n- Only returns active (published) articles; drafts are excluded.\n- Content field is intentionally omitted to keep payloads lightweight.\n- Use `next_token` from the response to fetch the next page.\n", "parameters": [ { "name": "api_key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Your Local Falcon API key." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search keyword - matches against title and content." }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by category ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10 }, "description": "Results per page (default 10)." }, { "name": "next_token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination token from previous response." } ], "responses": { "200": { "description": "Articles returned successfully.", "content": { "application/json": { "examples": { "listAll": { "summary": "Success - List All", "value": { "code": 200, "success": true, "data": { "total": 74, "count": 10, "next_token": "VDBSSlBRPT0=", "articles": [ { "id": "KB92", "title": "How To Use Share of AI Voice (SAIV)", "summary": "", "categories": [ "Map Scan Tool", "Reporting" ], "tags": [ "saiv" ], "views": 371, "up_votes": 0, "down_votes": 0, "date_created": "1765227725", "date_updated": "1765824506", "date_updated_formatted": "2025-12-15 13:48:26", "date_created_formatted": "2025-12-08 16:02:05" } ] } } }, "search": { "summary": "Success - Search", "value": { "code": 200, "success": true, "data": { "total": 5, "count": 5, "next_token": null, "articles": [ { "id": "KB45", "title": "Billing & Subscription FAQ", "summary": "", "categories": [ "Billing" ], "tags": [ "billing", "subscription" ], "views": 1200, "up_votes": 3, "down_votes": 0 } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/grid/": { "post": { "operationId": "calculateGridPoints", "tags": [ "On-Demand API" ], "summary": "Calculate Grid Points from Base Coordinate", "description": "Returns all calculated coordinate points based on provided geocoordinate center point and distance arguments.\n\nThis endpoint requires on_demand_api_access permission.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "lat", "lng", "grid_size", "radius", "measurement" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "lat": { "type": "string", "description": "The center point latitude value." }, "lng": { "type": "string", "description": "The center point longitude value." }, "grid_size": { "type": "string", "description": "The size of your desired grid.", "enum": [ "3", "5", "7", "9", "11", "13", "15", "17", "19", "21" ] }, "radius": { "type": "string", "description": "The radius of your grid from center point to outer most north/east/south/west point. Expects 0.1 to 100." }, "measurement": { "type": "string", "description": "The measurement unit of your radius.", "enum": [ "mi", "km" ] } } } } } }, "responses": { "200": { "description": "Grid points calculated successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "lat": "40.1419777", "lng": "-74.8225408", "grid_size": "7", "radius": "5", "measurement": "mi" }, "data": [ { "lat": 40.069692964032754, "lng": -74.91709872286705 }, { "lat": 40.093787876021835, "lng": -74.91709872286705 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/places/": { "post": { "operationId": "searchGoogleMyBusinessLocations", "tags": [ "On-Demand API" ], "summary": "Search for Google My Business Locations", "description": "Returns a list of found Google My Business locations based on search query, including Service Area Businesses (SAB).\n\nThis endpoint runs searches only against Google Maps and requires on_demand_api_access permission.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "query" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "query": { "type": "string", "description": "Your search term." }, "near": { "type": "string", "description": "To narrow your results, you can enter a city, state, country, etc." } } } } } }, "responses": { "200": { "description": "Business location search results returned successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "query": "home supply", "near": "Levittown, PA" }, "data": { "count": 20, "suggestions": [ { "place_id": "ChIJvT1tK9m3xokRZqyragH9EdM", "lat": 39.997790699999996, "lng": -75.12491729999999, "name": "PA Home Supply", "address": "300 E Allegheny Ave, Philadelphia, PA 19134", "sab": false, "map_link": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c6b7d92b6d3dbd:0xd311fd016aabac66", "rating": "4.2", "reviews": 128 }, { "place_id": "ChIJg8TgbQ1OwYkRySX_6nDg6cA", "lat": 40.1014039, "lng": -74.8637779, "name": "US Supply Company", "address": "Route 13 & Bath Road, Bristol, PA 19007", "sab": false, "map_link": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c14e0d6de0c483:0xc0e9e070eaff25c9", "rating": "4.5", "reviews": 28 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/result/": { "post": { "operationId": "getBusinessRankingAtCoordinate", "tags": [ "On-Demand API" ], "summary": "Get Business Ranking at Specific Coordinate Point", "description": "Get search results and ranking data at the specified coordinate point for a specified business.\n\nThis endpoint runs searches only against Google Maps and requires on_demand_api_access permission.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "lat", "lng", "keyword" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "lat": { "type": "string", "description": "The data point latitude value." }, "lng": { "type": "string", "description": "The data point longitude value." }, "keyword": { "type": "string", "description": "The desired search term or keyword." }, "zoom": { "type": "string", "description": "Desired zoom level. Expects 0 to 18. Defaults to 13.", "default": "13" } } } } } }, "responses": { "200": { "description": "Ranking data at coordinate returned successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "lat": "40.1419777", "lng": "-74.8225408", "keyword": "home supply store", "zoom": "" }, "data": { "found": false, "rank": false, "count": 20, "results": [ { "rank": 1, "place_id": "ChIJZUCy2B5RwYkR8PNPwVtnGnU", "business": "Ace Hardware", "address": "8730 New Falls Rd, Levittown, PA 19054", "url": "http://www.acehardware.com/mystore/index.jsp?store=03193&cid=localstore03193", "display_url": "acehardware.com", "rating": 4.6, "reviews": 363, "lat": 40.1737982, "lng": -74.83101979999999, "map_url": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c1511ed8b24065:0x751a675bc14ff3f0" }, { "rank": 2, "place_id": "ChIJg8TgbQ1OwYkRySX_6nDg6cA", "business": "US Supply Company", "address": "Route 13 & Bath Road, Bristol, PA 19007", "url": "http://www.ussupply.com/", "display_url": "ussupply.com", "rating": 4.5, "reviews": 28, "lat": 40.1014039, "lng": -74.8637779, "map_url": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c14e0d6de0c483:0xc0e9e070eaff25c9" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/search/": { "post": { "operationId": "keywordSearchAtCoordinate", "tags": [ "On-Demand API" ], "summary": "Keyword Search at a Specific Coordinate Point", "description": "Get search results at the specified coordinate point without any rank comparison data.\n\nThis endpoint runs searches only against Google Maps and requires on_demand_api_access permission.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "lat", "lng", "keyword" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "lat": { "type": "string", "description": "The data point latitude value." }, "lng": { "type": "string", "description": "The data point longitude value." }, "keyword": { "type": "string", "description": "The desired search term or keyword." }, "zoom": { "type": "string", "description": "Desired zoom level. Expects 0 to 18. Defaults to 13.", "default": "13" } } } } } }, "responses": { "200": { "description": "Search results at coordinate returned successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "lat": "40.1419777", "lng": "-74.8225408", "keyword": "home supply store", "zoom": "" }, "data": { "count": 20, "results": [ { "place_id": "ChIJZUCy2B5RwYkR8PNPwVtnGnU", "business": "Ace Hardware", "address": "8730 New Falls Rd, Levittown, PA 19054", "url": "http://www.acehardware.com/mystore/index.jsp?store=03193&cid=localstore03193", "display_url": "acehardware.com", "rating": 4.6, "reviews": 363, "lat": 40.1737982, "lng": -74.83101979999999, "map_url": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c1511ed8b24065:0x751a675bc14ff3f0" }, { "place_id": "ChIJg8TgbQ1OwYkRySX_6nDg6cA", "business": "US Supply Company", "address": "Route 13 & Bath Road, Bristol, PA 19007", "url": "http://www.ussupply.com/", "display_url": "ussupply.com", "rating": 4.5, "reviews": 28, "lat": 40.1014039, "lng": -74.8637779, "map_url": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c14e0d6de0c483:0xc0e9e070eaff25c9" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/scan/": { "post": { "operationId": "runFullGridSearch", "tags": [ "On-Demand API" ], "summary": "Run a Full Grid Search", "description": "Get search results and ranking data for the specified business across a full grid of coordinate points.\n\nThis endpoint runs searches only against Google Maps and requires on_demand_api_access permission.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "keyword", "lat", "lng", "grid_size", "radius", "measurement" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Google Place ID of the business to match against in results." }, "keyword": { "type": "string", "description": "The desired search term or keyword." }, "lat": { "type": "string", "description": "The data point latitude value." }, "lng": { "type": "string", "description": "The data point longitude value." }, "grid_size": { "type": "string", "description": "The size of your desired grid.", "enum": [ "3", "5", "7", "9", "11", "13", "15" ] }, "radius": { "type": "string", "description": "The radius of your grid from center point to outer most north/east/south/west point. Expects 0.1 to 100." }, "measurement": { "type": "string", "description": "The measurement unit of your radius.", "enum": [ "mi", "km" ] } } } } } }, "responses": { "200": { "description": "Full grid search completed successfully.", "content": { "application/json": { "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJ6ULSRklQwYkR_V5GGobrWTc", "keyword": "groceries near me", "lat": "40.1419777", "lng": "-74.8225408", "grid_size": "7", "radius": "5", "measurement": "mi" }, "data": { "points": 49, "found": 25, "percent": 51.02040816326531, "arp": 5.591836734693878, "atrp": 15.877551020408163, "solv": 2.0408163265306123, "results": [ { "lat": 40.069692964032754, "lng": -74.91709872286705, "found": false, "rank": false, "count": 20, "results": [ { "rank": 1, "place_id": "ChIJyXtlfg5MwYkR27568vWUMo8", "business": "ACME Markets", "address": "23 Levitt Pkwy, Willingboro, NJ 08046", "url": "https://local.acmemarkets.com/nj/willingboro/23-levitt-pkwy.html", "display_url": "local.acmemarkets.com", "rating": 3.9, "reviews": 1467, "lat": 40.0515873, "lng": -74.8912802, "map_url": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c14c0e7e657bc9:0x8f3294f5f27abedb" }, { "rank": 2, "place_id": "ChIJ5ziIHR5NwYkRCjikxL5ktWk", "business": "ALDI", "address": "1445 Street Rd, Bensalem, PA 19020", "url": "https://stores.aldi.us/pa/bensalem/1445-street-road", "display_url": "stores.aldi.us", "rating": 4.5, "reviews": 1157, "lat": 40.0904069, "lng": -74.9389672, "map_url": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c14d1e1d8838e7:0x69b564bec4a4380a" } ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } } } }