Amerikaanse staten of Canadese provincies met beschikbare nummers opvragen

Gebruik deze optionele stap voor de Verenigde Staten of Canada om de zoekopdracht te beperken tot een staat of provincie. Alleen US en CA worden geaccepteerd.

• Elke vermelding beschrijft de prefixen met beschikbare nummers voor die staat of provincie op het moment van de aanvraag.
• Volg next_function om de gebieden van de staat of provincie op te vragen. De link bevat al het filter state, maar niet pid.
• Bij het opzoeken van gebieden worden gegevens over staten en provincies op een iets andere manier vergeleken. Als voor een staat of provincie de link next_function het resultaat No areas found teruggeeft, roep dan getareas aan zonder een staat of provincie op te geven.
• Controleer status.code voordat u response uitleest. Een niet-ondersteund land of een land zonder overeenkomende voorraad levert code 404 op zonder bijbehorende HTTP-status.
• Een lege lijst met code 200 betekent dat er voorraad is, maar dat gegevens over de staat of provincie ontbreken. Roep getareas aan zonder een staat of provincie op te geven.

Aanvraag

Vereist: HTTP Basic-authenticatie of een Bearer-token (zie Authenticatie en API-antwoorden). Bij mislukte authenticatie wordt HTTP 401 teruggegeven voordat de zoekopdracht wordt uitgevoerd.

GET met isocode in het pad. Als het padsegment ontbreekt, wordt in plaats daarvan een als formuliergegevens gecodeerd veld isocode uitgelezen. De optionele parameter pid wordt in de querystring verzonden.

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

Antwoord

Standaard antwoordstructuur. Bij succes is status.code 200, is status.msg leeg en bevat status.results het aantal vermeldingen. response is een lijst die is gesorteerd op name (niet hoofdlettergevoelig) en vervolgens op de code in state. Velden: state (code van de staat of provincie uit de staatgegevens van de prefixen, doorgaans twee letters; ongebruikelijke waarden worden ongewijzigd doorgegeven); name (naam uit de catalogus, of de code als de catalogus er geen naam voor heeft); country_iso; available (totale voorraad van alle getelde prefixen, altijd groter dan 0); prefix_count (aantal getelde prefixen met beschikbare nummers); is_mobile (1 als ten minste één getelde prefix mobiele telefonie ondersteunt; altijd 0 voor US, tenzij uw account is ingeschakeld voor Amerikaanse mobiele nummers); sms_coverage (1 als ten minste één getelde prefix sms-dekking heeft); returns_numbers (1 als bij ten minste één getelde prefix de indicator voor het teruggeven van nummers is ingesteld of de waarde daarvoor ontbreekt); next_function ('v3/getareas/{isocode}?state={state}'). Als er prefixen met beschikbare nummers bestaan maar geen daarvan gegevens over een staat of provincie bevat, is het resultaat status.code 200 met een lege lijst en status.results 0.

Voorbeeld van de antwoordstructuur; dit zijn geen actuele accountgegevens of een actuele prijsopgave.

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

Fouten

• 500: msg 'ISO Code parameter is required': isocode ontbreekt of is leeg. Dit is een aanvraagfout die kan worden verholpen. Er wordt geen bijbehorende HTTP-status ingesteld; lees status.code uit.
• 404: msg 'getstates is only available for US and CA': elke andere landcode. Er wordt geen bijbehorende HTTP-status ingesteld.
• 404: msg 'No states found': geen prefixen met beschikbare nummers voldoen aan de filters voor land en bron. Er wordt geen bijbehorende HTTP-status ingesteld.
• 401: Authenticatie ontbreekt of is mislukt. Wordt verzonden met HTTP-status 401.

Beschikbaarheid en neveneffecten

• Alleen opzoeken. Er wordt niets gereserveerd, besteld of gewijzigd. available is uitsluitend informatief en houdt geen nummers voor u vast.