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. **Download OpenAPI Spec:** [JSON](https://docs.localfalcon.com/openapi.json) ยท [YAML](https://docs.localfalcon.com/openapi.yaml) ๐Ÿ“š **API Guides:** [Getting Started, Tutorials & Best Practices]( https://docs.localfalcon.com/guides/ ) ## Quick Start ### Option A: OAuth 2.1 via MCP Server (Recommended for AI Agents & Integrations) 1. **Connect to the MCP server** at `https://mcp.localfalcon.com` โ€” all API capabilities are exposed as structured tools with full OAuth session management. This is the recommended path for AI platforms, connector directories, and any third-party integration. ### Option B: API Key for Direct REST API Access 1. **Get your API key** from the [API Credentials](https://www.localfalcon.com/api/credentials/) page in your dashboard. 2. **Make your first request** โ€” try listing your saved locations with a simple POST to `/v1/locations/`. 3. **Explore the endpoints** below, organized by feature area. Base URL: `https://api.localfalcon.com` ## API Versions The Local Falcon API has two endpoint versions: - **v1 endpoints** โ€” The original API. Primarily used for retrieving reports, listing resources, and the On-Demand API. - **v2 endpoints** โ€” The current API. Used for running scans, managing locations, campaigns, Falcon Guard, and more. Both versions are fully supported. Use whichever version provides the endpoint you need โ€” many features have endpoints in both versions. ## Authentication Local 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. ### OAuth 2.1 (Recommended for Integrations) For 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. See **[AI Agent & Connector Integration](#section/AI-Agent-Connector-Integration)** below for full OAuth details. ### API Key (Direct REST API Access) For direct REST API calls, pass your `api_key` with each request: - **POST requests** โ€” Send `api_key` as a form data field in the request body (`application/x-www-form-urlencoded`). - **GET requests** โ€” Send `api_key` as a query parameter. Alternatively, you can pass the same API key value as a Bearer token in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` Both methods authenticate identically โ€” the Bearer header is a convenience for clients that prefer header-based authentication. You 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. **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. ## Standard Response Format Every endpoint returns a JSON envelope with this structure: | Field | Type | Description | |-------|------|-------------| | `code` | integer | HTTP status code | | `code_desc` | string or false | Status description (e.g., `"OK"`, `"Bad Request"`) | | `success` | boolean | Whether the request succeeded | | `message` | string or false | Error message if failed, `false` if successful | | `parameters` | object | Parameters received by the endpoint | | `data` | object | Response payload (varies by endpoint) | ## Error Codes | Code | Description | |------|-------------| | 200 | OK โ€” Request successful | | 400 | Bad Request โ€” Missing or invalid parameters | | 401 | Unauthorized โ€” Invalid or missing API key | | 404 | Not Found โ€” Resource not found | | 429 | Too Many Requests โ€” Rate limit exceeded | | 500 | Server Error โ€” Unexpected server error | ## Field Masks Many endpoints support a `fieldmask` parameter to control which fields are returned, reducing payload size. - **Multiple fields**: `fieldmask=report_key,arp,atrp,solv` - **Nested fields**: Use dot notation โ€” `fieldmask=reports.*.report_key,reports.*.date` - **Wildcards**: Use `*` to select a field from every item in an array ## AI Agent & Connector Integration The 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. ### Why Use the MCP Server? - **OAuth 2.1 with PKCE** โ€” Industry-standard authorization for secure, user-consented access. No API keys to manage or rotate. - **Structured tool interface** โ€” All API operations are exposed as typed, validated tools with built-in parameter validation and error handling. - **Session management** โ€” The MCP server handles token lifecycle, rate limiting, and request orchestration. - **Platform-ready** โ€” Designed for direct registration with AI connector directories (Anthropic, OpenAI, and others). ### OAuth 2.1 Flow Details | Parameter | Value | |-----------|-------| | **Grant type** | Authorization Code with PKCE (S256, mandatory) | | **Authorization URL** | `https://www.localfalcon.com/oauth-v2/authorize` | | **Token URL** | `https://www.localfalcon.com/oauth-v2/token` | | **Revocation URL** | `https://www.localfalcon.com/oauth-v2/revoke` | | **MCP Server** | `https://mcp.localfalcon.com` | | **npm package** | [`@local-falcon/mcp`](https://www.npmjs.com/package/@local-falcon/mcp) | ### Architecture The 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. For direct REST API access without the MCP layer, use API key authentication as described in the [Authentication](#section/Authentication) section above. ## Also See - [API Guides](https://docs.localfalcon.com/guides/) โ€” Getting started tutorials, metric definitions, grid configuration, fieldmask recipes, and worked examples - [OpenAPI Spec (YAML)](https://docs.localfalcon.com/openapi.yaml) ยท [OpenAPI Spec (JSON)](https://docs.localfalcon.com/openapi.json) - [llms.txt](https://docs.localfalcon.com/llms.txt) โ€” Machine-readable site index for AI agents - [Local Falcon Platform](https://www.localfalcon.com) ยท [Register Free](https://www.localfalcon.com/register) - [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) 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. 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. schemas: StandardResponse: type: object description: > The standard envelope returned by all API endpoints. Every response follows this structure regardless of the specific endpoint called. 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. 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. 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. data: type: object additionalProperties: true description: > The returned data payload. Contents vary by endpoint. 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. 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. example: "STORE-001" LocationDetailed: allOf: - $ref: "#/components/schemas/LocationBasic" - type: object description: > Full location information including all basic fields plus additional detail fields. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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". 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. 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. 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. 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. 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. 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. Use **POST /v2/run-scan/** to run new scans, and the **/v1/** endpoints to list and retrieve report data. - name: Locations description: | Search for business locations, save them to your account, and list all connected locations. Locations must be saved to your account before they can be used in scans. - 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. Use **/v2/campaigns/** endpoints to manage campaigns and **/v1/campaigns/** to retrieve campaign reports. - 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. - name: Reviews Analysis description: | Retrieve AI-powered analysis reports for your business reviews. - name: Account description: | View your Local Falcon account information including subscription details, credit balance, and usage. - 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. - 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. For 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. x-tagGroups: - name: Core tags: - Scans & Reports - Locations - Campaigns - name: Features tags: - Falcon Guard - Reviews Analysis - Account - Knowledge Base - name: Advanced tags: - On-Demand API paths: /v1/autoscans/: post: tags: - Scans & Reports summary: List all Scheduled Scans operationId: listScheduledScans description: | Allows you to retrieve a list of all Auto Scans associated with your Local Falcon account. If 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. 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. If 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. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - api_key properties: api_key: type: string description: Your Local Falcon API key. query: type: string description: Search query. Matches against location name, address, Place ID, or store code. limit: type: integer minimum: 1 maximum: 100 default: 10 description: The number of results you wish to retrieve. next_token: type: string description: >- This parameter is used to get the next 'page' of results. The value used with the parameter is provided from a previous response by this endpoint if more 'pages' of results exist. responses: '200': description: Successful response content: application/json: schema: type: object properties: code: type: integer code_desc: type: boolean success: type: boolean message: type: boolean parameters: type: object data: type: object properties: count: type: integer next_token: type: string locations: type: array items: type: object properties: id: type: string platform: type: string place_id: type: string name: type: string address: type: string lat: type: string lng: type: string rating: type: string reviews: type: string store_code: oneOf: - type: string - type: boolean url: type: string phone: type: string categories: type: object additionalProperties: type: string groups: type: array items: type: string example: code: 200 code_desc: false success: true message: false parameters: query: "" data: count: 10 next_token: "VFhwUk1rNTZZM2c9" locations: - id: "ChIJ2VRoeR_YcEgRwPypNJIvj8A" platform: "google" place_id: "ChIJ2VRoeR_YcEgRwPypNJIvj8A" name: "JWS COTSWOLD BUILDERS Ltd." address: "Weston House, Weston Rd, Bretforton, Evesham WR11 7HW, United Kingdom" lat: "52.0865272" lng: "-1.8584223" rating: "0.000" reviews: "0" store_code: false url: "http://jwscotswold.co.uk/" phone: "" categories: construction_company: "Construction company" groups: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' /v1/location-groups/: post: tags: - Locations summary: List All Location Groups operationId: listLocationGroups description: | Get a full list of all location groups in your Local Falcon account, including the number of locations and the Place IDs contained in each group. Groups 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`. If 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. 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. If 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. 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. 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. If 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. 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. 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. If 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. 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. 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. If 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. 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. 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. If 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. 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. 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. If 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. 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. 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. If 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. 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. 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. If 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. 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. 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 Endpoints - Scans & Reports # ============================================================================= /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. Businesses 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. 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 Endpoints - Locations # ============================================================================= /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). This endpoint runs searches only against Google Maps. Every successful location search is charged two (2) credits. 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 Endpoints - Account # ============================================================================= /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 Endpoints - Falcon Guard # ============================================================================= /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. When protecting locations, each business location needs to have already been added to your Saved Locations in your Local Falcon dashboard. 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 Endpoints - Campaigns # ============================================================================= /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:
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)
Many fields accept either a single value or a comma-delimited list of values (for example `place_id`, `keyword`, `platforms`). A campaign cannot be modified while it is currently running โ€” wait until the run finishes before calling this endpoint. 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. - **Required** when `action` is `add-location`, `modify-location`, or `remove-location`. - **Optional** when `action` is `add-keyword` or `update-keyword` to scope the keyword(s) to specific location(s) already in the campaign. keyword: type: string description: | The keyword(s) to act on. Supports a single value or multiple values separated by commas. **Required** when `action` is `add-keyword`, `update-keyword`, or `remove-keyword`. 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`. 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`. 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. The 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. 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 Endpoints - Knowledge Base # ============================================================================= /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. Notes: - Content is returned as markdown (converted from HTML on the server). - Preserves headings, links, images, lists, bold/italic, and other formatting. - Image URLs are fully qualified. - The `id` field returns with "KB" prefix (e.g., "KB70") but the URL path accepts just the number. 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. Notes: - Only returns active (published) articles; drafts are excluded. - Content field is intentionally omitted to keep payloads lightweight. - Use `next_token` from the response to fetch the next page. 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' # ============================================================================= # On-Demand API Endpoints # ============================================================================= /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. This endpoint requires on_demand_api_access permission. 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). This endpoint runs searches only against Google Maps and requires on_demand_api_access permission. 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. This endpoint runs searches only against Google Maps and requires on_demand_api_access permission. 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. This endpoint runs searches only against Google Maps and requires on_demand_api_access permission. 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. This endpoint runs searches only against Google Maps and requires on_demand_api_access permission. 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'