Routes API में, दूरी का मेट्रिक्स की अगली-पीढ़ी की टेक्नोलॉजी का इस्तेमाल करके देखें.

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

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

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

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

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

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

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

एक सामान्य डिस्टेंस मैट्रिक्स एपीआई अनुरोध आम तौर पर यहां दिए गए फ़ॉर्म में होता है:

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

जहां output, रिस्पॉन्स का फ़ॉर्मैट दिखाता है (आम तौर पर json या xml).

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

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

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

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

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

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

खास वर्ण

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

मान्य यूआरएल वर्णों के बारे में खास जानकारी

सेट करें	वर्ण	यूआरएल का इस्तेमाल
अक्षर और अंक	अ ब क ई एफ़ ग एच इ वै ड ल् म	टेक्स्ट स्ट्रिंग, स्कीम का इस्तेमाल (`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 की सभी वेब सेवाओं और स्टैटिक वेब एपीआई के लिए, यूआरएल में ज़्यादा से ज़्यादा 16384 वर्ण हो सकते हैं. ज़्यादातर सेवाओं के लिए, इस वर्ण सीमा तक शायद ही कभी पहुंचना होगा. हालांकि, ध्यान रखें कि कुछ सेवाओं के कई पैरामीटर होते हैं, जिनकी वजह से यूआरएल लंबे हो सकते हैं.

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 का इस्तेमाल करते हैं, क्योंकि यह आम तौर पर एक्सएमएल प्रोसेसिंग लाइब्रेरी में काम करता है.

KML के साथ एक्सएमएल प्रोसेस करना

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

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

{7/} एक्सप्रेशन

X {0/} के बारे में अच्छी तरह जानने से, बेहतर पार्सिंग स्कीम डेवलप करने में मदद मिलती है. यह सेक्शन इस बात पर फ़ोकस करेगा कि किसी एक्सएमएल दस्तावेज़ के एलिमेंट को X मुफ़्त में कैसे इस्तेमाल किया जाता है. इससे, आपको कई एलिमेंट को ठीक करने और जटिल क्वेरी बनाने में मदद मिलेगी.

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

हम अपने उदाहरणों को दिखाने के लिए, इस ऐब्स्ट्रैक्ट एक्सएमएल का इस्तेमाल करेंगे:

<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>

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

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

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

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

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

डिफ़ॉल्ट रूप से, एक्स पाथ एक्सप्रेशन सभी एलिमेंट से मेल खाते हैं. एक्सप्रेशन को किसी खास एलिमेंट से मैच करने से रोका जा सकता है. इसके लिए, आपको स्क्वेयर ब्रैकेट ([]) में एक predicate लगानी होगी. उदाहरण के लिए, यह एक्सप्रेशन /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

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

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

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

एक्सएमएल दस्तावेज़ में मौजूद टेक्स्ट को टेक्स्ट नोड ऑपरेटर के ज़रिए X फ़ाइल एक्सप्रेशन में शामिल किया जाता है. यह ऑपरेटर "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 W3C स्पेसिफ़िकेशन देखें.

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

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

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

एक्स पाथ एक्सप्रेशन का मूल्यांकन करते समय, पक्का करें कि आप लौटाए जा सकने वाले किसी भी संभावित "नोड सेट" पर बार-बार इस्तेमाल करें. ये नतीजे, Java कोड में डीओएम नोड के तौर पर दिखाए जाते हैं. इसलिए, आपको किसी 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");
    }
  }
}