Elenca gli stati degli Stati Uniti o le province canadesi con numeri disponibili

Usa questo passaggio facoltativo per gli Stati Uniti o il Canada per restringere la ricerca a uno stato o a una provincia. Sono accettati solo US e CA.

• Ogni voce descrive i prefissi disponibili per quello stato al momento della richiesta.
• Segui next_function per elencare le aree dello stato. Include già il filtro state ma non pid.
• La ricerca delle aree usa criteri di corrispondenza leggermente diversi per le informazioni sullo stato. Se, per uno stato, next_function restituisce No areas found, chiama getareas senza specificare uno stato.
• Controlla status.code prima di leggere response. Un paese non supportato, oppure un paese senza disponibilità corrispondente ai criteri, restituisce il codice 404 senza uno stato HTTP corrispondente.
• Un elenco vuoto con codice 200 indica che esiste disponibilità, ma senza informazioni sullo stato. Chiama getareas senza specificare uno stato.

Richiesta

Obbligatorio: autenticazione HTTP Basic o token Bearer (vedi Autenticazione e risposte API). Se l'autenticazione non riesce, viene restituita una risposta HTTP 401 prima di eseguire la ricerca.

GET con isocode nel percorso. Se il segmento del percorso viene omesso, viene invece letto un campo isocode codificato come dati di modulo. Il parametro facoltativo pid viene inviato nella stringa di query.

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

Risposta

Struttura standard della risposta. In caso di successo, status.code è 200, status.msg è vuoto e status.results è il numero di voci. response è un elenco ordinato per name (senza distinzione tra maiuscole e minuscole), poi per il codice state. Campi: state (codice dello stato o della provincia ricavato dai dati sullo stato dei prefissi, normalmente di due lettere; i valori insoliti vengono restituiti senza modifiche); name (nome nel catalogo, oppure il codice se il catalogo non contiene un nome corrispondente); country_iso; available (disponibilità totale per tutti i prefissi conteggiati, sempre maggiore di 0); prefix_count (numero di prefissi disponibili conteggiati); is_mobile (1 se almeno un prefisso conteggiato supporta la telefonia mobile; sempre 0 per US, a meno che il tuo account non sia abilitato ai numeri mobili degli Stati Uniti); sms_coverage (1 se almeno un prefisso conteggiato ha copertura SMS); returns_numbers (1 se almeno un prefisso conteggiato ha l'indicatore di restituzione dei numeri attivo oppure non ha un valore per tale indicatore); next_function ('v3/getareas/{isocode}?state={state}'). Se esistono prefissi disponibili ma nessuno contiene informazioni sullo stato, il risultato è status.code 200 con un elenco vuoto e status.results 0.

Struttura della risposta a scopo illustrativo; non rappresenta dati dell'account in tempo reale né un preventivo attuale.

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

Errori

• 500: msg 'ISO Code parameter is required': isocode è assente o vuoto. Si tratta di un errore della richiesta che può essere corretto. Non viene impostato uno stato HTTP corrispondente; leggi status.code.
• 404: msg 'getstates is only available for US and CA': qualsiasi altro codice paese. Non viene impostato uno stato HTTP corrispondente.
• 404: msg 'No states found': nessun prefisso disponibile corrisponde ai filtri per paese e fonte. Non viene impostato uno stato HTTP corrispondente.
• 401: autenticazione assente o non riuscita. Inviato con stato HTTP 401.

Disponibilità ed effetti collaterali

• Solo consultazione. Non prenota, non ordina e non modifica nulla. available ha valore informativo e non blocca alcun numero.