Get Next Location

POST/api/v1/jobs/spiderMaps/campaigns/{campaign_id}/next

Overview

This endpoint is the core of the campaign workflow. Each call:

1. Finds the next pending location in the campaign
2. Automatically submits a SpiderMaps job for that location
3. Updates campaign progress
4. Returns job details and progress statistics

info

Workflow Pattern: Call /next in a loop until has_more is false to process all locations in a campaign.

Path Parameters

campaign_idstringrequired

The campaign ID returned from /submit

Response

has_moreboolean

true if more locations remain, false when campaign is complete

statusstring

Campaign status: active, completed, stopped

current_taskobject

Details of the submitted job (null when complete)

Task Properties

job_idstring

UUID of the submitted SpiderMaps job

location_idinteger

Database ID of the location

search_stringstring

Full search query sent to Google Maps (e.g., "restaurants Luxembourg City, Luxembourg")

display_namestring

Human-readable location name

progressobject

Campaign progress statistics

Progress Properties

totalinteger

Total locations in campaign

pendinginteger

Locations not yet submitted

submittedinteger

Jobs submitted (queued/processing)

completedinteger

Successfully completed jobs

failedinteger

Failed jobs

percentagenumber

Completion percentage (0-100)

Examples

Basic Usage

cURL

curl -X POST https://spideriq.ai/api/v1/jobs/spiderMaps/campaigns/camp_lu_restaurants_abc123/next \
  -H "Authorization: Bearer <your_token>"

Python

import requests

campaign_id = "camp_lu_restaurants_abc123"
response = requests.post(
    f"https://spideriq.ai/api/v1/jobs/spiderMaps/campaigns/{campaign_id}/next",
    headers={"Authorization": "Bearer <your_token>"}
)
result = response.json()

print(f"Job submitted: {result['current_task']['job_id']}")
print(f"Location: {result['current_task']['search_string']}")
print(f"Progress: {result['progress']['percentage']:.1f}%")
print(f"Has more: {result['has_more']}")

Response (In Progress):

{
  "has_more": true,
  "status": "active",
  "current_task": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "location_id": 28451,
    "search_string": "restaurants Luxembourg City, Luxembourg",
    "display_name": "Luxembourg City"
  },
  "progress": {
    "total": 12,
    "pending": 10,
    "submitted": 2,
    "completed": 0,
    "failed": 0,
    "percentage": 16.67
  }
}

Response (Campaign Complete):

{
  "has_more": false,
  "status": "completed",
  "current_task": null,
  "progress": {
    "total": 12,
    "pending": 0,
    "submitted": 0,
    "completed": 12,
    "failed": 0,
    "percentage": 100.0
  }
}

Complete Campaign Loop

Python

import requests
import time

API_BASE = "https://spideriq.ai/api/v1"
TOKEN = "<your_token>"
headers = {"Authorization": f"Bearer {TOKEN}"}

# Create campaign
campaign = requests.post(
    f"{API_BASE}/jobs/spiderMaps/campaigns/submit",
    headers=headers,
    json={"query": "restaurants", "country_code": "LU"}
).json()

campaign_id = campaign["campaign_id"]
print(f"Created campaign: {campaign_id}")
print(f"Total locations: {campaign['total_locations']}")

# Process all locations
job_ids = []
while True:
    result = requests.post(
        f"{API_BASE}/jobs/spiderMaps/campaigns/{campaign_id}/next",
        headers=headers
    ).json()

    if result["current_task"]:
        job_ids.append(result["current_task"]["job_id"])
        print(f"Submitted: {result['current_task']['display_name']} ({result['progress']['percentage']:.0f}%)")

    if not result["has_more"]:
        print(f"\nCampaign complete! Submitted {len(job_ids)} jobs.")
        break

    # Optional: small delay between submissions
    time.sleep(0.5)

JavaScript

const API_BASE = 'https://spideriq.ai/api/v1';
const TOKEN = '<your_token>';
const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'Content-Type': 'application/json'
};

async function runCampaign() {
  // Create campaign
  const campaignRes = await fetch(`${API_BASE}/jobs/spiderMaps/campaigns/submit`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ query: 'restaurants', country_code: 'LU' })
  });
  const campaign = await campaignRes.json();

  console.log(`Created campaign: ${campaign.campaign_id}`);
  console.log(`Total locations: ${campaign.total_locations}`);

  // Process all locations
  const jobIds = [];
  while (true) {
    const res = await fetch(`${API_BASE}/jobs/spiderMaps/campaigns/${campaign.campaign_id}/next`, {
      method: 'POST',
      headers
    });
    const result = await res.json();

    if (result.current_task) {
      jobIds.push(result.current_task.job_id);
      console.log(`Submitted: ${result.current_task.display_name} (${result.progress.percentage.toFixed(0)}%)`);
    }

    if (!result.has_more) {
      console.log(`\nCampaign complete! Submitted ${jobIds.length} jobs.`);
      break;
    }

    await new Promise(r => setTimeout(r, 500));
  }
}

N8N / Xano Integration

The /next endpoint is designed for easy integration with workflow automation tools:

Loop Node:
  Condition: response.has_more == true

  HTTP Request:
    Method: POST
    URL: /api/v1/jobs/spiderMaps/campaigns/{{campaign_id}}/next

  Store: response.current_task.job_id → job_ids[]

  Wait: 500ms (optional)

Error Responses

Campaign Not Found

{
  "detail": "Campaign not found: invalid_campaign_id"
}

Campaign Already Completed

When calling /next on an already-completed campaign:

{
  "has_more": false,
  "status": "completed",
  "current_task": null,
  "progress": {
    "total": 12,
    "pending": 0,
    "submitted": 0,
    "completed": 12,
    "failed": 0,
    "percentage": 100.0
  }
}

Related Endpoints

📈

Check Status

Get detailed campaign status and statistics

⏹️

Stop Campaign

Pause a running campaign