Create Campaign - SpiderIQ API

Overview

Create a new SpiderMaps campaign that will scrape business listings across multiple locations in a country. The campaign system handles location iteration automatically, making it easy to scrape entire countries or regions.

v2.14.0 Feature: The Campaign System includes a location database with 44,691 cities across 240 countries.

v2.15.0 Workflow Orchestration: Enable automatic job chaining with the workflow parameter to run SpiderMaps → SpiderSite → SpiderVerify automatically. See Orchestrated Campaigns Guide.

Request Body

query

string

required

The search query for Google Maps (e.g., “restaurants”, “hotels”, “dentists”)

country_code

string

required

ISO 2-letter country code (e.g., “FR” for France, “DE” for Germany)

name

string

Optional campaign name for identification

filter

object

Location filter configuration

Show Filter Properties

mode

string

default:"all"

Filter mode: all, population, cities_only, custom, regions

min_population

integer

Minimum city population (for population mode)

max_population

integer

Maximum city population (for population mode)

location_ids

array

Specific location IDs to include (for custom mode)

admin_regions

array

Admin regions to include (for regions mode)

workflow

object

v2.15.0: Workflow orchestration configuration for automatic job chaining.

Show Workflow Properties

spidersite

object

SpiderSite configuration for website crawling.

Show SpiderSite Properties

enabled

boolean

default:"false"

Enable automatic SpiderSite jobs for businesses with valid domains

max_pages

integer

default:"10"

Maximum pages to crawl per website (1-50)

crawl_strategy

string

default:"bestfirst"

Crawl strategy: bestfirst, bfs, dfs

enable_spa

boolean

default:"true"

Enable SPA/JavaScript rendering

extract_team

boolean

default:"false"

Extract team members using AI

extract_company_info

boolean

default:"false"

Extract company info using AI

product_description

string

Your product description for CHAMP lead scoring

icp_description

string

Your ICP description for CHAMP lead scoring

spiderverify

object

SpiderVerify configuration for email verification.

Show SpiderVerify Properties

enabled

boolean

default:"false"

Enable automatic email verification

max_emails_per_business

integer

default:"10"

Maximum emails to verify per business (1-50)

check_gravatar

boolean

default:"false"

Check for Gravatar images

check_dnsbl

boolean

default:"false"

Check spam blacklists

Filter out social media URLs (Facebook, Instagram, etc.)

filter_review_sites

boolean

default:"true"

Filter out review sites (Yelp, TripAdvisor, etc.)

filter_directories

boolean

default:"true"

Filter out business directories (YellowPages, etc.)

filter_maps

boolean

default:"true"

Filter out map links (Google Maps, Waze, etc.)

Filter Modes

Mode	Description	Use Case
`all`	All locations in the country	Complete country coverage
`population`	Filter by population range	Target cities of specific size
`cities_only`	Only cities, no postcodes	Skip postcode-level granularity
`custom`	Specific location IDs	Target specific pre-selected cities
`regions`	Specific admin regions	Target states/provinces

Response

campaign_id

string

Unique campaign identifier (e.g., “camp_fr_restaurant_20251222_abc123”)

status

string

Campaign status: active, paused, completed, stopped

query

string

The search query used

country_code

string

The country code

total_locations

integer

Number of locations to be scraped

next_location_id

integer

ID of the first location to be processed

created_at

string

ISO timestamp of creation

has_workflow

boolean

v2.15.0: Whether workflow orchestration is enabled for this campaign

workflow_config

object

v2.15.0: The workflow configuration if enabled (mirrors the request)

Examples

Basic Campaign (All Locations)

curl -X POST https://spideriq.di-atomic.com/api/v1/jobs/spiderMaps/campaigns/submit \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "restaurants",
    "country_code": "LU"
  }'

Response:

{
  "campaign_id": "camp_lu_restaurants_20251222171302_cee5b94a",
  "status": "active",
  "query": "restaurants",
  "country_code": "LU",
  "total_locations": 12,
  "next_location_id": 28451,
  "created_at": "2025-12-22T17:13:02Z"
}

Population-Filtered Campaign

curl -X POST https://spideriq.di-atomic.com/api/v1/jobs/spiderMaps/campaigns/submit \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "hotels",
    "country_code": "DE",
    "name": "Germany Hotels - Major Cities",
    "filter": {
      "mode": "population",
      "min_population": 500000
    }
  }'

Response:

{
  "campaign_id": "camp_de_hotels_20251222171518_f65c4dce",
  "status": "active",
  "query": "hotels",
  "country_code": "DE",
  "total_locations": 14,
  "next_location_id": 12301,
  "created_at": "2025-12-22T17:15:18Z"
}

Orchestrated Campaign (v2.15.0)

Full workflow with SpiderMaps → SpiderSite → SpiderVerify chain:

curl -X POST https://spideriq.di-atomic.com/api/v1/jobs/spiderMaps/campaigns/submit \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "restaurants",
    "country_code": "FR",
    "name": "France Restaurants - Lead Gen",
    "filter": {
      "mode": "population",
      "min_population": 100000
    },
    "workflow": {
      "spidersite": {
        "enabled": true,
        "max_pages": 10,
        "crawl_strategy": "bestfirst",
        "enable_spa": true,
        "extract_company_info": true,
        "product_description": "Restaurant management software",
        "icp_description": "Restaurant owners seeking efficiency"
      },
      "spiderverify": {
        "enabled": true,
        "max_emails_per_business": 5,
        "check_gravatar": false
      },
      "filter_social_media": true,
      "filter_review_sites": true
    }
  }'

Response:

{
  "campaign_id": "camp_fr_restaurants_20251223_a1b2c3d4",
  "status": "active",
  "query": "restaurants",
  "country_code": "FR",
  "total_locations": 42,
  "next_location_id": 15201,
  "created_at": "2025-12-23T10:30:00Z",
  "has_workflow": true,
  "workflow_config": {
    "spidersite": {
      "enabled": true,
      "max_pages": 10,
      "crawl_strategy": "bestfirst"
    },
    "spiderverify": {
      "enabled": true,
      "max_emails_per_business": 5
    },
    "filter_social_media": true,
    "filter_review_sites": true
  }
}

For orchestrated campaigns, use the /workflow-results endpoint to get aggregated data from all three services (SpiderMaps + SpiderSite + SpiderVerify) in a single response.

Error Responses

Invalid Country Code

{
  "detail": "No locations found for country XX"
}

No Matching Locations

{
  "detail": "No locations match the specified filter criteria"
}

Next Steps

After creating a campaign, use the /next endpoint to start submitting jobs:

Get Next Location

Get the next location and automatically submit a SpiderMaps job

API Reference

​Overview

​Request Body

​Filter Modes

​Response

​Examples

​Basic Campaign (All Locations)

​Population-Filtered Campaign

​Orchestrated Campaign (v2.15.0)

​Error Responses

​Invalid Country Code

​No Matching Locations

​Next Steps

Get Next Location

Overview

Request Body

Filter Modes

Response

Examples

Basic Campaign (All Locations)

Population-Filtered Campaign

Orchestrated Campaign (v2.15.0)

Error Responses

Invalid Country Code

No Matching Locations

Next Steps