Lista täckningsområden för ett land

När du har valt ett land (och, för USA eller Kanada, eventuellt en delstat eller provins från getstates), anropa getareas för att se var nummer erbjuds. Spara områdets uuid till nästa steg.

Varje område leder till ett av två möjliga nästa steg:

• available > 0: next_function är v3/getprefixes/{uuid}, med ?state= tillagt när du har filtrerat efter delstat. Använd detta för att bläddra bland prefix.
• available = 0: området har prefix men inga nummer i lager, och next_function är v3/order/{uuid}. Se dokumentationen för beställningar för att ta reda på vad detta steg kräver.

available är det sammanlagda lagersaldot för hela området, även när du filtrerar efter delstat. Delstatsfiltret accepterar en kod eller ett fullständigt namn, men fungerar bara för US och CA. Om ett delstatsfilter returnerar No areas found, försök igen utan filtret. Kontrollerna utförs i följande ordning: saknad landskod, okänt land, delstatsfilter för ett annat land, ogiltig delstat, inga matchande områden. Var och en av dessa returnerar koden 500 eller 404 i status.code, utan motsvarande HTTP-status.

Begäran

Krävs: HTTP Basic eller en Bearer-token (se Autentisering och API-svar). Misslyckad autentisering besvaras med HTTP 401 innan uppslagningen utförs.

GET med isocode i sökvägen och de valfria parametrarna state och pid i frågesträngen. Om sökvägssegmentet utelämnas läses i stället ett formulärkodat isocode-fält.

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'

Svar

Standardiserad svarsstruktur. Vid ett lyckat anrop är status.code 200, status.msg är 'Results: N', status.results är N och response är en lista sorterad efter områdesnamn. Fält: uuid (opak områdesidentifierare som används i nästa steg); country_uuid (opak landsidentifierare med 32 tecken, behövs inte senare); name; area_type och number_type (katalogbeskrivningar; posterna avser inte nödvändigtvis lokala nummertyper); country_iso; is_mobile (0 eller 1, från områdets mobilflaggor; alltid 0 för US om inte ditt konto är aktiverat för mobilnummer i US); available (sammanlagt lagersaldo för områdets matchande prefix, inte begränsat till den begärda delstaten); sms_coverage (0 eller 1); returns_numbers (0 eller 1, det högsta flaggvärdet bland områdets prefix); latitude och longitude; state_iso; next_function. state_iso: med ett delstatsfilter är detta den kod som filtret har tolkats till. För US och CA utan filter är det koden för den delstat vars namn är identiskt med områdesnamnet, annars områdets lagrade värde, annars en kod som härleds från områdets prefixdata. För andra länder är det det lagrade värdet och kan vara tomt. next_function är 'v3/getprefixes/{uuid}' (med tillägget '?state={code}' vid filtrering) när available är större än 0, annars 'v3/order/{uuid}'. Områden som helt saknar matchande prefix utelämnas. Områden med prefix men utan nummer i lager returneras med available 0.

Exempel på svarsstruktur; detta är inte kontodata i realtid eller en aktuell offert.

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

Fel

• 500: msg 'ISO Code parameter is required': isocode saknas eller är tomt. Detta är ett fel i begäran som kan rättas till. Ingen motsvarande HTTP-status anges.
• 404: msg 'Error: no such country': landskoden är okänd. Ingen motsvarande HTTP-status anges.
• 404: msg 'State filter is only available for US and CA': ett icke-tomt värde för state skickades för ett annat land. Ingen motsvarande HTTP-status anges.
• 404: msg 'Invalid state': state är varken en känd kod eller ett känt namn för landet. Ingen motsvarande HTTP-status anges.
• 404: msg 'No areas found': inget område matchar filtren för land, källa och delstat. Ingen motsvarande HTTP-status anges.
• 401: Autentisering saknas eller misslyckades. Skickas med HTTP-status 401.

Tillgänglighet och sidoeffekter

• Endast uppslagning för kundkonton. Inget reserveras, beställs eller ändras.
• available är endast information och kan ändras före nästa steg.