SpyFu CSV Processor API Documentation

Overview

The SpyFu CSV Processor API allows you to:

Look up ad spend data for individual domains
Process bulk CSV files with company domains
Import data directly from Google Sheets
Get real-time processing status updates
Download enriched CSV files with ad spend data

Pro Tip: All data comes directly from SpyFu's database with intelligent caching to minimize API calls.

Authentication

API credentials are managed server-side. No authentication headers required for public endpoints.

Note: SpyFu API credentials are securely stored as environment variables on the server.

Domain Lookup

POST

Endpoint

/lookup_domain

Description

Get ad spend data and top keywords for a single domain. Returns real-time data from SpyFu API.

Request Body

Parameter	Type	Required	Description
`domain`	string	✅ Yes	Domain name (e.g., "zillow.com")
`company_name`	string	❌ No	Company name for better matching

Example Request

curl -X POST https://your-app.vercel.app/lookup_domain \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "zillow.com",
    "company_name": "Zillow"
  }'

Example Response

{
  "success": true,
  "domain": "zillow.com",
  "ad_spend": "$3,735,000.00",
  "keywords": [
    {
      "keyword": "real estate",
      "cpc": "$4.25",
      "search_volume": "5000"
    },
    {
      "keyword": "homes for sale",
      "cpc": "$3.80",
      "search_volume": "3200"
    }
  ]
}

Process CSV

POST

Endpoint

/process

Description

Upload a CSV file or provide a Google Sheets URL to process multiple domains in bulk.

Request Parameters

Parameter	Type	Required	Description
`file`	file	*	CSV file with company/domain data
`google_sheet_url`	string	*	Published Google Sheets URL

* Either file or google_sheet_url is required

Example Request (Form Data)

curl -X POST https://your-app.vercel.app/process \
  -F "file=@companies.csv"

Example Response

{
  "status": "processing",
  "message": "Your CSV is being processed",
  "redirect": "/processing_status"
}

CSV Format

Required columns:
• Company Name (or variants)
• Domain/Website (or variants)

Supported formats: .csv files with headers

Processing Status

GET

Endpoints

/processing_status /processing_status_ajax

Description

Check the status of CSV processing. The AJAX endpoint returns JSON for real-time updates.

Response Fields

Field	Type	Description
`status`	string	processing, complete, error
`progress`	integer	Percentage complete (0-100)
`domains_processed`	integer	Number of domains processed
`cache_hits`	integer	Domains found in cache
`api_calls`	integer	Fresh API calls made

Example Request

curl https://your-app.vercel.app/processing_status_ajax

Example Response

{
  "status": "processing",
  "progress": 75,
  "domains_processed": 12,
  "total_domains": 16,
  "error_count": 1,
  "cache_hits": 8,
  "api_calls": 4
}

Real-time Updates: Use the AJAX endpoint to poll for status updates every 3 seconds.

Download Results

GET

Endpoint

/download_csv

Description

Download the processed CSV file with ad spend data. Only available when processing is complete.

Response

Returns a CSV file download with the following columns:

Original company data
ad_spend_usd - Monthly ad spend
Status - Processing result

Example Request

curl -O https://your-app.vercel.app/download_csv

Sample Output

Company Name,Domain,ad_spend_usd,Status
Zillow,zillow.com,$3735000.00,Success
Redfin,redfin.com,$648200.00,Success
Example Co,example.com,Not available,No data found

Error Codes

HTTP Code	Error Type	Description	Solution
`400`	Bad Request	Missing or invalid parameters	Check request format and required fields
`500`	Internal Server Error	SpyFu API error or server issue	Retry request or contact support
`503`	Service Unavailable	API credentials not configured	Contact administrator