ऑथेंटिकेशन

किसी पते से प्रतिदिन पहले 2,500 अनुरोधों के लिए कोई कुंजी नहीं चाहिए। कुंजी उसके बाद की हर चीज़ के लिए है: यह तय करती है कि कोई अनुरोध किसके क्रेडिट या पैकेज से लिया जाएगा और कौन सी मशीनें इसका उपयोग कर सकती हैं, और यह आपको उपयोग का इतिहास देती है। कुंजियाँ मुफ़्त हैं और पाने में एक मिनट लगता है।

बिना कुंजी के

बिना किसी क्रेडेंशियल के अनुरोध भेजें और उसका जवाब मिलेगा। इस तरह हर पते को प्रतिदिन 2,500 अनुरोध मिलते हैं, जो 00:00 UTC से हर एंडपॉइंट और हर ड्रॉप-इन होस्ट पर गिने जाते हैं, और डेटा व जवाब वही होते हैं जो भुगतान करने वाले खाते को मिलते हैं। उसके बाद API रीसेट तक Retry-After हेडर के साथ 429 quota_exceeded जवाब देता है; कोई शुल्क नहीं लगता और कुछ भी कतार में नहीं रखा जाता।

दो बातें जानने लायक हैं। एक ही नेटवर्क के पते एक ही कोटा साझा करते हैं, इसलिए कोई व्यस्त ऑफ़िस, कैंपस या एक क्लाउड रीजन इसे किसी अकेली मशीन से तेज़ी से खत्म कर सकता है। और एक नेटवर्क और उससे इस्तेमाल होने वाली कुंजियाँ एक ही कोटा से लेती हैं: बिना कुंजी के किए गए अनुरोध घटाते हैं कि उस नेटवर्क से इस्तेमाल होने वाली कुंजी को आज कितना मिलेगा, और उस कुंजी पर किए गए मुफ़्त अनुरोध घटाते हैं कि नेटवर्क को बिना कुंजी के कितना मिलेगा। इसलिए साइन अप करने से क्रेडिट, पैकेज और इतिहास मिलते हैं, उसी जगह से दूसरे मुफ़्त 2,500 नहीं।

कुंजी पाना

www.mygeocode.com/signup पर अपने नाम, एक ईमेल पते और एक पासवर्ड के साथ साइन अप करें। आपकी पहली कुंजी उसी समय एक बार दिखाई जाती है; इसे कॉपी कर लें, क्योंकि केवल इसका हैश सहेजा जाता है। API कुंजियाँ के अंतर्गत जितनी चाहें उतनी और कुंजियाँ बनाएँ, हर एक को एक लेबल दें (हर सर्वर या हर एप्लिकेशन के लिए एक कुंजी अच्छी आदत है), और किसी भी कुंजी को कभी भी रद्द करें।

हर कुंजी के प्रतिदिन 2,500 मुफ़्त अनुरोध होते हैं, जो 00:00 UTC से हर एंडपॉइंट और हर ड्रॉप-इन होस्ट पर गिने जाते हैं। उसके बाद अनुरोध खाते के प्रीपेड क्रेडिट से €0.0001 प्रति अनुरोध की दर पर लिए जाते हैं, जब तक कि कुंजी किसी Unlimited पैकेज की न हो।

कुंजी भेजना

इनमें से कोई भी तरीका हर होस्ट पर काम करता है। हेडर को प्राथमिकता दें: क्वेरी स्ट्रिंग सर्वर लॉग, ब्राउज़र हिस्ट्री और प्रॉक्सी में पहुँच जाती हैं।

$ curl -H "X-API-Key: mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl -H "Authorization: Bearer mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_7f3c2a19e04b...d1"

$ curl -u "mg_7f3c2a19e04b...d1:" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

ड्रॉप-इन होस्ट पर कुंजी वहाँ भी जाती है जहाँ मूल प्रदाता की कुंजी जाती थी: Google, Bing, Geocode.Farm, OpenCage, LocationIQ, TomTom और MapQuest के लिए key; HERE और Geoapify के लिए apiKey; Mapbox के लिए access_token; Geocodio के लिए api_key; PositionStack और ipstack के लिए access_key; ipinfo के लिए token। Nominatim और Open-Elevation क्लाइंट key= या एक हेडर जोड़ते हैं, क्योंकि उन दोनों सेवाओं की अपनी कोई कुंजी नहीं होती।

क्वेरी पैरामीटर के अलावा, क्रेडेंशियल भेजने के चार तरीके हर होस्ट पर स्वीकार किए जाते हैं, ताकि जो क्लाइंट लाइब्रेरी प्रदाता के तरीके से ऑथेंटिकेट करती है उसमें कोई बदलाव न करना पड़े: X-API-Key हेडर, Authorization: Bearer, कुंजी को यूज़र नेम बनाकर HTTP Basic ऑथेंटिकेशन (जो curl -u KEY: भेजता है, और जिसका ipinfo के उदाहरण उपयोग करते हैं), और X-Goog-Api-Key हेडर जो Google के क्लाइंट भेजते हैं। जिन एंडपॉइंट पर POST किया जाता है, उनके लिए फ़ॉर्म बॉडी में रखी कुंजी भी पढ़ी जाती है। होस्ट नेम और कुंजी बदलना ही पूरा माइग्रेशन है।

दो तरह की कुंजियाँ

	उपयोग के अनुसार भुगतान वाली कुंजी	Unlimited कुंजी
यह कैसे मिलती है	डैशबोर्ड में बनाएँ, मुफ़्त	हर Unlimited पैकेज (€50 प्रति माह) के साथ आती है
मुफ़्त अनुरोध	प्रतिदिन 2,500	सभी
मुफ़्त कोटा से ऊपर	खाते के क्रेडिट से €0.0001 प्रति अनुरोध; बैलेंस खाली होने पर `402`	कुछ नहीं
IP स्लॉट (रोलिंग 24 घंटे)	2	3
जब पैकेज समाप्त हो जाए		कुंजी उपयोग के अनुसार भुगतान वाली कुंजी के रूप में काम करती रहती है

IP स्लॉट

एक कुंजी का उपयोग एक समय में सीमित संख्या में IP पतों से किया जा सकता है: उपयोग के अनुसार भुगतान वाली कुंजी के लिए दो, Unlimited कुंजी के लिए तीन। नियम रोलिंग है, हर पते के हिसाब से:

जब कोई पता पहली बार कुंजी का उपयोग करता है तो वह एक स्लॉट ले लेता है, और उस पहले अनुरोध से 24 घंटे तक उसे अपने पास रखता है।
जब वे 24 घंटे पूरे हो जाते हैं तो स्लॉट अपने आप खाली हो जाता है, चाहे बाकी पते कुछ भी कर रहे हों। अगर वही पता बाद में वापस आता है तो वह बस फिर से एक स्लॉट ले लेता है।
जब सभी स्लॉट घिरे हों तब किसी नए पते से आया अनुरोध 403 और कोड key_ip_limit के साथ अस्वीकार कर दिया जाता है। संदेश बताता है कि अगला स्लॉट कब खाली होगा। अस्वीकार किए गए अनुरोध गिने नहीं जाते।

तो अगर दो सर्वरों ने पहली बार किसी कुंजी का उपयोग 02:00 बजे किया और तीसरे ने 04:00 बजे, तो दो स्लॉट अगले दिन 02:00 बजे और तीसरा 04:00 बजे खाली होगा। डैशबोर्ड दिखाता है कि किसी कुंजी के स्लॉट किन पतों के पास हैं और हर एक कब खाली होगा। और मशीनें चाहिए? उपयोग के अनुसार भुगतान वाली और कुंजियाँ बनाएँ, या और Unlimited पैकेज जोड़ें; हर पैकेज अपनी कुंजी लाता है।

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

कुंजियाँ और ब्राउज़र

JavaScript या मोबाइल ऐप में कुंजी न रखें। कोई भी इसे पेज से पढ़ सकता है, और हर विज़िटर एक नया IP पता होता है, इसलिए दूसरे या तीसरे विज़िटर के बाद कुंजी के स्लॉट खत्म हो जाते हैं। API को अपने सर्वर से कॉल करें और कुंजी वहीं रखें। JavaScript मैप ड्रॉप-इन टाइल और लाइब्रेरी बिना कुंजी के लोड करते हैं; केवल उनकी जियोकोडिंग कॉल को आपके सर्वर से होकर जाना होता है।

रद्द करना और बदलना

डैशबोर्ड में कुंजी रद्द करें और वह एक मिनट के भीतर काम करना बंद कर देती है। पहले नई कुंजी बनाएँ, उसे डिप्लॉय करें, फिर पुरानी को रद्द करें; इस बीच दोनों काम करती हैं। कुंजियाँ अपने आप कभी समाप्त नहीं होतीं।

अस्वीकृतियाँ

HTTP	`code`	अर्थ
401	`missing_key`	कोई कुंजी नहीं भेजी गई और इस सर्वर पर बिना कुंजी वाला एक्सेस बंद है (डिफ़ॉल्ट रूप से यह चालू रहता है)।
429	`quota_exceeded`	पते ने बिना कुंजी के आज का अपना मुफ़्त कोटा इस्तेमाल कर लिया है; `Retry-After` बताता है कि रीसेट में कितना समय बाकी है।
401	`invalid_key`	कुंजी मौजूद नहीं है।
401	`key_revoked`	कुंजी रद्द कर दी गई थी।
402	`no_credits`	आज का मुफ़्त कोटा इस्तेमाल हो चुका है और खाते का बैलेंस खाली है।
403	`key_ip_limit`	कुंजी के सभी IP स्लॉट दूसरे पतों के पास हैं।
403	`account_suspended`	खाता निलंबित है; सपोर्ट से संपर्क करें।

इनमें से कोई भी कोटा में नहीं गिना जाता और न ही क्रेडिट खर्च करता है। ड्रॉप-इन होस्ट पर इन्हें मूल प्रदाता के ढाँचे में बताया जाता है; संगतता देखें।