Skip to main content

Submit SpiderMaps Job

POST/api/v1/jobs/spiderMaps/submit

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​

payloadobjectrequired

Job configuration payload

priorityintegerdefault: 0

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

Response​

successboolean

Whether the job was successfully queued

job_idstring

Unique identifier for the submitted job (UUID format)

typestring

Always spiderMaps for this endpoint

statusstring

Initial job status (always queued)

messagestring

Confirmation message

Example Request​

curl -X POST https://spideriq.ai/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​

{
  "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_namestring

Official business name

data.addressstring

Full formatted address

data.phonestring

Phone number (raw format as displayed on Google Maps)

data.phone_e164string

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

Example: +33147075514

data.phone_nationalstring

Phone number in national format (v2.7.0+)

Example: 01 47 07 55 14

data.phone_typestring

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_validboolean

Whether the phone number format is valid (v2.7.0+)

Note: Invalid numbers still include phone field with raw value.

data.image_urlstring

Permanent URL to business image stored in SeaweedFS (v2.7.0+)

Format: https://media.spideriq.ai/vibe/gmaps_{place_id}_1.jpg

Note: Returns Google URL as fallback if storage fails. Null if no images available.

data.websitestring

Business website URL

data.ratingnumber

Google Maps rating (1.0 - 5.0)

data.review_countinteger

Total number of Google reviews

data.hoursobject

Business hours by day of week

Example:

{
  "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.categoriesarray

Business categories/types

Example: ["Restaurant", "Italian Restaurant", "Pizza Place"]

data.place_idstring

Google Maps Place ID (unique identifier)

data.coordinatesobject

Latitude and longitude

Example: {"lat": 37.4220, "lng": -122.0841}

data.photosarray

URLs to business photos

data.price_levelstring

Price range indicator ($ to $$$$)

data.popular_timesobject

Hourly popularity data (if available)

data.fuzziq_uniqueboolean

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.spideriq.ai/vibe/gmaps_ChIJkxq-0GRv5kcR5q-bLdl_5lY_1.jpg",
    "amenities": ["Dine-in", "Takeaway", "Delivery"],
    "accessibility": "Wheelchair-accessible car park",
    "fuzziq_unique": true
  }
}
note

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.ai/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​

  1. Go to Google Maps
  2. Search for the business
  3. 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​

warning

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

info

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

tip

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