किसी देश के कवरेज क्षेत्रों की सूची प्राप्त करें

देश चुनने के बाद (और अमेरिका या कनाडा के लिए, चाहें तो getstates से राज्य चुनने के बाद), getareas को कॉल करके देखें कि किन क्षेत्रों में नंबर उपलब्ध कराए जाते हैं। क्षेत्र का uuid अगले चरण के लिए सँभालकर रखें।

हर क्षेत्र के लिए अगले दो चरणों में से एक लागू होता है:

• available > 0: next_function का मान है v3/getprefixes/{uuid}, जिसके अंत में ?state= जोड़ा जाता है यदि आपने राज्य के आधार पर फ़िल्टर किया हो। इसका उपयोग प्रीफ़िक्स देखने के लिए करें।
• available = 0: क्षेत्र में प्रीफ़िक्स हैं लेकिन स्टॉक नहीं है, और next_function का मान है v3/order/{uuid}। इस चरण की आवश्यकताओं के लिए ऑर्डर देने संबंधी दस्तावेज़ देखें।

available पूरे क्षेत्र का कुल मान है, तब भी जब आप राज्य के आधार पर फ़िल्टर करते हैं। राज्य फ़िल्टर कोड या पूरा नाम स्वीकार करता है, लेकिन केवल US और CA के लिए काम करता है। यदि राज्य फ़िल्टर लगाने पर No areas found मिलता है, तो फ़िल्टर हटाकर फिर प्रयास करें। जाँचें इस क्रम में होती हैं: देश का कोड न होना, अज्ञात देश, किसी अन्य देश के लिए राज्य फ़िल्टर, अमान्य राज्य, कोई मेल खाता क्षेत्र न होना। इनमें से हर स्थिति में लौटाया जाने वाला कोड है 500 या 404 और यह इस फ़ील्ड में मिलता है: status.code, लेकिन उसके अनुरूप HTTP स्थिति नहीं मिलती।

अनुरोध

आवश्यक: HTTP Basic या Bearer टोकन (प्रमाणीकरण और API प्रतिक्रियाएँ देखें)। प्रमाणीकरण विफल होने पर खोज चलने से पहले ही HTTP 401 के साथ जवाब दिया जाता है।

GET अनुरोध में पाथ में isocode और क्वेरी स्ट्रिंग में वैकल्पिक state तथा pid पैरामीटर भेजें। यदि पाथ का वह खंड नहीं दिया जाता, तो उसकी जगह फ़ॉर्म-एन्कोडेड isocode फ़ील्ड पढ़ी जाती है।

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

प्रतिक्रिया

मानक प्रतिक्रिया आवरण। सफलता पर status.code का मान 200, status.msg का मान 'Results: N', status.results का मान N होता है, और response क्षेत्र के नाम के क्रम में व्यवस्थित सूची होती है। फ़ील्ड: uuid (अगले चरण में इस्तेमाल होने वाला क्षेत्र पहचानकर्ता, जिसके आंतरिक अर्थ की व्याख्या नहीं करनी चाहिए); country_uuid (32-अक्षर वाला देश पहचानकर्ता, जिसके आंतरिक अर्थ की व्याख्या नहीं करनी चाहिए और जिसकी आगे आवश्यकता नहीं होती); name; area_type और number_type (कैटलॉग के विवरणक; प्रविष्टियाँ आवश्यक रूप से स्थानीय नंबर प्रकार की नहीं होतीं); country_iso; is_mobile (0 या 1, क्षेत्र के मोबाइल संकेतकों से लिया जाता है; US के लिए हमेशा 0 होता है, जब तक आपके खाते में US के मोबाइल नंबर सक्षम न हों); available (क्षेत्र के सभी मेल खाते प्रीफ़िक्स में कुल स्टॉक, जो अनुरोध में दिए गए राज्य तक सीमित नहीं होता); sms_coverage (0 या 1); returns_numbers (0 या 1, क्षेत्र के प्रीफ़िक्स में सबसे अधिक संकेतक मान); latitude और longitude; state_iso; next_function। state_iso: राज्य फ़िल्टर होने पर यह फ़िल्टर से निर्धारित राज्य कोड होता है। US और CA के लिए फ़िल्टर न होने पर यह उस राज्य का कोड होता है जिसका नाम क्षेत्र के नाम से मेल खाता है; ऐसा राज्य न मिलने पर क्षेत्र का संग्रहित मान, और वह भी न मिलने पर क्षेत्र के प्रीफ़िक्स डेटा से निकाला गया कोड होता है। अन्य देशों के लिए यह संग्रहित मान होता है और खाली भी हो सकता है। next_function का मान 'v3/getprefixes/{uuid}' (फ़िल्टर होने पर इसके साथ '?state={code}' जुड़ता है) होता है जब available का मान 0 से अधिक हो, अन्यथा 'v3/order/{uuid}' होता है। जिन क्षेत्रों में कोई भी मेल खाता प्रीफ़िक्स नहीं है, उन्हें छोड़ दिया जाता है। जिन क्षेत्रों में प्रीफ़िक्स हैं लेकिन स्टॉक नहीं है, उन्हें available के मान 0 के साथ लौटाया जाता है।

यह प्रतिक्रिया की संरचना का उदाहरण है; यह खाते का वास्तविक समय का डेटा या वर्तमान मूल्य प्रस्ताव नहीं है।

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

त्रुटियाँ

• 500: msg 'ISO Code parameter is required': isocode नहीं दिया गया है या खाली है। यह अनुरोध की ऐसी त्रुटि है जिसे सुधारा जा सकता है। इसके अनुरूप HTTP स्थिति सेट नहीं की जाती।
• 404: msg 'Error: no such country': देश का कोड अज्ञात है। इसके अनुरूप HTTP स्थिति सेट नहीं की जाती।
• 404: msg 'State filter is only available for US and CA': किसी अन्य देश के लिए state का गैर-खाली मान भेजा गया था। इसके अनुरूप HTTP स्थिति सेट नहीं की जाती।
• 404: msg 'Invalid state': state न तो उस देश का कोई ज्ञात राज्य कोड है और न ही कोई ज्ञात राज्य नाम। इसके अनुरूप HTTP स्थिति सेट नहीं की जाती।
• 404: msg 'No areas found': कोई भी क्षेत्र देश, स्रोत और राज्य के फ़िल्टरों से मेल नहीं खाता। इसके अनुरूप HTTP स्थिति सेट नहीं की जाती।
• 401: प्रमाणीकरण नहीं दिया गया है या विफल हो गया है। HTTP स्थिति 401 के साथ भेजा जाता है।

उपलब्धता और अन्य प्रभाव

• ग्राहक खातों के लिए केवल जानकारी खोजने की सुविधा। इससे कुछ भी आरक्षित नहीं होता, कोई ऑर्डर नहीं दिया जाता और कोई बदलाव नहीं होता।
• available केवल जानकारी के लिए है और अगले चरण से पहले बदल सकता है।