Python में Google Search API ट्यूटोरियल: अनुरोध और परिणाम
Senior Web Scraping Engineer
संक्षेप (TL;DR):
- Scrapeless Google Search API, Python को संरचित सर्च डेटा लौटाती है। प्रमाणीकरण किए गए JSON अनुरोध में
q,glऔरhlसबमिट करें। - HTTP 200 और HTTP 201 को अलग तरह से संभालने की ज़रूरत है। पूर्ण हुआ परिणाम सीधे पढ़ें; लंबित टास्क ID को सुरक्षित रखें और उसी मौजूदा टास्क को बाद में प्राप्त करें।
- सफल HTTP response के बाद भी डेटा जाँच ज़रूरी है। पंक्तियों का उपयोग करने से पहले
organic_resultsको मान्य करें। - response को सुरक्षित रखना बाद के विश्लेषण को आसान बनाता है। शीर्षक, snippets या links चुनने से पहले JSON सहेजें।
परिचय: Python में सर्च परिणाम को उपयोगी बनाएं
कोई भी सर्च अनुरोध केवल तभी किसी एप्लिकेशन के लिए उपयोगी होता है जब वह एप्लिकेशन पूर्ण हो चुके डेटा और अभी भी चल रहे टास्क के बीच अंतर कर सके। response.text प्रिंट करने वाला एक छोटा स्क्रिप्ट आपको शुरुआत करने में मदद करता है, लेकिन वह इन दोनों अवस्थाओं को आपस में मिला देता है।
यह Google Search API Python ट्यूटोरियल Scrapeless Google Search API के लिए एक छोटा client तैयार करता है। आप एक query कॉन्फ़िगर करेंगे, उसे सबमिट करेंगे, एक लंबित टास्क को संभालेंगे, और ऐसा response सहेजेंगे जिसे कोई दूसरा स्क्रिप्ट inspect कर सके। उदाहरण सामान्य वेब सर्च का उपयोग करता है। Images, Local, Videos और Shopping में अलग-अलग result sections होते हैं और उन्हें अपनी अलग validation की आवश्यकता होती है।
कोड Scrapeless से बात करता है; यह Google का Custom Search JSON API या Search Console API नहीं है। आपका एप्लिकेशन, आपकी साइट के ट्रैफ़िक रिपोर्ट्स के बजाय एक search snapshot प्राप्त करता है। यदि आप पहले से व्यापक Scrapeless actor request model के साथ काम करते हैं, तो अनुरोध लिफ़ाफ़ा आपको परिचित लगेगा।
आवश्यकताएँ
आपको Python, requests पैकेज, और सेवा तक पहुँच वाले Scrapeless API key की आवश्यकता है। प्रोजेक्ट के लिए एक virtual environment का उपयोग करें और python -m pip install requests के साथ Requests इंस्टॉल करें। स्क्रिप्ट चलाने से पहले अपने process environment में SCRAPELESS_API_KEY सेट करें। key को source files, साझा किए जाने वाले notebooks और response logs से दूर रखें।
स्थानीय environment variable इस स्क्रिप्ट के लिए चुना गया एक convention है। HTTP authentication header x-api-token है। इनकी भूमिकाएँ अलग हैं: Python variable को पढ़ता है, फिर header में उसका मान API endpoint को भेजता है।
नीचे दिए गए संपूर्ण प्रोग्राम को google_search.py के रूप में सहेजें और python google_search.py से चलाएँ। यह प्रोग्राम working directory में serp.json बनाता है। यदि आप पिछली responses को सुरक्षित रखना चाहते हैं तो हर प्रयोग के लिए अलग directory का उपयोग करें।
q, gl, और hl कॉन्फ़िगर करें
q पैरामीटर सर्च क्वेरी प्रदान करता है, gl सर्च country चुनता है, और hl सर्च language चुनता है। ये नियंत्रण input के अंदर होते हैं, आस-पास के request object में actor नाम के साथ।
| Field | Example | What to Check |
|---|---|---|
actor |
scraper.google.search |
actor को top level पर रखें |
input.q |
coffee |
जिस query की आप तुलना करना चाहते हैं, उसे ठीक वैसा ही सुरक्षित रखें |
input.gl |
us |
परिणाम के साथ अनुरोधित country रिकॉर्ड करें |
input.hl |
en |
अनुरोधित language को अलग से रिकॉर्ड करें |
यहीं से इस छोटे input के साथ शुरुआत करें। Location और search filters तुरंत जोड़ देने से यह पहचानना कठिन हो जाता है कि किस parameter ने output को बदला। जब आप request को विस्तृत करें, तो current Google Search parameters को पास रखें।
Body को Requests के json= argument के साथ भेजें। यह Python object को JSON के रूप में serializes करता है और उपयुक्त content type सेट करता है। JSON objects और arrays, JSON data format में अलग-अलग संरचनाएँ हैं; जो response सफलतापूर्वक parse हो जाता है, वह अपने-आप आपकी एप्लिकेशन द्वारा अपेक्षित object shape नहीं बन जाता।
Request भेजें और लंबित Task प्राप्त करें
client एक search task सबमिट करता है, फिर केवल उसी स्थिति में result endpoint को जाँचता है जब वह task अभी भी process हो रहा हो। एक पूर्ण response caller को Python dictionary के रूप में लौटा दिया जाता है।
Google Search quickstart POST /api/v1/scraper/request का उपयोग करता है। इस API के लिए, HTTP 201 का अर्थ है कि processing जारी है और इसमें taskId शामिल होता है। task result workflow GET /api/v1/scraper/result/{taskId} के साथ उस ID को प्राप्त करता है।
यह स्टेटस कोड की एप्लिकेशन-विशिष्ट व्याख्या है। सामान्य HTTP semantics specification स्टेटस क्लास परिभाषित करता है, जबकि सर्विस कॉन्ट्रैक्ट आपके क्लाइंट को बताता है कि किसी पेंडिंग टास्क को कैसे हैंडल करना है।
प्रोग्राम परिणाम जाँच को दस तक सीमित करता है, दो-सेकंड के अंतराल के साथ। ये उदाहरण के रूप में क्लाइंट सेटिंग हैं, न कि सर्विस लिमिट या किसी निश्चित कंप्लीशन समय का वादा। नेटवर्क टाइमआउट हर रिक्वेस्ट पर अलग से लागू होते हैं। अगर टास्क पेंडिंग रहता है, तो एक्सेप्शन में उसका ID शामिल होता है ताकि कोई ऑपरेटर उसे सुरक्षित रख सके।
python
import json
import os
import time
from pathlib import Path
from urllib.parse import quote
import requests
BASE = "https://api.scrapeless.com/api/v1/scraper"
def google_search(query):
headers = {"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
response = requests.post(
BASE + "/request", headers=headers,
json={"actor": "scraper.google.search", "input": query},
timeout=(10, 60), allow_redirects=False,
)
task_id = None
for poll in range(11):
response.raise_for_status()
if response.status_code not in (200, 201):
raise RuntimeError(f"Unexpected HTTP status: {response.status_code}")
data = response.json()
if not isinstance(data, dict):
raise ValueError("Expected a JSON object")
if response.status_code == 200:
return data
if task_id is None:
task_id = data.get("taskId")
if not isinstance(task_id, str) or not task_id:
raise ValueError("Pending response has no taskId")
if poll == 10:
raise TimeoutError(f"Task still pending; retain taskId={task_id}")
time.sleep(2)
response = requests.get(
BASE + "/result/" + quote(task_id, safe=""),
headers=headers, timeout=(10, 30), allow_redirects=False,
)
def organic_rows(data):
rows = data.get("organic_results")
if not isinstance(rows, list):
raise ValueError("organic_results is missing or is not an array")
if not all(isinstance(row, dict) for row in rows):
raise ValueError("organic_results contains a non-object item")
return rows
if __name__ == "__main__":
query = {"q": "coffee", "gl": "us", "hl": "en"}
try:
result = google_search(query)
Path("serp.json").write_text(
json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
)
rows = organic_rows(result)
print(f"Saved serp.json; organic rows: {len(rows)}")
for row in rows:
print(row.get("position"), row.get("title"), row.get("link"))
except requests.HTTPError as exc:
raise SystemExit(f"HTTP request failed: {exc.response.status_code}")
except requests.RequestException:
raise SystemExit("Network request did not complete")
except (ValueError, RuntimeError, TimeoutError, KeyError) as exc:
raise SystemExit(str(exc))
पहला raise_for_status() HTTP एरर रिस्पॉन्स को पकड़ता है। स्पष्ट स्टेटस जाँच अप्रत्याशित नॉन-एरर स्टेटस को भी अस्वीकार कर देती है। JSON पार्सिंग उन जाँचों के बाद होती है, और रिज़ल्ट वेलिडेटर तब चलता है जब API बताता है कि टास्क पूरा हो गया है। हर स्टेज एक अलग सवाल का जवाब देता है।
Scrapeless के साथ स्क्रैपिंग शुरू करें
Scrapeless के साथ अपने वेब स्क्रैपिंग और ऑटोमेशन वर्कफ़्लो को पावर अप करें!
आज ही साइन अप करें और पाएं $5 का फ्री क्रेडिट — कोई क्रेडिट कार्ड ज़रूरी नहीं।अभी अपना फ्री क्रेडिट Scrapeless Dashboard में क्लेम करें।
मूल रिस्पॉन्स खोए बिना organic_results पढ़ें
organic_results ऐरे में पूर्ण रिस्पॉन्स में ऑर्गैनिक रिज़ल्ट रिकॉर्ड होते हैं। हर रिकॉर्ड से position, title, snippet, और link जैसे फ़ील्ड पढ़ें, और निरीक्षण के लिए मूल ऑब्जेक्ट को सुरक्षित रखें।
इस ट्यूटोरियल को तैयार करते समय इस्तेमाल की गई बेसलाइन coffee रिक्वेस्ट ने HTTP 200 और gl=us तथा hl=en के साथ आठ ऑर्गैनिक रिकॉर्ड लौटाए। वह काउंट एक रिस्पॉन्स का वर्णन करता है। उसी क्वेरी के लिए बाद की रिक्वेस्ट में पंक्तियों की संख्या या सर्च फीचर्स की व्यवस्था अलग हो सकती है।
प्रोग्राम ऑर्गैनिक ऐरे को वैलिडेट करने से पहले JSON को सेव कर देता है। यह तब मायने रखता है जब किसी पूर्ण रिस्पॉन्स का आकार अप्रत्याशित हो: आप यह देख सकते हैं कि क्या पहुँचा, बजाय इसके कि वैलिडेशन के एक्सेप्शन उठाने पर वह खो जाए। Python का JSON encoding and decoding interface ensure_ascii=False के ज़रिए नॉन-ASCII टेक्स्ट को पढ़ने योग्य बनाए रखने का समर्थन करता है।
तीन केस को अलग-अलग ट्रीट करें। खाली ऐरे एक ऑब्ज़र्व्ड कलेक्शन है जिसमें कोई ऑर्गैनिक आइटम नहीं है। अनुपस्थित कुंजी के लिए ऐसी कोई गारंटी नहीं है। ग़लत टाइप का मान एक स्कीमा समस्या है। स्क्रिप्ट पहले केस को स्वीकार करती है और बाकी दो पर रुक जाती है, बजाय इसके कि उन्हें चुपचाप खाली लिस्ट से बदल दे।
लौटाए गए लिंक को भी कॉन्टेक्स्ट चाहिए। सीधी दिखने वाली URL एक डेस्टिनेशन कैंडिडेट है; Google इंटरमीडियरी को टारगेट वेबसाइट मानने से पहले अतिरिक्त हैंडलिंग की ज़रूरत होती है। यह पहला ट्यूटोरियल लौटाए गए मान को प्रिंट करता है, बिना यह दावा किए कि फ़ाइनल डेस्टिनेशन को वेरिफ़ाई कर लिया गया।
सही लेयर पर फ़ेल्योर को हैंडल करें
किसी एक्सेप्शन को फ़ेल हुए स्टेज की पहचान करानी चाहिए, बिना ऑथेंटिकेशन हेडर को उजागर किए या किसी फ़ेल रिक्वेस्ट को वैध दिखने वाले खाली रिज़ल्ट में बदले।
| Observation | Meaning for This Client | Next Inspection |
|---|---|---|
| Missing environment variable | ऑथेंटिकेशन लोकली कॉन्फ़िगर नहीं था | प्रोसेस एन्वायरनमेंट जाँचें |
| HTTP 400 | API ने रिक्वेस्ट को अस्वीकार कर दिया | इनपुट नाम, टाइप, और कॉम्बिनेशन जाँचें |
| HTTP 429 | सर्विस रिक्वेस्ट लिमिट की रिपोर्ट कर रही है | रिक्वेस्ट फ़्रीक्वेंसी और अकाउंट कोटा जाँचें |
| Other HTTP error | कोई पूर्ण रिज़ल्ट स्वीकार नहीं किया गया | जांच के लिए स्टेटस और रिक्वेस्ट कॉन्टेक्स्ट रखें |
| Invalid JSON | बॉडी को पार्स नहीं किया जा सका | रिस्पॉन्स को नियंत्रित डायग्नोस्टिक लॉग में निरीक्षण करें |
| Missing organic array | पेलोड इस कंज़्यूमर से मेल नहीं खाता | सेव किए गए JSON और रिक्वेस्टेड सर्च मोड की जाँच करें |
| Pending-task limit reached | इस क्लाइंट द्वारा कंप्लीशन नहीं देखा गया | टास्क ID सुरक्षित रखें और जॉब को अधूरा मार्क करें |
सैंपल जानबूझकर पूरे रिक्वेस्ट हेडर या सर्वर एरर बॉडी प्रिंट करने से बचता है। किसी बड़े सर्विस में, क्वेरी कॉन्फ़िगरेशन, स्टेटस और टास्क ID (जब उपलब्ध हो) के साथ स्ट्रक्चर्ड डायग्नॉस्टिक्स लिखें। किसी फ़ेल रन को पूर्ण ऑब्ज़र्वेशन से अलग रिकॉर्ड करें ताकि डाउनस्ट्रीम रिपोर्ट फ़ेल्योर को अनुपस्थिति समझने की गलती न कर सकें।
निष्कर्ष: पहले क्लाइंट को छोटा रखें
एक उपयोगी Google Search API Python क्लाइंट के लिए स्पष्ट पथ होता है: क्वेरी सबमिट करें, ज़रूरत हो तो मौजूदा टास्क प्राप्त करें, रिस्पॉन्स को सुरक्षित रखें, और वे फ़ील्ड वैलिडेट करें जिन्हें आपका एप्लिकेशन कंज़्यूम करता है। जब यह पथ काम करने लगे, तो एक समय में एक इनपुट डाइमेंशन जोड़ें।
Google Search API उत्पाद विवरण का उपयोग करके सेवा चुनें और वर्तमान कीमतों के आधार पर दोहराई जाने वाली संग्रह योजना बनाएं। बड़ा डेटासेट बनाने से पहले हर सहेजी गई प्रतिक्रिया के साथ अनुरोध कॉन्फ़िगरेशन जरूर रखें।
अपना सर्च डेटा वर्कफ़्लो बनाएं
हमारे समुदाय में उन डेवलपर्स से जुड़ें जो सर्च डेटा के साथ काम कर रहे हैं: Discord · Telegram.
एक Scrapeless अकाउंट बनाएं और बड़ी कलेक्शन शेड्यूल करने से पहले इस ट्यूटोरियल को छोटे क्वेरी सेट पर लागू करें।
सामान्य प्रश्न (FAQ)
प्रश्न: क्या Python बिना SDK के Google Search API को कॉल कर सकता है?
हाँ। उदाहरण में Requests और दस्तावेज़ित HTTP एंडपॉइंट का उपयोग किया गया है। इसके लिए किसी AI एजेंट या किसी फ़्रेमवर्क-विशिष्ट SDK की ज़रूरत नहीं है।
प्रश्न: क्या HTTP 201 में अंतिम सर्च परिणाम होता है?
इस API के लिए, HTTP 201 एक लंबित टास्क को दर्शाता है। taskId को सुरक्षित रखें और उस टास्क को रिज़ल्ट एंडपॉइंट के ज़रिए प्राप्त करें।
प्रश्न: क्या gl=us यह साबित करता है कि हर परिणाम अमेरिकी है?
नहीं। देश एक सर्च इनपुट है, हर लौटाए गए पेज के लिए नागरिकता का लेबल नहीं। लोकल सटीकता के लिए अलग वैलिडेशन विधि की आवश्यकता होती है।
प्रश्न: क्या अनुपस्थित organic_results key को खाली सूची मान लेना चाहिए?
नहीं। अनुपस्थित key और स्पष्ट रूप से खाली एरे दो अलग अवलोकन हैं। यह रिपोर्ट करने से पहले कि कोई ऑर्गेनिक रिकॉर्ड नहीं लौटाए गए, प्रतिक्रिया की संरचना (response shape) जांचें।
प्रश्न: क्या आपको अलग प्रॉक्सी कॉन्फ़िगर करने की ज़रूरत है?
इस बेसिक रिक्वेस्ट के लिए किसी अलग प्रॉक्सी कॉन्फ़िगरेशन की ज़रूरत नहीं है। API खुद ही रिट्रीवल संभालती है; ट्रांसपोर्ट या लोकेशन सेटिंग्स जोड़ने से पहले पैरामीटर कॉन्ट्रैक्ट देखें।
प्रश्न: क्या स्क्रिप्ट हर रिज़ल्ट लिंक के पीछे की सामग्री सत्यापित करती है?
नहीं। यह एक सर्च स्नैपशॉट इकट्ठा करती है। गंतव्य सत्यापन और पेज-कंटेंट वैलिडेशन अलग चरण हैं।
स्क्रैपलेस में, हम केवल सार्वजनिक रूप से उपलब्ध डेटा का उपयोग करते हैं, जबकि लागू कानूनों, विनियमों और वेबसाइट गोपनीयता नीतियों का सख्ती से अनुपालन करते हैं। इस ब्लॉग में सामग्री केवल प्रदर्शन उद्देश्यों के लिए है और इसमें कोई अवैध या उल्लंघन करने वाली गतिविधियों को शामिल नहीं किया गया है। हम इस ब्लॉग या तृतीय-पक्ष लिंक से जानकारी के उपयोग के लिए सभी देयता को कोई गारंटी नहीं देते हैं और सभी देयता का खुलासा करते हैं। किसी भी स्क्रैपिंग गतिविधियों में संलग्न होने से पहले, अपने कानूनी सलाहकार से परामर्श करें और लक्ष्य वेबसाइट की सेवा की शर्तों की समीक्षा करें या आवश्यक अनुमतियाँ प्राप्त करें।



