Når du har valgt et land (og, for USA eller Canada, eventuelt en delstat fra getstates), kaller du getareas for å se hvor numre tilbys. Ta vare på områdets uuid til neste trinn.
Hvert område fører til ett av to neste trinn:
- available > 0:
next_functionerv3/getprefixes/{uuid}, med?state=lagt til når du har filtrert etter delstat. Bruk dette til å bla gjennom prefikser. - available = 0: området har prefikser, men ingen numre på lager, og
next_functionerv3/order/{uuid}. Se bestillingsdokumentasjonen for kravene til dette trinnet.
available er totalen for hele området, også når du filtrerer etter delstat. Delstatsfilteret godtar en kode eller et fullstendig navn, men fungerer bare for US og CA. Hvis et delstatsfilter returnerer No areas found, prøver du igjen uten filteret. Kontrollene utføres i denne rekkefølgen: manglende landskode, ukjent land, delstatsfilter for et annet land, ugyldig delstat, ingen samsvarende områder. Hver av disse returnerer kode 500 eller 404 i status.code, uten en tilsvarende HTTP-status.
Forespørsel
Påkrevd: HTTP Basic eller et Bearer-token (se Autentisering og API-svar). Mislykket autentisering besvares med HTTP 401 før oppslaget utføres.
GET med isocode i stien og de valgfrie parameterne state og pid i spørringsstrengen. Hvis stisegmentet utelates, leses et skjemakodet 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åkrevd | Beskrivelse |
|---|---|---|---|
isocode | string | Ja | Landskode i henhold til ISO 3166-1 alpha-2. Det skilles ikke mellom store og små bokstaver; innledende og avsluttende blanktegn ignoreres. Landet må være kjent for MultiTEL; det trenger ikke å være oppført i getcountries. |
| Navn | Type | Påkrevd | Beskrivelse |
|---|---|---|---|
state | string | Nei | Bare for US og CA. Godtar en delstats- eller provinskode på to bokstaver med store eller små bokstaver, eller et fullstendig navn (uten skille mellom store og små bokstaver; innledende og avsluttende mellomrom ignoreres, og flere påfølgende mellomrom inne i navnet slås sammen til ett), for eksempel NY eller new york. En tom verdi ignoreres. Når en delstat er angitt, returneres bare områder som har minst ett prefiks med numre på lager registrert for den delstaten, men available er fortsatt totalen for hele området. next_function fra getstates inneholder allerede denne parameteren. |
pid | string | Nei | Avansert og valgfri. Avgrenser resultatene til områder som er merket for én lagerkilde og har minst ett prefiks fra denne kilden (numre på lager kreves ikke), og begrenser available og den øvrige statistikken til denne kilden. Bruk bare en verdi du har fått fra MultiTEL, enten som tall eller i heksadesimal form med 32 tegn, og utelat den ved vanlig bruk. Ukjente verdier og verdier som dette endepunktet ikke godtar, ignoreres uten feilmelding. |
Svar
Standard svarstruktur. Ved vellykket forespørsel er status.code 200, status.msg er 'Results: N', status.results er N, og response er en liste sortert etter områdenavn. Felt: uuid (ugjennomsiktig områdeidentifikator som brukes i neste trinn); country_uuid (ugjennomsiktig landidentifikator på 32 tegn, trengs ikke senere); name; area_type og number_type (katalogbeskrivelser; oppføringene gjelder ikke nødvendigvis lokale nummertyper); country_iso; is_mobile (0 eller 1, fra områdets mobilflagg; alltid 0 for US med mindre kontoen din er aktivert for mobilnumre i US); available (samlet lagerbeholdning for områdets samsvarende prefikser, ikke begrenset til den angitte delstaten); sms_coverage (0 eller 1); returns_numbers (0 eller 1, den høyeste flaggverdien blant områdets prefikser); latitude og longitude; state_iso; next_function. state_iso: Med et delstatsfilter er dette koden som filteret er tolket til. For US og CA uten filter er dette delstaten med samme navn som området, ellers den lagrede områdeverdien, ellers en kode utledet fra områdets prefiksdata. For andre land er dette den lagrede verdien, som kan være tom. next_function er 'v3/getprefixes/{uuid}' (med '?state={code}' lagt til ved filtrering) når available er større enn 0, ellers 'v3/order/{uuid}'. Områder uten noe samsvarende prefiks utelates. Områder med prefikser, men uten numre på lager, returneres med available 0.
Eksempel på svarstruktur; dette er verken kontodata i sanntid eller et gjeldende 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"
}
]
}Feil
- 500: msg 'ISO Code parameter is required': isocode mangler eller er tom. Dette er en feil i forespørselen som kan rettes. Ingen tilsvarende HTTP-status angis.
- 404: msg 'Error: no such country': landskoden er ukjent. Ingen tilsvarende HTTP-status angis.
- 404: msg 'State filter is only available for US and CA': en verdi som ikke er tom, ble sendt i state for et annet land. Ingen tilsvarende HTTP-status angis.
- 404: msg 'Invalid state': state er verken en kjent kode eller et kjent navn for landet. Ingen tilsvarende HTTP-status angis.
- 404: msg 'No areas found': ingen områder samsvarer med filtrene for land, kilde og delstat. Ingen tilsvarende HTTP-status angis.
- 401: Autentisering mangler eller mislyktes. Sendes med HTTP-status 401.
Tilgjengelighet og sideeffekter
- Kun oppslag for kundekontoer. Det reserverer, bestiller eller endrer ingenting.
- available er kun til informasjon og kan endres før neste trinn.