POST
https://spideriq.ai
/
api
/
v1
/
jobs
/
spiderMapsEnrich
/
submit
Submit SpiderMapsEnrich Job
curl --request POST \
  --url https://spideriq.ai/api/v1/jobs/spiderMapsEnrich/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payload": {
    "google_cid": "<string>",
    "google_place_id": "<string>",
    "place_url": "<string>",
    "original_data": {},
    "exclude_vps": [
      {}
    ],
    "use_proxy": true,
    "enrich_options": {
      "reviews": {
        "enabled": true,
        "max_count": 123,
        "include_all": true,
        "negative_only": true
      },
      "photos": {
        "enabled": true,
        "max_count": 123
      },
      "popular_times": true,
      "store_images": true
    },
    "snowball": {
      "enabled": true,
      "max_depth": 123,
      "max_places_per_seed": 123
    },
    "test": true
  },
  "priority": 123
}
'
{
  "job_id": "<string>",
  "type": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "message": "<string>",
  "data": {
    "name": "<string>",
    "address": "<string>",
    "phone": "<string>",
    "website": "<string>",
    "rating": 123,
    "category": "<string>",
    "enriched": true,
    "enriched_at": "<string>"
  },
  "reviews": [
    {}
  ],
  "review_analysis": {
    "total_extracted": 123,
    "rating_distribution": {},
    "negative_reviews": [
      {}
    ],
    "negative_count": 123,
    "negative_percentage": 123,
    "owner_response_rate_negative": 123,
    "common_complaints": [
      {}
    ]
  },
  "photos": [
    {}
  ],
  "photos_original": [
    {}
  ],
  "review_tags": [
    {}
  ],
  "menu_link": "<string>",
  "street_view_url": "<string>",
  "popular_times": {},
  "related_places_found": 123,
  "metadata": {
    "worker_id": "<string>",
    "vps_id": "<string>",
    "proxy_used": true,
    "scrape_time_ms": 123,
    "reviews_extracted": 123,
    "reviews_returned": 123,
    "photos_extracted": 123,
    "photos_hosted": 123,
    "negative_reviews_count": 123
  }
}

Overview

SpiderMapsEnrich is a second-stage enrichment worker that visits individual Google Maps place pages to extract detailed data not available from the initial SpiderMaps discovery crawl.
Two-Stage Architecture:
  1. SpiderMaps - Discovers businesses via search (returns basic info for 100+ results)
  2. SpiderMapsEnrich - Enriches individual places (returns reviews, photos, analysis)

Best For

  • Extracting customer reviews and sentiment analysis
  • Getting negative review breakdown for competitor research
  • Downloading and hosting business photos
  • Popular times data extraction
  • Related places discovery (snowball expansion)
  • Deep dive on specific businesses from SpiderMaps results

Request Body

payload
object
required
Job configuration payload
priority
integer
default:"5"
Job priority (0-10, higher = processed first).

Response

job_id
string
Unique job identifier (UUID format).
type
string
Always spiderMapsEnrich.
status
string
Initial status: queued.
created_at
string
Job creation timestamp (ISO 8601).
message
string
Confirmation message.

Example Request

curl -X POST https://spideriq.ai/api/v1/jobs/spiderMapsEnrich/submit \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "google_cid": "0x87c9f95545605943:0x6bad649f33559c94"
    }
  }'

Example Response

201 Created
{
  "job_id": "9c1e51c6-ae76-46d2-958e-b77061ef197d",
  "type": "spiderMapsEnrich",
  "status": "queued",
  "created_at": "2026-01-18T12:31:37.073080",
  "message": "Job submitted successfully"
}

Results Structure

When the job completes, results include:

Core Business Data

data
object
Core business information.

Reviews

reviews
array
Array of extracted reviews.Each review contains:
  • review_id - Unique review identifier
  • author - Reviewer name
  • rating - Star rating (1-5)
  • text - Review text
  • date - Review date (relative, e.g., “2 weeks ago”)
  • is_local_guide - Whether reviewer is a Local Guide
  • has_owner_response - Whether owner responded
  • owner_response - Owner’s response (if any)

Review Analysis

review_analysis
object
Automated review sentiment analysis.

Photos

photos
array
Hosted photo URLs (SpiderMedia).Format: https://media.spideriq.ai/client-{client_id}/gmaps/gmaps_enrich_{cid}_{n}.jpg
photos_original
array
Original Google CDN photo URLs (fallback).

Additional Fields

review_tags
array
Keyword summaries from reviews.Example: ["Great pizza", "Fast service", "Cash only"]
Direct URL to restaurant menu (if available).
street_view_url
string
Constructed Street View URL from coordinates.
Busy hours data by day of week.
Count of related places discovered (for snowball).

Metadata

metadata
object
Processing metadata.

Complete Results Example

{
  "success": true,
  "job_id": "9c1e51c6-ae76-46d2-958e-b77061ef197d",
  "type": "spiderMapsEnrich",
  "status": "completed",
  "processing_time_seconds": 44.13,
  "data": {
    "data": {
      "name": "Joe's Pizza",
      "address": "7 Carmine St, New York, NY 10014",
      "phone": "(212) 366-1182",
      "website": "https://joespizzanyc.com",
      "rating": 4.5,
      "category": "Pizza restaurant"
    },
    "reviews": [
      {
        "review_id": "abc123",
        "author": "John D.",
        "rating": 5,
        "text": "Best pizza in NYC!",
        "date": "2 weeks ago",
        "is_local_guide": true,
        "has_owner_response": false
      }
    ],
    "review_analysis": {
      "total_extracted": 50,
      "rating_distribution": {
        "5_star": 35,
        "4_star": 8,
        "3_star": 4,
        "2_star": 2,
        "1_star": 1
      },
      "negative_reviews": ["Service was slow...", "Overpriced for what you get..."],
      "negative_count": 3,
      "negative_percentage": 6.0,
      "owner_response_rate_negative": 66.7,
      "common_complaints": ["service", "value"]
    },
    "photos": [
      "https://media.spideriq.ai/client-cli_xxx/gmaps/gmaps_enrich_0x123_1.jpg",
      "https://media.spideriq.ai/client-cli_xxx/gmaps/gmaps_enrich_0x123_2.jpg"
    ],
    "review_tags": ["Great pizza", "Fast service", "Cash only"],
    "menu_link": "https://joespizzanyc.com/menu",
    "street_view_url": "https://www.google.com/maps/@40.7305,-73.9996,3a,75y,90t/data=...",
    "popular_times": {},
    "related_places_found": 15,
    "metadata": {
      "worker_id": "spider-maps-enrich-1",
      "vps_id": "llm5",
      "proxy_used": true,
      "scrape_time_ms": 42094,
      "reviews_extracted": 50,
      "reviews_returned": 50,
      "photos_extracted": 5,
      "photos_hosted": 5,
      "negative_reviews_count": 3
    }
  }
}

Complaint Categories

The common_complaints field categorizes negative reviews:
CategoryKeywords Detected
serviceslow service, rude, ignored, unfriendly
food_qualitycold food, stale, undercooked, bland
cleanlinessdirty, filthy, bugs, smell
valueoverpriced, expensive, ripoff, small portions
wait_timelong wait, slow, took forever
managementmanager, owner, refused, no refund

Processing Time

ConfigurationTypical Time
Basic enrichment (no reviews)15-30 seconds
With 50 reviews30-60 seconds
With 200 reviews60-120 seconds
With proxyAdd 15-30 seconds

Error Cases

Invalid Identifier

{
  "detail": "At least one of google_place_id, google_cid, or place_url is required"
}

Place Not Found

{
  "success": false,
  "status": "failed",
  "error": "Place not found at provided identifier"
}

Next Steps