国の提供エリア一覧を取得する

国を選択し（米国またはカナダでは、必要に応じて getstates から州を選択して）、getareas を呼び出すと、番号が提供されているエリアを確認できます。次の手順で使用するため、エリアの uuid を保持してください。

各エリアの次の手順は、次のいずれかになります。

• available > 0：next_function は v3/getprefixes/{uuid} で、州で絞り込んだ場合は ?state= が追加されます。この参照先を使ってプレフィックスを参照してください。
• available = 0：エリアにはプレフィックスがありますが在庫はなく、next_function は v3/order/{uuid} です。この手順に必要な条件については、注文に関するドキュメントを参照してください。

available は、州で絞り込んだ場合でもエリア全体の合計です。州フィルターにはコードまたは正式名称を指定できますが、使用できるのは US と CA のみです。州フィルターを指定して No areas found が返された場合は、州フィルターを外して再試行してください。チェックは、国コードの欠落、未知の国、対象外の国への州フィルター指定、無効な州、一致するエリアなし、の順で実行されます。これらの場合、それぞれコード 500 または 404 を status.code で返しますが、対応する HTTP ステータスは設定されません。

リクエスト

必須：HTTP Basic 認証または Bearer トークン（「認証と API レスポンス」を参照）。認証に失敗した場合は、検索を実行する前に HTTP 401 を返します。

GET を使用し、パスに isocode、クエリ文字列に任意の state および pid パラメーターを指定します。パスセグメントが省略された場合は、代わりにフォームエンコードされた isocode フィールドが読み取られます。

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'

レスポンス

標準のエンベロープ形式です。成功時は status.code が 200、status.msg が 'Results: N'、status.results が N となり、response はエリア名順に並んだリストです。フィールド：uuid（次の手順で使用する、内部構造を解釈せずに扱うエリア識別子）；country_uuid（内部構造を解釈せずに扱う 32 文字の国識別子。以降の手順では不要）；name；area_type および number_type（カタログ上の分類情報。項目が必ずしも市内番号の種別とは限りません）；country_iso；is_mobile（0 または 1。エリアのモバイルフラグに基づきます。US では、アカウントで US の携帯電話番号の利用が有効になっていない限り、常に 0）；available（エリア内の条件に一致するプレフィックス全体の在庫合計。指定した州には限定されません）；sms_coverage（0 または 1）；returns_numbers（0 または 1。エリア内のプレフィックスのフラグの最大値）；latitude および longitude；state_iso；next_function。state_iso：州フィルターがある場合は、フィルターの解決結果となるコードです。US と CA でフィルターがない場合は、エリア名と名前が一致する州のコード、それがなければエリアに保存されている値、それもなければエリアのプレフィックスデータから導出されるコードになります。その他の国では、保存されている値となり、空の場合もあります。next_function は 'v3/getprefixes/{uuid}'（フィルター指定時は '?state={code}' を追加）となるのが available が 0 より大きい場合で、それ以外は 'v3/order/{uuid}' です。条件に一致するプレフィックスが一つもないエリアは除外されます。プレフィックスはあるものの在庫がないエリアは、available が 0 として返されます。

レスポンスの構造を示す例です。実際のアカウントデータや現時点の見積もりではありません。

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

エラー

• 500：msg 'ISO Code parameter is required'：isocode が指定されていないか、空白です。リクエストを修正することで解消できるエラーです。対応する HTTP ステータスは設定されません。
• 404：msg 'Error: no such country'：国コードが認識されません。対応する HTTP ステータスは設定されません。
• 404：msg 'State filter is only available for US and CA'：対象外の国に対して、空ではない state が送信されました。対応する HTTP ステータスは設定されません。
• 404：msg 'Invalid state'：state が、その国で認識される州のコードにも名称にも一致しません。対応する HTTP ステータスは設定されません。
• 404：msg 'No areas found'：国、供給元、州のフィルター条件に一致するエリアがありません。対応する HTTP ステータスは設定されません。
• 401：認証情報がないか、認証に失敗しました。HTTP ステータス 401 とともに返されます。

利用条件と副作用

• 顧客アカウントでの検索専用です。予約、注文、変更は一切行いません。
• available は参考情報であり、次の手順に進むまでに変わる可能性があります。