Elencare le aree di copertura di un paese

Dopo aver scelto un paese (e, per gli Stati Uniti o il Canada, facoltativamente uno stato tramite getstates), chiama getareas per vedere dove vengono offerti i numeri. Conserva l'identificativo dell'area uuid per il passaggio successivo.

Ogni area conduce a uno dei due passaggi successivi:

• available > 0: next_function è v3/getprefixes/{uuid}, con ?state= aggiunto se hai applicato un filtro per stato. Usalo per consultare i prefissi.
• available = 0: l'area ha prefissi ma nessun numero disponibile, e next_function è v3/order/{uuid}. Consulta la documentazione sugli ordini per conoscere i requisiti di questo passaggio.

available è il totale dell'intera area, anche quando applichi un filtro per stato. Il filtro per stato accetta un codice o un nome completo, ma funziona solo per US e CA. Se un filtro per stato restituisce No areas found, riprova senza il filtro. I controlli vengono eseguiti in questo ordine: codice paese mancante, paese sconosciuto, filtro per stato applicato a un altro paese, stato non valido, nessuna area corrispondente. Ciascuno di questi casi restituisce il codice 500 o 404 in status.code, senza uno stato HTTP corrispondente.

Richiesta

Obbligatorio: autenticazione HTTP Basic o token Bearer (vedi Autenticazione e risposte API). In caso di autenticazione non riuscita, viene restituita una risposta HTTP 401 prima dell'esecuzione della ricerca.

GET con isocode nel percorso e i parametri facoltativi state e pid nella stringa di query. Se il segmento del percorso viene omesso, viene invece letto un campo isocode codificato come dato di modulo.

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'

Risposta

Struttura contenitore standard. In caso di successo, status.code è 200, status.msg è 'Results: N', status.results è N e response è un elenco ordinato per nome dell'area. Campi: uuid (identificativo opaco dell'area usato nel passaggio successivo); country_uuid (identificativo opaco del paese di 32 caratteri, non necessario in seguito); name; area_type e number_type (descrittori di catalogo; le voci non rappresentano necessariamente tipi di numeri locali); country_iso; is_mobile (0 o 1, ricavato dagli indicatori di telefonia mobile dell'area; sempre 0 per US, a meno che il tuo account non sia abilitato per i numeri mobili di US); available (totale dei numeri disponibili per tutti i prefissi corrispondenti dell'area, non limitato allo stato richiesto); sms_coverage (0 o 1); returns_numbers (0 o 1, il valore più alto dell'indicatore tra i prefissi dell'area); latitude e longitude; state_iso; next_function. state_iso: con un filtro per stato, è il codice risultante dalla risoluzione del filtro. Per US e CA senza filtro, è lo stato il cui nome coincide con quello dell'area; in alternativa, è il valore memorizzato per l'area e, in mancanza di questo, un codice ricavato dai dati dei prefissi dell'area. Per gli altri paesi, è il valore memorizzato e può essere vuoto. next_function è 'v3/getprefixes/{uuid}' (con l'aggiunta di '?state={code}' quando viene applicato il filtro) se available è maggiore di 0, altrimenti è 'v3/order/{uuid}'. Le aree prive di qualsiasi prefisso corrispondente vengono omesse. Le aree con prefissi ma senza numeri disponibili vengono restituite con available pari a 0.

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

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

Errori

• 500: msg 'ISO Code parameter is required': isocode è mancante o vuoto. Si tratta di un errore della richiesta che può essere corretto. Non viene impostato uno stato HTTP corrispondente.
• 404: msg 'Error: no such country': il codice paese è sconosciuto. Non viene impostato uno stato HTTP corrispondente.
• 404: msg 'State filter is only available for US and CA': è stato inviato un valore non vuoto di state per un altro paese. Non viene impostato uno stato HTTP corrispondente.
• 404: msg 'Invalid state': state non è né un codice né un nome noto per il paese. Non viene impostato uno stato HTTP corrispondente.
• 404: msg 'No areas found': nessuna area corrisponde ai filtri per paese, fonte e stato. Non viene impostato uno stato HTTP corrispondente.
• 401: autenticazione mancante o non riuscita. Inviato con stato HTTP 401.

Disponibilità ed effetti collaterali

• Sola consultazione, riservata agli account cliente. Non prenota, non ordina e non modifica nulla.
• available ha valore informativo e può cambiare prima del passaggio successivo.