Lista stanów USA lub prowincji Kanady z dostępnymi numerami

Ten opcjonalny krok pozwala zawęzić wyszukiwanie w Stanach Zjednoczonych lub Kanadzie do stanu lub prowincji. Akceptowane są tylko US i CA.

• Każdy wpis opisuje prefiksy z dostępnymi numerami w danym stanie lub prowincji w chwili wysłania żądania.
• Skorzystaj z odnośnika next_function, aby wyświetlić obszary danego stanu lub prowincji. Zawiera on już filtr state, ale nie zawiera pid.
• Wyszukiwanie obszarów dopasowuje informacje o stanie lub prowincji w nieco inny sposób. Jeśli odnośnik dla danego stanu lub prowincji w polu next_function zwraca No areas found, wywołaj zamiast tego getareas bez podawania stanu lub prowincji.
• Sprawdź status.code przed odczytaniem response. Nieobsługiwany kraj lub kraj bez pasujących dostępnych numerów powoduje zwrócenie kodu 404 bez odpowiadającego mu statusu HTTP.
• Pusta lista z kodem 200 oznacza, że numery są dostępne, ale nie mają informacji o stanie lub prowincji. Wywołaj getareas bez podawania stanu lub prowincji.

Żądanie

Wymagane: uwierzytelnianie HTTP Basic lub token Bearer (zobacz Uwierzytelnianie i odpowiedzi API). Nieudane uwierzytelnianie powoduje odpowiedź HTTP 401 przed wykonaniem wyszukiwania.

GET z isocode w ścieżce. Jeśli segment ścieżki zostanie pominięty, zamiast niego odczytywane jest pole isocode zakodowane w formacie formularza. Opcjonalny parametr pid jest przesyłany w ciągu zapytania.

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

Odpowiedź

Standardowa struktura odpowiedzi. W przypadku powodzenia status.code ma wartość 200, status.msg jest puste, a status.results zawiera liczbę wpisów. response to lista posortowana według name (bez rozróżniania wielkości liter), a następnie według kodu w state. Pola: state (kod stanu lub prowincji pobrany z informacji o stanie lub prowincji przypisanych do prefiksów, zwykle dwuliterowy; nietypowe wartości są przekazywane bez zmian); name (nazwa z katalogu lub kod, jeśli katalog nie zawiera dla niego nazwy); country_iso; available (łączna liczba dostępnych numerów we wszystkich zliczanych prefiksach, zawsze większa niż 0); prefix_count (liczba zliczanych prefiksów z dostępnymi numerami); is_mobile (1, jeśli którykolwiek ze zliczanych prefiksów obsługuje telefonię komórkową; zawsze 0 dla US, chyba że Twoje konto ma włączony dostęp do numerów komórkowych w USA); sms_coverage (1, jeśli którykolwiek ze zliczanych prefiksów ma obsługę SMS); returns_numbers (1, jeśli którykolwiek ze zliczanych prefiksów ma ustawiony znacznik zwracania numerów lub nie ma wartości tego znacznika); next_function ('v3/getareas/{isocode}?state={state}'). Jeśli istnieją prefiksy z dostępnymi numerami, ale żaden nie ma informacji o stanie lub prowincji, wynikiem jest status.code 200 z pustą listą i status.results 0.

Przykładowa struktura odpowiedzi; nie przedstawia bieżących danych konta ani aktualnej oferty cenowej.

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

Błędy

• 500: msg 'ISO Code parameter is required': brak isocode lub jego wartość jest pusta. Jest to błąd żądania, który można poprawić. Nie jest ustawiany odpowiadający mu status HTTP; odczytaj status.code.
• 404: msg 'getstates is only available for US and CA': dowolny inny kod kraju. Nie jest ustawiany odpowiadający mu status HTTP.
• 404: msg 'No states found': żadne prefiksy z dostępnymi numerami nie pasują do filtrów kraju i źródła. Nie jest ustawiany odpowiadający mu status HTTP.
• 401: Brak uwierzytelniania lub uwierzytelnianie nie powiodło się. Wysyłane ze statusem HTTP 401.

Dostępność i skutki uboczne

• Wyłącznie wyszukiwanie. Nie rezerwuje, nie zamawia ani niczego nie zmienia. available ma charakter informacyjny i nie rezerwuje numerów.