Arcstar Universal One API (ENGLISH)

Overview

 ■ Users can use Arcstar Universal One APIs as below.
  (For Japan domestic line only)

  ・Arcstar Universal One Contract Detail API
  ・Arcstar Universal One Traffic Info API
  ・Arcstar Universal One Planned Outage Info API(Guarantee Plan)
   - Planned Outage List API
   - Planned Outage Detail Info API
  ・Arcstar Universal One Planned Outage Info API(Best Effort Plan)
  
 ■ Notice

  To use this API, users need to send mail to Support(https://developer.ntt.com/ja/contact.html)including below information.
If you don't have Developer Portal account, please fill in 【Comments/Question】.

 【Required information】
   - User Information(Company name, Devision, Contat person)
   - Start date of use
   - Purpose of use
   - Contact info (e.g phone number, e-mail,etc..)

  ※The person in charge of corresponding service will contact you.

Resource URL

 Please use global common domain, or the individual region domain.
 If you want to use the global common domain, depending on the circumstances of your available points, your request connect to the nearest API gateway.1

1.Base Path(Global Load Balance)

https://api.ntt.com/v1/uno

2.Base Path(Region)

https://{region}.api.ntt.com/v1/uno
  • region is jp|us|uk
  • e.g. https://us.api.ntt.com/v1/uno
  • Specifiable regions will be expanded in the future

Resource Information  

Key Value
Response format JSON
Authentication(OAuth) YES
Bandwidth control #1 YES

Contract Detail API

 By using this API, you can get detail information of Contract data of Arcstar Universal One filtered by VPN group ID and contract ID in JSON format.

  • Applicable to Japan domestic line only.

To get the Contract information

GET /v1/uno/contracts/{vpnGroupId}/{contractId} 

Request Parameters

Name Description Type Mandatory
vpnGroupId VPN Group ID
e.g.'V'+8 digit number
path variable Yes
contractId Specify contract ID
e.g. 'N'+9 digit number
path variable Yes

Example Request

GET /v1/uno/contracts/V12345678/N123456789 
HEADER Authorization: Bearer [YOUR_ACCESS_TOKEN]*
* For details on acquiring tokens, please refer to the OAuth API page

Response Parameters

Name Description Type Mandatory
addressType Address category
Classification for determining the address type in retaining the address in the address information.
KYS:Contractor Address
STB:Installation Address
String No
postalNumber Zipcode Int No
address Address
Address information of Japanese / English notation
String No
addressCode Address code
Code to identify the address
String No
banchi1 Address1
Address information1
String No
banchi2 Addres2
Address information2
String No
banchi3 Address3
Address information3
String No
building1 Building1
Building information1
String No
building2 Building2
Building information2
String No
building3 Building3
Building information3
String No
samakata Samakata
Samakata information
String No
productName
Name of product code
String No
productTypeName Product type name
Name of product type code
String No
itemNameProduct Item name_Contract item details
Item ID_Name of contract item details
String No
detailItemValue Detailed item value
Detail item value
String No

Example Result

{
  "addressInfo": [
    {
      "addressType": "KYS",
      "postalNumber": "1000011",
      "address": "東京都千代田●●1丁目",
      "addressCode": "12345678901",
      "banchi1": "1番6号",
      "banchi2": "",
      "banchi3": "",
      "building1": "●●●日比谷ビル",
      "building2": "",
      "building3": "",
      "samakata": ""
    },
    {
      "addressType": "STB",
      "postalNumber": "1000011",
      "address": "東京都千代田区●●1丁目",
      "addressCode": "12345678901",
      "banchi1": "1番6号",
      "banchi2": "",
      "banchi3": "",
      "building1": "●●●日比谷ビル",
      "building2": "1F",
      "building3": "",
      "samakata": ""
    }
  ],
  "productInfo": [
    {
      "productName": "Universal One",
      "productTypeName": "サービス",
      "productDetailInfo": []
    },
    {
      "productName": "L2",
      "productTypeName": "レイヤー",
      "productDetailInfo": []
    },
    {
      "productName": "ギャランティ",
      "productTypeName": "プラン",
      "productDetailInfo": []
    },
    {
      "productName": "メイン(主回線)",
      "productTypeName": "回線利用用途",
      "productDetailInfo": [
        {
          "itemNameProduct": "冗長化グループ番号",
          "detailItemValue": ""
        },
        {
          "itemNameProduct": "VPN番号",
          "detailItemValue": "V12345678"
        }
      ]
    },
    {
      "productName": "ギャランティアクセス",
      "productTypeName": "アクセス",
      "productDetailInfo": []
    },
    {
      "productName": "イーサタイプ(NTTCom光アクセス)",
      "productTypeName": "タイプ",
      "productDetailInfo": []
    },
    {
      "productName": "Ether",
      "productTypeName": "イーサネット種別",
      "productDetailInfo": []
    },
    {
      "productName": "全二重",
      "productTypeName": "通信方式",
      "productDetailInfo": []
    },
    {
      "productName": "10M",
      "productTypeName": "品目",
      "productDetailInfo": []
    },
    {
      "productName": "設置場所情報",
      "productTypeName": "部材",
      "productDetailInfo": [
        {
          "itemNameProduct": "設置場所事業所名",
          "detailItemValue": "●●●日比谷ビル"
        }
      ]
    },
    {
      "productName": "L2 設置無",
      "productTypeName": "UNO-T",
      "productDetailInfo": []
    }
  ]
}

Traffic Info API

 By using this API, you can get Traffic information of Arcstar Universal One filtered by VPN group ID and contract number and utilization / traffic in JSON and PNG format.

To get the Traffic Information

GET /v1/uno/traffic/{vpnGroupId}/{contractId}?dataType={dataType}&from={from}&to={to}&direction={direction}&interval={interval}&format={format}       

Request Parameters

Name Description Type Mandatory
vpnGroupId VPN Group ID
e.g.'V'+8 digit number
path variable Yes
contractId Contract ID
e.g.'N'+9 digit number
path variable Yes
dataType Data item
utilization:Domestic line utilization rate(%)
traffic:Domestic line information amount(bps)
query argument Yes
from Display start date/time #1#2 query argument Yes
to Display end date/time #1#2 query argument Yes
direction Data transmission / reception path type
in:reception 、out:transmission、inout:reception /transmission (both)
query argument Yes
interval Plot interval
realtime(5 minutes interval),daily(24h interval) 
query argument Yes
format Return value format
json:JSON format、png:graph image in PNG format
query argument Yes

#1. Specify JST
#2. Valid only when it is real-time

Example Request

GET /v1/uno/traffic/V12345678/N123456789?dataType=utilization&from=201801010000&to=201812312359&direction=in&interval=realtime&format=json     

Response Parameters

Name Description Type Mandatory
version Version String Yes
from Interval (From)
yyyy-MM-dd HH:mm format
String No
to Interval (To)
yyyy-MM-dd HH:mm format
String No
utilization / traffic Information on line utilization rate/ line information amount
The value changes depending on the specified data type
utilization:Output when dataType is utilization
traffic:Output when dataType is traffic
String No
prefecture Prefecture String No
companyName Company name String No
lineUseRateDayMax maximun line utilization of the day String No
in maximum reception amount
Output only when the direction (type) of the request parameter is in (reception), inout (reception / transmission)
String No
out Maximum transmission amount
Output only when the direction (type) of the request parameter is out (transmission), inout (reception / transmission)
String No
lineUseRate / trafficVolume Type of traffic data
The value changes depending on the specified data type
line_use_rate:Output when dataType is utilization
traffic_volume:Output when dataType is traffic
String No
in Line utilization rate(%) / Line information amount(bps)
Output only when the direction (type) of the request parameter is in (reception), inout (reception / transmission)
String No
out Line utilization (%) / Line information amount (bps)
Output only when the direction (type) of the request parameter is out (transmission), inout (reception / transmission)
String No
datetime Target date month
yyyy-MM-dd HH:mm format
String No
value Line utilization (%) / Line information amount (bps) String No
requestDateFrom Display start date/time (From)
yyyy-MM-ddTHH:mm+0900 format
String Yes
requestDateTo Display start date/time (To)
yyyy-MM-ddTHH:mm+0900 format
String Yes

Example Result

{
 "version": "1.00",
 "contractState": {
  "period": {
   "from": "2018-08-31 00:00",
   "to": ""
  }
 },
 "utilization": {
  "prefecture": "神奈川県",
  "companyName": "●●●●",
  "lineUseRateDayMax": {
   "in": "100.0",
   "out": "100.0"
  },
  "lineUseRate": {
   "in": [
    {
     "datetime": "2018-11-01 00:00",
     "value": "0.00466543888888888963"
    },
    {
     "datetime": "2018-11-02 00:00",
     "value": "0.00938773518518518958"
    },
    {
     "datetime": "2018-11-03 00:00",
     "value": "0.00471911851851852023"
    }
   ],
   "out": [
    {
     "datetime": "2018-11-01 00:00",
     "value": "0.00544012592592593019"
    },
    {
     "datetime": "2018-11-02 00:00",
     "value": "0.00545079814814814975"
    },
    {
     "datetime": "2018-11-03 00:00",
     "value": "5.41481481481481009e-06"
    }
   ]
  }
 },
 "requestDateFrom": "2018-11-01T12:00+0900",
 "requestDateTo": "2018-11-03T13:00+0900"
}

Planned Outage List API(Guarantee Plan)

 By using this API, you can get Planned Outage List of Arcstar Universal One Guarantee Plan in JSON format.

To get the Planned Outage List

GET /v1/uno/maintenance?plan=guarantee&updateTimeFrom={updateTimeFrom}&updateTimeTo={updateTimeTo}   

Request Parameters

Name Description Type Mandatory
plan Specify constraction data plan
Fixed value:guarantee
query argument Yes
updateTimeFrom Specify last modefied(from)
Example of date specification:20180101
Example of date specification:201801010000
query argument Yes
updateTimeTo Specify last modefied(to)
Example of date specification:20181231
Example of date specification:201812312359
query argument Yes

Example Request

GET /v1/uno/maintenance?plan=guarantee&updateTimeFrom=20180803&updateTimeTo=20180827
HEADER Authorization: Bearer [YOUR_ACCESS_TOKEN]*
* Please refer to the OAuth API page for token acquisition.

Response Parameters

Name Description Type Mandatory
totalCount Tortal count of search result Int Yes
pageNumber Page number of search result Int No
pageSize Tortal count page of search result Int No
prePageNumber Previous page number Int No
nextPageNumber Next page number Int No
firstPageNumber First page number Int No
lastPageNumber Last page number Int No
lineContractId Service conreact ID String No
agmUuid Borrowed line UUID String No
lastModifiedAc Last modified date
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No

    
* If the number of search result pages is 2 or more, there is a possibility that all of the corresponding data could not be acquired, please narrow down the conditions and execute the API again.

Example Result

{
  "totalCount": 3,
  "pageNumber": "1",
  "pageSize": "1000",
  "prePageNumber": "1",
  "nextPageNumber": "1",
  "firstPageNumber": "1",
  "lastPageNumber": "1",
  "items": [
    {
      "lineContractId": "N123456780",
      "amgUuid": "5F123456789012345678901234567890",
      "lastModifiedAc": "2018-01-22T16:34:12.059+0900"
    },
    {
      "lineContractId": "N123456781",
      "amgUuid": "5F123456789012345678901234567890",
      "lastModifiedAc": "2018-01-22T16:34:12.180+0900"
    },
    {
      "lineContractId": "N123456782",
      "amgUuid": "5F123456789012345678901234567890",
      "lastModifiedAc": "2018-01-22T16:34:12.633+0900"
    }
  ]
}

Planned Outage Detail Info API(Guarantee Plan)

 By using this API, you can get Planned Outage Detail Information of Arcstar Universal One Guarantee Plan in JSON format.

To get the detail information of Planned Outage

GET /v1/uno/maintenance/{vpnGroupId}/{contractId}?plan=guarantee&agmUuid={agmUuid}     

Request Parameters

Name Description Type Mandatory
vpnGroupId VPN Group ID
e.g.'V'+8 digit number
path variable Yes
contractId Contract ID
e.g.'N'+9 digit number
path variable Yes
plan Constraction data plan
Fixed value:guarantee
query argument Yes
agmUuid Borrowed line UUID query argument No

Example Request

GET /v1/uno/maintenance/V1245678/N123456789?plan=guarantee&agmUuid=x23fd9dae90adbewefdwe482000000000000001
HEADER Authorization: Bearer [YOUR_ACCESS_TOKEN]*
* For details on acquiring tokens, please refer to the OAuth API page

Response Parameters

Name Description Type Mandatory
totalCount Tortal count of search result Int Yes
pageNumber Page number of search result Int No
pageSize Tortal count page of search result Int No
prePageNumber Previous page number Int No
nextPageNumber Next page number Int No
firstPageNumber First page number Int No
lastPageNumber Last page number Int No
lastModifiedAc Last modified date
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
lineContractId Service conreact ID String No
agmUuid Borrowed line UUID String No
switchInfo1StartDay Line data/Switching data①Start date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
switchInfo1EndDay Line data/Switching data①End date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
switchInfo1ImpactTime Line data/Switching data①time String No
switchInfo1TimeUnit Line data/Switching data①unit String No
switchInfo2StartDay Line data/Switching data②Start date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
switchInfo2EndDay Line data/Switching data②End date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
switchInfo2ImpactTime Line data/Switching data②time String No
switchInfo2TimeUnit Line data/Switching data②unit String No
vpSwitchDateStartDay Line data/VP Switching schedule Start date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
vpSwitchDateEndDay Line data/VP Switching schedule End date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
vpSwitchDateImpactTime Line data/V PSwitching schedule time String No
vpSwitchDateTimeUnit Line data/VP Switching schedule unit String No
vpCutBackDateStartDay Line data/VP Scheduled return Start date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
vpCutBackDateEndDay Line data/VP Scheduled return End date-time
yyyy-MM-ddTHH:mm:ss.SSS+0900 format
String No
vpCutBackDateImpactTime Line data/VP Scheduled return time String No
vpCutBackDateTimeUnit Line data/VP Scheduled return unit String No

Example Result

{
  "totalCount": "1",
  "pageNumber": "1",
  "pageSize": "10",
  "prePageNumber": "1",
  "nextPageNumber": "1",
  "firstPageNumber": "1",
  "lastPageNumber": "1",
  "items": [
    {
      "lastModifiedAc": "2018-01-04T12:24:33.506+0900",
      "agmUuid": "5E23F123456789123456789123456789",
      "lineContractId": "N123456789",
      "switchInfo1StartDay": "2018-01-26T03:00:00.000+0900",
      "switchInfo1EndDay": "2018-01-26T05:00:00.000+0900",
      "switchInfo1ImpactTime": "3",
      "switchInfo1TimeUnit": "1",
      "switchInfo2StartDay": null,
      "switchInfo2EndDay": null,
      "switchInfo2ImpactTime": null,
      "switchInfo2TimeUnit": null,
      "vpSwitchDateStartDay": null,
      "vpSwitchDateEndDay": null,
      "vpSwitchDateImpactTime": null,
      "vpSwitchDateTimeUnit": null,
      "vpCutBackDateStartDay": null,
      "vpCutBackDateEndDay": null,
      "vpCutBackDateImpactTime": null,
      "vpCutBackDateTimeUnit": null
    }
  ]
}

 ■The way to judge Start Day, End Day and Impact Time of Planned Outage
 ・Start Day
  (1) Set 「vpSwitchDateStartDay」 or 「vpCutBackDateStartDay」, which has value.
  (2) In case of both「vpSwitchDateStartDay」 and 「vpCutBackDateStartDay」 has value,
    set one which has earlier date.
  (3) Set 「Switching data①」 or 「Switching data②」, which has value.
  (4) In case of both「Switching data①」 and 「Switching data②」 has value,
    set one which has earlier date.

 ・End Day
  (1) set 「vpSwitchDateEndDay」 or 「vpCutBackDateEndDay」, which has value.
  (2) In case of both「vpSwitchDateEndDay」 and 「vpCutBackDateEndDay」 has value,
    set one which has earlier date.
  (3) set 「Switching data①」 or 「Switching data②」, which has value.
  (4) In case of both「Switching data①」 and 「Switching data②」 has value,
    set one which has earlier date.

 ・Impact Time
  (1) In case「method, time, unit, number of times」of vpSwitch, set it.
  (2) In case「method, time, unit, number of times」of vpCutBack, set it.
  (3) In case「method, time, unit, number of times」of Switching data①, set it.
  (4) In case「method, time, unit, number of times」of Switching data②, set it.

Planned Outage Info API(Best Effort Plan)

 By using this API, you can get Planned Outage information of Arcstar Universal One Best Effort Plan filtered by VPN group ID, product code, contract ID and area code in JSON format.

To get the detail information of Planned Outage

GET /v1/uno/maintenance?plan=besteffort&vpnGroupId={vpnGroupId}&contractid={contractid}&areacode={areacode}&goodscode={goodscode} 

Request Parameters

Name Description Type Mandatory
plan specify construction information plan
fixed value:besteffort
query argument Yes
vpnGroupId VPN Group ID
e.g.'V'+8 digit number
query argument Yes
contractId Specify the contract ID
e.g.'N'+9 digits number
query argument No
areaCode specify area code
area code: 3 digit number
query argument No
goodsCode Specify product code
Fixed value: vpn-besteffort
query argument Yes

Area Code

Location code Prefecture code
301: Hokkaido 401: Hokkaido
302: Tohoku 402: Aomori, 403: Iwate, 404: Miyagi, 405: Akita, 406: Yamagata, 407: Fukushima
303: Kanto 408: Tokyo, 409: Kanagawa, 410: Saitama, 411: Chiba, 412 Ibaraki, 413: Tochigi, 414: Gunma
304: Tokai 421: Aichi, 422: Gifu, 423: Shizuoka, 424: Mie
305: Koushinetsu 415: Yamanashi, 416: Niigata, 417: Nagano
306: Hokuriku 418: Toyama, 419: Ishikawa, 420: Fukui
307: Kinki 425: Osaka, 426: Hyogo, 427: Kyoto, 428: Shiga, 429: Nara, 430: Wakayama
308: Chugoku 431: Tottori, 432: Shimane, 433: Okayama, 434: Hiroshima, 435: Yamaguchi
309: Shikoku 436: Tokushima, 437: Kagawa, 438: Ehime, 439: Kochi
310: Kyushu 440: Fukuoka, 441: Saga, 442: Nagasaki, 443: Kumamoto, 444: Oita, 445: Miyazaki, 446: Kagoshima, 447: Okinawa|.

Example Request

GET /v1/uno/maintenance?plan=besteffort&vpnGroupId=V12345678&contractId=N123456789&areaCode=408&goodsCode=vpn-besteffort     
HEADER Authorization: Bearer [YOUR_ACCESS_TOKEN]*
* Please refer to the OAuth API page for token acquisition.

Response Parameters

Name Description Type Mandatory
title Construction / fault title String No
kind Construction / trouble type
1: Construction 2: trouble
Int No
kindDescription Construction / trouble type name String No
code Construction / trouble ID String No
displayUpdateDate updated date for display(JST)
yyyy-MM-ddTHH:mm+0900 format(JST)
String No
displayUpdateDateUtc updated date for display(UTC)
yyyy-MM-ddTHH:mmZ format(UTC)
String No
maintenanceStatus Maintenance status
1: Before Construction 2: Under Construction 3: Done
Int No
maintenanceStatusDescription Maintenance status name String No
troubleStatus Trouble status 1: Failed 2: Restored Int No
troubleStatusDescription trouble status name String No
importantFlg Important flag
0: Normal (0 for faults fixed) 1: Important
Int No
importantDescription Important Description String No
maintenanceStartDate Maintenance start date
yyyy-MM-ddTHH:mm+0900 format(JST)
String No
maintenanceEndDate Maintenance end date
yyyy-MM-ddTHH:mm+0900 format(JST)
String No
troubleOccuredDate Trouble occured date
yyyy-MM-ddTHH:mm+0900 format(JST)
String No
troubleRestoreDate Trouble restore date
yyyy-MM-ddTHH:mm+0900 format(JST)
String No
maintenanceStartDateUtc Maintenance Start Date(UTC)
yyyy-MM-ddTHH:mmZ format(UTC)
String No
maintenanceEndDateUtc Maintenance End Date(UTC)
yyyy-MM-ddTHH:mmZ format(UTC)
String No
troubleOccuredDateUtc Trouble occured date(UTC)
yyyy-MM-ddTHH:mmZ format(UTC)
String No
troubleRestoreDateUtc Trouble restore date(UTC)
yyyy-MM-ddTHH:mmZ format(UTC)
String No
targetArea Affected area code String No
mainTextPc Text for PC site String No
influencedPlanDisplay Affected service (for screen display)
Services that are affected by actual screen display during construction / fault registration
String No
targetFacilityDisplay Affected facility (for screen display)
Facility that are affected by actual screen display during construction / fault registration
String No
targetAreaDisplay Affected area (for screen display)
Area that are affected by actual screen display during construction / fault registration
String No

Example Result

{
  "items": [
    {
      "title": "【L3 ベストエフォート】青森県エリア地域IP網メンテナンス工事のお知らせ",
      "kind": 1,
      "kindDescription": "工事",
      "code": "12001",
      "displayUpdateDate":"2018-10-19T15:04+0900",
      "displayUpdateDateUtc":"2018-10-19T06:04Z",
      "maintenanceStatus": 3,
      "maintenanceStatusDescription": "完了",
      "troubleStatus": "",
      "troubleStatusDescription": "",
      "importantFlg": 0,
      "importantDescription": "通常",
      "maintenanceStartDate": "2018-10-26T00:00+0900",
      "maintenanceEndDate": "2018-10-26T06:00+0900",
      "troubleOccuredDate": "",
      "troubleRestoreDate": "",
      "maintenanceStartDateUtc": "2018-10-25T15:00Z",
      "maintenanceEndDateUtc": "2018-10-25T21:00Z",
      "troubleOccuredDateUtc": "",
      "troubleRestoreDateUtc": "",
       "targetArea": "402",
      "mainTextPc": "特定加入者回線部分のアクセスポイントで、工事時間帯において一時的にご利用できなくなる場合がございます。",
      "influencedPlanDisplay": "特定加入者回線部分(光ネクスト)",
      "targetFacilityDisplay": "",
      "targetAreaDisplay": "青森県エリアの全域"
    }
  ]
}


  1. Dec. 2014 currently, DNS round robin operation. Apr. 2015 or later, API request will automatically connect to geographically close API gateway