Λίστα πολιτειών των ΗΠΑ ή επαρχιών του Καναδά με διαθέσιμους αριθμούς

Χρησιμοποιήστε αυτό το προαιρετικό βήμα για τις Ηνωμένες Πολιτείες ή τον Καναδά, ώστε να περιορίσετε την αναζήτηση ανά πολιτεία ή επαρχία. Γίνονται δεκτά μόνο τα 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 έχει πληροφοριακό χαρακτήρα και δεν δεσμεύει αριθμούς.