ऑटोकंप्लीट (नया)

परिचय

ऑटोकंप्लीट (नया) एक वेब सेवा है. यह एचटीटीपी अनुरोध के जवाब में, जगह के सुझाव और क्वेरी के सुझाव देती है. अनुरोध में, टेक्स्ट से खोजने के लिए स्ट्रिंग और भौगोलिक सीमाएं तय करें. इससे खोज के दायरे को कंट्रोल किया जा सकेगा.

ऑटोकंप्लीट (नया) सुविधा, इनपुट के पूरे शब्दों और सबस्ट्रिंग से मैच कर सकती है. इससे जगहों के नाम, पते, और प्लस कोड का पता चलता है. इसलिए, ऐप्लिकेशन उपयोगकर्ता के टाइप करते समय क्वेरी भेज सकते हैं, ताकि जगह और क्वेरी के अनुमान तुरंत लगाए जा सकें.

ऑटोकंप्लीट (नया) सुविधा से मिले जवाब में, दो तरह के सुझाव शामिल हो सकते हैं:

• जगह के बारे में अनुमान: कारोबारों, पतों, और लोकप्रिय जगहों जैसी जगहों के बारे में अनुमान. ये अनुमान, दिए गए इनपुट टेक्स्ट स्ट्रिंग और खोज के दायरे के आधार पर लगाए जाते हैं. जगह के बारे में अनुमान लगाने की सुविधा डिफ़ॉल्ट रूप से चालू होती है.
• क्वेरी के अनुमान: इनपुट टेक्स्ट स्ट्रिंग और खोज के इलाके से मैच होने वाली क्वेरी स्ट्रिंग. क्वेरी के अनुमान, डिफ़ॉल्ट रूप से नहीं दिखाए जाते. जवाब में क्वेरी के अनुमान जोड़ने के लिए, includeQueryPredictions अनुरोध पैरामीटर का इस्तेमाल करें.

उदाहरण के लिए, आपने ऑटोकंप्लीट (नया) को कॉल किया. इसके लिए, आपने इनपुट के तौर पर एक ऐसी स्ट्रिंग का इस्तेमाल किया जिसमें उपयोगकर्ता का कुछ इनपुट, "Sicilian piz" शामिल है. साथ ही, खोज के दायरे को कैलिफ़ोर्निया के सैन फ़्रांसिस्को तक सीमित किया गया है. इसके बाद, जवाब में जगह के अनुमानों की एक सूची होती है. ये अनुमान, खोज स्ट्रिंग और खोज क्षेत्र से मेल खाते हैं. जैसे, "Sicilian Pizza Kitchen" नाम का रेस्टोरेंट और उस जगह के बारे में जानकारी.

जगह के अनुमान, उपयोगकर्ता को दिखाए जाते हैं, ताकि वह अपनी पसंद की जगह चुन सके. जगह के बारे में मिले किसी भी सुझाव की ज़्यादा जानकारी पाने के लिए, Place Details (New) का अनुरोध किया जा सकता है.

जवाब में, क्वेरी के सुझावों की सूची भी शामिल हो सकती है. ये सुझाव, खोज स्ट्रिंग और खोज के लिए चुने गए इलाके से मैच करते हैं. जैसे, "सिसिलियन पिज़्ज़ा और पास्ता". जवाब में, क्वेरी के सुझाव से जुड़ी हर जानकारी में text फ़ील्ड शामिल होता है. इसमें टेक्स्ट से खोजें के लिए सुझाया गया टेक्स्ट स्ट्रिंग होता है. ज़्यादा जानकारी के साथ खोजने के लिए, उस स्ट्रिंग को टेक्स्ट खोज (नया) के इनपुट के तौर पर इस्तेमाल करें.

एपीआई एक्सप्लोरर की मदद से, लाइव अनुरोध किए जा सकते हैं. इससे आपको एपीआई और उसके विकल्पों के बारे में जानकारी मिलती है:

ऑटोकंप्लीट (नया) अनुरोध

Autocomplete (नया) का अनुरोध, इस तरह के यूआरएल पर किया गया एचटीटीपी पोस्ट अनुरोध होता है:

https://places.googleapis.com/v1/places:autocomplete

सभी पैरामीटर को JSON अनुरोध के मुख्य हिस्से में या हेडर में, पोस्ट अनुरोध के हिस्से के तौर पर पास करें. उदाहरण के लिए:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

काम करने वाले पैरामीटर

जवाब के बारे में जानकारी

Autocomplete (New) सेवा, रिस्पॉन्स के तौर पर एक JSON ऑब्जेक्ट दिखाती है. जवाब में:

• suggestions कलेक्शन में, अनुमानित जगहों और क्वेरी को उनकी अहमियत के हिसाब से क्रम में रखा जाता है. हर जगह को placePrediction फ़ील्ड से और हर क्वेरी को queryPrediction फ़ील्ड से दिखाया जाता है.
• placePrediction फ़ील्ड में, किसी जगह के अनुमान के बारे में पूरी जानकारी होती है. इसमें जगह का आईडी और टेक्स्ट के तौर पर ब्यौरा शामिल होता है.
  • input पैरामीटर में दिए गए उपयोगकर्ता के इनपुट से ज़्यादा मेल खाने के लिए, जगह के अनुमान के टेक्स्ट ब्यौरे में जगहों, सड़कों, और पते के अन्य कॉम्पोनेंट के वैकल्पिक नाम शामिल हो सकते हैं. ये वैकल्पिक नाम, एक ही जगह के आईडी के लिए, जगह की जानकारी के नतीजों में displayName और पते वाले फ़ील्ड में दिखाए गए नामों से अलग हो सकते हैं.
  • इस संदर्भ में, कुछ जगहों के वैकल्पिक नाम, languageCode पैरामीटर के आधार पर अनुमानित भाषा से अलग भाषा में हो सकते हैं. ऐसा इसलिए होता है, क्योंकि उपयोगकर्ता के इनपुट से कौनसे नाम ज़्यादा मिलते हैं.
• queryPrediction फ़ील्ड में, क्वेरी के अनुमान के बारे में पूरी जानकारी होती है.

पूरा JSON ऑब्जेक्ट इस फ़ॉर्म में होता है:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

ज़रूरी पैरामीटर

• इनपुट

  वह टेक्स्ट स्ट्रिंग जिसमें खोजना है. पूरे शब्द और सबस्ट्रिंग, जगहों के नाम, पते, और प्लस कोड डालें. ऑटोकंप्लीट (नई) सेवा, इस स्ट्रिंग के आधार पर संभावित मैच दिखाती है. साथ ही, नतीजों को उनकी प्रासंगिकता के आधार पर क्रम में लगाती है.

ज़रूरी नहीं पैरामीटर

• FieldMask

  जवाब फ़ील्ड मास्क बनाकर, जवाब में दिखाए जाने वाले फ़ील्ड की सूची तय करें. एचटीटीपी हेडर X-Goog-FieldMask का इस्तेमाल करके, रिस्पॉन्स फ़ील्ड मास्क को तरीके से पास करें.

  सुझाव वाले फ़ील्ड की कॉमा लगाकर अलग की गई लिस्ट डालें. उदाहरण के लिए, सुझाव के suggestions.placePrediction.text.text और suggestions.queryPrediction.text.text को वापस पाने के लिए.

    X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

  सभी फ़ील्ड वापस पाने के लिए, * का इस्तेमाल करें.

    X-Goog-FieldMask: *

• includeFutureOpeningBusinesses

  अगर true है, तो यह उन कारोबारों को दिखाता है जो आने वाले समय में खुलने वाले हैं. डिफ़ॉल्ट रूप से, यह false पर सेट होता है.

• includedPrimaryTypes

  किसी जगह के लिए, टेबल A या टेबल B में दी गई सूची में से सिर्फ़ एक प्राइमरी टाइप चुना जा सकता है. उदाहरण के लिए, प्राइमरी टाइप "mexican_restaurant" या "steak_house" हो सकता है.

  डिफ़ॉल्ट रूप से, एपीआई input पैरामीटर के आधार पर सभी जगहों की जानकारी दिखाता है. भले ही, जगह से जुड़ी प्राइमरी टाइप वैल्यू कुछ भी हो. includedPrimaryTypes पैरामीटर पास करके, नतीजों को किसी खास प्राइमरी टाइप या प्राइमरी टाइप तक सीमित करें.

  इस पैरामीटर का इस्तेमाल करके, टेबल A या टेबल B से ज़्यादा से ज़्यादा पांच टाइप वैल्यू तय करें. जवाब में शामिल होने के लिए, किसी जगह का प्राइमरी टाइप, बताई गई वैल्यू में से किसी एक से मेल खाना चाहिए.

  इस पैरामीटर में, (regions) या (cities) में से कोई एक भी शामिल हो सकता है. (regions) टाइप के कलेक्शन, इलाकों या डिविज़न के लिए फ़िल्टर करते हैं. जैसे, आस-पास के इलाके और पिन कोड. (cities) टाइप कलेक्शन, उन जगहों को फ़िल्टर करता है जिन्हें Google एक शहर के तौर पर पहचानता है.

  अगर अनुरोध में ये गड़बड़ियां हैं, तो उसे INVALID_REQUEST गड़बड़ी के साथ अस्वीकार कर दिया जाता है:

  • पांच से ज़्यादा टाइप दिए गए हैं.
  • (cities) या (regions) के अलावा, किसी अन्य टाइप की सूचना सेट की गई हो.
  • किसी ऐसे टाइप की जानकारी दी गई हो जिसकी पहचान नहीं की जा सकी.

• includePureServiceAreaBusinesses

  true पर सेट करने पर, जवाब में ऐसे कारोबार शामिल होते हैं जो ग्राहकों को सीधे तौर पर सेवाएं देते हैं या उनसे संपर्क करते हैं. हालांकि, उनके पास कारोबार की कोई जगह नहीं होती. अगर इसे false पर सेट किया जाता है, तो एपीआई सिर्फ़ उन कारोबारों की जानकारी दिखाता है जिनकी काम करने की कोई तय जगह है.

• includeQueryPredictions

  अगर true है, तो जवाब में जगह और क्वेरी, दोनों के सुझाव शामिल होते हैं. डिफ़ॉल्ट वैल्यू false है. इसका मतलब है कि जवाब में सिर्फ़ जगहों के बारे में अनुमान शामिल होते हैं.

• includedRegionCodes

  नतीजों में सिर्फ़ उन क्षेत्रों को शामिल करें जिनके बारे में बताया गया है. इन्हें ज़्यादा से ज़्यादा 15 ccTLD ("टॉप-लेवल डोमेन") की दो वर्णों वाली वैल्यू के ऐरे के तौर पर बताया गया है. अगर इसे शामिल नहीं किया जाता है, तो जवाब पर कोई पाबंदी नहीं लगाई जाती है. उदाहरण के लिए, जर्मनी और फ़्रांस के क्षेत्रों को सीमित करने के लिए:

      "includedRegionCodes": ["de", "fr"]

  अगर locationRestriction और includedRegionCodes, दोनों की जानकारी दी जाती है, तो नतीजे दोनों सेटिंग के इंटरसेक्शन वाले इलाके में दिखते हैं.

• inputOffset

  शून्य पर आधारित यूनिकोड वर्ण ऑफ़सेट. इससे input में कर्सर की जगह की जानकारी मिलती है. कर्सर की पोज़िशन से, इस बात पर असर पड़ सकता है कि कौनसे अनुमान दिखाए जाएंगे. अगर यह फ़ील्ड खाली है, तो इसकी डिफ़ॉल्ट वैल्यू input की अवधि के बराबर होती है.

• languageCode

  नतीजे दिखाने के लिए पसंदीदा भाषा. अगर input में इस्तेमाल की गई भाषा, languageCode से तय की गई वैल्यू से अलग है, तो नतीजे अलग-अलग भाषाओं में हो सकते हैं. इसके अलावा, अगर नतीजे में मिली जगह का अनुवाद स्थानीय भाषा से languageCode में नहीं किया गया है, तो भी नतीजे अलग-अलग भाषाओं में हो सकते हैं.

  • पसंदीदा भाषा बताने के लिए, आपको आईईटीएफ़ बीसीपी-47 भाषा कोड का इस्तेमाल करना होगा.
  • अगर languageCode नहीं दिया गया है, तो एपीआई, Accept-Language हेडर में दी गई वैल्यू का इस्तेमाल करता है. अगर दोनों में से कोई भी वैल्यू तय नहीं की गई है, तो डिफ़ॉल्ट वैल्यू en होती है. अगर आपने अमान्य भाषा कोड डाला है, तो एपीआई INVALID_ARGUMENT गड़बड़ी का मैसेज दिखाता है.
  • पसंदीदा भाषा का असर, एपीआई से मिले नतीजों के सेट पर पड़ता है. साथ ही, इससे यह तय होता है कि नतीजे किस क्रम में दिखाए जाएंगे. इससे, एपीआई की वर्तनी की गलतियों को ठीक करने की क्षमता पर भी असर पड़ता है.
  • हर अनुरोध में उपयोगकर्ता के इनपुट के आधार पर, जगह के सुझावों को अलग-अलग तरीके से फ़ॉर्मैट किया जाता है.
    • input पैरामीटर में मौजूद मैचिंग शब्दों को सबसे पहले चुना जाता है. इसके लिए, languageCode पैरामीटर में बताई गई भाषा के हिसाब से नामों का इस्तेमाल किया जाता है . अगर ऐसा नहीं होता है, तो उन नामों का इस्तेमाल किया जाता है जो उपयोगकर्ता के इनपुट से सबसे ज़्यादा मेल खाते हैं.
    • जगहों के नामों को, input पैरामीटर में दिए गए शब्दों से मैच करने के लिए, दूसरे नामों का इस्तेमाल करके फ़ॉर्मैट किया जा सकता है. इनमें languageCode पैरामीटर में बताई गई भाषा के अलावा, अन्य भाषाओं में दिए गए नाम भी शामिल हैं.
    • मोहल्ले के पते, स्थानीय भाषा में फ़ॉर्मैट किए जाते हैं. साथ ही, उन्हें ऐसी स्क्रिप्ट में लिखा जाता है जिसे उपयोगकर्ता पढ़ सके. हालांकि, ऐसा सिर्फ़ तब किया जाता है, जब input पैरामीटर में मौजूद शर्तों से मिलती-जुलती शर्तें चुन ली गई हों.
    • input पैरामीटर में दी गई शर्तों से मेल खाने वाली शर्तें चुनने के बाद, अन्य सभी पते पसंदीदा भाषा में दिखाए जाते हैं. अगर नाम आपकी पसंदीदा भाषा में उपलब्ध नहीं है, तो एपीआई सबसे मिलते-जुलते नाम का इस्तेमाल करता है.

• locationBias या locationRestriction

  खोज के दायरे को तय करने के लिए, locationBias या locationRestriction में से किसी एक की जानकारी दी जा सकती है, लेकिन दोनों की नहीं. locationRestriction का मतलब है कि नतीजे, तय किए गए इलाके के अंदर ही होने चाहिए. वहीं, locationBias का मतलब है कि नतीजे, तय किए गए इलाके के आस-पास होने चाहिए, लेकिन वे इलाके से बाहर भी हो सकते हैं.

  • locationBias

    खोजने के लिए कोई हिस्सा तय करता है. इस जगह को पूर्वाग्रह के तौर पर इस्तेमाल किया जाता है. इसका मतलब है कि बताई गई जगह के आस-पास के नतीजे दिखाए जा सकते हैं. इसमें बताई गई जगह से बाहर के नतीजे भी शामिल हो सकते हैं.

  • locationRestriction

    खोजने के लिए कोई हिस्सा तय करता है. तय किए गए इलाके से बाहर के नतीजे नहीं दिखाए जाते.

  locationBias या locationRestriction क्षेत्र को रेक्टैंगल व्यूपोर्ट या सर्कल के तौर पर तय करें.

  • किसी सर्कल को उसके केंद्र बिंदु और मीटर में दी गई त्रिज्या से तय किया जाता है. रेडियस, 0.0 और 50,000.0 के बीच होना चाहिए. हालांकि, इन दोनों में से भी कोई संख्या हो सकती है. डिफ़ॉल्ट वैल्यू 0.0 है. locationRestriction के लिए, आपको रेडियस को 0.0 से ज़्यादा पर सेट करना होगा. ऐसा न होने पर, अनुरोध के लिए कोई नतीजा नहीं मिलता.

    उदाहरण के लिए:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

  • रेक्टैंगल, अक्षांश-देशांतर का व्यूपोर्ट होता है. इसे दो डायगनल विपरीत low और ऊंचे पॉइंट के तौर पर दिखाया जाता है. व्यूपोर्ट को एक बंद क्षेत्र माना जाता है. इसका मतलब है कि इसमें इसकी सीमा शामिल होती है. अक्षांश की सीमाएं -90 से 90 डिग्री के बीच होनी चाहिए. साथ ही, देशांतर की सीमाएं -180 से 180 डिग्री के बीच होनी चाहिए:

    • अगर low = high है, तो व्यूपोर्ट में सिर्फ़ एक पॉइंट होता है.
    • अगर low.longitude > high.longitude है, तो देशांतर की रेंज उल्टी हो जाती है (व्यूपोर्ट, 180 डिग्री देशांतर रेखा को पार कर जाता है).
    • अगर low.longitude = -180 डिग्री और high.longitude = 180 डिग्री है, तो व्यूपोर्ट में सभी देशांतर शामिल होते हैं.
    • अगर low.longitude = 180 डिग्री और high.longitude = -180 डिग्री है, तो देशांतर की रेंज खाली होती है.

    low और high, दोनों फ़ील्ड में वैल्यू डालना ज़रूरी है. साथ ही, बॉक्स में वैल्यू डालना भी ज़रूरी है. व्यू पोर्ट खाली होने पर गड़बड़ी होती है.

    उदाहरण के लिए, इस व्यूपोर्ट में न्यूयॉर्क शहर की पूरी जानकारी शामिल है:

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

• origin

  वह ऑरिजिन पॉइंट जिससे डेस्टिनेशन तक की सीधी दूरी कैलकुलेट की जाती है. यह वैल्यू, distanceMeters के तौर पर दिखती है. अगर यह वैल्यू नहीं दी जाती है, तो सीधी दूरी नहीं दिखाई जाएगी. अक्षांश और देशांतर निर्देशांक के तौर पर जानकारी देना ज़रूरी है:

  "origin": {
      "latitude": 40.477398,
      "longitude": -74.259087
  }

• regionCode

  जवाब को फ़ॉर्मैट करने के लिए इस्तेमाल किया गया क्षेत्र कोड. इसे दो वर्णों वाली ccTLD ("टॉप-लेवल डोमेन") वैल्यू के तौर पर तय किया जाता है. ज़्यादातर ccTLD कोड, ISO 3166-1 कोड के जैसे ही होते हैं. हालांकि, कुछ अपवाद भी हैं. उदाहरण के लिए, यूनाइटेड किंगडम का ccTLD "uk" (.co.uk) है, जबकि इसका ISO 3166-1 कोड "gb" है. तकनीकी तौर पर, यह "यूनाइटेड किंगडम ऑफ़ ग्रेट ब्रिटेन और नॉदर्न आयरलैंड" के लिए है.

  सुझाव, देश/इलाके के कोड के आधार पर भी पक्षपातपूर्ण हो सकते हैं. Google का सुझाव है कि regionCode को उपयोगकर्ता की क्षेत्रीय प्राथमिकता के हिसाब से सेट करें.

  अगर आपने कोई अमान्य क्षेत्र कोड डाला है, तो एपीआई INVALID_ARGUMENT गड़बड़ी का मैसेज दिखाता है. लागू कानून के आधार पर, पैरामीटर से नतीजों पर असर पड़ सकता है.

• sessionToken

  सेशन टोकन, उपयोगकर्ता की जनरेट की गई स्ट्रिंग होती हैं. ये Autocomplete (New) कॉल को "सेशन" के तौर पर ट्रैक करती हैं. Autocomplete (New) सेवा, सेशन टोकन का इस्तेमाल करती है. इससे, उपयोगकर्ता की खोज क्वेरी के अपने-आप पूरे होने की सुविधा के लिए, क्वेरी और चुनने के चरणों को बिलिंग के मकसद से अलग-अलग सेशन में बांटा जाता है. ज़्यादा जानकारी के लिए, सेशन टोकन देखें.

नतीजों को बायस करने के लिए पैरामीटर चुनना

ऑटोकंप्लीट (नया) सुविधा के उदाहरण

locationRestriction का इस्तेमाल करके, खोज को किसी इलाके तक सीमित करना

locationRestriction में, खोज के लिए जगह की जानकारी दी जाती है. बताए गए इलाके से बाहर के नतीजे नहीं दिखाए जाते. इस उदाहरण में, सैन फ़्रांसिस्को के बीच में 5,000 मीटर के दायरे वाले सर्कल के लिए अनुरोध को सीमित करने के लिए, locationRestriction का इस्तेमाल किया गया है:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

चुने गए इलाकों के सभी नतीजे, suggestions कलेक्शन में शामिल होते हैं:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

रेक्टैंगुलर व्यूपोर्ट में खोजों को सीमित करने के लिए, locationRestriction का इस्तेमाल भी किया जा सकता है. यहां दिए गए उदाहरण में, अनुरोध को सैन फ़्रांसिस्को के डाउनटाउन तक सीमित किया गया है:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

नतीजे, suggestions ऐरे में शामिल हैं:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

locationBias का इस्तेमाल करके, किसी इलाके के हिसाब से खोज के नतीजों को पक्षपाती बनाना

locationBias के साथ, जगह की जानकारी बायस के तौर पर काम करती है. इसका मतलब है कि चुनी गई जगह के आस-पास के नतीजे दिखाए जा सकते हैं. इनमें चुनी गई जगह से बाहर के नतीजे भी शामिल हैं. यहां दिए गए उदाहरण में, सैन फ़्रांसिस्को के डाउनटाउन के लिए अनुरोध किया गया है:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

नतीजों में अब कई और आइटम शामिल हैं. इनमें 5, 000 मीटर के दायरे से बाहर के नतीजे भी शामिल हैं:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

रेक्टैंगुलर व्यूपोर्ट के हिसाब से खोज के नतीजों को प्राथमिकता देने के लिए, locationBias का इस्तेमाल भी किया जा सकता है. यहां दिए गए उदाहरण में, अनुरोध को सैन फ़्रांसिस्को के डाउनटाउन तक सीमित किया गया है:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

जवाब में, आयताकार व्यूपोर्ट के अंदर खोज के नतीजे दिखते हैं. हालांकि, बायस की वजह से कुछ नतीजे तय की गई सीमाओं से बाहर होते हैं. नतीजे, suggestions कलेक्शन में भी शामिल होते हैं:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

includedPrimaryTypes का इस्तेमाल करें

includedPrimaryTypes पैरामीटर का इस्तेमाल करके, टेबल A, टेबल B या सिर्फ़ (regions) या सिर्फ़ (cities) से, ज़्यादा से ज़्यादा पांच टाइप वैल्यू तय करें. जवाब में किसी जगह को शामिल करने के लिए, यह ज़रूरी है कि वह बताई गई प्राइमरी टाइप वैल्यू में से किसी एक से मेल खाती हो.

इस उदाहरण में, "Soccer" की input स्ट्रिंग तय की गई है. साथ ही, नतीजों को "sporting_goods_store" टाइप की जगहों तक सीमित करने के लिए, includedPrimaryTypes पैरामीटर का इस्तेमाल किया गया है:

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

includedPrimaryTypes पैरामीटर को शामिल न करने पर, नतीजों में ऐसे कारोबार शामिल हो सकते हैं जिन्हें आपको शामिल नहीं करना है. जैसे, "athletic_field".

क्वेरी के अनुमानों का अनुरोध करना

क्वेरी के अनुमान डिफ़ॉल्ट रूप से नहीं दिखाए जाते. जवाब में क्वेरी के अनुमान जोड़ने के लिए, includeQueryPredictions अनुरोध पैरामीटर का इस्तेमाल करें. उदाहरण के लिए:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

suggestions कैटगरी में अब जगह के सुझाव और क्वेरी के सुझाव, दोनों शामिल हैं. जैसा कि ऊपर जवाब के बारे में जानकारी में दिखाया गया है. क्वेरी के अनुमान से जुड़ी हर जानकारी में, text फ़ील्ड शामिल होता है. इसमें टेक्स्ट खोजने के लिए सुझाई गई स्ट्रिंग होती है. क्वेरी के लिए मिले सुझावों के बारे में ज़्यादा जानकारी पाने के लिए, टेक्स्ट से खोजें (नई) का अनुरोध किया जा सकता है.

ऑरिजिन का इस्तेमाल करना

इस उदाहरण में, अक्षांश और देशांतर निर्देशांक के तौर पर अनुरोध में origin शामिल करें. origin को शामिल करने पर, Autocomplete (New) जवाब में distanceMeters फ़ील्ड को शामिल करता है. इसमें origin से मंज़िल तक की सीधी दूरी शामिल होती है. इस उदाहरण में, ऑरिजिन को सैन फ़्रांसिस्को के सेंटर पर सेट किया गया है:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

जवाब में अब distanceMeters शामिल है:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

आने वाले समय में खुलने वाले कारोबारों को ढूंढना

यहां न्यू मीडोज़, इडाहो में आने वाले समय में खुलने वाले कारोबारों के लिए, ऑटोकंप्लीट (नया) के अनुरोध का उदाहरण दिया गया है:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

जवाब में जगह के बारे में जानकारी दी गई है, लेकिन खुलने की तारीख़ शामिल नहीं है.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

जवाब में दूरी की जानकारी मौजूद नहीं है

कुछ मामलों में, रिस्पॉन्स बॉडी में distanceMeters मौजूद नहीं होता है. भले ही, अनुरोध में origin शामिल हो. ऐसा इन स्थितियों में हो सकता है:

• distanceMeters को route के अनुमानों में शामिल नहीं किया जाता.
• distanceMeters को तब शामिल नहीं किया जाता, जब इसकी वैल्यू 0 हो. ऐसा उन अनुमानों के लिए होता है जो दी गई origin जगह से एक मीटर से कम दूरी पर होते हैं.

पार्स किए गए ऑब्जेक्ट से distanceMeters फ़ील्ड को पढ़ने की कोशिश करने वाली क्लाइंट लाइब्रेरी, 0 वैल्यू वाला फ़ील्ड दिखाएंगी. उपयोगकर्ताओं को गुमराह करने से बचने के लिए, उन्हें शून्य दूरी न दिखाएं.

ऑटोकंप्लीट (नया) ऑप्टिमाइज़ेशन

इस सेक्शन में, ऑटोकंप्लीट (नया) सेवा का ज़्यादा से ज़्यादा फ़ायदा पाने के सबसे सही तरीके बताए गए हैं.

यहां कुछ सामान्य दिशा-निर्देश दिए गए हैं:

• उपयोगकर्ता इंटरफ़ेस बनाने का सबसे आसान तरीका यह है कि आप इनमें से किसी एक का इस्तेमाल करें: Maps JavaScript API ऑटोकंप्लीट (नया) विजेट, Android के लिए Places SDK ऑटोकंप्लीट (नया) विजेट, या iOS के लिए Places SDK ऑटोकंप्लीट (नया) विजेट.
• शुरुआत से ही, ऑटोकंप्लीट (नई) सुविधा के डेटा फ़ील्ड के बारे में ज़रूरी जानकारी पाएं.
• जगह के हिसाब से खोज के नतीजों को प्राथमिकता देने और जगह के हिसाब से पाबंदी लगाने वाले फ़ील्ड का इस्तेमाल करना ज़रूरी नहीं है. हालांकि, इससे अपने-आप पूरा होने की सुविधा की परफ़ॉर्मेंस पर काफ़ी असर पड़ सकता है.
• गड़बड़ी को मैनेज करने की सुविधा का इस्तेमाल करें, ताकि अगर एपीआई से कोई गड़बड़ी होती है, तो आपका ऐप्लिकेशन ठीक से काम करे.
• पक्का करें कि जब कोई विकल्प न चुना गया हो, तब आपका ऐप्लिकेशन काम करे. साथ ही, उपयोगकर्ताओं को आगे बढ़ने का विकल्प दे.

लागत को ऑप्टिमाइज़ करने के सबसे सही तरीके

लागत ऑप्टिमाइज़ेशन की बुनियादी सेटिंग

ऑटोकंप्लीट (नई) सेवा का इस्तेमाल करने की लागत को ऑप्टिमाइज़ करने के लिए, Place Details (New) और ऑटोकंप्लीट (नई) विजेट में फ़ील्ड मास्क का इस्तेमाल करें. इससे आपको सिर्फ़ ऑटोकंप्लीट (नई) के डेटा फ़ील्ड मिलेंगे.

लागत ऑप्टिमाइज़ेशन की बेहतर सेटिंग

ऑटोकंप्लीट (नई) सुविधा को प्रोग्राम के हिसाब से लागू करें, ताकि एसकेयू: ऑटोकंप्लीट अनुरोध की कीमत को ऐक्सेस किया जा सके. साथ ही, Place Details (New) के बजाय, चुनी गई जगह के बारे में Geocoding API के नतीजे पाने का अनुरोध किया जा सके. अगर ये दोनों शर्तें पूरी होती हैं, तो हर अनुरोध के हिसाब से तय की गई Geocoding API की कीमत, हर सेशन (सेशन के आधार पर) के हिसाब से तय की गई कीमत से ज़्यादा किफ़ायती होती है:

• अगर आपको सिर्फ़ उपयोगकर्ता की चुनी गई जगह का अक्षांश और देशांतर या पता चाहिए, तो Geocoding API, Place Details (New) API के कॉल की तुलना में कम कीमत पर यह जानकारी उपलब्ध कराता है.
• अगर उपयोगकर्ता, ऑटोकंप्लीट (नया वर्शन) के चार या इससे कम सुझावों में से किसी एक को चुनते हैं, तो हर अनुरोध के हिसाब से तय की गई कीमत, हर सेशन के हिसाब से तय की गई कीमत से ज़्यादा किफ़ायती हो सकती है.

क्या आपके ऐप्लिकेशन को, चुनी गई जगह के अक्षांश/देशांतर और पते के अलावा कोई और जानकारी चाहिए?

परफ़ॉर्मेंस के सबसे सही तरीके

यहां दिए गए दिशा-निर्देशों में, ऑटोकंप्लीट (नया वर्शन) की परफ़ॉर्मेंस को ऑप्टिमाइज़ करने के तरीके बताए गए हैं:

• ऑटोकंप्लीट (नया) सुविधा को लागू करते समय, देश से जुड़ी पाबंदियां, जगह के हिसाब से सुझाव देने की सुविधा, और (प्रोग्राम के हिसाब से लागू करने के लिए) भाषा की प्राथमिकता जोड़ें. विजेट के लिए, भाषा से जुड़ी प्राथमिकता सेट करने की ज़रूरत नहीं होती. ऐसा इसलिए, क्योंकि वे उपयोगकर्ता के ब्राउज़र या मोबाइल डिवाइस से भाषा से जुड़ी प्राथमिकताएं चुनते हैं.
• अगर ऑटोकंप्लीट (नया) के साथ मैप दिखाया जाता है, तो मैप व्यूपोर्ट के हिसाब से जगह की जानकारी को प्राथमिकता दी जा सकती है.
• जब कोई उपयोगकर्ता ऑटोकंप्लीट (नया) सुविधा के सुझावों में से किसी को नहीं चुनता है, तो आम तौर पर ऐसा इसलिए होता है, क्योंकि इनमें से कोई भी सुझाव, उपयोगकर्ता के हिसाब से नहीं होता. ऐसे में, ज़्यादा काम के नतीजे पाने के लिए, उपयोगकर्ता के ओरिजनल इनपुट का फिर से इस्तेमाल किया जा सकता है:
  • अगर आपको लगता है कि उपयोगकर्ता सिर्फ़ पते की जानकारी डालेगा, तो Geocoding API को किए गए कॉल में, उपयोगकर्ता के ओरिजनल इनपुट का फिर से इस्तेमाल करें.
  • अगर आपको लगता है कि उपयोगकर्ता किसी जगह का नाम या पता डालकर क्वेरी करेगा, तो Place Details (नई) का अनुरोध करें. अगर आपको सिर्फ़ किसी खास इलाके के नतीजे चाहिए, तो जगह के हिसाब से नतीजे दिखाने की सुविधा का इस्तेमाल करें.
  इन स्थितियों में भी Geocoding API का इस्तेमाल करना सबसे सही रहता है:
  • ऐसे लोग जो सबप्रीमाइज़ के पते डालते हैं. जैसे, किसी बिल्डिंग में मौजूद खास यूनिट या अपार्टमेंट के पते. उदाहरण के लिए, चेक गणराज्य के पते "Stroupežnického 3191/17, Praha" के लिए, ऑटोकंप्लीट (नया) की सुविधा से आंशिक सुझाव मिलता है.
  • ऐसे उपयोगकर्ता जो न्यूयॉर्क शहर में "23-30 29th St, Queens" या हवाई द्वीप के काउआई में "47-380 Kamehameha Hwy, Kaneohe" जैसे सड़क के हिस्से के प्रीफ़िक्स वाले पते डालते हैं.

लोकेशन के हिसाब से पक्षपात करना

location और radius पैरामीटर पास करके, नतीजों को किसी खास इलाके के हिसाब से दिखाएं. इससे ऑटोकंप्लीट (नया) को यह निर्देश मिलता है कि वह तय किए गए इलाके के हिसाब से नतीजे दिखाने को प्राथमिकता दे. तय किए गए इलाके से बाहर के नतीजे अब भी दिख सकते हैं. includedRegionCodes पैरामीटर का इस्तेमाल करके, नतीजों को फ़िल्टर किया जा सकता है. इससे सिर्फ़ किसी देश में मौजूद जगहों के नतीजे दिखते हैं.

जगह की जानकारी को सीमित करना

locationRestriction पैरामीटर पास करके, नतीजों को किसी तय जगह तक सीमित करें.

locationRestriction पैरामीटर जोड़कर, नतीजों को location और radius पैरामीटर से तय किए गए इलाके तक सीमित किया जा सकता है. इससे Autocomplete (New) को यह निर्देश मिलता है कि वह सिर्फ़ उस इलाके के नतीजे दिखाए.

इसे आज़माएं!

APIs Explorer की मदद से, सैंपल अनुरोध किए जा सकते हैं. इससे आपको एपीआई और उसके विकल्पों के बारे में जानकारी मिलती है.

1. पेज की दाईं ओर मौजूद, एपीआई आइकॉन api को चुनें.

2. अनुरोध के पैरामीटर में बदलाव करें. यह ज़रूरी नहीं है.

3. Execute बटन को चुनें. डायलॉग बॉक्स में, वह खाता चुनें जिसका इस्तेमाल करके आपको अनुरोध करना है.

4. APIs Explorer पैनल में, फ़ुलस्क्रीन आइकॉन fullscreen को चुनें. इससे APIs Explorer विंडो बड़ी हो जाएगी.