Routes API के साथ, दिशा-निर्देशों की अगली-पीढ़ी की टेक्नोलॉजी को आज़माएं.

इस पेज का अनुवाद Cloud Translation API से किया गया है.

निर्देश एपीआई वेब सेवाओं का इस्तेमाल करने के सबसे सही तरीके

Google Maps Platform की वेब सेवाएं, Google की सेवाओं के एचटीटीपी इंटरफ़ेस का एक कलेक्शन हैं. ये सेवाएं, आपके मैप ऐप्लिकेशन के लिए भौगोलिक डेटा उपलब्ध कराती हैं.

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

वेब सेवा क्या है?

Google Maps Platform की वेब सेवाएं, बाहरी सेवाओं से Maps API के डेटा का अनुरोध करने और Maps ऐप्लिकेशन में डेटा का इस्तेमाल करने के लिए एक इंटरफ़ेस हैं. इन सेवाओं को मैप के साथ इस्तेमाल करने के लिए डिज़ाइन किया गया है. ऐसा, Google Maps Platform की सेवा की शर्तों में बताई गई लाइसेंस से जुड़ी पाबंदियों के मुताबिक किया गया है.

Maps APIs की वेब सेवाएं, खास यूआरएल के लिए एचटीटीपी(एस) अनुरोधों का इस्तेमाल करती हैं. साथ ही, सेवाओं के लिए यूआरएल पैरामीटर और/या JSON फ़ॉर्मैट में पोस्ट किया गया डेटा, आर्ग्युमेंट के तौर पर पास करती हैं. आम तौर पर, ये सेवाएं आपके ऐप्लिकेशन के लिए, रिस्पॉन्स बॉडी में JSON या एक्सएमएल के तौर पर डेटा दिखाती हैं, ताकि उसे पार्स और/या प्रोसेस किया जा सके.

Directions API का सामान्य अनुरोध, आम तौर पर इस फ़ॉर्मैट में होता है:

https://maps.googleapis.com/maps/api/directions/output?parameters

यहां output, जवाब के फ़ॉर्मैट के बारे में बताता है. आम तौर पर, यह json या xml होता है.

ध्यान दें: Directions API के सभी ऐप्लिकेशन के लिए पुष्टि करना ज़रूरी है. पुष्टि करने के क्रेडेंशियल के बारे में ज़्यादा जानें.

एसएसएल/टीएलएस ऐक्सेस

Google Maps Platform के उन सभी अनुरोधों के लिए एचटीटीपीएस ज़रूरी है जिनमें एपीआई पासकोड का इस्तेमाल किया जाता है या उपयोगकर्ता का डेटा शामिल होता है. एचटीटीपी के ज़रिए किए गए ऐसे अनुरोधों को अस्वीकार किया जा सकता है जिनमें संवेदनशील डेटा शामिल हो.

मान्य यूआरएल बनाना

आपको लग सकता है कि "मान्य" यूआरएल अपने-आप साबित हो जाता है, लेकिन ऐसा नहीं है. उदाहरण के लिए, ब्राउज़र के पता बार में डाले गए यूआरएल में खास वर्ण (जैसे, "上海+中國") हो सकते हैं. ब्राउज़र को ट्रांसमिशन से पहले, उन वर्णों को इंटरनल तौर पर किसी दूसरी एन्कोडिंग में बदलना पड़ता है. इसी तरह, UTF-8 इनपुट जनरेट करने या स्वीकार करने वाला कोई भी कोड, UTF-8 वर्णों वाले यूआरएल को "मान्य" मान सकता है. हालांकि, वेब सर्वर पर भेजने से पहले, उन वर्णों का अनुवाद करना भी ज़रूरी होगा. इस प्रोसेस को यूआरएल को कोड में बदलना या पर्सेंट कोड में बदलना कहा जाता है.

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

विशेष वर्ण

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

यूआरएल में इस्तेमाल किए जा सकने वाले वर्ण

सेट करें	वर्ण	यूआरएल का इस्तेमाल
अक्षर और अंक	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	टेक्स्ट स्ट्रिंग, स्कीम का इस्तेमाल (`http`), पोर्ट (`8080`) वगैरह.
गैर-आरक्षित	- _ . ~	टेक्स्ट स्ट्रिंग
बुकिंग की गई	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	कंट्रोल वर्ण और/या टेक्स्ट स्ट्रिंग

मान्य यूआरएल बनाते समय, आपको यह पक्का करना होगा कि उसमें सिर्फ़ वे वर्ण हों जो टेबल में दिखाए गए हैं. वर्णों के इस सेट का इस्तेमाल करने के लिए, यूआरएल को आम तौर पर, दो समस्याओं का सामना करना पड़ता है. पहला, कुछ वर्णों को छोड़ना और दूसरा, कुछ वर्णों को बदलना:

आपको जिन वर्णों को हैंडल करना है वे ऊपर दिए गए सेट में शामिल नहीं हैं. उदाहरण के लिए, 上海+中國 जैसी विदेशी भाषाओं के वर्णों को ऊपर दिए गए वर्णों का इस्तेमाल करके एन्कोड करना ज़रूरी है. आम तौर पर, यूआरएल में स्पेस का इस्तेमाल नहीं किया जा सकता. हालांकि, अक्सर स्पेस को प्लस '+' वर्ण का इस्तेमाल करके दिखाया जाता है.
ऊपर दिए गए सेट में वर्ण, रिज़र्व किए गए वर्णों के तौर पर मौजूद होते हैं, लेकिन इनका इस्तेमाल लिटरल तौर पर किया जाना चाहिए. उदाहरण के लिए, यूआरएल में ? का इस्तेमाल, क्वेरी स्ट्रिंग की शुरुआत को दिखाने के लिए किया जाता है. अगर आपको स्ट्रिंग "? और Mysterions" का इस्तेमाल करना है, तो आपको '?' वर्ण को कोड में बदलना होगा.

यूआरएल में बदले जाने वाले सभी वर्णों को, '%' कैरेक्टर और उनके UTF-8 कैरेक्टर से जुड़ी दो वर्णों वाली हेक्स वैल्यू का इस्तेमाल करके एन्कोड किया जाता है. उदाहरण के लिए, UTF-8 में 上海+中國 को यूआरएल-कोड में बदलकर %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B किया जाएगा. ? and the Mysterians स्ट्रिंग को कोड में बदलकर, %3F+and+the+Mysterians या %3F%20and%20the%20Mysterians किया जाएगा.

ऐसे सामान्य वर्ण जिन्हें एन्कोड करने की ज़रूरत होती है

कुछ सामान्य वर्ण ऐसे होते हैं जिन्हें कोड में बदलना ज़रूरी होता है. जैसे:

असुरक्षित वर्ण	एन्कोड की गई वैल्यू
स्पेस	`%20`
"	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

उपयोगकर्ता के इनपुट से मिले यूआरएल को बदलना कभी-कभी मुश्किल हो सकता है. उदाहरण के लिए, कोई उपयोगकर्ता "5th&Main St." के तौर पर पता डाल सकता है. आम तौर पर, आपको अपने यूआरएल को उसके हिस्सों से बनाना चाहिए. साथ ही, उपयोगकर्ता के किसी भी इनपुट को लिटरल वर्ण के तौर पर इस्तेमाल करना चाहिए.

इसके अलावा, Google Maps Platform की सभी वेब सेवाओं और स्टैटिक वेब एपीआई के लिए, यूआरएल में 16,384 वर्ण ही इस्तेमाल किए जा सकते हैं. ज़्यादातर सेवाओं के लिए, वर्ण की यह सीमा शायद ही पूरी हो. हालांकि, ध्यान दें कि कुछ सेवाओं में कई पैरामीटर होते हैं, जिनकी वजह से यूआरएल लंबे हो सकते हैं.

Google API का सही तरीके से इस्तेमाल करना

खराब तरीके से डिज़ाइन किए गए एपीआई क्लाइंट, इंटरनेट और Google के सर्वर, दोनों पर ज़रूरत से ज़्यादा लोड डाल सकते हैं. इस सेक्शन में, एपीआई के क्लाइंट के लिए कुछ सबसे सही तरीके दिए गए हैं. इन सबसे सही तरीकों को अपनाने से, एपीआई का गलती से गलत इस्तेमाल करने पर, आपके ऐप्लिकेशन को ब्लॉक होने से बचाया जा सकता है.

एक्सपोनेंशियल बैकऑफ़

कुछ मामलों में, आपके अनुरोध को पूरा करने में कोई गड़बड़ी हो सकती है. आपको 4XX या 5XX एचटीटीपी रिस्पॉन्स कोड मिल सकता है या आपके क्लाइंट और Google के सर्वर के बीच टीसीपी कनेक्शन काम नहीं कर सकता. अक्सर, अनुरोध को फिर से करने की कोशिश करना फ़ायदेमंद होता है. ऐसा इसलिए, क्योंकि मूल अनुरोध अस्वीकार होने पर, फ़ॉलोअप अनुरोध स्वीकार किया जा सकता है. हालांकि, Google के सर्वर से बार-बार अनुरोध करना ज़रूरी नहीं है. इस तरह के लूप होने पर, आपके क्लाइंट और Google के बीच के नेटवर्क पर लोड बढ़ सकता है. इससे कई लोगों को समस्याएं हो सकती हैं.

बेहतर तरीका यह है कि हर बार थोड़ी देर बाद कोशिश की जाए. आम तौर पर, हर बार कोशिश करने पर, इंतज़ार का समय कई गुना बढ़ जाता है. इसे एक्सपोनेंशियल बैकऑफ़ कहा जाता है.

उदाहरण के लिए, मान लें कि कोई ऐप्लिकेशन टाइम ज़ोन एपीआई से यह अनुरोध करना चाहता है:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

यहां दिए गए Python के उदाहरण में, एक्सपोनेंशियल बैकऑफ़ के साथ अनुरोध करने का तरीका बताया गया है:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

आपको यह भी ध्यान रखना चाहिए कि ऐप्लिकेशन कॉल चेन में, फिर से कोशिश करने का कोड ऊपर न हो. इससे बार-बार अनुरोध किए जाते हैं.

सिंक किए गए अनुरोध

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

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

तय समय पर बजने वाले अलार्म के जवाब में एपीआई कॉल करना अच्छा नहीं है. ऐसा करने पर, एपीआई कॉल को समय के हिसाब से बराबर बांटने के बजाय, मिनट की शुरुआत में सिंक किया जाता है. यह सिंक, अलग-अलग डिवाइसों के बीच भी किया जाता है. खराब तरीके से डिज़ाइन किए गए ऐप्लिकेशन में ऐसा करने पर, हर मिनट की शुरुआत में सामान्य लेवल के मुकाबले ट्रैफ़िक में 60 गुना बढ़ोतरी होगी.

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

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

जवाब प्रोसेस करना

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

इस सेक्शन में, वेब सेवा के रिस्पॉन्स से डाइनैमिक तौर पर इन वैल्यू को निकालने का तरीका बताया गया है.

Google Maps की वेब सेवाएं, ऐसे जवाब देती हैं जिन्हें समझना आसान होता है. हालांकि, ये जवाब पूरी तरह से उपयोगकर्ता के हिसाब से नहीं होते. क्वेरी करते समय, हो सकता है कि आप डेटा का सेट दिखाने के बजाय, कुछ खास वैल्यू निकालना चाहें. आम तौर पर, आपको वेब सेवा से मिले जवाबों को पार्स करना होगा और सिर्फ़ उन वैल्यू को निकालना होगा जिनमें आपकी दिलचस्पी है.

पार्स करने की स्कीम इस बात पर निर्भर करती है कि आउटपुट को एक्सएमएल या JSON में दिखाया जा रहा है. JSON रिस्पॉन्स, पहले से ही JavaScript ऑब्जेक्ट के तौर पर मौजूद होते हैं. इसलिए, क्लाइंट पर JavaScript में ही इनका प्रोसेस किया जा सकता है. एक्सएमएल फ़ॉर्मैट में मौजूद एलिमेंट को प्रोसेस करने के लिए, एक्सएमएल प्रोसेसर और एक्सएमएल क्वेरी लैंग्वेज का इस्तेमाल किया जाना चाहिए. हम यहां दिए गए उदाहरणों में XPath का इस्तेमाल करते हैं, क्योंकि आम तौर पर एक्सएमएल प्रोसेसिंग लाइब्रेरी में इसका इस्तेमाल किया जाता है.

XPath की मदद से एक्सएमएल प्रोसेस करना

एक्सएमएल, स्ट्रक्चर्ड जानकारी का एक ऐसा फ़ॉर्मैट है जिसका इस्तेमाल डेटा इंटरचेंज के लिए किया जाता है. हालांकि, यह JSON की तरह छोटा नहीं है, लेकिन एक्सएमएल में ज़्यादा भाषाओं के साथ काम करने की सुविधा और बेहतर टूल मिलते हैं. उदाहरण के लिए, Java में एक्सएमएल को प्रोसेस करने के लिए कोड, javax.xml पैकेज में पहले से मौजूद होता है.

एक्सएमएल रिस्पॉन्स प्रोसेस करते समय, आपको एक्सएमएल दस्तावेज़ में नोड चुनने के लिए, सही क्वेरी भाषा का इस्तेमाल करना चाहिए. ऐसा करने के बजाय, यह नहीं माना जाना चाहिए कि एलिमेंट, एक्सएमएल मार्कअप में सटीक जगहों पर मौजूद हैं. XPath एक सिंटैक्स है, जिसका इस्तेमाल करके एक्सएमएल दस्तावेज़ में मौजूद नोड और एलिमेंट की खास जानकारी दी जा सकती है. XPath एक्सप्रेशन की मदद से, एक्सएमएल रिस्पॉन्स दस्तावेज़ में किसी खास कॉन्टेंट की पहचान की जा सकती है.

XPath एक्सप्रेशन

XPath के बारे में थोड़ी जानकारी होने पर, बेहतर पार्सिंग स्कीम बनाने में काफ़ी मदद मिलती है. इस सेक्शन में, एक्सएमएल दस्तावेज़ में मौजूद एलिमेंट को एक्सपैथ की मदद से ऐक्सेस करने के तरीके के बारे में बताया जाएगा. इससे, आपको एक से ज़्यादा एलिमेंट ऐक्सेस करने और जटिल क्वेरी बनाने में मदद मिलेगी.

XPath, किसी एक्सएमएल दस्तावेज़ में एलिमेंट चुनने के लिए एक्सप्रेशन का इस्तेमाल करता है. इसके लिए, डायरेक्ट्री पाथ के लिए इस्तेमाल किए जाने वाले सिंटैक्स का इस्तेमाल किया जाता है. ये एक्सप्रेशन, एक्सएमएल दस्तावेज़ के ट्री में मौजूद एलिमेंट की पहचान करते हैं. यह ट्री, डीओएम की तरह ही हैरारकी वाला होता है. आम तौर पर, XPath एक्सप्रेशन में ज़्यादा जानकारी शामिल होती है. इसका मतलब है कि वे उन सभी नोड से मैच करेंगे जो दी गई शर्तों से मैच करते हैं.

उदाहरणों को समझाने के लिए, हम इस एक्सएमएल का इस्तेमाल करेंगे:

<WebServiceResponse>
 <status>OK</status>
 <result>
  <type>sample</type>
  <name>Sample XML</name>
  <location>
   <lat>37.4217550</lat>
   <lng>-122.0846330</lng>
  </location>
 </result>
 <result>
  <message>The secret message</message>
 </result>
</WebServiceResponse>

एक्सप्रेशन में नोड चुनना

XPath से चुने गए विकल्प, नोड चुनते हैं. रूट नोड में पूरा दस्तावेज़ शामिल होता है. इस नोड को चुनने के लिए, "/" जैसे खास एक्सप्रेशन का इस्तेमाल किया जाता है. ध्यान दें कि रूट नोड, आपके एक्सएमएल दस्तावेज़ का टॉप-लेवल नोड नहीं होता. असल में, यह इस टॉप-लेवल एलिमेंट के एक लेवल ऊपर होता है और इसमें यह शामिल होता है.

एलिमेंट नोड, एक्सएमएल दस्तावेज़ ट्री में मौजूद अलग-अलग एलिमेंट दिखाते हैं. उदाहरण के लिए, <WebServiceResponse> एलिमेंट, ऊपर दी गई हमारी सैंपल सेवा में दिखाए गए टॉप-लेवल एलिमेंट को दिखाता है. अलग-अलग नोड को, एब्सोलूट या रिलेटिव पाथ के ज़रिए चुना जाता है. इन पाथ में "/" वर्ण मौजूद होता है या नहीं, इससे यह पता चलता है कि पाथ एब्सोलूट है या रिलेटिव.

एब्सोल्यूट पाथ: "/WebServiceResponse/result" एक्सप्रेशन, <WebServiceResponse> नोड के सभी <result> नोड चुनता है. (ध्यान दें कि ये दोनों एलिमेंट, रूट नोड "/" से आते हैं.)
मौजूदा कॉन्टेक्स्ट से रिलेटिव पाथ: एक्सप्रेशन "result", मौजूदा कॉन्टेक्स्ट में मौजूद किसी भी <result> एलिमेंट से मैच करेगा. आम तौर पर, आपको कॉन्टेक्स्ट के बारे में चिंता करने की ज़रूरत नहीं होती, क्योंकि आम तौर पर वेब सेवा के नतीजों को एक एक्सप्रेशन के ज़रिए प्रोसेस किया जाता है.

इनमें से किसी भी एक्सप्रेशन को वाइल्डकार्ड पाथ जोड़कर बेहतर बनाया जा सकता है. वाइल्डकार्ड पाथ को डबल स्लैश ("//") से दिखाया जाता है. इस वाइल्डकार्ड से पता चलता है कि बीच में मौजूद पाथ में शून्य या उससे ज़्यादा एलिमेंट मैच हो सकते हैं. उदाहरण के लिए, XPath एक्सप्रेशन "//formatted_address," मौजूदा दस्तावेज़ में उस नाम के सभी नोड से मैच करेगा. एक्सप्रेशन //viewport//lat, उन सभी <lat> एलिमेंट से मैच करेगा जो पैरंट के तौर पर <viewport> को ट्रैक कर सकते हैं.

डिफ़ॉल्ट रूप से, XPath एक्सप्रेशन सभी एलिमेंट से मैच करते हैं. किसी खास एलिमेंट से मैच करने के लिए, एक्सप्रेशन को सीमित किया जा सकता है. इसके लिए, स्क्वेयर ब्रैकेट ([]) में प्रेडिकेट दें. उदाहरण के लिए, XPath एक्सप्रेशन "/GeocodeResponse/result[2] हमेशा दूसरा नतीजा दिखाता है.

एक्सप्रेशन का टाइप
रूट नोड	XPath एक्सप्रेशन: "`/`" चुना गया विकल्प: <WebServiceResponse> <status>OK</status> <result> <type>sample</type> <name>Sample XML</name> <location> <lat>37.4217550</lat> <lng>-122.0846330</lng> </location> </result> <result> <message>The secret message</message> </result> </WebServiceResponse>
एब्सोल्यूट पाथ	XPath एक्सप्रेशन: "`/WebServiceResponse/result`" चुना गया विकल्प: <result> <type>sample</type> <name>Sample XML</name> <location> <lat>37.4217550</lat> <lng>-122.0846330</lng> </location> </result> <result> <message>The secret message</message> </result>
वाइल्डकार्ड वाला पाथ	XPath एक्सप्रेशन: "`/WebServiceResponse//location`" चुना गया विकल्प: <location> <lat>37.4217550</lat> <lng>-122.0846330</lng> </location>
प्रीडिकेट वाला पाथ	XPath एक्सप्रेशन: "`/WebServiceResponse/result[2]/message`" चुना गया विकल्प: <message>The secret message</message>
पहले `result` के सभी डायरेक्ट चाइल्ड	XPath एक्सप्रेशन: "`/WebServiceResponse/result[1]/`" चुना गया विकल्प:* <type>sample</type> <name>Sample XML</name> <location> <lat>37.4217550</lat> <lng>-122.0846330</lng> </location>
ऐसे `result` का `name` जिसका `type` टेक्स्ट "सैंपल" है.	XPath एक्सप्रेशन: "`/WebServiceResponse/result[type/text()='sample']/name`" चुना गया विकल्प: Sample XML

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

ध्यान दें कि XPath, एट्रिब्यूट नोड के साथ भी काम करता है. हालांकि, Google Maps की सभी वेब सेवाएं, एट्रिब्यूट के बिना एलिमेंट दिखाती हैं. इसलिए, एट्रिब्यूट की मैचिंग ज़रूरी नहीं है.

एक्सप्रेशन में टेक्स्ट चुनना

एक्सएमएल दस्तावेज़ में मौजूद टेक्स्ट को टेक्स्ट नोड ऑपरेटर के ज़रिए, एक्सपैथ एक्सप्रेशन में बताया जाता है. यह ऑपरेटर "text()", चुने गए नोड से टेक्स्ट निकालने का संकेत देता है. उदाहरण के लिए, XPath एक्सप्रेशन "//formatted_address/text()", <formatted_address> एलिमेंट में मौजूद सारा टेक्स्ट दिखाएगा.

एक्सप्रेशन का टाइप
सभी टेक्स्ट नोड (व्हाइटस्पेस शामिल है)	XPath एक्सप्रेशन: "`//text()`" चुना गया विकल्प: sample Sample XML 37.4217550 -122.0846330 The secret message
टेक्स्ट चुनना	XPath एक्सप्रेशन: "`/WebServiceRequest/result[2]/message/text()`" चुना गया विकल्प: The secret message
कॉन्टेक्स्ट के हिसाब से टेक्स्ट चुनना	XPath एक्सप्रेशन: "`/WebServiceRequest/result[type/text() = 'sample']/name/text()`" चुना गया विकल्प: Sample XML

इसके अलावा, किसी एक्सप्रेशन का आकलन करके नोड का सेट रिटर्न किया जा सकता है. इसके बाद, उस "नोड सेट" पर दोहराए जाने वाले हर नोड से टेक्स्ट निकाला जा सकता है. हम इस उदाहरण में इस तरीके का इस्तेमाल करते हैं.

XPath के बारे में ज़्यादा जानकारी के लिए, XPath W3C स्पेसिफ़िकेशन देखें.

Java में XPath का आकलन करना

Java में, एक्सएमएल को पार्स करने और javax.xml.xpath.* पैकेज में XPath एक्सप्रेशन का इस्तेमाल करने के लिए, कई सुविधाएं उपलब्ध हैं. इस वजह से, इस सेक्शन में दिए गए सैंपल कोड में, एक्सएमएल को हैंडल करने और एक्सएमएल सेवा के जवाबों से डेटा पार्स करने का तरीका बताने के लिए, Java का इस्तेमाल किया गया है.

अपने Java कोड में XPath का इस्तेमाल करने के लिए, आपको सबसे पहले XPathFactory के किसी इंस्टेंस को इंस्टैंशिएट करना होगा. इसके बाद, XPath ऑब्जेक्ट बनाने के लिए, उस फ़ैक्ट्री पर newXPath() को कॉल करना होगा. इसके बाद, यह ऑब्जेक्ट evaluate() तरीके का इस्तेमाल करके, पास किए गए एक्सएमएल और एक्सपाथ एक्सप्रेशन को प्रोसेस कर सकता है.

XPath एक्सप्रेशन का आकलन करते समय, पक्का करें कि आप उन सभी संभावित "नोड सेट" पर जाएं जो रिटर्न किए जा सकते हैं. ये नतीजे, Java कोड में DOM नोड के तौर पर दिखाए जाते हैं. इसलिए, आपको NodeList ऑब्जेक्ट में ऐसी कई वैल्यू कैप्चर करनी चाहिए. साथ ही, उन नोड से कोई टेक्स्ट या वैल्यू निकालने के लिए, उस ऑब्जेक्ट को दोहराना चाहिए.

यहां दिए गए कोड में, XPath ऑब्जेक्ट बनाने, उसे एक्सएमएल और एक्सपैथ एक्सप्रेशन असाइन करने, और काम का कॉन्टेंट प्रिंट करने के लिए एक्सप्रेशन का आकलन करने का तरीका बताया गया है.

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}