Skip to main content
Index

Get Generator and Generator Tag Information over Rest API

Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix IBX SmartView, contact your local Equinix Service Desk. 

Step 2: Get a list of all the assets

The first step is to get a list of all the assets to which a given customer has visibility. Invoke the IBX SmartView API below by providing your Equinix customer account number, your IBX code, for e.g. CH1 and the classification, such as electrical to obtain a list of all the electrical assets that are visible to you. For example, here we will get a Generator (electrical generator) and some key attributes of the Generator, such as alarmStatus, resiliencyStatus, alarmLastTriggeredTime and alarmLastCleared. All other electrical assets are also returned as part of the response.

The following screenshots show a sample curl request to fetch the list of assets for the account number. 

 

curl -X 

GET "https://api.equinix.com/asset/v1/list?accountNo=1&ibx=CH1&classification=Electrical"     

-H "content-type: application/json"                                                                            
-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The list of all electrical assets including generators is returned as shown in the partial result below.

 

{
  "payLoad": {
    "classification": "Electrical",
    "categories": [
      {
        "templates": [
          {
            "assets": [
              {
                "assetId": "CH1.Gen-1",
                "ibx": "CH1",
                "alarmStatus": "OK",
                "resiliencyStatus": "Resiliency as Designed",
                "alarmLastTriggeredTime": "Sep 16,2016 04:41 PM",
                "alarmLastClearedTime": "Sep 16,2016 04:43 PM"
              },
              {
                "assetId": "CH1.Gen-2",
                "ibx": "CH1",
                "alarmStatus": "OK",
                "resiliencyStatus": "Resiliency as Designed",
                "alarmLastTriggeredTime": "Sep 20,2016 04:48 PM",
                "alarmLastClearedTime": "Sep 20,2016 04:53 PM"
              },
              {
                "assetId": "CH1.Gen-3",
                "ibx": "CH1",
                "alarmStatus": "OK",
                "resiliencyStatus": "Resiliency as Designed",
                "alarmLastTriggeredTime": "Oct 04,2016 07:54 AM",
                "alarmLastClearedTime": "Oct 04,2016 08:41 AM"
              }
            ],
            "templateId": "Generator"
          }
        ],
        "categoryName": "Global"
      }
    ]
  },
  "status": {
    "type": "INFO",
    "statuscode": "1000",
    "msg": "OK"
  }
}

 

Refer to Get Assets List under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details. 

Step 3: Get Asset details

If you pick one of these assets and you want more details on the asset attributes, you can use the asset details API. You can do so by, specifying the account number, IBX code, specific asset ID and its electrical or mechanical classification. Upon invoking the API, you will see for example, for CH1, the asset with type generator is returned along with its three other attributes. Among these attributes; fuelHours is one, the current value of which is the time and unit of measure, in hours. Another attribute is currentAlarmStatus, along with several other attributes such as runningEmergencyServices (yes or no), and voltage (0 volts). You can replace the assetId that was returned from the asset list API call and retrieve the attributes of another asset.

The following screenshots show a sample curl request to get assets details for a given account number, assetId, and classification.

 

curl -X 

GET "https://api.equinix.com/asset/v1/details?accountNo=1&ibx=CH1&assetId=CH1.Gen-1&classification=Electrical"

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

Details of the given generator are returned as shown below.

 

{
  "payLoad": {
    "assetId": "CH1.Gen-1",
    "assetType": "Generator",
    "userPrefTimeZone": "America/Los_Angeles",
    "tags": [
      {
        "value": "78.5",
        "tagId": "CH1.Gen-1:fuelhours",
        "tagDisplayName": "Fuel Hours",
        "uom": "h",
        "alarmStatus": "OK",
        "readingTime": "20190324023353"
      },
      {
        "value": "0",
        "tagId": "CH1.Gen-1:runningemergencyservice",
        "tagDisplayName": "Running Emergency Service",
        "uom": "",
        "alarmStatus": "OK",
        "readingTime": "20190324023421"
      },
      {
        "value": "0.0",
        "tagId": "CH1.Gen-1:voltage",
        "tagDisplayName": "Voltage",
        "uom": "V",
        "alarmStatus": "OK",
        "readingTime": "20190324022309"
      },
      {
        "value": "NORMAL",
        "tagId": "CH1.Gen-1:alarm",
        "tagDisplayName": "Alarm",
        "uom": "",
        "alarmStatus": "OK",
        "readingTime": "20190324022351"
      },
      {
        "value": "0",
        "tagId": "CH1.Gen-1:runningnonemergencyservice",
        "tagDisplayName": "Running NonEmergency Service",
        "uom": "",
        "alarmStatus": "OK",
        "readingTime": "20190324023421"
      },
      {
        "value": "READY TO START, AUTO",
        "tagId": "CH1.Gen-1:summary",
        "tagDisplayName": "Summary",
        "uom": "",
        "alarmStatus": "OK",
        "readingTime": "20190324023421"
      }
    ],
    "lastMaintenanceDate": "Mar 17,2019",
    "manufacturerName": "CATERPILLAR",
    "equipmentModelNumber": "SR-4B",
    "equipmentSerialNumber": "5JW00638",
    "alarmLastTriggeredTime": null,
    "alarmLastProcessedTime": null
  },
  "status": {
    "type": "INFO",
    "statuscode": "1000",
    "msg": "OK"
  }
}

 

Refer to Get Asset Details under the API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details. 

Step 4: Get affected locations for a given asset

As a next step you may want to get all the affected locations of assets with a given assetId. This call will return all your cages and cabinets in power circuits that are being serviced by the asset. To make the call for affected assets, you will need to provide your customer account number, your IBX code and the assetId which was initially procured via a call to the API which fetches the list of assets. If the classification is electrical, then you will obtain information on the cage, cabinet and power circuits that are being serviced by that particular asset. This offers information on your assets that are impacted by the particular asset, for example, ASTS (Automatic static transfer switch).

The following screenshots show a sample curl request to get supported location assets for a given account number, classification, and assetId. 

 

curl -X 

GET "https://api.equinix.com/asset/v1/tagpoint/affected-assets?accountNo=1&ibx=CH1&classification=Electrical&assetId=CH1.ASTS-1-2-A"

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The call returns a list of all the location assets that are supported by the assetId above.

 

{
  "payLoad": {
    "cages": [
      {
        "name": "CH1:05:BCM000",
        "type": "cage",
        "cabinets": [
          {
            "name": "CH1:05:BCM000:9999",
            "type": "cabinet",
            "circuits": [
              {
                "name": "14488436",
                "type": "circuit"
              },
              {
                "name": "M10294567",
                "type": "circuit"
              },
              {
                "name": "20679430",
                "type": "circuit"
              }
            ]
          }
        ],
        "circuits": null
      },
      {
        "name": "CH1:05:FE00021",
        "type": "cage",
        "cabinets": [
          {
            "name": "CH1:05:FE00021:0101",
            "type": "cabinet",
            "circuits": [
              {
                "name": "20744057",
                "type": "circuit"
              }
            ]
          }
        ],
        "circuits": null
      }
    ]
  },
  "status": {
    "type": "INFO",
    "statuscode": "1000",
    "msg": "OK"
  }
}

 

Refer to Get affected locations for given assets under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details. 

Step 5: Get tag for a given asset

The next API that we can call is that which fetches the tag for an asset. A tag is an attribute of a specific asset which can have one or more tags. This API accepts the account number, IBX code, and tag ID as inputs to return the current value of that asset attribute or tag. For example, for the generator attribute fuelHours, you can obtain the current value which is a number denoting the number of hours, and the unit of measure in “hours”. The value returned for this attribute would be the last read value. If you need to retrieve more than one attribute, you can use the post flavor of this API.

The following screenshot shows the curl request to get a generator tagpoint fuelhours. 

 

curl -X 

GET "https://api.equinix.com/asset/v1/tagpoint/current?accountNo=1&ibx=CH1&tagId=CH1.Gen-1:fuelhours"

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

This call returns all the tagpoint details for fuelhours as shown below.

 

{
    "payLoad": [
        {
            "value": "77.9",
            "tagId": "CH1.Gen-1:fuelhours",
            "tagDisplayName": "Fuel Hours",
            "uom": "h",
            "readingTime": "20190324033354"
        }
    ],
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

Refer to Get tag point for a given asset under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details.