کسی ملک کے کوریج والے علاقوں کی فہرست حاصل کریں

ملک منتخب کرنے کے بعد (اور امریکہ یا کینیڈا کے لیے، چاہیں تو ریاست منتخب کرنے کے لیے 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 صرف معلومات کے لیے ہے اور اگلے مرحلے سے پہلے بدل سکتی ہے۔