Listaa maan kattavuusalueet

Kun olet valinnut maan (ja Yhdysvaltojen tai Kanadan tapauksessa halutessasi osavaltion tai provinssin luettelosta getstates), kutsu toimintoa getareas nähdäksesi, millä alueilla numeroita tarjotaan. Säilytä alueen uuid-tunniste seuraavaa vaihetta varten.

Kukin alue johtaa jompaankumpaan seuraavista vaiheista:

• available > 0: next_function on v3/getprefixes/{uuid}, johon lisätään ?state= silloin, kun käytit osavaltiosuodatinta. Käytä sitä etuliitteiden selaamiseen.
• available = 0: alueella on etuliitteitä mutta ei numeroita varastossa, ja next_function on v3/order/{uuid}. Katso tämän vaiheen vaatimukset tilausdokumentaatiosta.

available on koko alueen kokonaismäärä myös silloin, kun käytät osavaltiosuodatinta. Osavaltiosuodatin hyväksyy koodin tai koko nimen, mutta toimii vain maissa US ja CA. Jos osavaltiosuodatin palauttaa viestin No areas found, yritä uudelleen ilman suodatinta. Tarkistukset tehdään tässä järjestyksessä: puuttuva maakoodi, tuntematon maa, osavaltiosuodatin muulle maalle, virheellinen osavaltio, ei vastaavia alueita. Kukin näistä palauttaa koodin 500 tai 404 kentässä status.code, mutta vastaavaa HTTP-tilakoodia ei aseteta.

Pyyntö

Pakollinen: HTTP Basic -todennus tai Bearer-tunniste (katso Todennus ja API-vastaukset). Jos todennus epäonnistuu, palautetaan HTTP 401 ennen haun suorittamista.

GET-pyyntö, jossa isocode on polussa ja valinnaiset parametrit state ja pid kyselymerkkijonossa. Jos polun osa puuttuu, sen sijaan luetaan lomakekoodattu isocode-kenttä.

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'

Vastaus

Vakiomuotoinen vastausrakenne. Onnistuneessa vastauksessa status.code on 200, status.msg on 'Results: N', status.results on N ja response on alueen nimen mukaan järjestetty luettelo. Kentät: uuid (seuraavassa vaiheessa käytettävä alueen tunniste, jonka sisällöllä ei ole tulkittavaa merkitystä); country_uuid (32-merkkinen maan tunniste, jonka sisällöllä ei ole tulkittavaa merkitystä ja jota ei tarvita myöhemmin); name; area_type ja number_type (luettelon kuvaustietoja; tietueet eivät välttämättä edusta paikallisnumerotyyppejä); country_iso; is_mobile (0 tai 1 alueen matkapuhelinlippujen perusteella; aina 0 maalle US, ellei tililläsi ole otettu käyttöön maan US matkapuhelinnumeroita); available (alueen vastaavien etuliitteiden yhteenlaskettu varastomäärä, joka ei rajoitu pyydettyyn osavaltioon); sms_coverage (0 tai 1); returns_numbers (0 tai 1, alueen etuliitteiden suurin lippuarvo); latitude ja longitude; state_iso; next_function. state_iso: osavaltiosuodatinta käytettäessä arvo on suodatinta vastaavaksi selvitetty koodi. Maissa US ja CA ilman suodatinta arvo on sen osavaltion tai provinssin koodi, jonka nimi vastaa alueen nimeä; muutoin käytetään alueelle tallennettua arvoa tai sen puuttuessa alueen etuliitetiedoista johdettua koodia. Muissa maissa käytetään tallennettua arvoa, joka voi olla tyhjä. next_function on 'v3/getprefixes/{uuid}' (suodatettaessa siihen lisätään '?state={code}'), kun available on suurempi kuin 0, ja muulloin 'v3/order/{uuid}'. Alueet, joilla ei ole yhtään vastaavaa etuliitettä, jätetään pois. Alueet, joilla on etuliitteitä mutta ei numeroita varastossa, palautetaan siten, että available on 0.

Havainnollistava vastausrakenne; ei tilin reaaliaikaisia tietoja eikä ajantasainen hintatarjous.

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

Virheet

• 500: msg 'ISO Code parameter is required': isocode puuttuu tai on tyhjä. Tämä on korjattavissa oleva pyyntövirhe. Vastaavaa HTTP-tilakoodia ei aseteta.
• 404: msg 'Error: no such country': maakoodi on tuntematon. Vastaavaa HTTP-tilakoodia ei aseteta.
• 404: msg 'State filter is only available for US and CA': muulle maalle lähetettiin state-parametri, jonka arvo ei ollut tyhjä. Vastaavaa HTTP-tilakoodia ei aseteta.
• 404: msg 'Invalid state': state ei ole maan tunnettu osavaltio- tai provinssikoodi eikä tunnettu nimi. Vastaavaa HTTP-tilakoodia ei aseteta.
• 404: msg 'No areas found': mikään alue ei vastaa maa-, lähde- ja osavaltiosuodattimia. Vastaavaa HTTP-tilakoodia ei aseteta.
• 401: Todennus puuttuu tai epäonnistui. Lähetetään HTTP-tilakoodilla 401.

Saatavuus ja sivuvaikutukset

• Vain tietojen haku asiakastileille. Haku ei varaa, tilaa eikä muuta mitään.
• available on viitteellinen tieto ja voi muuttua ennen seuraavaa vaihetta.