הצגת מדינות בארצות הברית או פרובינציות בקנדה עם מספרים במלאי

השתמשו בשלב האופציונלי הזה עבור ארצות הברית או קנדה כדי לצמצם את החיפוש לפי מדינה או פרובינציה. רק 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 אם קידומת כלשהי שנספרה תומכת במספרים ניידים; תמיד 0 עבור US, אלא אם החשבון שלכם מאופשר לשימוש במספרים ניידים בארצות הברית); sms_coverage (1 אם לקידומת כלשהי שנספרה יש כיסוי SMS); 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 מיועד למידע בלבד ואינו שומר מספרים.