Places API की मदद से, रास्ते में पड़ने वाली जगहें खोजना

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

Routes API

रास्ते में पड़ने वाली जगहों को खोजने के लिए, हम Routes API का इस्तेमाल करेंगे. Routes API के रिस्पॉन्स से मिला रूट डेटा, ओरिजनल जगह से लेकर डेस्टिनेशन तक के LatLong कोऑर्डिनेट की एक सीरीज़ होती है. रास्ते के डेटा में लेग और चरण शामिल होते हैं, जो सड़क नेटवर्क के हिसाब से होते हैं.

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

इस ट्यूटोरियल में, हमने लंदन (-37.8167,144.9619) से मैनचेस्टर (-37.8155, 144.9663) तक के रास्ते का इस्तेमाल किया है

उदाहरण में दिया गया रास्ता: लंदन से मैनचेस्टर

पहला चरण: Routes API से कोई रास्ता पाना

Routes API से कोई रूट पाने के लिए, आपको यह जानकारी देनी होगी:

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

{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}

कॉल करते समय, यह पक्का करें कि आपने हेडर फ़ील्ड मास्क में "encodedPolyline" फ़ील्ड शामिल किया हो.

headers = {
    "Content-Type": "application/json",
    "X-Goog-FieldMask": "routes.distanceMeters,routes.duration,routes.legs,routes.polyline.encodedPolyline"
}

पूरा दस्तावेज़, जिसमें रास्ता पाने और रास्ते की पॉलीलाइन पाने के तरीके के उदाहरण दिए गए हैं.

अनुरोध में यह जानकारी देने के बाद, Routes API एक रूट ऑब्जेक्ट दिखाएगा. रूट ऑब्जेक्ट में यह जानकारी शामिल होगी:

• रास्ते की कुल दूरी
• रास्ते की कुल अवधि
• रास्ते के चरण और पैर
• रास्ते, लेग, और चरणों की एन्कोड की गई पॉलीलाइन.

{
  "routes": [
    {
      "legs": [
        {
          "distanceMeters": 321799,
          "duration": "15401s",
          "staticDuration": "14518s",
          "polyline": {
            "encodedPolyline": "y_kyH`_XOr@q@xKGnBBZ|AlGPj@Y^k@^MEqAfAQLK?eI … <rest of content removed for readability>"
          },
          "startLocation": {
            "latLng": {
              "latitude": 51.507334500000006,
              "longitude": -0.1280107
            }
          },
          "endLocation": {
            "latLng": {
              "latitude": 53.4808513,
              "longitude": -2.2425864
            }
          },
          "steps": [
            {
              "distanceMeters": 320,
              "staticDuration": "82s",
              "polyline": {
                "encodedPolyline": "y_kyH`_XOr@q@xKGnBBZ|AlG"
              },
              "startLocation": {
                "latLng": {
                  "latitude": 51.507334500000006,
                  "longitude": -0.1280107
                }
              },
              "endLocation": {
                "latLng": {
                  "latitude": 51.507207,
                  "longitude": -0.1323681
                }
              },
              "navigationInstruction": {
                "maneuver": "DEPART",
                "instructions": "Head northwest on Trafalgar Sq/A4 toward Spring Gardens\nContinue to follow A4\nLeaving toll zone\nEntering toll zone\nLeaving toll zone in 210m at Haymarket"
              },
              "localizedValues": {
                "distance": {
                  "text": "0.3 km"
                },
                "staticDuration": {
                  "text": "1 min"
                }
              },
# rest of the response removed for readability

दूसरा चरण: रास्ते में मौजूद जगहों को खोजने का अनुरोध करना

Places API की टेक्स्ट सर्च सुविधा में, 'रास्ते में पड़ने वाली जगहें खोजें' अनुरोध करने की सुविधा होती है. इसकी मदद से, किसी रास्ते में पड़ने वाली जगहों को खोजा जा सकता है. रास्ते में खोज करने का अनुरोध करने के लिए, आपको कम से कम यह जानकारी देनी होगी:

• फ़ील्ड मास्क, जिसमें यह जानकारी होती है कि जवाब में कौनसे फ़ील्ड दिखाए गए हैं
• Google Cloud Console में चालू किए गए एपीआई के लिए मान्य एपीआई पासकोड
• खोज के लिए इस्तेमाल किया गया टेक्स्ट स्ट्रिंग, जिसमें यह बताया गया हो कि आपको किस तरह की जगहें खोजनी हैं. उदाहरण के लिए, "मसालेदार शाकाहारी रेस्टोरेंट"
• रास्ते की एन्कोड की गई पॉलीलाइन. इसे Routes API के पिछले कॉल से वापस पाया गया है
• Places Text Search API एंडपॉइंट का यूआरएल

import requests

url = 'https://places.googleapis.com/v1/places:searchText'
api_key = 'YOUR_API_KEY'  # Replace with your actual API key
route_polyline = 'YOUR_ROUTE_POLYLINE'  # Replace with your encoded route polyline

headers = {
    'Content-Type': 'application/json',
    'X-Goog-Api-Key': api_key,
    'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.priceLevel'
}

data = {
    "textQuery":
 "Spicy Vegetarian Food",
    "searchAlongRouteParameters": {
        "polyline": {
            "encodedPolyline": route_polyline
        }
    }
}

response = requests.post(url, headers=headers, json=data)

अनुरोध के डेटा का उदाहरण

'रास्ते में खोजें' सुविधा के लिए किए गए अनुरोध के जवाब में, रास्ते में मौजूद जगहों की सूची दिखेगी. यहां उदाहरण के तौर पर दिए गए डेटा का एक छोटा सा हिस्सा दिया गया है. जवाब की लंबाई को सीमित किया जा सकता है. इसके लिए, नतीजों की ज़्यादा से ज़्यादा संख्या वाले पैरामीटर सेट करें. साथ ही, ज़्यादा फ़ील्ड जोड़ने से, मिले डेटा की मात्रा बढ़ जाती है. Places API के रिस्पॉन्स के बारे में ज़्यादा जानकारी पाने के लिए, दस्तावेज़ देखें.

{
  "places": [
    {
      "formattedAddress": "33 Haymarket, London SW1Y 4HA, UK",
      "displayName": {
        "text": "xxx",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "224 Piccadilly, London W1J 9HP, UK",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "yyy",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "63 Neal St, London WC2H 9PJ, UK",
      "displayName": {
        "text": "zzz",
        "languageCode": "en"
      }
    },

जवाब के डेटा का उदाहरण

रास्ते की खास जानकारी और रास्ते में लगने वाला अतिरिक्त समय

सिर्फ़ जगहों की जानकारी मिलना अच्छी बात है, लेकिन इन जगहों पर पहुंचने में कितना समय लगता है, इसकी जानकारी देने से ज़्यादा मदद मिलेगी. Places API की टेक्स्ट से खोजने की सुविधा के ज़रिए, एसएआर में रास्ते की खास जानकारी फ़ील्ड भी दिखाया जा सकता है. इसमें यात्रा में लगने वाला समय और दूरी, दोनों शामिल होती हैं. RoutingSummaries डेटा फ़ील्ड, रिस्पॉन्स रूट का चाइल्ड है. इसलिए, आपको फ़ील्ड मास्क में "places." प्रीफ़िक्स शामिल नहीं करना चाहिए.

'X-Goog-FieldMask': 'places.displayName,places.formattedAddress,places.priceLevel,routingSummaries'

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

"routingParameters": {
      "origin": {
        "latitude":  -37.8167,
        "longitude": 144.9619
      }
    }

जवाब मिलने पर, इसमें एक नया सेक्शन होता है. इसमें रास्ते की खास जानकारी होती है. इसमें लेग होते हैं, जिनमें अवधि और दूरी मीटर में होती है.

"routingSummaries": [
    {
      "legs": [
        {
          "duration": "662s",
          "distanceMeters": 3093
        }
      ]
    },

इसके बाद, हम देखेंगे कि रास्ते में कहां से खोज शुरू करनी है.

तीसरा चरण: रास्ते में दो घंटे की दूरी पर मौजूद जगह की जानकारी पाना

सामान्य इस्तेमाल के ऐसे मामले पर विचार करें जहां ड्राइवर को रास्ते की शुरुआत में नहीं, बल्कि आगे जाकर रेस्टोरेंट ढूंढने हैं. हमारे उदाहरण में, लंदन से मैनचेस्टर तक की यात्रा में करीब चार घंटे लगते हैं. ड्राइवर को रास्ते में दो घंटे की दूरी पर कोई रेस्टोरेंट ढूंढना है. इस अनुरोध से हमें 120 मिनट * 60 सेकंड = 7200 सेकंड की अवधि मिलती है.

Routes API से मिले जवाब में, हमें रास्ते के हर लेग और लेग के हर चरण की अवधि मिलती है. पक्का करें कि आपने अपने अनुरोध में फ़ील्ड मास्क में "legs" फ़ील्ड को शामिल किया हो. जब तक कुल अवधि दो घंटे या 7,200 सेकंड की सीमा तक नहीं पहुंच जाती, तब तक पैरों और कदमों को घुमाते रहें. इसके बाद, हमें वह लेग और चरण मिल गया है जिसे SAR अनुरोध के लिए मूल जगह के तौर पर सेट करना है

अपने काम को तेज़ी से पूरा करने के लिए, Python के लिए पॉलीलाइन लाइब्रेरी का इस्तेमाल किया जा सकता है. इसका इस्तेमाल, "polyline.endodedPolyline" डेटा फ़ील्ड से निर्देशांक पाने के लिए किया जा सकता है.

अपने एनवायरमेंट टर्मिनल में ये कमांड चलाएं.

> pip install polyline

import requests
import polyline

# We've covered getting a Routes API response earlier,
data = response.json()

  # Extract the first route and its encoded polyline
  route = data["routes"][0]
  polyline_points = polyline.decode(route["polyline"]["encodedPolyline"])

  # Calculate total duration of the route in seconds
  total_duration_seconds = route["duration"]

  # Calculate the desired time offset in seconds, 2h = 120 minutes * 60
  desired_time_offset_seconds = time_offset_minutes * 60

  # Iterate through the legs and steps to find the point at the desired time offset
  elapsed_time_seconds = 0
  for leg in route["legs"]:
      for step in leg["steps"]:
          step_duration_seconds = step["staticDuration"]

          # Check if the desired time offset falls within this step, remove last "s" from string and convert to int
          second_value = int(step_duration_seconds[:-1])
          if elapsed_time_seconds + second_value >= desired_time_offset_seconds:
              # Interpolate to find the exact point within the step
              fraction_of_step = (desired_time_offset_seconds - elapsed_time_seconds) / second_value
              step_polyline_points = polyline.decode(step["polyline"]["encodedPolyline"])
              index = int(len(step_polyline_points) * fraction_of_step)
              return step_polyline_points[index]

          elapsed_time_seconds += second_value

  # If the point is not found (e.g., time offset exceeds route duration)
  return None

अब हमें रास्ते में वह जगह मिल गई है जहां पहुंचने में दो घंटे लगते हैं. इसलिए, हम इसका इस्तेमाल अनुरोध में कर सकते हैं. "origin" पैरामीटर में अक्षांश और देशांतर जोड़ें. यह "routingParameters" पैरामीटर का हिस्सा है. हमारा सुझाव है कि आप "routingSummaries" डेटा फ़ील्ड का इस्तेमाल करें. इसके बारे में हम पहले बता चुके हैं. अगर चाहें, तो यात्रा के मोड और टोल से बचने के निर्देशों जैसे अतिरिक्त पैरामीटर भी जोड़े जा सकते हैं.

"routingParameters": {
    "origin": {
      "latitude": xx.xxxx,
      "longitude": yy.yyyy
    },
    "travelMode":"DRIVE",
    "routeModifiers": {
      "avoidTolls": true
    }
  }

नतीजों का उदाहरण (खोज की जगह दिखाने के लिए कार का आइकॉन जोड़ा गया है).

इमेज में दिखाया गया है कि एपीआई, रास्ते के आखिर में मौजूद जगहों के बारे में जानकारी देता है. साथ ही, यात्रा के बीच में मौजूद जगहों के बारे में भी जानकारी देता है. खोज के लिए अब भी Google Maps Platform के उसी डेटा का इस्तेमाल किया जाता है. इसमें जगह की अहमियत और दूरी के साथ-साथ अन्य पहलुओं को भी ध्यान में रखा जाता है.

निष्कर्ष

इस ट्यूटोरियल में हमने दो Google Maps Platform API, Routes और Places को एक साथ इस्तेमाल करने का तरीका सीखा. इससे यात्रा का प्लान बनाया जा सकता है और यात्रा शुरू होने के दो घंटे बाद खाने-पीने की जगहें ढूंढी जा सकती हैं. इसके लिए, आपको एक एन्कोड की गई पॉलीलाइन की ज़रूरत होगी. इसमें रास्ते के हर चरण के लिए अक्षांश और देशांतर के निर्देशांक शामिल होने चाहिए. साथ ही, आपको 'रास्ते के साथ खोजें' सुविधा के अनुरोध की जगह सेट करनी होगी, ताकि आपको सबसे अच्छे नतीजे मिल सकें.

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

अगले चरण

• दस्तावेज़ में दिए गए उदाहरण आज़माएं.
• सुझाव/राय दें या शिकायत करें.

इसके बारे में और पढ़ें:

• कोड में बदली गई पॉलीलाइन को डिकोड करने वाली यूटिलिटी
• Routes API

योगदान देने वाले लोग

Google इस दस्तावेज़ को मैनेज करता है. इसे मूल रूप से इस योगदानकर्ता ने लिखा है.

मुख्य लेखक: मिको तोइवानन | Google Maps Platform Solutions Engineer