US-Bundesstaaten oder kanadische Provinzen mit verfügbaren Rufnummern auflisten

Mit diesem optionalen Schritt können Sie die Suche für die Vereinigten Staaten oder Kanada auf einen Bundesstaat oder eine Provinz eingrenzen. Nur US und CA werden akzeptiert.

• Jeder Eintrag beschreibt die zum Zeitpunkt der Anfrage verfügbaren Rufnummernpräfixe des jeweiligen Bundesstaats bzw. der jeweiligen Provinz.
• Folgen Sie next_function für eine Liste der Gebiete des Bundesstaats bzw. der Provinz. Der Link enthält bereits den Filter state, jedoch nicht pid.
• Bei der Gebietssuche werden Angaben zum Bundesstaat bzw. zur Provinz etwas anders abgeglichen. Wenn der Link für einen Bundesstaat oder eine Provinz unter next_function das Ergebnis No areas found zurückgibt, rufen Sie stattdessen getareas ohne Angabe eines Bundesstaats bzw. einer Provinz auf.
• Prüfen Sie status.code vor dem Auslesen von response. Für ein nicht unterstütztes Land oder ein Land ohne passenden Bestand wird der Code 404 ohne entsprechenden HTTP-Status zurückgegeben.
• Eine leere Liste mit dem Code 200 bedeutet, dass Bestand vorhanden ist, jedoch keine Angaben zum Bundesstaat bzw. zur Provinz vorliegen. Rufen Sie getareas ohne Angabe eines Bundesstaats bzw. einer Provinz auf.

Anfrage

Erforderlich: HTTP-Basic-Authentifizierung oder Bearer-Token (siehe Authentifizierung und API-Antworten). Bei fehlgeschlagener Authentifizierung wird vor Ausführung der Abfrage mit HTTP 401 geantwortet.

GET mit isocode im Pfad. Wird das Pfadsegment weggelassen, wird stattdessen ein formularcodiertes Feld isocode ausgelesen. Der optionale Parameter pid wird in der Abfragezeichenfolge übermittelt.

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

Antwort

Standardmäßige Antwortstruktur. Bei Erfolg ist status.code 200, status.msg ist leer und status.results enthält die Anzahl der Einträge. response ist eine Liste, die nach name (ohne Unterscheidung von Groß- und Kleinschreibung) und anschließend nach dem Code in state sortiert ist. Felder: state (Code des Bundesstaats oder der Provinz aus den entsprechenden Angaben der Präfixe, normalerweise zwei Buchstaben; ungewöhnliche Werte werden unverändert weitergegeben); name (Name aus dem Katalog oder der Code, wenn der Katalog dafür keinen Namen enthält); country_iso; available (Gesamtbestand aller gezählten Präfixe, immer größer als 0); prefix_count (Anzahl der gezählten Präfixe mit verfügbarem Bestand); is_mobile (1, wenn mindestens eines der gezählten Präfixe Mobilfunk unterstützt; für US immer 0, es sei denn, Ihr Konto ist für US-Mobilfunknummern freigeschaltet); sms_coverage (1, wenn mindestens eines der gezählten Präfixe SMS-Abdeckung bietet); returns_numbers (1, wenn bei mindestens einem der gezählten Präfixe das Kennzeichen für die Rückgabe von Rufnummern gesetzt ist oder dafür kein Wert vorliegt); next_function ('v3/getareas/{isocode}?state={state}'). Wenn Präfixe mit verfügbarem Bestand vorhanden sind, aber keines Angaben zum Bundesstaat bzw. zur Provinz enthält, ist das Ergebnis status.code 200 mit einer leeren Liste und status.results 0.

Beispiel zur Veranschaulichung der Antwortstruktur; keine aktuellen Kontodaten und kein aktuelles Preisangebot.

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

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; lesen Sie status.code aus.
• 404: msg 'getstates is only available for US and CA': bei jedem anderen Ländercode. Es wird kein entsprechender HTTP-Status gesetzt.
• 404: msg 'No states found': Keine Präfixe mit verfügbarem Bestand entsprechen den Länder- und Quellenfiltern. Es wird kein entsprechender HTTP-Status gesetzt.
• 401: Die Authentifizierung fehlt oder ist fehlgeschlagen. Wird mit dem HTTP-Status 401 gesendet.

Verfügbarkeit und Auswirkungen

• Reine Abfrage. Sie reserviert, bestellt oder ändert nichts. available dient nur zur Information und reserviert keine Rufnummern.