Λίστα περιοχών κάλυψης μιας χώρας

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