Når du har valgt et land (og for USA eller Canada eventuelt en delstat fra getstates), skal du kalde getareas for at se, hvor der tilbydes numre. Gem områdets uuid til næste trin.
Hvert område fører til et af to mulige næste trin:
- available > 0:
next_functionerv3/getprefixes/{uuid}, med?state=tilføjet, hvis du har filtreret efter delstat. Brug det til at se præfikser. - available = 0: området har præfikser, men ingen numre på lager, og
next_functionerv3/order/{uuid}. Se dokumentationen om bestilling for at få oplysninger om, hvad dette trin kræver.
available er den samlede lagerbeholdning for hele området, også når du filtrerer efter delstat. Delstatsfilteret accepterer en kode eller et fuldt navn, men virker kun for US og CA. Hvis et delstatsfilter returnerer No areas found, skal du prøve igen uden filteret. Kontrollerne udføres i denne rækkefølge: manglende landekode, ukendt land, delstatsfilter for et andet land, ugyldig delstat, ingen matchende områder. Hver af disse returnerer koden 500 eller 404 i status.code, uden en tilsvarende HTTP-status.
Forespørgsel
Påkrævet: HTTP Basic eller et Bearer-token (se Godkendelse og API-svar). Mislykket godkendelse besvares med HTTP 401, før opslaget udføres.
GET med isocode i stien og de valgfrie parametre state og pid i forespørgselsstrengen. Hvis stisegmentet udelades, læses et formularkodet isocode-felt i stedet.
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'| Navn | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
isocode | string | Ja | Landekode i formatet ISO 3166-1 alpha-2. Der skelnes ikke mellem store og små bogstaver; indledende og afsluttende blanktegn ignoreres. Landet skal være kendt af MultiTEL; det behøver ikke at optræde i getcountries. |
| Navn | Type | Påkrævet | Beskrivelse |
|---|---|---|---|
state | string | Nej | Kun US og CA. Accepterer en delstats- eller provinskode på to bogstaver med vilkårlig brug af store og små bogstaver eller et fuldt navn (der skelnes ikke mellem store og små bogstaver; indledende og afsluttende mellemrum ignoreres, og flere på hinanden følgende mellemrum inde i navnet samles til ét), for eksempel NY eller new york. En tom værdi ignoreres. Når en delstat er angivet, returneres kun områder, der har mindst ét præfiks med numre på lager registreret for den pågældende delstat, men available er stadig den samlede lagerbeholdning for hele området. next_function fra getstates indeholder allerede denne parameter. |
pid | string | Nej | Avanceret og valgfri. Begrænser resultaterne til områder, der er markeret for én lagerkilde og har mindst ét præfiks fra den pågældende kilde (numre på lager er ikke påkrævet), og begrænser available og de øvrige statistikker til denne kilde. Brug kun en værdi, som MultiTEL har oplyst, enten som tal eller som en hexadecimal værdi på 32 tegn, og udelad parameteren ved normal brug. Ukendte værdier og værdier, som dette endepunkt ikke accepterer, ignoreres uden fejlmeddelelse. |
Svar
Standardformat for svar. Ved et vellykket opslag er status.code 200, status.msg er 'Results: N', status.results er N, og response er en liste sorteret efter områdenavn. Felter: uuid (uigennemsigtig områdeidentifikator, der bruges i næste trin); country_uuid (uigennemsigtig landeidentifikator på 32 tegn, som ikke skal bruges senere); name; area_type og number_type (katalogbeskrivelser; posterne er ikke nødvendigvis lokale nummertyper); country_iso; is_mobile (0 eller 1, fra områdets mobilflag; altid 0 for US, medmindre din konto er aktiveret til mobilnumre fra US); available (samlet lagerbeholdning på tværs af områdets matchende præfikser, ikke begrænset til den forespurgte delstat); sms_coverage (0 eller 1); returns_numbers (0 eller 1, den højeste flagværdi blandt områdets præfikser); latitude og longitude; state_iso; next_function. state_iso: Med et delstatsfilter er dette den kode, som filteret er blevet omsat til. For US og CA uden filter er det delstaten, hvis navn er det samme som områdenavnet, ellers den gemte værdi for området, ellers en kode udledt af områdets præfiksdata. For andre lande er det den gemte værdi, som kan være tom. next_function er 'v3/getprefixes/{uuid}' (med '?state={code}' tilføjet ved filtrering), når available er større end 0, ellers 'v3/order/{uuid}'. Områder helt uden matchende præfikser udelades. Områder med præfikser, men uden numre på lager, returneres med available 0.
Illustration af svarstrukturen; ikke aktuelle kontodata eller et gældende pristilbud.
{
"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"
}
]
}Fejl
- 500: msg 'ISO Code parameter is required': isocode mangler eller er tom. Dette er en fejl i forespørgslen, som kan rettes. Der angives ingen tilsvarende HTTP-status.
- 404: msg 'Error: no such country': landekoden er ukendt. Der angives ingen tilsvarende HTTP-status.
- 404: msg 'State filter is only available for US and CA': der blev sendt en ikke-tom state-værdi for et andet land. Der angives ingen tilsvarende HTTP-status.
- 404: msg 'Invalid state': state er hverken en kendt kode eller et kendt navn for landet. Der angives ingen tilsvarende HTTP-status.
- 404: msg 'No areas found': intet område matcher filtrene for land, kilde og delstat. Der angives ingen tilsvarende HTTP-status.
- 401: Godkendelse mangler eller mislykkedes. Sendes med HTTP-status 401.
Tilgængelighed og sideeffekter
- Kun opslag for kundekonti. Opslaget reserverer, bestiller eller ændrer ikke noget.
- available er vejledende og kan ændre sig inden næste trin.