Nadat u een land hebt gekozen (en voor de VS of Canada eventueel een staat of provincie uit getstates), roept u getareas aan om te zien waar nummers worden aangeboden. Bewaar de gebiedsidentificatie uuid voor de volgende stap.
Elk gebied leidt naar een van twee vervolgstappen:
- available > 0:
next_functionisv3/getprefixes/{uuid}, met?state=eraan toegevoegd als u op staat of provincie hebt gefilterd. Gebruik dit om prefixen te bekijken. - available = 0: het gebied heeft prefixen maar geen voorraad, en
next_functionisv3/order/{uuid}. Raadpleeg de besteldocumentatie voor de vereisten voor deze stap.
available is het totaal voor het hele gebied, ook als u op staat of provincie filtert. Het filter accepteert een code of een volledige naam, maar werkt alleen voor US en CA. Als een filter op staat of provincie de melding No areas found oplevert, probeert u het opnieuw zonder dit filter. De controles worden in deze volgorde uitgevoerd: ontbrekende landcode, onbekend land, filter op staat of provincie voor een ander land, ongeldige staat of provincie, geen overeenkomende gebieden. Elk van deze gevallen geeft code 500 of 404 in status.code, zonder een overeenkomstige HTTP-status.
Verzoek
Vereist: HTTP Basic of een Bearer-token (zie Authenticatie en API-antwoorden). Bij mislukte authenticatie wordt HTTP 401 teruggegeven voordat de opzoekactie wordt uitgevoerd.
GET met isocode in het pad en de optionele parameters state en pid in de querystring. Als het padsegment wordt weggelaten, wordt in plaats daarvan een als formuliergegevens gecodeerd veld isocode gelezen.
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'| Naam | Type | Verplicht | Beschrijving |
|---|---|---|---|
isocode | string | Ja | Landcode volgens ISO 3166-1 alpha-2. Niet hoofdlettergevoelig; witruimte aan het begin en einde wordt genegeerd. Het moet een bij MultiTEL bekend land zijn; het land hoeft niet in getcountries te staan. |
| Naam | Type | Verplicht | Beschrijving |
|---|---|---|---|
state | string | Nee | Alleen voor US en CA. Accepteert een staat- of provinciecode van twee letters, ongeacht hoofdlettergebruik, of een volledige naam (niet hoofdlettergevoelig; spaties aan het begin en einde worden genegeerd en opeenvolgende spaties binnen de naam worden samengevoegd), bijvoorbeeld NY of new york. Een lege waarde wordt genegeerd. Als een staat of provincie is opgegeven, worden alleen gebieden teruggegeven waarvoor ten minste één prefix met voorraad voor die staat of provincie is geregistreerd, maar available blijft het totaal voor het hele gebied. De next_function uit getstates bevat deze parameter al. |
pid | string | Nee | Geavanceerd en optioneel. Beperkt de resultaten tot gebieden die voor één voorraadbron zijn gemarkeerd en ten minste één prefix uit die bron hebben (voorraad is niet vereist), en beperkt available en de overige statistieken tot die bron. Gebruik uitsluitend een door MultiTEL verstrekte waarde, in numerieke vorm of als hexadecimale waarde van 32 tekens, en laat deze parameter bij normaal gebruik weg. Onbekende waarden en waarden die dit eindpunt niet accepteert, worden zonder foutmelding genegeerd. |
Antwoord
Standaard antwoordstructuur. Bij succes is status.code 200, is status.msg 'Results: N', is status.results N en is response een lijst gesorteerd op gebiedsnaam. Velden: uuid (ondoorzichtige gebiedsidentificatie die in de volgende stap wordt gebruikt); country_uuid (ondoorzichtige landidentificatie van 32 tekens, later niet nodig); name; area_type en number_type (cataloguskenmerken; de vermeldingen betreffen niet noodzakelijk lokale nummertypen); country_iso; is_mobile (0 of 1, op basis van de indicatoren voor mobiele nummers van het gebied; altijd 0 voor US, tenzij uw account is ingeschakeld voor mobiele nummers uit US); available (totale voorraad van alle overeenkomende prefixen van het gebied, niet beperkt tot de opgevraagde staat of provincie); sms_coverage (0 of 1); returns_numbers (0 of 1, de hoogste indicatorwaarde onder de prefixen van het gebied); latitude en longitude; state_iso; next_function. state_iso: bij een filter op staat of provincie is dit de vastgestelde filtercode. Voor US en CA zonder filter is dit de staat of provincie waarvan de naam gelijk is aan de gebiedsnaam, anders de opgeslagen gebiedswaarde, en anders een code die is afgeleid van de prefixgegevens van het gebied. Voor andere landen is dit de opgeslagen waarde, die leeg kan zijn. next_function is 'v3/getprefixes/{uuid}' (met '?state={code}' erbij als er is gefilterd) wanneer available groter is dan 0, en anders 'v3/order/{uuid}'. Gebieden zonder enige overeenkomende prefix worden weggelaten. Gebieden met prefixen maar zonder voorraad worden teruggegeven met available 0.
Voorbeeld van de antwoordstructuur; geen actuele accountgegevens of actuele prijsopgave.
{
"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"
}
]
}Fouten
- 500: msg 'ISO Code parameter is required': isocode ontbreekt of is leeg. Dit is een corrigeerbare fout in het verzoek. Er wordt geen overeenkomstige HTTP-status ingesteld.
- 404: msg 'Error: no such country': de landcode is onbekend. Er wordt geen overeenkomstige HTTP-status ingesteld.
- 404: msg 'State filter is only available for US and CA': er is een niet-lege state voor een ander land meegestuurd. Er wordt geen overeenkomstige HTTP-status ingesteld.
- 404: msg 'Invalid state': state is geen bekende code en ook geen bekende naam voor het land. Er wordt geen overeenkomstige HTTP-status ingesteld.
- 404: msg 'No areas found': geen enkel gebied voldoet aan de filters voor land, bron en staat of provincie. Er wordt geen overeenkomstige HTTP-status ingesteld.
- 401: authenticatie ontbreekt of is mislukt. Wordt verzonden met HTTP-status 401.
Beschikbaarheid en neveneffecten
- Uitsluitend een opzoekactie voor klantaccounts. Er wordt niets gereserveerd, besteld of gewijzigd.
- available dient ter informatie en kan vóór de volgende stap veranderen.