Submit SpiderMaps Job - SpiderIQ API

Overview

Submit a SpiderMaps job to scrape business data from Google Maps. SpiderMaps uses the Google Maps Places API to extract comprehensive business information.

Best For

Local business research
Competitor analysis
Business directory creation
Lead generation
Location-based services
Market research

Request Body

payload

object

required

Job configuration payload

Show properties

search_query

string

Search query for Google Maps (e.g., “restaurants in Berlin, Germany”)Primary method for bulk scraping. Returns up to 100-120 businesses per query.Examples:

"Restaurant Berlin, Germany"
"Coffee shops 10711, Germany" (with postal code)
"Hotels Paris, France"

Note: Either search_query OR url is required (not both)

url

string

Google Maps URL or Place ID for a specific businessAlternative method for single business lookups.Formats accepted:

Full Google Maps URL: https://www.google.com/maps/place/...
Short URL: https://maps.app.goo.gl/...
Place ID: ChIJN1t_tDeuEmsRUsoyG83frY4

Example: https://www.google.com/maps/place/Golden+Gate+Bridge/@37.8199,-122.4783Note: Either search_query OR url is required (not both)

max_results

integer

default:"10"

Maximum number of results to scrape (1-100)For search queries, returns up to 100-120 businesses. For URLs, typically returns 1.

lang

string

default:"en"

Language code for Google Maps (en, es, fr, de, it, pt, etc.)Tip: Use local language for better results (e.g., “de” for Germany, “fr” for France)

extract_reviews

boolean

default:"false"

Extract customer reviews (increases processing time by 20-40 seconds)Warning: Significantly increases processing time

extract_photos

boolean

default:"false"

Extract photo URLs from listings (increases processing time by 10-20 seconds)Warning: Increases processing time

headless

boolean

default:"true"

Run browser in headless mode (recommended for production)Set to false only for debugging purposes

store_images

boolean

default:"true"

Store first business image in SeaweedFS media server (v2.7.0+)Returns permanent URL in image_url field instead of temporary Google URL.Example: https://media.di-atomic.com/vibe/gmaps_ChIJxxx_1.jpg

validate_phones

boolean

default:"true"

Validate and format phone numbers using libphonenumber (v2.7.0+)Returns validated phone data in phone_e164, phone_national, phone_type, and phone_valid fields.

fuzziq_enabled

boolean

Enable FuzzIQ deduplication for this job (v2.18.0+)When enabled, each business in the results will include a fuzziq_unique flag indicating whether it’s a new record or duplicate.Default: Uses client-level setting (typically true)

fuzziq_unique_only

boolean

Return only unique records, filtering out duplicates (v2.18.0+)When true, businesses that are duplicates of previously seen records will be excluded from the response.Default: Uses client-level setting (typically false)

priority

integer

default:"0"

Job priority (0-10, higher = processed first)

Response

success

boolean

Whether the job was successfully queued

job_id

string

Unique identifier for the submitted job (UUID format)

type

string

Always spiderMaps for this endpoint

status

string

Initial job status (always queued)

message

string

Confirmation message

Example Request

curl -X POST https://spideriq.di-atomic.com/api/v1/jobs/spiderMaps/submit \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.google.com/maps/place/Googleplex/@37.4220656,-122.0840897"
  }'

Example Response

201 Created

{
  "success": true,
  "job_id": "660e8400-e29b-41d4-a716-446655440001",
  "type": "spiderMaps",
  "status": "queued",
  "message": "SpiderMaps job queued successfully"
}

SpiderMaps Results Structure

When the job completes, results will include:

data.business_name

string

Official business name

data.address

string

Full formatted address

data.phone

string

Phone number (raw format as displayed on Google Maps)

data.phone_e164

string

Phone number in E.164 international format (v2.7.0+)Example: +33147075514

data.phone_national

string

Phone number in national format (v2.7.0+)Example: 01 47 07 55 14

data.phone_type

string

Phone number type detected by libphonenumber (v2.7.0+)Values: MOBILE, FIXED_LINE, FIXED_LINE_OR_MOBILE, VOIP, TOLL_FREE, PREMIUM_RATE, UNKNOWN

data.phone_valid

boolean

Whether the phone number format is valid (v2.7.0+)Note: Invalid numbers still include phone field with raw value.

data.image_url

string

Permanent URL to business image stored in SeaweedFS (v2.7.0+)Format: https://media.di-atomic.com/vibe/gmaps_{place_id}_1.jpgNote: Returns Google URL as fallback if storage fails. Null if no images available.

data.website

string

Business website URL

data.rating

number

Google Maps rating (1.0 - 5.0)

data.review_count

integer

Total number of Google reviews

data.hours

object

Business hours by day of weekExample:

{
  "monday": "9:00 AM - 5:00 PM",
  "tuesday": "9:00 AM - 5:00 PM",
  "wednesday": "9:00 AM - 5:00 PM",
  "thursday": "9:00 AM - 5:00 PM",
  "friday": "9:00 AM - 5:00 PM",
  "saturday": "Closed",
  "sunday": "Closed"
}

data.categories

array

Business categories/typesExample: ["Restaurant", "Italian Restaurant", "Pizza Place"]

data.place_id

string

Google Maps Place ID (unique identifier)

data.coordinates

object

Latitude and longitudeExample: {"lat": 37.4220, "lng": -122.0841}

data.photos

array

URLs to business photos

data.price_level

string

Price range indicator ($ to $$$$)

data.popular_times

object

Hourly popularity data (if available)

data.fuzziq_unique

boolean

Whether this business is unique in your dataset (v2.18.0+)

true: First time this business has been seen
false: This business is a duplicate of a previously scraped record

Note: Only present when fuzziq_enabled is true (default)

Complete Results Example

{
  "success": true,
  "job_id": "660e8400-e29b-41d4-a716-446655440001",
  "type": "spiderMaps",
  "status": "completed",
  "data": {
    "name": "La Réserve Du Terroir",
    "address": "13 R. Quincampoix, 75004 Paris, France",
    "phone": "33147075514",
    "phone_e164": "+33147075514",
    "phone_national": "01 47 07 55 14",
    "phone_type": "FIXED_LINE",
    "phone_valid": true,
    "website": "https://la-reserve-du-terroir-paris.com",
    "rating": 4.6,
    "reviews_count": 1385,
    "categories": ["French restaurant", "Wine bar"],
    "place_id": "ChIJkxq-0GRv5kcR5q-bLdl_5lY",
    "google_place_id": "ChIJkxq-0GRv5kcR5q-bLdl_5lY",
    "coordinates": {
      "latitude": 48.859703,
      "longitude": 2.349799
    },
    "image_url": "https://media.di-atomic.com/vibe/gmaps_ChIJkxq-0GRv5kcR5q-bLdl_5lY_1.jpg",
    "amenities": ["Dine-in", "Takeaway", "Delivery"],
    "accessibility": "Wheelchair-accessible car park",
    "fuzziq_unique": true
  }
}

v2.18.0 FuzzIQ Deduplication:

fuzziq_unique: true if this business is new, false if duplicate
Use fuzziq_unique_only: true in request to filter out duplicates

v2.7.0 Phone Validation:

phone_e164: E.164 formatted phone number
phone_national: Locally formatted phone number
phone_type: Type of phone (MOBILE, FIXED_LINE, VOIP, etc.)
phone_valid: Whether the phone is valid
image_url: Permanent hosted image URL

Use Cases

Local Business Research

# Research all coffee shops in a city
urls = [
    "https://www.google.com/maps/place/Coffee+Shop+A",
    "https://www.google.com/maps/place/Coffee+Shop+B",
    "https://www.google.com/maps/place/Coffee+Shop+C"
]

for url in urls:
    response = requests.post(
        "https://spideriq.di-atomic.com/api/v1/jobs/spiderMaps/submit",
        headers=headers,
        json={"url": url}
    )

Competitor Analysis

# Extract specific competitor data
data = {
    "url": "https://www.google.com/maps/place/Competitor+Restaurant",
    "fields": ["name", "rating", "review_count", "hours", "price_level"]
}

Lead Generation

# Extract contact information for outreach
data = {
    "url": "https://www.google.com/maps/place/Potential+Client",
    "fields": ["name", "phone", "website", "address"]
}

Finding Google Maps URLs

Method 1: Search on Google Maps

Go to Google Maps
Search for the business
Copy the URL from the address bar

Method 2: Short URLs

Click “Share” on Google Maps and copy the short URL:

https://maps.app.goo.gl/ABC123xyz

Method 3: Place ID

If you have a Place ID, you can use it directly:

ChIJN1t_tDeuEmsRUsoyG83frY4

Processing Time

Average: 3-8 seconds per business
With photos: Add 2-5 seconds

Limitations

API Quota: Google Maps API has daily quota limits. If quota is exceeded, jobs will fail with an error message.

Data accuracy: Data is sourced directly from Google Maps and is as accurate as Google’s information.

Batch processing: Submit multiple jobs concurrently for faster bulk scraping (respecting rate limits).

Error Cases

Invalid URL

{
  "detail": "Invalid Google Maps URL. Please provide a valid maps.google.com URL or Place ID."
}

Business Not Found

{
  "success": false,
  "job_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "failed",
  "error": "Business not found at provided URL"
}

API Quota Exceeded

{
  "success": false,
  "job_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "failed",
  "error": "Google Maps API quota exceeded. Please try again later."
}

Next Steps

Check Status

Monitor job progress

Get Results

Retrieve business data

Submit Generic Job

Use generic submit endpoint

SpiderSite Job

Scrape website content

API Reference

​Overview

​Best For

​Request Body

​Response

​Example Request

​Example Response

​SpiderMaps Results Structure

​Complete Results Example

​Use Cases

​Local Business Research

​Competitor Analysis

​Lead Generation

​Finding Google Maps URLs

​Method 1: Search on Google Maps

​Method 2: Short URLs

​Method 3: Place ID

​Processing Time

​Limitations

​Error Cases

​Invalid URL

​Business Not Found

​API Quota Exceeded

​Next Steps

Check Status

Get Results

Submit Generic Job

SpiderSite Job

Overview

Best For

Request Body

Response

Example Request

Example Response

SpiderMaps Results Structure

Complete Results Example

Use Cases

Local Business Research

Competitor Analysis

Lead Generation

Finding Google Maps URLs

Method 1: Search on Google Maps

Method 2: Short URLs

Method 3: Place ID

Processing Time

Limitations

Error Cases

Invalid URL

Business Not Found

API Quota Exceeded

Next Steps