Lys dekkingsgebiede vir 'n land

Kies eers 'n land (en, vir die VSA of Kanada, opsioneel 'n deelstaat uit getstates), en roep dan getareas aan om te sien waar nommers aangebied word. Bewaar die gebied se uuid vir die volgende stap.

Elke gebied lei na een van twee volgende stappe:

• available > 0: next_function is v3/getprefixes/{uuid}, met ?state= wat bygevoeg word wanneer jy volgens deelstaat gefiltreer het. Gebruik dit om deur voorvoegsels te blaai.
• available = 0: die gebied het voorvoegsels maar geen voorraad nie, en next_function is v3/order/{uuid}. Raadpleeg die besteldokumentasie vir die vereistes van hierdie stap.

available is die totaal vir die hele gebied, selfs wanneer jy volgens deelstaat filtreer. Die deelstaatfilter aanvaar 'n kode of 'n volle naam, maar werk slegs vir US en CA. As 'n deelstaatfilter die volgende teruggee: No areas found, probeer weer sonder die filter. Kontroles word in hierdie volgorde uitgevoer: ontbrekende landkode, onbekende land, deelstaatfilter vir 'n ander land, ongeldige deelstaat, geen ooreenstemmende gebiede nie. Elkeen hiervan gee die kode 500 of 404 in status.code, sonder 'n ooreenstemmende HTTP-status.

Versoek

Vereis: HTTP Basic of 'n Bearer-token (sien Stawing en API-antwoorde). Mislukte stawing word met HTTP 401 beantwoord voordat die opsoek uitgevoer word.

GET met isocode in die pad en die opsionele parameters state en pid in die navraagstring. As die padsegment weggelaat word, word 'n vormgekodeerde isocode-veld eerder gelees.

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'

Antwoord

Standaardomhulsel. By sukses is status.code 200, is status.msg 'Results: N', is status.results N, en is response 'n lys wat volgens gebiednaam gesorteer is. Velde: uuid (gebiedidentifiseerder sonder afleibare betekenis wat deur die volgende stap gebruik word); country_uuid (landidentifiseerder van 32 karakters sonder afleibare betekenis, wat nie later nodig is nie); name; area_type en number_type (katalogusbeskrywings; inskrywings is nie noodwendig plaaslike nommertipes nie); country_iso; is_mobile (0 of 1, uit die gebied se selfoonaanwysers; altyd 0 vir US tensy jou rekening vir selfoonnommers in US geaktiveer is); available (totale voorraad oor die gebied se ooreenstemmende voorvoegsels, nie beperk tot die aangevraagde deelstaat nie); sms_coverage (0 of 1); returns_numbers (0 of 1, die hoogste aanwyserwaarde onder die gebied se voorvoegsels); latitude en longitude; state_iso; next_function. state_iso: met 'n deelstaatfilter is dit die vasgestelde filterkode. Vir US en CA sonder 'n filter is dit die deelstaat waarvan die naam met die gebiednaam ooreenstem, anders die gestoorde gebiedwaarde, anders 'n kode wat uit die gebied se voorvoegseldata afgelei is. Vir ander lande is dit die gestoorde waarde en kan dit leeg wees. next_function is 'v3/getprefixes/{uuid}' (plus '?state={code}' wanneer gefiltreer word) wanneer available groter as 0 is, anders 'v3/order/{uuid}'. Gebiede sonder enige ooreenstemmende voorvoegsel word weggelaat. Gebiede met voorvoegsels maar geen voorraad nie word met available 0 teruggegee.

Voorbeeld van die antwoordstruktuur; dit is nie lewendige rekeningdata of 'n huidige kwotasie nie.

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

Foute

• 500: msg 'ISO Code parameter is required': isocode ontbreek of is leeg. Dit is 'n versoekfout wat reggestel kan word. Geen ooreenstemmende HTTP-status word gestel nie.
• 404: msg 'Error: no such country': die landkode is onbekend. Geen ooreenstemmende HTTP-status word gestel nie.
• 404: msg 'State filter is only available for US and CA': 'n nieleë state is vir 'n ander land gestuur. Geen ooreenstemmende HTTP-status word gestel nie.
• 404: msg 'Invalid state': state is nóg 'n bekende kode nóg 'n bekende naam vir die land. Geen ooreenstemmende HTTP-status word gestel nie.
• 404: msg 'No areas found': geen gebied stem met die land-, bron- en deelstaatfilters ooreen nie. Geen ooreenstemmende HTTP-status word gestel nie.
• 401: Stawing ontbreek of het misluk. Word met HTTP-status 401 gestuur.

Beskikbaarheid en newe-effekte

• Slegs 'n opsoek vir kliënterekeninge. Dit reserveer, bestel of verander niks nie.
• available dien ter inligting en kan voor die volgende stap verander.