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

परिचय

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

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

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

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

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

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

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

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

अपने-आप पूरा होने की सुविधा (नई) के अनुरोध

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

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

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

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

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

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

'अपने-आप पूरा होने की सुविधा (नई)' से मिले जवाब में एक 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 में अनुवाद नहीं किया गया है, तब भी ऐसा हो सकता है.

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

• locationBias या locationRestriction

  खोज के दायरे को तय करने के लिए, locationBias या locationRestriction में से किसी एक को तय किया जा सकता है. हालांकि, दोनों को एक साथ तय नहीं किया जा सकता. locationRestriction को उस क्षेत्र के तौर पर समझें जहां नतीजे दिखने चाहिए. वहीं, locationBias को उस क्षेत्र के तौर पर समझें जहां नतीजे दिखने चाहिए, लेकिन वे उस क्षेत्र के बाहर भी दिख सकते हैं.

  • locationBias

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

  • locationRestriction

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

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

  • किसी सर्कल को उसके सेंटर पॉइंट और मीटर में दी गई त्रिज्या से तय किया जाता है. रेडियस, 0.0 और 50000.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 कोड, आईएसओ 3166-1 कोड के जैसे ही होते हैं. हालांकि, कुछ अपवाद भी हैं. उदाहरण के लिए, यूनाइटेड किंगडम का ccTLD "uk" (.co.uk) है, जबकि इसका ISO 3166-1 कोड "gb" है. तकनीकी तौर पर, यह "ग्रेट ब्रिटेन और उत्तरी आयरलैंड का यूनाइटेड किंगडम" के लिए है.

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

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

• sessionToken

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

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

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

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

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

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) से, ज़्यादा से ज़्यादा पांच टाइप वैल्यू तय करें. जवाब में किसी जगह को शामिल करने के लिए, यह ज़रूरी है कि वह बताए गए प्राइमरी टाइप की वैल्यू में से किसी एक से मेल खाती हो.

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

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 शामिल करने पर, ऑटोकंप्लीट (नया वर्शन) जवाब में 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"
        ]
      }
    }
  ]
}

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

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

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

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

ऑटोकंप्लीट (नई) सुविधा के लिए ऑप्टिमाइज़ेशन

इस सेक्शन में, अपने-आप भरने की सुविधा (नई) का ज़्यादा से ज़्यादा फ़ायदा पाने के लिए, सबसे सही तरीकों के बारे में बताया गया है.

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

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

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

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

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

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

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

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

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

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

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

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

जगह की जानकारी के हिसाब से नतीजे दिखाना

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

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

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

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

इसे आज़माएं!

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

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

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

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

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