{ "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": "Manage Google Business Profile", "description": "Read and manage the Google Business Profile behind a connected location: profile details,\nhours, posts, media, services, attributes, action links, reviews and performance metrics.\n\nThese endpoints act on the Google profile directly, so they read and write live data rather\nthan Local Falcon report data. Every one is keyed on `place_id` and works only for locations\nconnected to a Google account in your Local Falcon account. Use **POST /v1/locations/** with\n`gbp_linked` set to `true` to list eligible locations.\n\nData is read from Google at request time, so a call reflects the profile as it stands right\nthen. **POST /v2/gbp/location/** and **POST /v2/gbp/google-updated/** return Google's own\nresource unchanged, so their field names are camelCase; every other endpoint returns\nsnake_case.\n\n**Array and object parameters are sent as form fields, not as JSON.** Index each entry, for\nexample `services[0][name]=Drain cleaning`. A JSON request body is not read.\n\n**Six endpoints require confirmation before they act**, because their effect cannot be\nundone. Send the matching token or the request is rejected with `GBP_CONFIRMATION_REQUIRED`\nand nothing is changed.\n\n| Endpoint | Send |\n|---|---|\n| **POST /v2/gbp/delete-post/** | `confirm=DELETE_POST` |\n| **POST /v2/gbp/delete-media/** | `confirm=DELETE_MEDIA` |\n| **POST /v2/gbp/delete-link/** | `confirm=DELETE_LINK` |\n| **POST /v2/gbp/delete-review-reply/** | `confirm=DELETE_REPLY` |\n| **POST /v2/gbp/update-attributes/** | `confirm=SET_ATTRIBUTES` |\n| **POST /v2/gbp/replace-services/** | `confirm=REPLACE_SERVICES` |\n\n**POST /v2/gbp/update-status/** also requires `confirm=CLOSED_PERMANENTLY` when closing a\nbusiness permanently.\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", "Manage Google Business Profile", "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." }, "gbp_linked": { "type": "boolean", "description": "Only return locations that are connected to a Google Business Profile. Connected locations can be used with the Google Business Profile endpoints." } } } } } }, "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" } }, "gbp_linked": { "type": "boolean", "description": "Whether this location is connected to a Google Business Profile." }, "gbp_location_id": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "The Google Business Profile location resource name, or `false` when not connected." }, "gbp_account_email": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "The email of the connected Google account, or `false` when not connected." } } } } } } } }, "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": [], "gbp_linked": true, "gbp_location_id": "locations/12345678901234567890", "gbp_account_email": "owner@example.com" } ] } } } } }, "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/gbp/location/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Get Business Profile Details", "operationId": "getGbpLocation", "description": "Retrieve the live Google Business Profile details for one of your connected locations, including name, categories, address, hours, website, service items, and profile description.\n\nThe location must be connected to a Google account in your Local Falcon account. Use **POST /v1/locations/** with `gbp_linked` set to `true` to list the locations eligible for this endpoint.\n\nData is read from Google at request time and is returned exactly as Google provides it, so field names are camelCase and the set of fields present varies by business category and by how much of the profile has been filled in.\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": "The Place ID of a connected location." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object", "description": "The Google Business Profile location resource. Returned as provided by Google, so the fields present depend on the business category and on how much of the profile has been completed." } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "name": "locations/12345678901234567890", "title": "Example Plumbing Co.", "phoneNumbers": { "primaryPhone": "(555) 123-4567" }, "categories": { "primaryCategory": { "name": "categories/gcid:plumber", "displayName": "Plumber" } }, "storefrontAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "60525", "administrativeArea": "IL", "locality": "La Grange", "addressLines": [ "100 Main Street" ] }, "websiteUri": "https://www.example.com/", "regularHours": { "periods": [ { "openDay": "MONDAY", "openTime": { "hours": 8 }, "closeDay": "MONDAY", "closeTime": { "hours": 17 } } ] }, "openInfo": { "status": "OPEN", "canReopen": true }, "metadata": { "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4", "mapsUri": "https://maps.google.com/maps?cid=1234567890123456789", "newReviewUri": "https://search.google.com/local/writereview?placeid=ChIJN1t_tDeuEmsRUsoyG83frY4", "hasVoiceOfMerchant": true }, "profile": { "description": "Family owned plumbing company serving the western suburbs since 1998." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/reviews/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Business Profile Reviews", "operationId": "listGbpReviews", "description": "Retrieve live Google Business Profile reviews for one or more connected locations, including the review text, star rating, reviewer name, and any reply already posted.\n\nReviews are read from Google at request time, so they reflect the current state of the profile rather than a Local Falcon snapshot.\n\n**Pagination.** When more reviews exist than the requested `limit`, the response returns a `next_token`. Pass that value back as `next_token` on the following request to retrieve the next page. On the final page `next_token` is returned as `false`. The token in a response always points at the next page, so continue until `next_token` is `false` rather than comparing tokens.\n\n**Filtering.** `unanswered` and `rating` are applied after the reviews are read from Google, so a filtered page may require several reads to fill. A filtered request walks up to 10 pages of Google results before returning what it has found.\n\n**Single review.** Supplying `review_id` returns just that review and ignores `limit`, `unanswered`, `rating`, and `next_token`.\n\n**Multiple locations.** `place_id` accepts up to 10 comma separated Place IDs. Each location is returned as its own entry under `locations`, and a location that fails returns `error` and `message` on its own entry rather than failing the whole request. `next_token` can only be used with a single Place ID.\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": "The Place ID of a connected location. Up to 10 comma separated Place IDs may be supplied." }, "review_id": { "type": "string", "description": "Retrieve a single review by its ID. When supplied, all other filter and pagination parameters are ignored." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "The number of reviews you wish to retrieve per location." }, "unanswered": { "type": "boolean", "description": "Only return reviews that do not yet have a reply." }, "rating": { "type": "string", "description": "Comma separated star ratings to include, from 1 to 5. For example, `1,2` returns only one and two star reviews." }, "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. Can only be used with a single Place ID." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of locations returned." }, "locations": { "type": "array", "items": { "type": "object", "properties": { "place_id": { "type": "string" }, "total_reviews": { "type": "integer", "description": "The total number of reviews on the profile, before any filtering." }, "average_rating": { "type": "string", "description": "The average rating across every review on the profile, formatted to three decimal places. Returned as a string." }, "count": { "type": "integer", "description": "The number of reviews returned on this page." }, "next_token": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "Token for the next page of results, or `false` when no further pages exist." }, "error": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "Error code, present only when reviews for this location could not be retrieved." }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "Error description, present only when reviews for this location could not be retrieved." }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": "string" }, "rating": { "type": "integer" }, "comment": { "type": "string", "nullable": true, "description": "The review text. Returned as `null` when the reviewer left a rating with no comment." }, "reviewer": { "type": "string" }, "reviewer_photo": { "type": "string" }, "date_created": { "type": "string" }, "date_updated": { "type": "string" }, "reply": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "The reply currently posted to this review, or `false` when there is none." }, "reply_date": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] } } } } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "unanswered": "1" }, "data": { "count": 1, "locations": [ { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "total_reviews": 43, "average_rating": "4.900", "count": 2, "next_token": "VVZWS1NWVnJlRmxXYXpoMFRraGtWV0Y2U205a1ZGRXhXVlZhUkZFeU9IbFZSbVI1", "reviews": [ { "review_id": "AbFvOqkORHz5CjZJDcSW9EcpiIomZZhA4nbvgER4PSFBmydugbfw94KegP", "rating": 5, "comment": "Quick, tidy, and fairly priced. Would use them again.", "reviewer": "Jordan Avery", "reviewer_photo": "https://lh3.googleusercontent.com/a/example=s120-c-rp-mo-br100", "date_created": "2026-08-17T01:32:12.436625Z", "date_updated": "2026-08-17T01:32:12.436625Z", "reply": false, "reply_date": false }, { "review_id": "AbFvOqlra4JAMUPTe_cF-6ATiAjmpL7tX8j7pNictad87iCMMBIsIlRkBO", "rating": 4, "comment": null, "reviewer": "Sam Okonkwo", "reviewer_photo": "https://lh3.googleusercontent.com/a/example=s120-c-rp-mo-br100", "date_created": "2026-07-26T19:33:15.885082Z", "date_updated": "2026-07-26T19:33:15.885082Z", "reply": false, "reply_date": false } ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/reply-review/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Reply to Business Profile Reviews", "operationId": "replyToGbpReviews", "description": "Post a reply to one or more Google Business Profile reviews. Replies are published to Google immediately and are publicly visible on the business profile.\n\nPosting a reply to a review that already has one replaces the existing reply.\n\n**Single reply.** Supply `place_id`, `review_id`, and `reply`.\n\n**Multiple replies.** Supply a `replies` array of up to 50 entries, each containing `place_id`, `review_id`, and `reply`. Entries may span different locations.\n\nEach reply is attempted independently. The response returns one entry per reply under `results`, along with `succeeded` and `failed` counts, so a failure on one reply does not prevent the others from posting. Replies are limited to 4096 characters.\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." }, "place_id": { "type": "string", "description": "The Place ID of a connected location. Required unless `replies` is supplied." }, "review_id": { "type": "string", "description": "The ID of the review to reply to. Required unless `replies` is supplied." }, "reply": { "type": "string", "maxLength": 4096, "description": "The reply text to publish. Required unless `replies` is supplied." }, "replies": { "type": "array", "maxItems": 50, "description": "An array of up to 50 replies, used instead of the single `place_id`, `review_id`, and `reply` parameters.", "items": { "type": "object", "required": [ "place_id", "review_id", "reply" ], "properties": { "place_id": { "type": "string" }, "review_id": { "type": "string" }, "reply": { "type": "string", "maxLength": 4096 } } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of replies attempted." }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "place_id": { "type": "string" }, "review_id": { "type": "string" }, "success": { "type": "boolean" }, "error": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "Error code, or `false` when the reply posted successfully." }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "Error description, or `false` when the reply posted successfully." }, "reply": { "type": "string", "description": "The reply text that was published. Present only on success." } } } } } } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "review_id": "AbFvOqkORHz5CjZJDcSW9EcpiIomZZhA4nbvgER4PSFBmydugbfw94KegP" }, "data": { "count": 1, "succeeded": 1, "failed": 0, "results": [ { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "review_id": "AbFvOqkORHz5CjZJDcSW9EcpiIomZZhA4nbvgER4PSFBmydugbfw94KegP", "success": true, "error": false, "message": false, "reply": "Thank you for the kind words, Jordan. We appreciate you taking the time to share this." } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/posts/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Business Profile Posts", "operationId": "listGbpPosts", "description": "List the posts published to a connected Google Business Profile.\n\nThe location must be connected to a Google account in your Local Falcon account. Use **POST /v1/locations/** with `gbp_linked` set to `true` to list the locations eligible for this endpoint.\n\nWhen more results exist the response carries a `next_token`. Pass it back as `next_token` to fetch the next page. When it is absent you have reached the end.\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": "The Place ID of a connected location." }, "post_id": { "type": "string", "description": "Retrieve a single post instead of a list." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." }, "next_token": { "type": "string", "description": "Page token from a previous response." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "limit": "2" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 2, "next_token": "CAESBkNBSVFBUQ", "posts": [ { "post_id": "7421632958301234567", "topic_type": "STANDARD", "language": "en", "summary": "Spring service checks are now open for booking.", "state": "LIVE", "search_url": "https://local.google.com/place?id=14788312141758070090&use=posts", "date_created": "2026-03-04T14:02:11.521182Z", "date_updated": "2026-03-04T14:02:11.521182Z", "media": [ { "name": "accounts/107534376805956115765/locations/2314871951955594566/media/localPosts/AF1QipPExampleMediaIdentifier", "media_format": "PHOTO", "google_url": "https://lh3.googleusercontent.com/p/AF1QipPExampleMediaIdentifier" } ], "call_to_action": { "action_type": "LEARN_MORE", "url": "https://www.example.com/" } }, { "post_id": "4291212913301234567", "topic_type": "OFFER", "language": "en", "summary": "10% off first visit.", "state": "LIVE", "search_url": "https://local.google.com/place?id=14788312141758070090&use=posts", "date_created": "2026-02-18T09:15:00.204118Z", "date_updated": "2026-02-18T09:15:00.204118Z", "offer": { "coupon_code": "FIRST10", "redeem_online_url": "https://www.example.com/offer" }, "event": { "title": "First visit discount", "schedule": { "start_date": { "year": 2026, "month": 2, "day": 18 }, "start_time": { "hours": 0 }, "end_date": { "year": 2026, "month": 3, "day": 18 }, "end_time": { "hours": 23, "minutes": 59, "seconds": 59 } } } } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/create-post/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Create a Business Profile Post", "operationId": "createGbpPost", "description": "Publish a post to a connected Google Business Profile.\n\nThe location must be connected to a Google account in your Local Falcon account. Use **POST /v1/locations/** with `gbp_linked` set to `true` to list the locations eligible for this endpoint.\n\n`event` is required when `topic_type` is `EVENT`, and `offer` is required when it is `OFFER`.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\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": "The Place ID of a connected location." }, "summary": { "type": "string", "description": "Post text, up to 1500 characters." }, "topic_type": { "type": "string", "description": "One of `STANDARD`, `EVENT`, `OFFER` or `ALERT`. Defaults to `STANDARD`." }, "call_to_action": { "type": "string", "description": "Optional button, with `action_type` and `url`. For example `call_to_action[action_type]=BOOK`." }, "media": { "type": "string", "description": "Optional media items, each with `media_format` and `source_url`." }, "event": { "type": "string", "description": "Event details. Required when `topic_type` is `EVENT`." }, "offer": { "type": "string", "description": "Offer details. Required when `topic_type` is `OFFER`." }, "language": { "type": "string", "description": "Language code. Defaults to `en`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "summary": "Spring service checks are now open for booking.", "topic_type": "STANDARD" }, "data": { "post_id": "7421632958301234567", "name": "accounts/107534376805956115765/locations/2314871951955594566/localPosts/7421632958301234567", "topic_type": "STANDARD", "summary": "Spring service checks are now open for booking.", "state": "LIVE", "search_url": "https://local.google.com/place?id=14788312141758070090&use=posts" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/update-post/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Update a Business Profile Post", "operationId": "updateGbpPost", "description": "Update an existing post on a connected Google Business Profile.\n\nFields you do not send are left as they are. Use `replace` to write a field wholesale instead of merging it. Sending `media` replaces every media item on the post.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "post_id" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "post_id": { "type": "string", "description": "The post to update." }, "summary": { "type": "string", "description": "Post text, up to 1500 characters." }, "call_to_action": { "type": "string", "description": "Button, with `action_type` and `url`." }, "media": { "type": "string", "description": "Replaces every media item on the post." }, "event": { "type": "string", "description": "Event details." }, "offer": { "type": "string", "description": "Offer details." }, "replace": { "type": "string", "description": "Comma separated field names to write wholesale rather than merge." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "post_id": "7421632958301234567", "summary": "Updated: spring service checks are open." }, "data": { "post_id": "7421632958301234567", "topic_type": "STANDARD", "summary": "Updated: spring service checks are open.", "state": "LIVE" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/delete-post/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Delete a Business Profile Post", "operationId": "deleteGbpPost", "description": "Delete a post from a connected Google Business Profile.\n\n**This endpoint requires confirmation.** Deleting a post cannot be undone. You must send `confirm=DELETE_POST` or the request is rejected with `GBP_CONFIRMATION_REQUIRED` and nothing is changed.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "post_id", "confirm" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "post_id": { "type": "string", "description": "The post to delete." }, "confirm": { "type": "string", "description": "Must be `DELETE_POST`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "post_id": "7421632958301234567", "confirm": "DELETE_POST" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "post_id": "7421632958301234567", "deleted": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/media/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Business Profile Media", "operationId": "listGbpMedia", "description": "List the photos and videos on a connected Google Business Profile.\n\nThe location must be connected to a Google account in your Local Falcon account. Use **POST /v1/locations/** with `gbp_linked` set to `true` to list the locations eligible for this endpoint.\n\nWhen more results exist the response carries a `next_token`. Pass it back as `next_token` to fetch the next page. When it is absent you have reached the end.\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": "The Place ID of a connected location." }, "media_id": { "type": "string", "description": "Retrieve a single media item instead of a list." }, "category": { "type": "string", "description": "Filter by category, for example `INTERIOR` or `LOGO`." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." }, "next_token": { "type": "string", "description": "Page token from a previous response." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "limit": "1" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 1, "next_token": "CAISBkNBSVFBUQ", "media": [ { "media_id": "AF1QipMExampleMediaIdentifier", "name": "accounts/107534376805956115765/locations/2314871951955594566/media/AF1QipMExampleMediaIdentifier", "media_format": "PHOTO", "category": "INTERIOR", "google_url": "https://lh3.googleusercontent.com/example", "thumbnail_url": "https://lh3.googleusercontent.com/example=s0", "source_url": false, "description": "Front counter", "date_created": "2025-11-02T18:44:07Z", "view_count": false } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/customer-media/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Customer Media", "operationId": "listGbpCustomerMedia", "description": "List the photos customers have added to a connected Google Business Profile. These are read only.\n\nWhen more results exist the response carries a `next_token`. Pass it back as `next_token` to fetch the next page. When it is absent you have reached the end.\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": "The Place ID of a connected location." }, "media_id": { "type": "string", "description": "Retrieve a single item instead of a list." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." }, "next_token": { "type": "string", "description": "Page token from a previous response." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "limit": "1" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 1, "next_token": "CAISBkNBSVFBUQ", "media": [ { "media_id": "CIHM0ogKEICAgIDExampleCustomerMedia", "name": "accounts/104510682491900620442/locations/8470462391924523650/media/customers/CIHM0ogKEICAgIDExampleCustomerMedia", "media_format": "PHOTO", "category": false, "google_url": "https://lh3.googleusercontent.com/gpms-cs-s/AFP8RcExample=s0", "thumbnail_url": "https://lh3.googleusercontent.com/gpms-cs-s/AFP8RcExample=s300", "source_url": false, "description": false, "date_created": "2026-01-19T21:03:55Z", "view_count": false } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/create-media/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Add Business Profile Media", "operationId": "createGbpMedia", "description": "Add a photo or video to a connected Google Business Profile.\n\nGoogle fetches the file from `source_url`, so it must be publicly reachable. `description` cannot be changed afterwards.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "media_format", "source_url", "category" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "media_format": { "type": "string", "description": "`PHOTO` or `VIDEO`." }, "source_url": { "type": "string", "description": "Public URL Google can fetch the file from." }, "category": { "type": "string", "description": "Category to file the item under, for example `INTERIOR`, `LOGO` or `COVER`." }, "description": { "type": "string", "description": "Optional description. Cannot be changed later." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "media_format": "PHOTO", "source_url": "https://www.example.com/storefront.jpg", "category": "EXTERIOR" }, "data": { "media_id": "AF1QipMExampleMediaIdentifier", "media_format": "PHOTO", "category": "EXTERIOR", "google_url": "https://lh3.googleusercontent.com/example" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/update-media/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Recategorise Business Profile Media", "operationId": "updateGbpMedia", "description": "Move a photo or video into a different category on a connected Google Business Profile.\n\nOnly the category can be changed. `COVER` and `PROFILE` are not accepted here.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "media_id", "category" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "media_id": { "type": "string", "description": "The media item to recategorise." }, "category": { "type": "string", "description": "New category. Cannot be `COVER` or `PROFILE`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "media_id": "AF1QipMExampleMediaIdentifier", "category": "INTERIOR" }, "data": { "media_id": "AF1QipMExampleMediaIdentifier", "media_format": "PHOTO", "category": "INTERIOR" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/delete-media/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Delete Business Profile Media", "operationId": "deleteGbpMedia", "description": "Delete a photo or video from a connected Google Business Profile.\n\n**This endpoint requires confirmation.** Deleting media cannot be undone. You must send `confirm=DELETE_MEDIA` or the request is rejected with `GBP_CONFIRMATION_REQUIRED` and nothing is changed.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "media_id", "confirm" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "media_id": { "type": "string", "description": "The media item to delete." }, "confirm": { "type": "string", "description": "Must be `DELETE_MEDIA`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "media_id": "AF1QipMExampleMediaIdentifier", "confirm": "DELETE_MEDIA" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "media_id": "AF1QipMExampleMediaIdentifier", "deleted": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/links/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Business Profile Action Links", "operationId": "listGbpLinks", "description": "List the action links on a connected Google Business Profile, such as booking or ordering buttons.\n\nLinks Google sourced from a third party aggregator come back with `is_editable` set to false and cannot be changed or removed through this API.\n\nWhen more results exist the response carries a `next_token`. Pass it back as `next_token` to fetch the next page. When it is absent you have reached the end.\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": "The Place ID of a connected location." }, "link_id": { "type": "string", "description": "Retrieve a single link instead of a list." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." }, "next_token": { "type": "string", "description": "Page token from a previous response." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "limit": "1" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 1, "next_token": false, "links": [ { "link_id": "cdcb959b9f5ed00b", "name": "locations/2516212120133929686/placeActionLinks/cdcb959b9f5ed00b", "action_type": "APPOINTMENT", "uri": "https://www.example.com/book", "is_preferred": true, "is_editable": true, "provider_type": "MERCHANT", "date_created": "2025-09-25T23:20:57.156743Z", "date_updated": "2026-08-20T01:45:15.961087Z" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/action-types/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Available Action Link Types", "operationId": "listGbpActionTypes", "description": "List the action link types a connected location is allowed to use. Use this before **POST /v2/gbp/create-link/**, because the valid set depends on the location's category.\n\nWhen more results exist the response carries a `next_token`. Pass it back as `next_token` to fetch the next page. When it is absent you have reached the end.\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": "The Place ID of a connected location. Used to select which Google account the lookup runs against." }, "language": { "type": "string", "description": "Language code. Defaults to `en`." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." }, "next_token": { "type": "string", "description": "Page token from a previous response." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "limit": "3" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 3, "next_token": false, "action_types": [ { "place_action_type": "APPOINTMENT", "display_name": "Appointment links" }, { "place_action_type": "ONLINE_APPOINTMENT", "display_name": "Online appointment links" }, { "place_action_type": "DINING_RESERVATION", "display_name": "Dining reservation links" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/create-link/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Add a Business Profile Action Link", "operationId": "createGbpLink", "description": "Add an action link to a connected Google Business Profile.\n\n`action_type` must be one the location supports. Call **POST /v2/gbp/action-types/** first to see the valid set.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "action_type" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "action_type": { "type": "string", "description": "Action type, for example `APPOINTMENT` or `FOOD_ORDERING`." }, "uri": { "type": "string", "description": "Where the button sends people." }, "is_preferred": { "type": "string", "description": "Whether this is the preferred link for its type." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "action_type": "APPOINTMENT", "uri": "https://www.example.com/book" }, "data": { "link_id": "cdcb959b9f5ed00b", "action_type": "APPOINTMENT", "uri": "https://www.example.com/book", "is_preferred": false, "is_editable": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/update-link/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Update a Business Profile Action Link", "operationId": "updateGbpLink", "description": "Change an action link on a connected Google Business Profile.\n\nFields you do not send are left as they are. Links with `is_editable` set to false cannot be changed.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "link_id" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "link_id": { "type": "string", "description": "The link to change." }, "uri": { "type": "string", "description": "New destination." }, "is_preferred": { "type": "string", "description": "Whether this is the preferred link for its type." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "link_id": "cdcb959b9f5ed00b", "uri": "https://www.example.com/appointments" }, "data": { "link_id": "cdcb959b9f5ed00b", "action_type": "APPOINTMENT", "uri": "https://www.example.com/appointments", "is_preferred": false, "is_editable": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/delete-link/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Delete a Business Profile Action Link", "operationId": "deleteGbpLink", "description": "Remove an action link from a connected Google Business Profile.\n\n**This endpoint requires confirmation.** Deleting a link cannot be undone. You must send `confirm=DELETE_LINK` or the request is rejected with `GBP_CONFIRMATION_REQUIRED` and nothing is changed.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "link_id", "confirm" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "link_id": { "type": "string", "description": "The link to remove." }, "confirm": { "type": "string", "description": "Must be `DELETE_LINK`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "link_id": "cdcb959b9f5ed00b", "confirm": "DELETE_LINK" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "link_id": "cdcb959b9f5ed00b", "deleted": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/services/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Business Profile Services", "operationId": "listGbpServices", "description": "List the services on a connected Google Business Profile.\n\nA service is either free form, where `name` is the label you chose, or structured, where Google supplies the service type. For a structured service `service_type_id` is populated and `name` carries the same identifier. `structured` tells the two apart.\n\nThe value in `name` is the matching key used by **add-services**, **remove-services** and **replace-services**.\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": "The Place ID of a connected location." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 2, "services": [ { "name": "Drain cleaning", "service_type_id": false, "description": false, "structured": false, "price": false }, { "name": "job_type_id:water_heater_repair", "service_type_id": "job_type_id:water_heater_repair", "description": "Repair and replacement for gas and electric water heaters.", "structured": true, "price": false } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/add-services/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Add Business Profile Services", "operationId": "addGbpServices", "description": "Add services to a connected Google Business Profile, keeping the ones already there.\n\nEach entry needs either a `name` for a free form service or a `service_type_id` for a structured one.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "services" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "services": { "type": "string", "description": "Services to add. Each with a `name` or a `service_type_id`, plus optional `description` and `price`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 3, "added": 1, "services": [ { "name": "Drain cleaning", "structured": false }, { "name": "Leak detection", "structured": false }, { "name": "job_type_id:water_heater_repair", "service_type_id": "job_type_id:water_heater_repair", "structured": true } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/remove-services/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Remove Business Profile Services", "operationId": "removeGbpServices", "description": "Remove named services from a connected Google Business Profile, keeping the rest.\n\nNames are matched without regard to case, against the `name` returned by **POST /v2/gbp/services/**.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "names" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "names": { "type": "string", "description": "Service names to remove, for example `names[0]=Drain cleaning`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 1, "removed": 1, "services": [ { "name": "Leak detection", "structured": false } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/replace-services/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Replace Business Profile Services", "operationId": "replaceGbpServices", "description": "Replace the entire service list on a connected Google Business Profile.\n\n**This endpoint requires confirmation.** Everything not present in the list you send is discarded and cannot be recovered. You must send `confirm=REPLACE_SERVICES` or the request is rejected with `GBP_CONFIRMATION_REQUIRED` and nothing is changed.\n\nAn empty list is rejected. To clear every service, clear `serviceItems` through **POST /v2/gbp/update-location/**.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "services", "confirm" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "services": { "type": "string", "description": "The complete list. Each with a `name` or a `service_type_id`, plus optional `description` and `price`." }, "confirm": { "type": "string", "description": "Must be `REPLACE_SERVICES`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "confirm": "REPLACE_SERVICES" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 1, "services": [ { "name": "Drain cleaning", "structured": false } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/attributes/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Get Business Profile Attributes", "operationId": "getGbpAttributes", "description": "List the attributes currently set on a connected Google Business Profile.\n\nOnly attributes that have a value are returned. To see everything that could be set, call **POST /v2/gbp/attribute-metadata/**.\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": "The Place ID of a connected location." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 2, "attributes": [ { "name": "attributes/has_wheelchair_accessible_entrance", "value_type": "BOOL", "values": [ true ] }, { "name": "attributes/is_small_business", "value_type": "BOOL", "values": [ true ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/update-attributes/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Set Business Profile Attributes", "operationId": "updateGbpAttributes", "description": "Set attributes on a connected Google Business Profile.\n\n**This endpoint requires confirmation.** An attribute can be set or changed but not removed: sending false records an explicit negative rather than clearing it. You must send `confirm=SET_ATTRIBUTES` or the request is rejected with `GBP_CONFIRMATION_REQUIRED` and nothing is changed.\n\nThis matters most for the identity attributes, such as `is_small_business` or the owned-by set, where a value you did not intend is a public claim about the business that this API cannot withdraw.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "attributes", "confirm" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "attributes": { "type": "string", "description": "Each with a `name` and one of `values`, `set_values`, `unset_values` or `uris`. For example `attributes[0][name]=has_wifi&attributes[0][value]=true`." }, "confirm": { "type": "string", "description": "Must be `SET_ATTRIBUTES`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "confirm": "SET_ATTRIBUTES" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "count": 1, "attributes": [ { "name": "attributes/has_wifi", "value_type": "BOOL", "values": [ true ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/attribute-metadata/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "List Available Attributes", "operationId": "listGbpAttributeMetadata", "description": "List the attributes available for a category and region, with their display names and accepted values. Use this to discover what **POST /v2/gbp/update-attributes/** will accept.\n\n`category` must carry the `gcid:` prefix, for example `gcid:plumber`. A value without it is rejected.\n\nWhen more results exist the response carries a `next_token`. Pass it back as `next_token` to fetch the next page. When it is absent you have reached the end.\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": "The Place ID of a connected location. Used to select which Google account the lookup runs against." }, "category": { "type": "string", "description": "Category name, including the prefix, for example `gcid:plumber`." }, "region_code": { "type": "string", "description": "Two letter country code. Defaults to the country of the location." }, "language": { "type": "string", "description": "Language code. Defaults to `en`." }, "show_all": { "type": "string", "description": "Return every attribute rather than only those for the category." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." }, "next_token": { "type": "string", "description": "Page token from a previous response." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "category": "gcid:plumber", "limit": "2" }, "data": { "region_code": "US", "language": "en", "count": 2, "next_token": "ABHRLXVExampleContinuationToken", "attributes": [ { "parent": "attributes/has_wheelchair_accessible_entrance", "value_type": "BOOL", "display_name": "Wheelchair accessible entrance", "group_display_name": "Accessibility", "value_metadata": [ { "value": true, "display_name": "Has wheelchair accessible entrance" } ] }, { "parent": "attributes/is_small_business", "value_type": "BOOL", "display_name": "Identifies as small business", "group_display_name": "From the business", "value_metadata": [ { "value": true, "display_name": "Identifies as small business" } ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/categories/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Search Business Profile Categories", "operationId": "listGbpCategories", "description": "Search the Google Business Profile category list, or look up specific categories by name.\n\nUse `query` to search, or `names` to fetch known categories directly. Each result carries the `more_hours_types` that category supports, which is what **POST /v2/gbp/update-hours/** accepts as a special hours type.\n\nWhen more results exist the response carries a `next_token`. Pass it back as `next_token` to fetch the next page. When it is absent you have reached the end.\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": "The Place ID of a connected location. Used to select which Google account the lookup runs against." }, "query": { "type": "string", "description": "Text to search categories for." }, "region_code": { "type": "string", "description": "Two letter country code. Defaults to the country of the location." }, "language": { "type": "string", "description": "Language code. Defaults to `en`." }, "names": { "type": "string", "description": "Comma separated category names to look up directly, for example `gcid:plumber`." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." }, "next_token": { "type": "string", "description": "Page token from a previous response." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "query": "plumb", "limit": "1" }, "data": { "region_code": "US", "language": "en", "count": 1, "next_token": "ABHRLXVExampleContinuationToken", "categories": [ { "name": "categories/gcid:plumber", "display_name": "Plumber", "more_hours_types": [ { "hours_type_id": "ONLINE_SERVICE_HOURS", "display_name": "Online service hours", "localized_display_name": "Online service hours" } ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/chains/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Search Business Profile Chains", "operationId": "listGbpChains", "description": "Search the Google chain list, or retrieve one chain by identifier. `chain_names` and `websites` are arrays, because Google holds a localised name and a regional site per market.\n\nResult order is not guaranteed to be stable between identical requests.\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": "The Place ID of a connected location. Used to select which Google account the lookup runs against." }, "query": { "type": "string", "description": "Chain name to search for." }, "chain_id": { "type": "string", "description": "Retrieve a single chain instead of searching." }, "limit": { "type": "integer", "description": "Number of results to return, 1 to 100. Values outside that range are rejected. Omit to use the default." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "query": "example", "limit": "1" }, "data": { "count": 1, "chains": [ { "name": "chains/ExampleChainIdentifier", "chain_names": [ { "display_name": "Example Chain", "language_code": "en" }, { "display_name": "Example Chain", "language_code": "fr" } ], "websites": [ { "uri": "https://www.example.com/" }, { "uri": "https://www.example.fr/" } ], "location_count": 412 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/verification/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Get Business Profile Verification Status", "operationId": "getGbpVerification", "description": "Get the verification standing of a connected Google Business Profile.\n\n`has_voice_of_merchant` is the practical signal: when it is false the profile is not fully in the merchant's control and some writes will be refused by Google. `guideline_issues` is true when Google has flagged the profile, with the reason in `guideline_reason`.\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": "The Place ID of a connected location." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "has_voice_of_merchant": true, "has_business_authority": true, "needs_verification": false, "ownership_conflict": false, "guideline_issues": false, "guideline_reason": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/google-updated/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Get Google's Version of a Profile", "operationId": "getGbpGoogleUpdated", "description": "Get the version of a profile that Google itself holds, alongside the list of fields that differ from yours.\n\nGoogle applies its own edits to a profile from other signals. `has_changes` tells you whether Google's version differs from yours, and `changed` lists the fields that have diverged. When nothing has diverged, `has_changes` is `false` and `changed` is an empty array.\n\nAs with **POST /v2/gbp/location/**, `location` is returned as Google provides it, so its field names are camelCase.\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": "The Place ID of a connected location." }, "fields_mask": { "type": "string", "description": "Comma separated fields to compare. Defaults to the same set as the location endpoint." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "has_changes": true, "changed": [ "regularHours", "phoneNumbers" ], "location": { "name": "locations/12345678901234567890", "languageCode": "en", "storeCode": "STORE-01", "title": "Example Plumbing Co.", "phoneNumbers": { "primaryPhone": "(555) 987-6543" }, "regularHours": { "periods": [ { "openDay": "MONDAY", "openTime": { "hours": 0 }, "closeDay": "MONDAY", "closeTime": { "hours": 17 } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/metrics/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Get Business Profile Performance Metrics", "operationId": "getGbpMetrics", "description": "Get daily performance metrics for a connected Google Business Profile.\n\n`metrics` lists the metric names covered, `totals` gives the sum per metric across the range, and `days` carries one entry per date with a value for every metric. `totals` equals the sum of the daily values.\n\nGoogle holds roughly 18 months of history and the most recent few days are usually not yet available. Days with no data are returned as zero.\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": "The Place ID of a connected location." }, "metrics": { "type": "string", "description": "Comma separated metric names. Defaults to every available metric." }, "start_date": { "type": "string", "description": "First day to report, `YYYY-MM-DD`." }, "end_date": { "type": "string", "description": "Last day to report, `YYYY-MM-DD`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "start_date": "2026-08-01", "end_date": "2026-08-03" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "start_date": "2026-08-01", "end_date": "2026-08-03", "metrics": [ "BUSINESS_IMPRESSIONS_DESKTOP_MAPS", "BUSINESS_IMPRESSIONS_MOBILE_MAPS", "BUSINESS_IMPRESSIONS_DESKTOP_SEARCH", "BUSINESS_IMPRESSIONS_MOBILE_SEARCH" ], "totals": { "BUSINESS_IMPRESSIONS_DESKTOP_MAPS": 1442, "BUSINESS_IMPRESSIONS_MOBILE_MAPS": 3610, "BUSINESS_IMPRESSIONS_DESKTOP_SEARCH": 289, "BUSINESS_IMPRESSIONS_MOBILE_SEARCH": 1104 }, "count": 3, "days": [ { "date": "2026-08-01", "metrics": { "BUSINESS_IMPRESSIONS_DESKTOP_MAPS": 501, "BUSINESS_IMPRESSIONS_MOBILE_MAPS": 1233, "BUSINESS_IMPRESSIONS_DESKTOP_SEARCH": 96, "BUSINESS_IMPRESSIONS_MOBILE_SEARCH": 372 } }, { "date": "2026-08-02", "metrics": { "BUSINESS_IMPRESSIONS_DESKTOP_MAPS": 460, "BUSINESS_IMPRESSIONS_MOBILE_MAPS": 1188, "BUSINESS_IMPRESSIONS_DESKTOP_SEARCH": 91, "BUSINESS_IMPRESSIONS_MOBILE_SEARCH": 361 } }, { "date": "2026-08-03", "metrics": { "BUSINESS_IMPRESSIONS_DESKTOP_MAPS": 481, "BUSINESS_IMPRESSIONS_MOBILE_MAPS": 1189, "BUSINESS_IMPRESSIONS_DESKTOP_SEARCH": 102, "BUSINESS_IMPRESSIONS_MOBILE_SEARCH": 371 } } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/update-location/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Update Business Profile Details", "operationId": "updateGbpLocation", "description": "Update the Google Business Profile details of a connected location.\n\nFields are merged: anything you do not send is left as it is. Use `replace` to write a field wholesale instead, and `clear` to empty one.\n\n`updates` is keyed by Google field name, for example `updates[title]` or `updates[profile][description]`.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\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": "The Place ID of a connected location." }, "updates": { "type": "string", "description": "Fields to update, keyed by Google field name." }, "clear": { "type": "string", "description": "Comma separated field names to clear." }, "replace": { "type": "string", "description": "Comma separated field names to write wholesale rather than merge." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "updated": "title,profile.description", "location": { "name": "locations/12345678901234567890", "title": "Example Plumbing Co.", "profile": { "description": "Family owned plumbing company serving the western suburbs since 1998." } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/update-hours/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Update Business Profile Hours", "operationId": "updateGbpHours", "description": "Update the regular or special hours on a connected Google Business Profile.\n\nRegular and special hours are handled independently: sending only `special` leaves `regular` untouched, and the reverse. Special hours are keyed by date, so sending one date does not disturb the others.\n\nMidnight is expressed as `{\"hours\": 0}`. A period that runs to the end of the day closes at `{\"hours\": 24}`.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\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": "The Place ID of a connected location." }, "regular": { "type": "string", "description": "Regular hour periods, each with `open_day`, `open_time`, `close_day` and `close_time`." }, "special": { "type": "string", "description": "Special hour periods, each keyed by date." }, "clear": { "type": "string", "description": "Comma separated, `regular` and/or `special`." }, "replace": { "type": "string", "description": "Comma separated, `regular` and/or `special`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "updated": "special_hours", "regular_hours": { "periods": [ { "open_day": "MONDAY", "open_time": { "hours": 8 }, "close_day": "MONDAY", "close_time": { "hours": 17 } } ] }, "special_hours": { "special_hour_periods": [ { "start_date": { "year": 2026, "month": 12, "day": 25 }, "closed": true } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/update-status/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Update Business Profile Open Status", "operationId": "updateGbpStatus", "description": "Open a connected Google Business Profile, or mark it temporarily or permanently closed.\n\n**Closing permanently requires confirmation.** When `status` is `CLOSED_PERMANENTLY` you must also send `confirm=CLOSED_PERMANENTLY`. A permanent closure is very hard to undo through Google and should be treated as final.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "status" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "status": { "type": "string", "description": "`OPEN`, `CLOSED_TEMPORARILY` or `CLOSED_PERMANENTLY`." }, "confirm": { "type": "string", "description": "Required when `status` is `CLOSED_PERMANENTLY`. Must repeat the status." }, "opening_date": { "type": "string", "description": "Optional opening date, `YYYY-MM-DD`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "status": "CLOSED_TEMPORARILY" }, "data": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "open_info": { "status": "CLOSED_TEMPORARILY", "can_reopen": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/gbp/delete-review-reply/": { "post": { "tags": [ "Manage Google Business Profile" ], "summary": "Delete a Business Profile Review Reply", "operationId": "deleteGbpReviewReply", "description": "Delete the reply on one or more Google Business Profile reviews.\n\n**This endpoint requires confirmation.** The reply is removed from public view and cannot be recovered. You must send `confirm=DELETE_REPLY` or the request is rejected with `GBP_CONFIRMATION_REQUIRED` and nothing is changed.\n\nSend a single `place_id` and `review_id`, or a `replies` array to work through several at once. Each entry is reported separately, so one failure does not stop the rest.\n\nArray parameters are sent as form fields, not as JSON. Index each entry, for example `services[0][name]=Drain cleaning`. A JSON request body is not read.\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "api_key", "place_id", "review_id", "confirm" ], "properties": { "api_key": { "type": "string", "description": "Your Local Falcon API key." }, "place_id": { "type": "string", "description": "The Place ID of a connected location." }, "review_id": { "type": "string", "description": "The review whose reply should be deleted." }, "replies": { "type": "string", "description": "Alternative to the single form. Each entry with a `place_id` and `review_id`." }, "confirm": { "type": "string", "description": "Must be `DELETE_REPLY`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "code_desc": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "parameters": { "type": "object" }, "data": { "type": "object" } } }, "example": { "code": 200, "code_desc": false, "success": true, "message": false, "parameters": { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "review_id": "AbFvOqkExampleReviewIdentifier", "confirm": "DELETE_REPLY" }, "data": { "count": 1, "results": [ { "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4", "review_id": "AbFvOqkExampleReviewIdentifier", "success": true } ] } } } } }, "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" } } } } } }