LOlocalfalcon
Campaigns

Create a Campaign

Changed on

Create a new campaign in Local Falcon. Campaigns allow you to schedule recurring scans for one or multiple locations with one or multiple keywords.

Every location must already be in your Saved Locations (see /v2/locations/add). Each run scans every location × keyword × platform, so adding platforms with platform multiplies the scans, and the credits, per run.

Keywords may contain placeholders that are filled in per location at run time, so one keyword such as {category} {city} works across locations in different cities.

Use keyword_type to choose whether keywords run on map platforms, AI platforms or both, and location_settings to give individual locations their own grid or platforms.

All parameters are validated before anything is created, so a 400 response means no campaign was created. Duplicate keywords (ignoring case) and empty entries in place_id or keyword are skipped.

If a single location or keyword can't be added, the campaign is still created and the problem is listed in exceptions. If a later step fails after the campaign has been created, the response includes step and data.campaign_key, and the campaign is left as an unstarted draft. Starting the campaign fails with 400 when the account doesn't have enough credits.

post/v2/campaigns/create

Request

  • Base URL
    https://api.localfalcon.com
  • Auth
    none declared

Request body application/x-www-form-urlencoded

api_keystring required

Your Local Falcon API key.

namestring required

A name to give the campaign.

measurement'mi' | 'km' required

The measurement unit of your radius.

grid_size'3' | '5' | '7' | '9' | '11' | '13' | '15' | '17' | '19' | '21' required

The size of your desired grid.

radiusstring required

The radius of your grid from center point to outer most north/east/south/west point. Expects 0.1 to 100.

frequency'one-time' | 'daily' | 'weekly' | 'biweekly' | 'monthly' | 'every-2-weeks' | 'every-3-weeks' | 'every-4-weeks' required

The specific run frequency for the campaign.

place_idstring required

The location(s) to include in the campaign. Supports multiple Place IDs, separated by commas. Each must already be in your Saved Locations.

keywordstring required

The keyword(s) to run against the campaign locations. Supports multiple keywords, separated by commas.

Keywords may contain placeholders, filled in per location at run time:

  • {category} — the location's first category
  • {city}, {locality}, {state}, {state_code}, {zip}
  • {country} — the country code, for example US

A placeholder with no saved value for that location becomes empty. A location with no category keeps the literal text {category}. Example: {category} near me,{category} {city}.

Keywords are split on commas, so never put a comma inside a keyword: {category} in {city}, {state_code} becomes two keywords.

platformstring

The platform(s) to scan, separated by commas. Defaults to native, which scans maps only.

  • native — each location's own map platform (Google Maps, or Apple Maps for Apple listings)
  • google, apple — Google Maps, Apple Maps
  • gaio, aimode, chatgpt, gemini — Google AI Overviews, Google AI Mode, ChatGPT, Gemini

Each platform adds one scan per location and keyword on every run.

keyword_type'traditional' | 'ai' | 'both'

Which platforms the campaign's keywords run on. Defaults to both.

  • traditional — map platforms only (google, apple)
  • ai — AI platforms only (gaio, aimode, chatgpt, gemini)
  • both — every platform in the campaign

A keyword runs only where its type and the location's platforms overlap, so keyword_type=ai with platform=native produces no scans.

location_settingsstring

Per-location overrides, as a JSON object keyed by Place ID. Every key must also be in place_id. Each value may set:

  • grid_size — same options as the campaign grid_size
  • radius — 0.1 to 100
  • measurement — mi or km
  • platforms — comma-separated, same options as platform

Anything left out uses the campaign's value. Locations not listed use the campaign settings.

start_datestring required

The date when your campaign runs the first time. Expects date formatted as MM/DD/YYYY.

start_timestring required

The time of day your campaign should run. Expects friendly time formatted like "9:00 AM".

ai_analysis'0' | '1'

Whether campaign scans should include AI analysis.

notify'0' | '1'

Whether email notification should be enabled for the campaign.

email_recipientsstring

Recipients of email notification. Required if notify is set to 1. Supports multiple email addresses, separated by commas.

email_subjectstring

Email subject of the email notification. Required if notify is set to 1.

email_bodystring

Email body of the email notification if notify is set to 1.

Example request

{
  "platform": "native,chatgpt",
  "location_settings": "{\"ChIJUW__IQikz4kRMzHhVYurBuo\":{\"grid_size\":\"9\",\"radius\":\"3\",\"platforms\":\"native,chatgpt\"}}"
}

Response

Campaign created successfully.

Changes

  • 304db93dea96Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new every-2-weeks enum value to the request property

    • info

      added the new every-3-weeks enum value to the request property

    • info

      added the new every-4-weeks enum value to the request property