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

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

Routes API

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

रास्ते, कोड में बदली गई पॉलीलाइन के तौर पर भी दिखाए जाते हैं. इसे एसएआर अनुरोध में इनपुट पैरामीटर के तौर पर पास किया जाता है. पॉलीलाइन को कोड में बदलने की सुविधा, एक ऐसा एल्गोरिदम है जो डेटा को कम डेटा वाले फ़ॉर्मैट में बदलता है. इसकी मदद से, निर्देशांक की सीरीज़ को एक स्ट्रिंग के तौर पर सेव किया जा सकता है. 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 के टेक्स्ट से खोजने की सुविधा में, एसएआर की मदद से रास्ते की जानकारी वाला फ़ील्ड भी दिख सकता है. इसमें यात्रा में लगने वाला समय और दूरी, दोनों की जानकारी होती है. रूटिंग की खास जानकारी वाला डेटा फ़ील्ड, रिस्पॉन्स रूट का चाइल्ड होता है. इसलिए, आपको फ़ील्ड मास्क में "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 सेकंड = 7,200 सेकंड की अवधि मिलती है.

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

अपने काम को तेज़ करने के लिए, 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 के दो एपीआई, Routes और Places को एक साथ इस्तेमाल करने का तरीका जाना. इससे, यात्रा की योजना बनाने और यात्रा के दो घंटे बाद खाने की जगहें ढूंढने में मदद मिलती है. इसके लिए, आपको एक कोड वाली पॉलीलाइन बनानी होगी. इसमें, रास्ते के हर चरण के लिए अक्षांश और देशांतर के निर्देशांक शामिल होने चाहिए. साथ ही, बेहतर नतीजे पाने के लिए, 'रास्ते के साथ खोजें' अनुरोध के ऑरिजिन को सेट करना होगा.

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

अगली कार्रवाइयां

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

इसके बारे में और पढ़ने के लिए, ये लेख पढ़ें:

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

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

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

मुख्य लेखक: मिकको तोइवानन | Google Maps Platform के सलूशन इंजीनियर