Abdeckungsgebiete eines Landes auflisten

Nachdem Sie ein Land ausgewählt haben (und für die USA oder Kanada optional einen Bundesstaat oder eine Provinz aus getstates), rufen Sie getareas auf, um zu sehen, wo Rufnummern angeboten werden. Merken Sie sich die Gebietskennung uuid für den nächsten Schritt.

Für jedes Gebiet folgt einer von zwei nächsten Schritten:

• available > 0: next_function ist v3/getprefixes/{uuid}, wobei ?state= angehängt wird, wenn Sie nach Bundesstaat oder Provinz gefiltert haben. Verwenden Sie diesen Aufruf, um die Präfixe zu durchsuchen.
• available = 0: Das Gebiet hat Präfixe, aber keinen Bestand, und next_function ist v3/order/{uuid}. Die Voraussetzungen für diesen Schritt finden Sie in der Bestelldokumentation.

available ist der Gesamtbestand des Gebiets, auch wenn Sie nach Bundesstaat oder Provinz filtern. Der Bundesstaaten- oder Provinzfilter akzeptiert einen Code oder einen vollständigen Namen, funktioniert jedoch nur für US und CA. Wenn eine Abfrage mit diesem Filter No areas found zurückgibt, versuchen Sie es erneut ohne den Filter. Die Prüfungen erfolgen in dieser Reihenfolge: fehlender Ländercode, unbekanntes Land, Bundesstaaten- oder Provinzfilter für ein anderes Land, ungültiger Bundesstaat oder ungültige Provinz, keine passenden Gebiete. In jedem dieser Fälle wird der Code 500 oder 404 in status.code, ohne entsprechenden HTTP-Status, zurückgegeben.

Anfrage

Erforderlich: HTTP Basic oder ein Bearer-Token (siehe Authentifizierung und API-Antworten). Eine fehlgeschlagene Authentifizierung wird mit HTTP 401 beantwortet, bevor die Abfrage ausgeführt wird.

GET mit isocode im Pfad und den optionalen Parametern state und pid im Querystring. Wenn das Pfadsegment fehlt, wird stattdessen ein formularcodiertes Feld isocode ausgelesen.

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'

Antwort

Standard-Antwortstruktur. Bei Erfolg ist status.code gleich 200, status.msg gleich 'Results: N', status.results gleich N und response eine nach Gebietsnamen sortierte Liste. Felder: uuid (opake Gebietskennung, die im nächsten Schritt verwendet wird); country_uuid (opake 32-stellige Länderkennung, die später nicht benötigt wird); name; area_type und number_type (Katalogbeschreibungen; die Einträge sind nicht zwangsläufig Ortsrufnummerntypen); country_iso; is_mobile (0 oder 1, aus den Mobilfunkkennzeichen des Gebiets; für US immer 0, sofern Ihr Konto nicht für Mobilfunknummern aus US freigeschaltet ist); available (Gesamtbestand aller passenden Präfixe des Gebiets, nicht auf den angefragten Bundesstaat oder die angefragte Provinz beschränkt); sms_coverage (0 oder 1); returns_numbers (0 oder 1, der höchste Kennzeichenwert unter den Präfixen des Gebiets); latitude und longitude; state_iso; next_function. state_iso: Bei Verwendung eines Bundesstaaten- oder Provinzfilters ist dies der aufgelöste Filtercode. Für US und CA ohne Filter ist dies der Bundesstaat oder die Provinz, dessen beziehungsweise deren Name mit dem Gebietsnamen übereinstimmt, andernfalls der für das Gebiet gespeicherte Wert, andernfalls ein aus den Präfixdaten des Gebiets abgeleiteter Code. Für andere Länder ist es der gespeicherte Wert, der auch leer sein kann. next_function ist 'v3/getprefixes/{uuid}' (bei Verwendung eines Filters ergänzt um '?state={code}'), wenn available größer als 0 ist, andernfalls 'v3/order/{uuid}'. Gebiete ohne jegliches passendes Präfix werden ausgelassen. Gebiete mit Präfixen, aber ohne Bestand werden mit available 0 zurückgegeben.

Beispielhafte Antwortstruktur; keine aktuellen Kontodaten und kein aktuelles Preisangebot.

{
  "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"
    }
  ]
}

Fehler

• 500: msg 'ISO Code parameter is required': isocode fehlt oder ist leer. Dies ist ein korrigierbarer Fehler in der Anfrage. Es wird kein entsprechender HTTP-Status gesetzt.
• 404: msg 'Error: no such country': Der Ländercode ist unbekannt. Es wird kein entsprechender HTTP-Status gesetzt.
• 404: msg 'State filter is only available for US and CA': Für ein anderes Land wurde ein nicht leerer Wert für state gesendet. Es wird kein entsprechender HTTP-Status gesetzt.
• 404: msg 'Invalid state': state ist weder ein bekannter Code noch ein bekannter Name für das Land. Es wird kein entsprechender HTTP-Status gesetzt.
• 404: msg 'No areas found': Kein Gebiet entspricht den Filtern für Land, Quelle und Bundesstaat oder Provinz. Es wird kein entsprechender HTTP-Status gesetzt.
• 401: Die Authentifizierung fehlt oder ist fehlgeschlagen. Wird mit HTTP-Status 401 gesendet.

Verfügbarkeit und Nebenwirkungen

• Reine Abfrage für Kundenkonten. Es wird nichts reserviert, bestellt oder geändert.
• available dient der Information und kann sich vor dem nächsten Schritt ändern.