دستیاب نمبروں والی امریکی ریاستوں یا کینیڈین صوبوں کی فہرست حاصل کریں

امریکہ یا کینیڈا کے لیے تلاش کو ریاست یا صوبے تک محدود کرنے کے لیے یہ اختیاری مرحلہ استعمال کریں۔ صرف US اور CA قبول کیے جاتے ہیں۔

• ہر اندراج درخواست کے وقت اس ریاست کے لیے اسٹاک میں موجود نمبر پریفکس کی تفصیل دیتا ہے۔
• یہ لنک کھولیں: next_function۔ اس سے ریاست کے علاقوں کی فہرست ملتی ہے۔ اس میں پہلے ہی یہ فلٹر شامل ہے: state، لیکن یہ شامل نہیں ہے: pid۔
• علاقوں کی تلاش میں ریاست کی معلومات کا ملاپ قدرے مختلف انداز سے ہوتا ہے۔ اگر کسی ریاست کے اس لنک سے: next_function یہ نتیجہ ملے: No areas found، تو اس کے بجائے یہ فنکشن کال کریں: getareas، اور ریاست مت بتائیں۔
• اس کی جانچ کریں: status.code، پھر یہ پڑھیں: response۔ غیر معاون ملک یا ایسے ملک کے لیے جس کا کوئی مماثل اسٹاک نہیں ہے، یہ کوڈ لوٹایا جاتا ہے: 404، مگر اس کے مطابق HTTP اسٹیٹس نہیں دیا جاتا۔
• خالی فہرست کے ساتھ یہ کوڈ: 200 اس بات کی نشاندہی کرتا ہے کہ اسٹاک موجود ہے مگر اس میں ریاست کی معلومات نہیں ہیں۔ یہ فنکشن کال کریں: getareas، اور ریاست مت بتائیں۔

درخواست

لازمی: HTTP Basic توثیق یا Bearer ٹوکن (توثیق اور API کے جوابات دیکھیں)۔ توثیق ناکام ہونے پر تلاش چلنے سے پہلے HTTP 401 کے ساتھ جواب دیا جاتا ہے۔

GET درخواست میں isocode پاتھ میں دیا جاتا ہے۔ اگر پاتھ کا یہ حصہ نہ دیا جائے تو اس کے بجائے فارم انکوڈ شدہ isocode فیلڈ پڑھی جاتی ہے۔ اختیاری pid کوئری اسٹرنگ میں بھیجا جاتا ہے۔

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getstates/US'

جواب

جواب کا معیاری لفافہ۔ کامیابی پر status.code کی قدر 200 ہوتی ہے، status.msg خالی ہوتا ہے، اور status.results اندراجات کی تعداد ہوتی ہے۔ response ایک فہرست ہے جو پہلے name کے لحاظ سے (بڑے اور چھوٹے حروف کے فرق کے بغیر)، پھر state کے کوڈ کے لحاظ سے ترتیب دی جاتی ہے۔ فیلڈز: state (ریاست یا صوبے کا کوڈ جو پریفکس کے ریاست سے متعلق ڈیٹا سے لیا جاتا ہے، عموماً دو حروف؛ غیر معمولی قدریں بغیر تبدیلی کے آگے بھیج دی جاتی ہیں)؛ name (کیٹلاگ میں درج نام، یا اگر کیٹلاگ میں اس کا نام نہ ہو تو کوڈ)؛ country_iso؛ available (شمار کیے گئے تمام پریفکس کا کل اسٹاک، جو ہمیشہ 0 سے زیادہ ہوتا ہے)؛ prefix_count (اسٹاک میں موجود شمار کیے گئے پریفکس کی تعداد)؛ is_mobile (اگر شمار کیے گئے کسی بھی پریفکس میں موبائل کی صلاحیت ہو تو 1؛ US کے لیے ہمیشہ 0، الا یہ کہ آپ کے اکاؤنٹ میں امریکی موبائل نمبروں کی سہولت فعال ہو)؛ sms_coverage (اگر شمار کیے گئے کسی بھی پریفکس کو SMS کوریج حاصل ہو تو 1)؛ returns_numbers (اگر شمار کیے گئے کسی بھی پریفکس پر نمبر واپس کرنے کا فلیگ موجود ہو یا اس فلیگ کی کوئی قدر نہ ہو تو 1)؛ next_function ('v3/getareas/{isocode}?state={state}')۔ اگر پریفکس اسٹاک میں موجود ہوں لیکن کسی میں بھی ریاست کی معلومات نہ ہوں تو نتیجے میں status.code کی قدر 200، فہرست خالی، اور status.results کی قدر 0 ہوتی ہے۔

جواب کی ساخت کی مثالی صورت؛ یہ اکاؤنٹ کا براہ راست ڈیٹا یا موجودہ قیمت کی پیشکش نہیں ہے۔

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 2
  },
  "response": [
    {
      "state": "NY",
      "name": "New York",
      "country_iso": "US",
      "available": 120,
      "prefix_count": 8,
      "is_mobile": 0,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=NY"
    },
    {
      "state": "TX",
      "name": "Texas",
      "country_iso": "US",
      "available": 45,
      "prefix_count": 3,
      "is_mobile": 0,
      "sms_coverage": 0,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=TX"
    }
  ]
}

خرابیاں

• 500: msg 'ISO Code parameter is required': isocode موجود نہیں یا خالی ہے۔ یہ درخواست کی ایسی خرابی ہے جسے درست کیا جا سکتا ہے۔ اس کے مطابق HTTP اسٹیٹس مقرر نہیں کیا جاتا؛ status.code پڑھیں۔
• 404: msg 'getstates is only available for US and CA': کسی بھی دوسرے ملک کا کوڈ۔ اس کے مطابق HTTP اسٹیٹس مقرر نہیں کیا جاتا۔
• 404: msg 'No states found': اسٹاک میں موجود کوئی پریفکس ملک اور ماخذ کے فلٹرز سے مطابقت نہیں رکھتا۔ اس کے مطابق HTTP اسٹیٹس مقرر نہیں کیا جاتا۔
• 401: توثیق موجود نہیں یا ناکام ہو گئی ہے۔ HTTP اسٹیٹس 401 کے ساتھ بھیجا جاتا ہے۔

دستیابی اور ضمنی اثرات

• صرف تلاش کی کارروائی ہے۔ یہ کوئی چیز محفوظ یا آرڈر نہیں کرتی اور نہ ہی کسی چیز کو تبدیل کرتی ہے۔ available صرف معلومات کے لیے ہے اور نمبروں کو روک کر نہیں رکھتا۔