दस्तावेज़

हर चीज़ क्वेरी पैरामीटर के साथ https://api.mygeocode.com/v1/ पर एक GET अनुरोध है, जिसका जवाब JSON में मिलता है। यह पेज उन हिस्सों को बताता है जो हर एंडपॉइंट में साझा हैं। एंडपॉइंट पेज हर एंडपॉइंट के पैरामीटर और फ़ील्ड बताते हैं।

आपका पहला अनुरोध

किसी पते से प्रतिदिन पहले 2,500 अनुरोधों के लिए कोई कुंजी नहीं चाहिए। किसी भी मशीन से:

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

वह अनुरोध उन 2,500 मुफ़्त अनुरोधों में से 1 के रूप में गिना गया जो आपके पते को आज मिलते हैं। कुंजी के साथ यह कुंजी के खाते में गिना जाता, और हेडर में आपके क्रेडिट और IP स्लॉट के आँकड़े भी जुड़ जाते। रिस्पॉन्स हेडर बताते हैं कि आप कहाँ खड़े हैं:

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

किसी दूसरे प्रदाता से आ रहे हैं?

हो सकता है आपको इस पेज के बाकी हिस्से की ज़रूरत न हो। अगर आपका कोड पहले से Google Maps, Bing Maps, HERE, Mapbox, Geocode.Farm, Nominatim, OpenCage, LocationIQ, Geoapify, TomTom, MapQuest, Geocodio, PositionStack, ip-api, ipinfo, ipstack या Open-Elevation से बात करता है, तो हम एक ऐसा होस्ट चलाते हैं जो उस प्रदाता का अनुरोध और रिस्पॉन्स फ़ॉर्मैट बोलता है और उसके पीछे हमारा डेटा होता है। होस्टनेम बदलें, अपनी कुंजी वहाँ रखें जहाँ पुरानी कुंजी जाती थी, और अपना पार्सिंग कोड वैसा ही रखें। यही बात Google Maps JavaScript API, Bing Maps V8, HERE Maps for JavaScript, MapQuest.js, और MapLibre, Mapbox GL और Leaflet जियोकोडर प्लगइन पर भी लागू होती है।

• Google Maps
• Bing Maps
• HERE
• Mapbox
• Geocode.Farm
• Nominatim
• OpenCage
• LocationIQ
• Geoapify
• TomTom
• MapQuest
• Geocodio
• PositionStack
• ip-api
• ipinfo
• ipstack
• Open-Elevation
• JavaScript मैप लाइब्रेरी

ड्रॉप-इन कैसे काम करते हैं: पूरी होस्ट सूची, कुंजी मैपिंग, त्रुटि मैपिंग और माइग्रेशन चेकलिस्ट।

बेस URL और एंडपॉइंट

केवल HTTPS उपलब्ध है। सादे HTTP अनुरोध रीडायरेक्ट करने के बजाय 400 के साथ अस्वीकार कर दिए जाते हैं, ताकि कोई कुंजी गलती से कभी बिना एन्क्रिप्शन के न भेजी जाए। HTTP/2 और HTTP/3 समर्थित हैं। जब क्लाइंट gzip या br स्वीकार करता है, तो रिस्पॉन्स कंप्रेस करके भेजे जाते हैं।

रिस्पॉन्स एनवेलप

हर रिस्पॉन्स एक JSON ऑब्जेक्ट है जिसका status ok या error होता है।

• ok होने पर पेलोड आगे आता है: जो एंडपॉइंट कई मिलान लौटा सकते हैं उनके लिए results (एक array), रिवर्स जियोकोडिंग के लिए result (एक ऑब्जेक्ट या null), और IP तथा समय क्षेत्र लुकअप के लिए सपाट फ़ील्ड।
• error होने पर एक error ऑब्जेक्ट होता है जिसमें एक code स्ट्रिंग, एक message वाक्य और, जहाँ प्रासंगिक हो, वह param होता है जिसके कारण त्रुटि हुई। HTTP स्टेटस भी उसी के अनुरूप होता है। त्रुटियाँ देखें।

जो क्वेरी मान्य है लेकिन किसी से मेल नहीं खाती, वह खाली results array या null result के साथ ok होती है। यह त्रुटि नहीं है, और यह एक अनुरोध के रूप में गिनी जाती है।

पैरामीटर जो हर एंडपॉइंट स्वीकार करता है

पैरामीटर के नाम केस-सेंसिटिव हैं और छोटे अक्षरों में होते हैं। अज्ञात पैरामीटर अनदेखे किए जाते हैं, और खाली पैरामीटर को अनुपस्थित माना जाता है, ताकि कोई HTML फ़ॉर्म वैकल्पिक फ़ील्ड खाली भेज सके। निर्देशांक दशमलव डिग्री में होते हैं; lat -90 से 90 तक और lon -180 से 180 तक। टेक्स्ट UTF-8 में होता है और उसे URL-एनकोड किया जाना चाहिए।

ऑथेंटिकेशन एक पैराग्राफ़ में

कुंजी वैकल्पिक है: हर पते को बिना कुंजी के प्रतिदिन 2,500 मुफ़्त अनुरोध मिलते हैं। कुंजी X-API-Key हेडर, Authorization: Bearer टोकन या key पैरामीटर के रूप में भेजी जाती है; कुंजियाँ मुफ़्त हैं, और खाते के लिए आपका नाम, एक ईमेल पता और एक पासवर्ड चाहिए। हर कुंजी के अपने प्रतिदिन 2,500 मुफ़्त अनुरोध होते हैं; उसके बाद अनुरोध खाते के प्रीपेड क्रेडिट से €0.0001 प्रति अनुरोध की दर पर लिए जाते हैं, या Unlimited पैकेज (€50 प्रति माह) की कुंजी पर मुफ़्त होते हैं। एक ही नेटवर्क से बिना कुंजी वाले अनुरोध और कुंजी वाले अनुरोध एक ही दैनिक कोटा साझा करते हैं। उपयोग के अनुसार भुगतान वाली कुंजी हर रोलिंग 24 घंटों में दो IP पतों से काम करती है, Unlimited कुंजी तीन से। पूरे नियम ऑथेंटिकेशन पेज पर हैं।

कोटा हेडर

ब्राउज़र से कॉल करना

हर एंडपॉइंट पर CORS चालू है और कोटा हेडर उपलब्ध कराए जाते हैं, लेकिन पेज के सोर्स में रखी कुंजी सार्वजनिक होती है और कुछ ही विज़िटर के बाद उसके IP स्लॉट खत्म हो जाएँगे। कॉल अपने सर्वर से करें; कुंजियाँ और ब्राउज़र देखें।

वर्ज़निंग

पाथ प्रीफ़िक्स /v1/ ही वर्ज़न है। किसी वर्ज़न के भीतर हम फ़ील्ड और पैरामीटर जोड़ते हैं, लेकिन उन्हें कभी हटाते या उनका नाम नहीं बदलते, और किसी मौजूदा फ़ील्ड का अर्थ कभी नहीं बदलते। अगर कभी हमें कुछ तोड़ना पड़ा, तो वह /v2/ में जाएगा और /v1/ घोषणा के बाद कम से कम छह महीने तक काम करता रहेगा। नई चीज़ों की घोषणा ब्लॉग के समाचार सेक्शन में की जाती है।

आपके JSON पार्सर को उन फ़ील्ड को अनदेखा करना चाहिए जिन्हें वह नहीं जानता। आगे की संगतता के लिए बस यही एक ज़रूरत है।