Google Maps स्क्रैपर डॉक्स। क्वेरी से एक्सपोर्ट तक।

एक असली टास्क से शुरू करें#

1. एक वर्कस्पेस बनाएँ और व्यवसाय खोजें खोलें।
2. इसकी लोकेशन के साथ एक क्वेरी डालें, उदाहरण के लिए “ऑस्टिन, TX में डेंटिस्ट”।
3. अपनी रिकॉर्ड लिमिट और ऑप्शनल फ़िल्टर चुनें। रिट्रीवल के बाद फ़िल्टर लागू होते हैं।
4. मैक्सिमम यूनिट इस्तेमाल को रिव्यू करें। एनरिचमेंट रिज़र्व्ड सीलिंग को बढ़ाता है।
5. रन करें, सोर्स देखें, बिज़नेस चुनें और लिस्ट में सेव करें या CSV एक्सपोर्ट करें।

सेव की गई लिस्ट में एनरिचमेंट वापस लिखें#

“सेव की गई लिस्ट” में, ऐसे रिकॉर्ड चुनें जिनमें सोर्स ID हो और “चुना गया एनरिच करें” को उसके मैक्सिमम यूनिट बजट के साथ ऑथराइज़ करें। “बैच राइट-बैक की समीक्षा करें” नया बैच खोलता है; पेंडिंग टास्क बाद के प्रीव्यू तक स्किप रहते हैं। आप लिस्ट टूलबार से मौजूदा डिटेल्स या एनरिचमेंट बैच भी चुन सकते हैं।

एकदम सही रिक्वेस्ट की गई ID का प्रीव्यू करें और हर पहले/बाद की तुलना को एक्सपैंड करें। खाली फ़ील्ड भरने से मौजूदा वैल्यू बनी रहती हैं; चुने गए फ़ील्ड बदलने से सिर्फ़ आपके चुने हुए खाली सोर्स फ़ील्ड कॉपी होते हैं। स्किप की गई लिस्ट में डुप्लीकेट, अनमैच, एक्सपायर या रुके हुए टास्क रिव्यू करें। अप्लाई करने से पहले दिखाए गए चेंज्ड-रिकॉर्ड और स्किप्ड-टास्क काउंट को कन्फर्म करें। बदले हुए रिकॉर्ड, सोर्स या कॉन्फ़िगरेशन के लिए नए प्रीव्यू की ज़रूरत होती है।

सभी एलिजिबल अपडेट एक साथ कमिट होते हैं। स्टेज, नोट्स, टैग, असाइनमेंट और कस्टम फ़ील्ड वैसे ही रहते हैं। बैच राइट-बैक हिस्ट्री ओरिजिनल वैल्यू और हर रिकॉर्ड के लिए अनडू दिखाती है; बाद के एडिट रिस्टोरेशन को ब्लॉक करते हैं। वर्कस्पेस सेटिंग्स इनेबलमेंट और रिकॉर्ड कैप को कंट्रोल करती हैं। रिटेन किए गए रिज़ल्ट को वापस लिखने से कोई रिसर्च यूनिट इस्तेमाल नहीं होती है और यह डेटा स्रोत को कॉल नहीं करता है। अनसुलझे इंपोर्ट अभी भी अलग-अलग “मैच करें और मर्ज करें” का इस्तेमाल करते हैं।

एजेंट preview_batch_merge, apply_reviewed_batch_merge और read_batch_merge_receipt का इस्तेमाल एक ही रिव्यू हैश, स्कोप और आइडेम्पोटेंसी रिक्वायरमेंट के साथ करते हैं। सोर्स रिकॉर्ड से कभी भी राइट ऑथराइजेशन का अंदाजा न लगाएं।

किसी बिज़नेस होमपेज को इंस्पेक्ट करें#

खोलें वेबसाइट ऑडिट, या सेव किए गए रिकॉर्ड से इस वेबसाइट को इंस्पेक्ट करें चुनें। नॉर्मलाइज़्ड होमपेज को रिव्यू करें, एक यूनिट का अनुमान लगाएं और उसे ऑथराइज़ करें। पूरे किए गए HTTP/HTML ऑब्ज़र्वेशन को इंस्पेक्ट करें, उसे एक्सपोर्ट करें, एक रिपोर्ट बनाएं या एक रेगुलर मॉनिटर सेट करें। बल्क रिसर्च भी हर लाइन में एक वेबसाइट एक्सेप्ट करता है।

होमपेज जाँच लाइव मैप्स डेटा स्रोत का उपयोग नहीं करती। यह अधिकतम 256 KiB पढ़ती है, पाँच तक सुरक्षित रीडायरेक्ट का अनुसरण करती है और 15 सेकंड बाद रुक जाती है। यह JavaScript नहीं चलाती और रैंकिंग स्कोर नहीं निकालती। अवरुद्ध या समयसीमा पार करने वाली जाँच में भी एक इकाई लगती है।

{"kind":"website_audit","url":"https://example.com/","limit":1}

REST API#

GET      /api/health
GET      /api/me
GET      /api/v1/usage
POST     /api/v1/estimate
POST     /api/v1/jobs
GET      /api/v1/jobs/{id}
GET      /api/v1/jobs/{id}/results
POST     /api/v1/jobs/{id}/cancel
GET      /api/v1/jobs/{id}/export
GET/POST /api/v1/lists
GET/POST /api/v1/lists/{id}/items
PATCH    /api/v1/lists/{id}/items/{business_id}
GET/POST /api/monitors
PATCH    /api/monitors/{id}
POST     /mcp

एक बाउंडेड जॉब बनाएँ#

curl -X POST https://mapsscraper.dev/api/v1/jobs \
  -H "Authorization: Bearer $MAPSSCRAPER_API_KEY" \
  -H "Idempotency-Key: dentists-austin-tx-001" \
  -H "X-Max-Units: 1" \
  -H "Content-Type: application/json" \
  -d '{"kind":"search","query":"Dentists in Austin, TX","limit":20,"region":"us"}'

HTTP/1.1 202 Accepted
{"id":"6f1c2b3a-0000-4000-8000-000000000000","status":"queued","reserved":1}

उसी व्यावसायिक कार्रवाई को उसी आइडेम्पोटेंसी कुंजी के साथ दोबारा आज़माएँ। उस कुंजी के साथ बदला हुआ अनुरोध 409 लौटाता है। कार्य कतार में, चल रहा, पूरा, आंशिक, विफल, रद्द या अनिश्चित स्थितियों से गुज़रते हैं। अनिश्चित डेटा स्रोत अनुरोध के लिए स्वचालित सशुल्क रीप्ले के बजाय मिलान ज़रूरी है।

ज़्यादातर कार्य एक यूनिट उपयोग करते हैं। खोज या रैंक स्नैपशॉट पर संपर्क संवर्धन हर अनुरोधित रिकॉर्ड के लिए एक और यूनिट आरक्षित करता है और केवल मिले हुए रिकॉर्ड का शुल्क लेता है। व्यवसाय विवरण एक यूनिट लेते हैं, या संपर्क के साथ दो; संवर्धन दो यूनिट लेता है। X-Max-Units को कम से कम अनुमान के बराबर सेट करें।

Python में टास्क का अनुमान लगाएं, requests लाइब्रेरी से जॉब बनाएं, फ़ाइनल स्टेटस का इंतज़ार करें और सहेजे गए नतीजे पढ़ें:

import os
import time
import uuid

import requests

API = "https://mapsscraper.dev/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MAPSSCRAPER_API_KEY']}"}
task = {"kind": "search", "query": "Dentists in Austin, TX", "limit": 20, "region": "us"}

# An estimate reserves nothing.
units = requests.post(f"{API}/estimate", json=task, headers=HEADERS, timeout=30).json()["units"]

# Keep the key: a retry of the same task must send it again.
key = str(uuid.uuid4())
job = requests.post(
    f"{API}/jobs",
    json=task,
    headers={**HEADERS, "Idempotency-Key": key, "X-Max-Units": str(units)},
    timeout=30,
)
job.raise_for_status()
job_id = job.json()["id"]

while True:
    status = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS, timeout=30).json()["status"]
    if status not in ("queued", "running"):
        break
    time.sleep(5)

if status in ("completed", "partial"):
    page = requests.get(
        f"{API}/jobs/{job_id}/results",
        params={"offset": 0, "limit": 100},
        headers=HEADERS,
        timeout=30,
    ).json()
    for business in page["items"]:  # follow page["next_offset"] for more
        print(business.get("name"), business.get("phone_number"), business.get("website"))

आम गलतियाँ#

हर त्रुटि प्रतिक्रिया एक स्थिर कोड के साथ JSON होती है, और कुछ में विवरण भी होते हैं। कोड के आधार पर निर्णय लें; कई कोड एक ही HTTP स्थिति साझा कर सकते हैं।

{"error":{"code":"TASK_BUDGET_TOO_LOW","details":{"needed":11,"max_units":5}}}

AI सर्च जवाब की जांच करें#

AI सर्च विज़िबिलिटी एक Google AI ओवरव्यू ऑब्ज़र्वेशन को बनाए रखती है: सवाल, देश, भाषा, ऑप्शनल शहर का बायस, जवाब का टेक्स्ट और सेफ़ साइटेशन लिंक। ज़्यादा से ज़्यादा पाँच ब्रांड नाम और डोमेन जोड़ें, एक-यूनिट मैक्सिमम को रिव्यू करें, फिर टास्क को साफ़ तौर पर ऑथराइज़ करें। आपके एडमिनिस्ट्रेटर को वर्कस्पेस इनेबल करना होगा और एक लाइसेंस्ड सोर्स कनेक्ट करना होगा।

डेटा स्रोत को दोबारा कॉल किए बिना हिस्ट्री इंस्पेक्ट करें या एविडेंस एक्सपोर्ट करें। बेसलाइन की तुलना तभी करें जब क्वेरी, लोकेल और टारगेट मैच करें। मिसिंग ओवरव्यू का मतलब है अनजान विज़िबिलिटी; साइटेशन ऑर्डर सर्च रैंक नहीं है। अधूरे एविडेंस नेगेटिव मैच साबित नहीं कर सकते। मल्टी-इंजन ट्रैकिंग उपलब्ध नहीं है।

प्रश्नों के एक तय सेट पर नज़र रखने के लिए, सत्यापित मालिक या एडमिन एक आवर्ती सीरीज़ शेड्यूल कर सकता है: अधिकतम 10 प्रॉम्प्ट, हर 24 से 720 घंटे में, 90 दिनों के भीतर अधिकतम 30 अवलोकन। पूरी सीरीज़ के लिए अधिकतम यूनिट देखें और उसकी स्पष्ट पुष्टि करें। जब इसकी अनुमति या कॉन्फ़िगरेशन बदलता है, या कोई अवलोकन विफल या अनिश्चित होता है, तो सीरीज़ रुक जाती है; फिर से शुरू करने के लिए नया पूर्वावलोकन ज़रूरी है।

AI सर्च विज़िबिलिटी खोलें

किसी एरिया में सर्च करें और ज़्यादा पेज फ़ेच करें#

एक्सप्लोर में, एक टेक्स्ट लोकेशन, एक पॉइंट बायस, एक रेडियस या एक बाउंडिंग बॉक्स चुनें। पॉइंट बायस कोई बाउंड्री नहीं है। रेडियस और बॉक्स रिज़ल्ट बाहरी या इस्तेमाल न होने वाले कोऑर्डिनेट्स को बाहर करते हैं और एक्सक्लूज़न काउंट्स को बनाए रखते हैं। वर्कस्पेस सेटिंग्स रेडियस और बॉक्स साइज़ को कंट्रोल करती हैं। एंटीमेरिडियन को क्रॉस करने वाले बॉक्स को स्प्लिट करें; एक बाउंडेड सैंपल पूरा कवरेज साबित नहीं करता है।

रिव्यू और फोटो मेटाडेटा हर सोर्स पेज पर 100 रिकॉर्ड तक की इजाज़त देते हैं। रिज़ल्ट पूरा होने के बाद, एक्सप्लोर या टास्क हिस्ट्री में नतीजों के पेज खोलें। सही सोर्स ऑप्शन देखें, ऑथराइज़ेशन चेकबॉक्स पर टिक करें और एक और पेज लाने के लिए बजट सेट करें। सॉर्टिंग, भाषा, ट्रांसलेशन और फ़िल्टर चेन के लिए फिक्स्ड रहते हैं। गायब या दोहराए गए कर्सर, एक्सपायरी, कॉन्फ़िगर की गई लिमिट और अनिश्चित नतीजे कंटिन्यूएशन को रोकते हैं।

अगला सेव किया गया रिकॉर्ड पेज पढ़ना और मौजूदा पेज को एक्सपोर्ट करना डेटा स्रोत को कॉल नहीं करता है। नया सोर्स पेज लाना एक अलग पेड ऑपरेशन है। SDK और एजेंट के लिए, कंटिन्यूएशन प्रीव्यू पढ़ें, फिर एक स्टेबल आइडम्पोटेंसी की और साफ़ बजट के साथ उसका सही टास्क सबमिट करें। कर्सर कंटिन्यूएशन को शेड्यूल या बैच न करें।

पॉलीगॉन के अंदर रिसर्च प्लान करें#

एक्सैक्ट पॉलीगॉन फ़िल्टरिंग के साथ एक बाउंडेड रेक्टेंगल रिक्वेस्ट के लिए एक्सप्लोर में पॉलीगॉन बाउंड्री चुनें। बल्क रिसर्च में, GeoJSON पॉलीगॉन को इंपोर्ट या पेस्ट करने के लिए पॉलीगॉन बाउंड्री चुनें, उसके आकार की जांच करें, और हर सेल के लिए रो, कॉलम और रिकॉर्ड चुनें। स्कीमैटिक कोऑर्डिनेट और प्लान किए गए सेल दिखाता है; यह कोई स्ट्रीट मैप नहीं है।

पोजीशन [लॉन्गीट्यूड, लैटीट्यूड] का इस्तेमाल करती हैं। हर रिंग को उसकी पहली पोजीशन दोहराकर बंद करें; पहली रिंग बाहरी किनारा है और चार और रिंग तक बाहर रखे गए होल हैं। सेल्फ-इंटरसेक्शन, छूने वाले या ओवरलैप करने वाले होल, और एंटीमेरिडियन क्रॉसिंग रिजेक्ट हो जाते हैं। डेटलाइन पर अलग-अलग पॉलीगॉन का इस्तेमाल करें। वर्कस्पेस सेटिंग बाउंड पोजीशन, स्पैन और प्लान किए गए सेल।

“सेल रिव्यू करें & कुल बजट” डेटा स्रोत को कॉल नहीं करता है। हर रिटेन किए गए सेल की जांच करें, मैक्सिमम यूनिट सेट करें और चलाने से पहले साफ तौर पर कन्फर्म करें। सभी टास्क एक साथ रिज़र्व होते हैं या कोई भी स्वीकार नहीं किया जाता है। रसीदें ओरिजिनल प्लान और कॉन्फ़िगरेशन वर्शन को सुरक्षित रखती हैं। एक सोर्स रिज़ल्ट को पॉलीगॉन और सेल दोनों के लिए फ़िल्टर किया जाता है; शेयर्ड एज से डुप्लीकेट बिज़नेस बन सकते हैं। रिक्वेस्ट किया गया रिकॉर्ड काउंट एक सीलिंग है, सेंसस नहीं।

एजेंट preview_polygon_plan के बाद create_reviewed_polygon_batch का इस्तेमाल एकदम सही कॉम्पैक्ट प्लान, प्रीव्यू हैश, कन्फर्मेशन, स्टेबल की और एग्रीगेट बजट के साथ करते हैं। मौजूदा बैच हिस्ट्री, कैंसलेशन और हर टास्क के रिजल्ट/एक्सपोर्ट कंट्रोल का इस्तेमाल करें। अनिश्चित आउटकम कभी भी ऑटोमैटिकली दोबारा स्कैन नहीं किए जाते हैं।

रिटेन किए गए पेज चेन को एक्सपोर्ट करें#

नतीजों के पेज में, मल्टी-पेज एक्सपोर्ट खोलें और फुल-चेन एक्सपोर्ट का रिव्यू करें चुनें। चुने गए टास्क के ज़रिए पेज को रिव्यू करें, चुनें कि हर एकदम सही ID के लिए पहला रिकॉर्ड रखना है या सभी रिकॉर्ड रखना है, फिर प्राइवेट एक्सपोर्ट को कन्फर्म करें। इससे नया डेटा नहीं मिलता है या रिसर्च यूनिट का इस्तेमाल नहीं होता है। एक्सपोर्ट, प्रोग्रेस, कैंसलेशन और इंटीग्रिटी रिसीट के साथ डेटा कंट्रोल में भी दिखाई देते हैं।

पूरा होने के बाद JSONL, JSON, CSV या Excel डाउनलोड करें। बदले हुए कंटेंट वाले डुप्लीकेट ID को कॉन्फ्लिक्ट माना जाता है; पहला रिकॉर्ड सेव रहता है। बिना ID वाले रिकॉर्ड अलग रहते हैं। हर सोर्स पेज का अपना वेरिफाइड JSONL पार्ट होता है, इसलिए फेल हुआ ट्रांसफर पार्ट के हिसाब से फिर से शुरू हो सकता है। Excel 5 MB तक स्टोर किए गए पार्ट्स को सपोर्ट करता है; बड़े एक्सपोर्ट स्ट्रीमिंग फॉर्मेट का इस्तेमाल करते हैं। CSV, extra_fields_json में एक्स्ट्रा कॉलम रखता है।

ओनर और एडमिन सेटिंग्स में डेली रिक्वेस्ट, पेंडिंग एक्सपोर्ट, पेज और सोर्स बाइट लिमिट, और रिटेंशन को कॉन्फ़िगर करते हैं। सबसे पहले सोर्स की एक्सपायरी हमेशा लागू होती है। JSON या JSONL का इस्तेमाल करते समय पूरा मार्कर रखें, और डाउनलोड किए गए पार्ट्स को उनके SHA-256 रिसीट से वेरिफ़ाई करें। एक फ़्रोज़न चेन एक रिटेन किया गया सैंपल है, पूरे मार्केट कवरेज का प्रूफ़ नहीं।

साइट किए गए सबूतों के साथ रिव्यू थीम का एनालिसिस करें#

रिपोर्ट्स में रिव्यू स्टैटिस्टिक्स रिपोर्ट से शुरू करें। एक ओनर या एडमिन सेटिंग्स और इस्तेमाल में AI रिव्यू एनालिसिस चालू करता है और डेली कोशिशें, पेंडिंग टास्क, एक्सट्रैक्ट काउंट और क्यू लाइफ़टाइम सेट करता है। यह डिफ़ॉल्ट रूप से बंद रहता है।

एक जेनरेशन को ऑथराइज़ करने से पहले सही एक्सट्रैक्ट और मॉडल की जांच करने के लिए “एनालिसिस इनपुट रिव्यू करें” चुनें। रिपोर्ट ऑर्डर में 40 अलग-अलग एक्सट्रैक्ट और 10 KB तक एक्सट्रैक्ट टेक्स्ट चुने जाते हैं। एक जेनरेशन की अपनी AI एनालिसिस कैप होती हैं और यह मैप्स वॉलेट यूनिट का इस्तेमाल नहीं करता है। फेल या कैंसल की गई कोशिशें अभी भी गिनी जाती हैं।

हर सेव की गई थीम में चेक किए गए कोटेशन और सोर्स रेफरेंस शामिल होते हैं। काउंट अलग-अलग साइट किए गए हिस्सों से कैलकुलेट किए जाते हैं, थीम ओवरलैप हो सकती हैं, और AI इंटरप्रिटेशन गलत हो सकते हैं। रिज़ल्ट एक अलग रिपोर्ट के तौर पर खुलता है: इसे रिपोर्ट्स में देखें, फिर चुनें कि क्या शेयर करना है या PDF के तौर पर एक्सपोर्ट करना है। रिव्यू हिस्से कॉलम को छिपाने से AI एनालिसिस भी छिप जाता है।

जिन हिस्सों में कोई सपोर्टेड कस्टमर एक्सपीरियंस नहीं होता, वे बिना किसी रिपोर्ट के सबूत-इनसफिशिएंट रसीद दे सकते हैं। कोशिश अभी भी लिमिट में गिनी जाती है। किसी दूसरे एनालिसिस को ऑथराइज़ करने से पहले इनपुट को देखें। एक कैपेबिलिटी अपग्रेड पुराने क्यू में लगे अप्रूवल को इनफेरेंस से पहले रोक देता है; एक नया प्रीव्यू रिव्यू करें। मौजूदा रिपोर्ट अपना ओरिजिनल मॉडल और प्रॉम्प्ट वर्शन बनाए रखती हैं।

रसीदें क्यू में लगे, चल रहे, पूरे हुए, फेल, अनिश्चित, कैंसल या एक्सपायर हुए नतीजे दिखाती हैं। कैंसलेशन से रिपोर्ट बनने से रोका जाता है, हालांकि डिस्पैच किया गया एनालिसिस अभी भी लिमिट में गिना जाता है। अनिश्चित कॉल कभी भी ऑटोमैटिकली दोबारा नहीं चलाई जाती हैं। API, SDK और MCP एक ही प्रीव्यू हैश, साफ़ कन्फर्मेशन और आइडेम्पोटेंसी की का इस्तेमाल करते हैं।

क्लाइंट रिपोर्ट तैयार करें और शेयर करें#

रिपोर्ट्स में पूरी हुई रिसर्च से एक रिपोर्ट बनाएं। इसका टाइटल, ब्रांड, सेक्शन ऑर्डर और एविडेंस कॉलम एडिट करें, फिर प्रेजेंटेशन सेव करें। वर्कस्पेस सेटिंग्स डिफ़ॉल्ट ब्रांड कलर, एक बाउंडेड PNG लोगो, पब्लिशर वेबसाइट और फुटर देती हैं। मौजूदा सेव किए गए प्रेजेंटेशन तभी बदलते हैं जब आप उन्हें एडिट करते हैं या वर्कस्पेस डिफ़ॉल्ट लागू करते हैं।

रिव्यू की गई रिपोर्ट शेयर करें, जो एकदम सही पब्लिक प्रोजेक्शन दिखाती है। बिना चुने हुए एविडेंस फ़ील्ड और छिपे हुए सेक्शन स्टोर किए गए स्नैपशॉट से बाहर रखे जाते हैं। सोर्स क्वेरी डिफ़ॉल्ट रूप से प्राइवेट होती हैं; मेथोडोलॉजी दिखती रहती है। लिंक वाले किसी भी व्यक्ति या 25 वेरिफाइड ईमेल अकाउंट तक चुनें, एक एक्सपायरी सेट करें, और कंटेंट और ऑडियंस को साफ़ तौर पर कन्फर्म करें। आप शेयर पासवर्ड की भी ज़रूरत डाल सकते हैं; इसे लिंक से अलग से भेजें। वर्कस्पेस पॉलिसी हर रिज़ल्ट/रिपोर्ट शेयर पर पासवर्ड की ज़रूरत डाल सकती है। कोई इनविटेशन या ईमेल नहीं भेजा जाता है।

पूरा लिंक एक बार कॉपी करें। सीक्रेट अपने हिस्से में रहता है और ब्राउज़र स्टोरेज में नहीं रहता है। रिस्ट्रिक्टेड एक्सेस वाला रिसीवर एक अलाउड वेरिफाइड अकाउंट से साइन इन करता है, फिर ओरिजिनल लिंक खोलता है और रिक्वेस्ट किए जाने पर शेयर पासवर्ड डालता है। पासवर्ड रिकवर नहीं किए जा सकते; अगर कोई खो जाए तो उसे रद्द करें और नया लिंक बनाएं। एक्सपायरी सोर्स रिटेंशन से लिमिटेड होती है। डेटा कंट्रोल भविष्य का एक्सेस रद्द कर सकते हैं; डिलीट की गई रिपोर्ट, एक्सपायर हो चुके सोर्स और पॉज़्ड वर्कस्पेस नए रीड्स को रोकते हैं। डाउनलोड की गई कॉपी वापस नहीं ली जा सकतीं। JSON और ब्राउज़र प्रिंट / सेव PDF दिखाए गए प्रेजेंटेशन का इस्तेमाल करते हैं। सेव किया गया PDF जेनरेट करने से सेव किए गए वर्शन से एक प्राइवेट फ़ाइल बनती है, जिसमें A4 या लेटर पेपर और पोर्ट्रेट या लैंडस्केप ओरिएंटेशन होता है। पूरी की गई फ़ाइलों को मैचिंग रिव्यू किए गए शेयर से अटैच किया जा सकता है और उसके एक्सेस रूल्स इनहेरिट किए जा सकते हैं।

एजेंट preview_report_delivery, update_report_presentation, create_reviewed_report_share, list_report_shares और revoke_report_share का इस्तेमाल करते हैं। पब्लिकेशन के लिए रिव्यू किया गया वर्शन, स्नैपशॉट हैश, एक स्टेबल आइडेम्पोटेंसी की और साफ शेयरिंग ऑथराइजेशन की ज़रूरत होती है। एक्सटर्नल रिसर्च टेक्स्ट वह ऑथराइजेशन नहीं दे सकता।

एक रिटेन किया गया PDF जेनरेट करें#

प्रेजेंटेशन सेव करें, PDF एक्सपोर्ट में पेपर और ओरिएंटेशन चुनें, फिर जेनरेट करें। हिस्ट्री डाउनलोड या कैंसल कंट्रोल के साथ क्यूड, रेंडरिंग, पूरे हुए और रुके हुए रिक्वेस्ट दिखाती है। वर्कस्पेस सेटिंग्स इनेबलमेंट, डेली रिक्वेस्ट, पेंडिंग रिक्वेस्ट और रिटेंशन को कंट्रोल करती हैं। फ़ाइलें अपने सोर्स या कॉन्फ़िगर किए गए रिटेंशन पीरियड के साथ एक्सपायर हो जाती हैं, जो भी पहले आए। रेंडरिंग में रिसर्च यूनिट खर्च नहीं होती हैं। फेल या अनिश्चित रेंडर के लिए एक नए एक्सप्लिसिट रिक्वेस्ट की ज़रूरत होती है; वे ऑटोमैटिकली दोबारा कोशिश नहीं करते हैं।

एजेंट रिव्यू किए गए वर्शन, स्नैपशॉट हैश, confirmed_render और एक आइडेम्पोटेंसी की के साथ generate_report_pdf का इस्तेमाल करते हैं। list_report_pdfs और get_report_pdf रसीदों की जांच करते हैं; cancel_report_pdf पेंडिंग पब्लिकेशन को रोकता है। जेनरेट कोई शेयर नहीं बनाता है या कोई मैसेज नहीं भेजता है। प्राइवेट डाउनलोड और पाने वाले के अटैचमेंट रूट OpenAPI में हैं।

साइन किए हुए जॉब रिसीट पाएं#

इंटीग्रेशन में, एक पब्लिक HTTPS रिसीवर जोड़ें। इसके वन-टाइम साइनिंग सीक्रेट को सुरक्षित रूप से सेव करें, सेटिंग्स और यूसेज में डिलीवरी चालू करें, फिर डेस्टिनेशन को साफ़ तौर पर चालू करें। पूरा हुआ, थोड़ा, फेल, अनिश्चित या कैंसल हुआ जॉब इवेंट चुनें। टेस्ट सिर्फ़ एक टेस्ट फ़्लैग और मेटाडेटा भेजते हैं।

हर डिलीवरी में दो हस्ताक्षर योजनाएँ होती हैं। Standard Webhooks के लिए, webhook-signature में v1, के बाद webhook-id, webhook-timestamp और अनुरोध के सटीक मूल बॉडी को बिंदुओं से जोड़कर बने टेक्स्ट का base64 HMAC-SHA256 होता है। कुंजी whsec_ के बाद वाले टेक्स्ट का base64 डिकोड है।

मूल योजना अपरिवर्तित है: X-LocalOS-Signature में v1= के बाद X-LocalOS-Timestamp, एक बिंदु और मूल बॉडी का hex HMAC-SHA256 होता है, जिसकी कुंजी टेक्स्ट के रूप में पूरा whsec_ सीक्रेट है। X-LocalOS-Key-ID से सीक्रेट चुनें।

किसी भी योजना में, पाँच मिनट के भीतर का टाइमस्टैम्प ज़रूरी रखें और हस्ताक्षरों की तुलना स्थिर समय में करें। webhook-id और X-LocalOS-Event-ID में इवेंट ID हर पुनःप्रयास में एक जैसी रहती है: कोई बदलाव लागू करने से पहले इसे अद्वितीय रूप से सहेजें और डुप्लिकेट को 2xx प्रतिक्रिया से स्वीकार करें।

Node.js में Standard Webhooks हस्ताक्षर सत्यापित करें:

// Verifies a webhook delivery with Web Crypto only, so it runs on
// Node.js 20+, Deno, Bun and Cloudflare Workers without dependencies.
//   const event = await verifyWebhook({ secret, headers, body });
// secret: "whsec_..." or, while rotating, ["whsec_new", "whsec_old"].
// headers: a Headers object or a plain map such as req.headers.
// body: the raw body as text or bytes, before any JSON parsing.
// Returns the parsed event. Otherwise throws an error whose code says
// why the delivery must not be trusted.
export class WebhookVerificationError extends Error {
  constructor(code) {
    super(code);
    this.name = "WebhookVerificationError";
    this.code = code;
  }
}

const encoder = new TextEncoder();

function header(headers, name) {
  if (typeof headers.get === "function") {
    return headers.get(name) ?? undefined;
  }
  for (const [key, value] of Object.entries(headers)) {
    if (key.toLowerCase() === name) {
      return Array.isArray(value) ? value[0] : value;
    }
  }
  return undefined;
}

function base64(value) {
  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value) || value.length % 4) {
    return null;
  }
  try {
    return Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
  } catch {
    return null;
  }
}

// Checks every byte, so the time taken does not reveal a mismatch.
function sameBytes(a, b) {
  if (a.length !== b.length) return false;
  let difference = 0;
  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i];
  return difference === 0;
}

export async function verifyWebhook({
  secret,
  headers,
  body,
  toleranceSeconds = 300,
}) {
  if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) {
    throw new RangeError("toleranceSeconds must be 0 or more");
  }
  const fail = (code) => new WebhookVerificationError(code);
  const keys = [secret]
    .flat()
    .map((value) =>
      typeof value === "string" ? base64(value.replace(/^whsec_/, "")) : null,
    );
  if (!keys.length || keys.some((key) => !key?.length)) {
    throw fail("WEBHOOK_SECRET_INVALID");
  }
  const id = header(headers, "webhook-id");
  const timestamp = header(headers, "webhook-timestamp");
  const signatures = header(headers, "webhook-signature");
  if (!id || !timestamp || !signatures) {
    throw fail("WEBHOOK_HEADER_MISSING");
  }
  if (!/^\d{1,12}$/.test(timestamp)) {
    throw fail("WEBHOOK_TIMESTAMP_INVALID");
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    throw fail("WEBHOOK_TIMESTAMP_OUT_OF_RANGE");
  }
  const subtle = globalThis.crypto?.subtle;
  if (!subtle) throw fail("WEBHOOK_CRYPTO_UNAVAILABLE");
  const raw =
    typeof body === "string" ? encoder.encode(body) : new Uint8Array(body);
  const prefix = encoder.encode(`${id}.${timestamp}.`);
  const signed = new Uint8Array(prefix.length + raw.length);
  signed.set(prefix);
  signed.set(raw, prefix.length);
  const expected = await Promise.all(
    keys.map(async (key) => {
      const hmac = await subtle.importKey(
        "raw",
        key,
        { name: "HMAC", hash: "SHA-256" },
        false,
        ["sign"],
      );
      return new Uint8Array(await subtle.sign("HMAC", hmac, signed));
    }),
  );
  // Any listed v1 signature may match; at most 16 are checked.
  const verified = signatures
    .split(" ")
    .filter(Boolean)
    .slice(0, 16)
    .some((entry) => {
      const [version, value] = entry.split(",", 2);
      const given = version === "v1" && value ? base64(value) : null;
      return given !== null && expected.some((d) => sameBytes(given, d));
    });
  if (!verified) throw fail("WEBHOOK_SIGNATURE_INVALID");
  try {
    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
  } catch {
    throw fail("WEBHOOK_PAYLOAD_INVALID");
  }
}

डिलीवरी कम से कम एक बार होती है। नेटवर्क विफलताएँ, टाइमआउट और 2xx के अलावा हर उत्तर दोबारा आज़माया जाता है, जिसमें रीडायरेक्ट भी शामिल हैं, जिन्हें कभी फ़ॉलो नहीं किया जाता। अधिकतम आठ प्रयास लगभग 28 घंटों में फैले होते हैं: 5 सेकंड, 5 मिनट, 30 मिनट, 2 घंटे, 5 घंटे के बाद, फिर दो बार 10 घंटे, या बाद में जब प्राप्तकर्ता Retry-After भेजता है (एक दिन तक)। 410 Gone उत्तर गंतव्य को रोक देता है और उसकी लंबित डिलीवरी तब तक रद्द कर देता है जब तक आप उसे फिर से शुरू नहीं करते। प्रयास और त्रुटियाँ इंटीग्रेशन में दिखाई देती हैं। किसी गंतव्य को रोकने या हटाने से लंबित रसीदें रद्द हो जाती हैं; पहले से स्वीकार किए गए अनुरोध दस सेकंड के भीतर पूरे हो सकते हैं। सहेजी गई डिलीवरी रसीदों में कोई व्यावसायिक रिकॉर्ड, खोज शब्द, खाता क्रेडेंशियल या प्राप्तकर्ता की प्रतिक्रिया बॉडी शामिल नहीं होती।

नतीजे Google Sheets, Zapier, Make या n8n पर भेजें#

const crypto = require("crypto");
const { body, id, timestamp, signature, secret } = inputData;
const fresh =
  /^\d+$/.test(timestamp || "") &&
  Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const key = Buffer.from(
  String(secret).replace(/^whsec_/, ""),
  "base64",
);
const expected = crypto
  .createHmac("sha256", key)
  .update(`${id}.${timestamp}.${body}`)
  .digest();
const signed = String(signature || "")
  .split(" ")
  .some((entry) => {
    const [version, value = ""] = entry.split(",");
    const given = Buffer.from(value, "base64");
    return (
      version === "v1" &&
      given.length === expected.length &&
      crypto.timingSafeEqual(given, expected)
    );
  });
const valid = Boolean(id) && fresh && signed;
if (!valid) return { valid };
return { valid, job_id: JSON.parse(body).data.job_id };

const API = "https://mapsscraper.dev/api/v1";

function getJson(path) {
  const key = PropertiesService.getScriptProperties()
    .getProperty("MAPSSCRAPER_API_KEY");
  if (!key) throw new Error("Add the MAPSSCRAPER_API_KEY script property.");
  const response = UrlFetchApp.fetch(API + path, {
    headers: { Authorization: "Bearer " + key },
    muteHttpExceptions: true,
  });
  const status = response.getResponseCode();
  const text = response.getContentText();
  if (status !== 200) {
    throw new Error("HTTP " + status + ": " + text.slice(0, 200));
  }
  return JSON.parse(text);
}

// Text that starts with =, +, - or @ gets an apostrophe,
// so Sheets keeps it as text instead of running a formula.
function cell(value) {
  if (value === null || value === undefined) return "";
  if (typeof value === "object") value = JSON.stringify(value);
  const formula = typeof value === "string" && /^[=+\-@]/.test(value);
  return formula ? "'" + value : value;
}

function importLatestSearch() {
  const jobs = getJson("/jobs?page_size=25&kind=search").items;
  const job = jobs.find(
    (item) => item.status === "completed" || item.status === "partial",
  );
  if (!job) return;
  const path = "/jobs/" + job.id + "/export?format=json";
  const rows = getJson(path).items || [];
  if (!rows.length) return;
  const columns = [];
  rows.forEach((row) => Object.keys(row).forEach((name) => {
    if (!columns.includes(name)) columns.push(name);
  }));
  const values = [columns].concat(
    rows.map((row) => columns.map((name) => cell(row[name]))),
  );
  const book = SpreadsheetApp.getActive();
  const sheet =
    book.getSheetByName("MapsScraper") || book.insertSheet("MapsScraper");
  sheet.clearContents();
  sheet.getRange(1, 1, values.length, columns.length).setValues(values);
}

ज़रूरी सीमाएँ#

वेबसाइट न होने का मतलब है कि डेटा स्रोत ने कोई वेबसाइट नहीं दी। इससे यह साबित नहीं होता कि बिज़नेस की कोई वेबसाइट नहीं है। रैंक स्नैपशॉट एक डेटा स्रोत का रिज़ल्ट ऑर्डरिंग है, पूरा लोकल SEO ग्रिड नहीं। रिव्यू कलेक्शन AI से बनी सेंटीमेंट रिपोर्ट नहीं है। फ़ोटो मेटाडेटा हैं, लाइसेंस वाली इमेज डाउनलोड नहीं। बार-बार होने वाली सर्च स्नैपशॉट बनाए रखती हैं, स्टेबल आइडेंटिटी की तुलना करती हैं और वर्कस्पेस इनबॉक्स नोटिफ़िकेशन बनाती हैं। साइन की हुई वेबहुक रसीदें ऑप्ट-इन होती हैं और उनमें सिर्फ़ टास्क मेटाडेटा होता है; CRM-स्पेसिफ़िक फ़ील्ड सिंक्रोनाइज़ेशन अलग रहता है।