https://developer.equinix.com
For Public Viewing
body: 

Legend        Don't like reading - How about a 1-minute video?       Ask us

 

What is Equinix IBX SmartView?

Equinix IBX SmartView is a Data Center Infrastructure Monitoring (DCIM) solution. It allows customers to have, real-time access to environmental and operating information relevant to the IBX footprint as if those cages were all in-house. It provides the ability to get information for the Environmental, Mechanical, Electrical assets and Power draw. The picture below provides a high-level overview of IBX SmartView.

 

IBX SmartView High-Level Overview

 

Equinix IBX SmartView is offered to customers via web applications and via REST and Real-time APIs.  IBX SmartView API architecture is powered by the DCIM platform.

 

IBX SmartView

Our SAAS application, that provides unmatched visibility into core infrastructure at the local zone, cage, and cabinet-level. It provides, data that is relevant to customers, presented the same way for all IBX SmartView IBXs globally. It also provides you actionable insight that allows you to react to important events and proactively plan via configurable reports & alerts.

 

IBX SmartView APIs

Through a comprehensive set of REST Application Programming Interfaces (APIs) and supportive real-time APIs for partners as an extension of IBX SmartView, customers have greater flexibility to utilize data through near real-time and pragmatic REST APIs. They can also use IBX SmartView APIs to integrate core IBX SmartView data (environmental, power draw, mechanical and electrical) into third-party monitoring systems.

 


body: 

What are Equinix IBX SmartView APIs?

IBX SmartView APIs allow customers to build real-time dashboards and integrate real-time feeds with their automation systems. These APIs are classified into two categories:

 

  1. Near real-time APIs
  2. RESTful APIs

 

Near real-time APIs provide real-time, actionable information for both API and IBX SmartView users. APIs are defined in the form of events and objects. API developers can integrate APIs into their existing applications via secure subscription channels that integrate with multiple clouds. Integrating with near real-time events allows customers to respond to critical updates related to their core infrastructure in near real-time. 

REST APIs are ideal for developers looking to build applications that leverage IBX SmartView data. Customers who use REST APIs can seamlessly integrate the data into third-party applications. The APIs allow developers to retrieve data for core infrastructure components such as power draw, environmental and infrastructure assets, as well as, alarms, alerts, and notifications.

Both, REST and Real-time APIs allow developers to interact with Equinix IBX SmartView programmatically to monitor their data center infrastructure. (Refer API reference section or Catalog for more details.)  The diagram below presents an overview of the API architecture.

 

 

IBX SmartView Rest APIs  

The REST APIs provide customers the ability to fetch information about their assets at every IBX location. There are APIs for all the different asset classifications, alerts, and power. 

  • Hierarchy API  - Provides access to all IBX infrastructure asset details directly supporting a customer's cage, cabinet, or power circuit. Given an IBX, it allows retrieval of the cage, cabinet or circuit information which are deployed at the location.
  • Assets API - Provides visibility into the core mechanical or electrical assets and their operating status, for each customer's IBX footprint. Given an IBX, it allows retrieval of all information about the Equinix assets that are serving the colocation footprint at the location.
  • Power API  - Provides the power usage data for the cabinets and circuits. Given an IBX, it allows retrieval of all information about the power assets at the location.
  • Environmental API - Provides access to the environmental and operating information as if those cages were managed in-house. Given an IBX, it allows retrieval of all information about the environmental assets at the location.
  • Alarm API -  Provides the ability to get all the alarms that have ever triggered at the various IBX locations.
  • Alert API - Provides the ability to get all the configured push notification alerts. Configurable alerts ensure customers are notified when important events occur.
  • Subscription API - APIs for creating and managing near real-time feed subscriptions.

The REST APIs are useful for getting assets metadata for Equinix assets powering the infrastructure for a given customer. They also provide the ability to get the historical data collected from these assets over a period of time.

 

IBX SmartView Near Real-Time APIs 

The Near-Real-Time streaming APIs, are shown on the right-hand side of the diagram above, allow for streaming the data to an asynchronous channel. This data is collected from various IBX locations. The data that is collected at the different IBX locations, is streamed in near real-time to the subscriber. The data streaming is currently available on Google pub-sub, Amazon Web Services SNS and Microsoft Azure Service Bus channels via subscription.

Streaming data can also be retrieved in a machine native protocol such as SNMP an OPC, via a private async channel. This allows customers to integrate the data streams with their existing on-premise applications. Please reach out to the api-support@equinix.com for more details.

  • Tagpoint updated event - An asset tagpoint value for either was updated/received.
  • Power updated event  - A power usage value was updated/received.
  • Environment updated event - An environment value for temperature or humidity was updated/received.
  • Alarm updated event - An alarm was updated/received.
  • Alert updated event - An alert was updated/received.

 

Developer Portal 

The developer portal is a platform for accessing all the customer-facing APIs across all Equinix product lines. It allows developers to test drive their APIs using the playground features. It's intuitive and easy to use and allows developers to explore and deep dive into the individual APIs. It provides a preview of any upcoming APIs as well. 

 


body: 

How Equinix IBX SmartView APIs work?

Background

When a customer is onboarded, they are provided with user credentials. 

 

 

The customer must use these credentials to connect to the Equinix Developer Platform to generate a Consumer key and Consumer secret. 

 

 

The Consumer key and Consumer secret are essential for obtaining access and refresh tokens to authenticate API calls as described in the subsequent section.

 

Refer Generating Client ID and Client Secret key under Getting Started for instructions on how to generate Consumer key and Consumer secret.

 

Authorization flow

Step 1  - Request access and refresh token information by calling the Equinix OAuth API (/oauth2/v1/token) with the Consumer key, Consumer secret, and user credentials. 

 

 

Refer  Requesting Access and Refresh tokens under Getting Started for instructions on how to obtain an Authorization Token.

 

Step 2  - The API gateway makes an OAuth2 call to the identity provider using the submitted credentials.

 

Step 3  - The identity provider returns an OAuth2Access token to the API gateway.

 

Step 4  - The API gateway sends back the authorization token details to the client.

 

REST APIs consumption flow

Step 5  - The customer submits an API request with the obtained authorization token and respective API request payload. 

 

 

Refer How-to Guide section for instructions on how to call Equinix IBX SmartView APIs to establish connections.

 

Step 6  - API gateway validates the request and calls the relevant API.

 

Step 7  - The response is received by the API gateway.

 

Step 8  - The response is sent back to the client.

 

Step 9  - Customer accepts the connection and processes the IBX SmartView APIs response. 

 

Real-Time APIs consumption flow

Step 10 - Repeat steps 1 - 9 above to subscribe to a real-time feed.

 

Refer to Subscriptions APIs for details on how to subscribe to a real-time feed.

How-to Guide section for instructions on how to accept connections using Equinix IBX SmartView APIs.

 

Step 11 - Create a client to consume the real-time feed.

 

 

Refer to IBX SmartView samples for a sample client for consuming real-time feeds. 

 


body: 

How-to Guide for IBX SmartView use cases

Learn how to monitor a variety of assets using IBX SmartView APIs!

•   Environmental - Monitoring Temperature and Humidity
•   Power Draw - Monitoring Power Usage and Caps
•   Mechanical - Monitoring Cooling Systems
•   Electrical - Monitoring Power Availability

 

 

Overall, IBX SmartView supports different categories such as electrical assets, mechanical assets, environmental sensors in our assets. Across these different categories, we have the following capabilities:

 

  • Using the Assets REST APIs, you can get the asset information that is serving your colocation footprint in a particular IBX. In addition to the asset information, you can get all attributes of that asset that are exposed to you as a customer for those assets. For example, if you get a PDU electrical asset, you can also get the information about the voltage, the average KVA and other attributes of PDU.
  • Using the Asset Tags REST APIs, you can get the attributes of the asset tags and their current value.
  • Using the Alarms REST API, you can get all the alarms that have triggered across all your IBX locations and then you can filter those alarms by different parameters.
  • Using the Alerts REST APIs, you can get the historical data for alerts that have ever triggered across any of your sites or IBX location. You can also get the alerts that have been triggered but not acknowledged yet. The APIs allow you to get the alert definitions as well.
  • Using the streaming near real-time API, you can get streaming asset tag data as soon as it is collected data from the electrical, mechanical, and environmental sensors we stream them to the subscriber on a public cloud asynchronous channel or a machine native protocol, to your applications.
  • Using alarms near real-time streaming we stream the alarms as they get triggered at the IBX location and also stream the information about them getting cleared and them getting acknowledged by the Equinix operations team. Hence, all three events related to an alarm are stream to you.
  • Using alerts near real-time streaming you can get the alerts as they are getting triggered and getting acknowledged by you that information is streamed for all the various asset categories onto the subscribed streaming channel of your choice.

 


body: 

Pre-requisite

•   You have valid customer credentials.
•   You have been authorized to create, modify and delete connections by your master Admin.
•   You have a valid Client key and Client secret.

 


body: 

Getting Started

Learn the fundamentals of Equinix APIs.

 


body: 

Generating Client ID and Client Secret key

To obtain your client ID (consumer key) and client secret key (consumer secret), you must register your app in the developer portal according to your preferred environment. 

1. Login to Equinix Developer Platform using your login credentials.

 

If you are unaware of your login credentials for Equinix Developer Platform, contact your local Equinix Service Desk.

 

2. After logging in, click on the My Apps section as shown below.

 

 

3. Click on the Create New App button.

 

 

4. You will need to name your app and then select the app type to be used, you can either create an app for the Sandbox or Production environment. Once you’re ready click on the Create App button.

 

The sandbox environment is only a test environment that mimics the production environment and creates simulated API responses. 

If you are not an existing API customer, send an email to api-support@equnix.com to gain access to Equinix sandbox.

 

 

5. You should now have your app listed in the My Apps section as shown below:

 

 

6. When you select the application, your Client ID ( Consumer Key) and Client Secret (Consumer Secret) will be revealed.

 

 


body: 

Requesting Access and Refresh tokens

Access Token Flow

The access token is used to exchange data with the Equinix APIs and the refresh token is used to request a new access token should the access token expire. You can obtain your access token by either using the password or client credentials grant type as shown in the sample curl commands below:

 

The client_credentials grant type is used by users who do not want to use their Equinix login credentials (user name and user password) in exchange for an access token, whereas the password grant type is for users who are less hesitant. 

 

Refer to https://oauth.net/2/grant-types/ for more information about the different grant types and their usage. 

 

Access token using password grant type

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/token'

-H "content-type: application/json" 

-d '{

"grant_type": "password",

"user_name": "john.doe@example.com",

"user_password": "jd1@#$",

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890"

}'

 

Access token using client credentials grant type

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/token'

-H "content-type: application/json"

-d '{

"grant_type": "client_credentials",

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
grant_type Yes string password

"password"

"client_credentials"

Different ways to authorize access to resources. It indicates the type of grant to be presented in exchange for an access token.
user_name Yes string john.doe@example.com   The Equinix login username. This field is optional for client credentials grant type.
user_password Yes string jd1@#$   The Equinix login password. This field is optional for client credentials grant type.
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Portal.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer portal.
password_encoding No string md5-b64 "md5-b64"

An optional field for users who wish to encrypt their password when requesting an access token. Currently, only “md5-b64” hashing is supported. This field is only applicable to users who use password grant. 

 

 

Click here to learn how to encrypt your password using md5-b64 hashing.

 

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to create a client ID and client secret.

 

If you are unaware of your user credentials for the Equinix Developer Platform, contact your local Equinix Service Desk. 

 

Once authenticated, the respective token and timeout details will be sent to you as shown in the sample JSON responses below.

 

Sample response when using password grant type

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

    "refresh_token": "zxcvbn1JKLMNOPQRSTU",

    "refresh_token_timeout": "5184000"

}

 

Refresh token details will only be sent to customers that use password grant.

 

Sample response when using client credentials grant type

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

}

 

The description of the response payload is as follows:

 

Field Name Type Example Applicable Values Description
access_token string qwErtY8zyW1abcdefGHI   The authorization token to be used in subsequent API calls. 
token_timeout string 3600   The lifetime of an access token in seconds. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
user_name string john.doe@example.com   The Equinix login username.
token_type string Bearer

"Bearer"

The type of token. 
refresh_token string zxcvbn1JKLMNOPQRSTU   Access tokens have limited lifetimes. If your application needs access to an API beyond the lifetime of a single access token, you can obtain a refresh token. A refresh token allows your application to obtain new access tokens. This information is only applicable to "password" grant users. 
refresh_token_timeout string 5184000   The lifetime of a refresh token in seconds. For example, the value "5184000" denotes that the refresh token will expire in 60 days from the time the response was generated. This information is only applicable to "password" grant users.

 

To make a request to Equinix APIs, add the Authorization header to the HTTP request with the word "Bearer" prepended to the access token. For example with curl use,  -H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Refresh Token Flow

You can use a valid refresh token to obtain new access tokens to be used in API calls. A refresh token is valid for 60 days. You must submit your Client ID, Client Secret and Refresh Token to obtain refresh access tokens as shown in the sample curl command below.

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/refreshaccesstoken'

-H "content-type: application/json" 

-d '{

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890",

"refresh_token": "zxcvbn1JKLMNOPQRSTU"

}'

 

The description of the body parameters are as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Portal.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer portal.
refresh_token Yes string zxcvbn1JKLMNOPQRSTU   A refresh token allows your application to obtain a new access token and is provided in the response payload of an access token call.

 

Once requested, a new set of access token, refresh token, and timeout details will be sent to you.

 

{

    "access_token": "1abcdefGHIqwErtY8zyW",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

    "refresh_token": "1JKLMNOPQRSTUzxcvbn",

    "refresh_token_timeout": "5184000"

}

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to create a client ID and client secret.

 


body: 

Get Generator and Generator Tag information over Rest API

 


body: 

Step 1: Authenticate

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

 

Refer Generating Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer 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. 

 


body: 

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. Using IBX SmartView API below you can provide your Equinix customer account number, your IBX code, for e.g. CH1 and the classification, such as electrical. Invoking this API will return 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, alarmLastCleared. All other electrical assets are also returned as part of the response.

The following screenshots show a sample curl request to get the assets list 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"
  }
}

 

The description of the response payload is as follows:

 

Refer 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. 

 


body: 

Step 3: Get Asset details

If you pick one of these assets and you want more details of the asset which means the attributes of the assets you can use the asset details API. You can do so by, specifying the account number, the IBX code, the specific asset ID and its classification electrical or mechanical. Upon invoking the API, you will see that for CH1 the asset with type generator is returned along with the three other attributes of this asset. For example, fuelHours is one attribute, and the current value this attribute is the time and the unit of measure for this value is in hours. Another attribute is the currentAlarmStatus, along with several other attributes such as runningEmergencyServices (yes or no), voltage (0 volts), etc. 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 the 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' 

 

The 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 Get Asset Details under API Reference section for instructions on how to get asset details. You may skip this step if you already know the asset details. 

 


body: 

Step 4: Get affected locations for a given asset

As a next step you may want to get all the affected location assets given an assetId. This call will return all your cages and cabinets in power circuits that are being serviced by the given asset. In order to make the affected assets call, you will need to provide your customer account number, your IBX code and the assetId which was initially obtained via a call to the get asset list API. If the classification is electrical, then you will get the cage, cabinet and power circuits that are being serviced by that particular asset. This is a very good way to get your assets that are impacted by the particular asset, in this example we choose an ASTS (Automatic static transfer switch).

The following screenshots show a sample curl request to get supported location assets for the 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 Get affected locations for 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. 

 


body: 

Step 5: Get tag for a given asset

The next API that we can call is the get tag API. A tag is an attribute of a specific asset, and an asset can have one or more tags. This API accepts the account number, the IBX code, and the tag ID as an input and gives you the current value of that asset attribute or tag, in the response. For example, for the generator attribute fuelHours, you can get the current value which is a number denoting the number of hours, and the unit of measure is “hours”. The value returned for this attribute would be the last read value. This is a good way for getting the current snapshot of that particular attribute. If you need to retrieve more than one attribute, you can use the post flavor of the 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' 

 

The 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 Get tag point for 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. 

 


body: 

How to Get All alarms over Rest API

 


body: 

Step 1: Authenticate

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

 

Refer Generating Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer 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. 

 


body: 

Step 2: Get a list of all the alarms

Alarms API provides one endpoint Get all active alarms. Using this endpoint you can retrieve all the alarms that have triggered on all the assets serving your colocation footprint, across all of the IBX locations. You can filter down on those alarms using various parameters. In order to access the API you need to specify the Auth bearer token in the header, specify the account no, number of records you to want returned and the offset to start from. You can specify the groupByIBX to group the alarms by IBX.

In order to invoke the API call, provide the token, account number, page number 1, 10 records per page, offset 0 as input. The response includes a payload of a set of alarms.

The response includes fields like the IBX. AccountNo, assetId, asset type is UPS, severity is Urgent, status is active or not, ack true or false indicating whether Equinix ops team acknowledged the alarm or not. Tagid on which the alarm had triggered. Time at which the tag got processed. It also tells, if the given alarm condition returned to normal or if the status turns to false. This set of attributes is repeated for each alarm.

The following screenshot shows the curl request to get all active alarms. 

 

curl -X 

GET "https://api.equinix.com/alarm/v1/smartview/alarms?accountNo=1&limit=10"

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

List of all active alarms for affiliated to your customer account are returned below.

 

{
    "alarms": [
        {
            "ibx": "DC5",
            "accountNo": "1",
            "assetId": "DC5.UPS-R1",
            "assetType": "UPS",
            "assetClassification": "Electrical",
            "conditionName": "Alarm",
            "severity": "Urgent",
            "status": true,
            "ack": true,
            "tagId": "DC5.UPS-R1:alarm",
            "customerId": "ALL",
            "timeProcessed": 1550519327497,
            "timeTrigerred": 1546510663707,
            "timeNormalProcessed": 0,
            "customerassets": []
        },
        {
            "ibx": "CH3",
            "accountNo": "1",
            "assetId": "CH3.PDU-A3.A5",
            "assetType": "PDU",
            "assetClassification": "Electrical",
            "conditionName": "Alarm",
            "severity": "Urgent",
            "status": true,
            "ack": true,
            "tagId": "CH3.PDU-A3.A5:alarm",
            "customerId": "ALL",
            "timeProcessed": 1550322722748,
            "timeTrigerred": 1550071367746,
            "timeNormalProcessed": 0,
            "customerassets": []
        },
        {
            "ibx": "CH3",
            "accountNo": "1",
            "assetId": "CH3.STS-B1.A5",
            "assetType": "ASTS",
            "assetClassification": "Electrical",
            "conditionName": "Alarm",
            "severity": "Urgent",
            "status": false,
            "ack": false,
            "tagId": "CH3.STS-B1.A5:alarm",
            "customerId": "ALL",
            "timeProcessed": 1550509311772,
            "timeTrigerred": 1546342538650,
            "timeNormalProcessed": 1550509435530,
            "customerassets": []
        }
    ],
    "groupedAlarms": null,
    "totalCount": 2389
}

 

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

 


body: 

How to Get Temperature and Humidity information in Near Real-Time

 

Steps to retrieve real-time environmental data such as temperature and humidity for your cage and cabinets are shown below.

 

 


body: 

Via GCP Pubsub


body: 

Step 1: Create a real time channel subscription

1a) Authenticate

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

 

Refer Generating Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer 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. 

 

1b) Get a subscription

The first step is to create a subscription.

 

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

 


body: 

Step 2: Get Authenticate with Google pub sub

Authenticate with Google pub-sub using the access token and subscription URL from previous step.

 


body: 

Step 3: Setup and configuration

 

3 a) Download and setup RealTime feed consumer code.

 

3 b) Configure the following ENV variable while running the code. GOOGLE_APPLICATION_CREDENTIALS=/localpath/client_secrets.json

 

3 c) Execute the class com.equinix.dcim.subscriber.FeedTest with method init

 

package main;

import java.util.Properties;
import java.util.concurrent.TimeUnit;
import com.equinix.dcim.subscriber.Feed;
import com.equinix.dcim.subscriber.goog.GoogleConfiguration;
import com.equinix.dcim.subscriber.impl.FeedImpl;

public class FeedTest {
	  public static void main(String args[]) throws Exception {
	        Feed feed = new FeedImpl();
	        Properties props = new Properties();

	        GoogleConfiguration googleConfiguration = new GoogleConfiguration("eighth-pursuit-162421", "equinix_uat1");
	        feed.registerConsumer((x) -> {
	            System.out.println(x.toString());
	        });

	        feed.init(googleConfiguration);
	        int i = 0;
	        System.out.println("Started!!!");
	        while (i < 2) {
	            TimeUnit.SECONDS.sleep(600);
	            i++;
	        }
	    }
}

 

3 d) Send email to api-support@equinix.com  to request for the client secret file “client_secrets.json” for read access.

 


body: 

Step 4: Retrieve the near real-time feeds 

Retrieve the near real-time feeds using the subscription URL that the consumer had created in Step 3.

 


body: 

Via AWS SNS


body: 

Step 1: Create a real time channel subscription

1a) Authenticate

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

 

Refer Generating Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer 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. 

 

1b) Get a subscription

The first step is to create a subscription.

 

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

 


body: 

Step 2: Authenticate with AWS SNS

Authenticate with AWS SNS using the access token and subscription URL from previous step.


body: 

Step 3: Setup and configuration

3a) Download and setup RealTime feed consumer code.

 

3b) Configure the following ENV variable while running the code. GOOGLE_APPLICATION_CREDENTIALS=/localpath/client_secrets.json

 

3c) Execute the class com.equinix.dcim.subscriber.FeedTest with method init

 

AWS_CREDENTIAL_PROFILES_FILE=/Users/apps/aws_client_secrets.json
 
import com.amazonaws.regions.Regions;
import com.amazonaws.services.logs.AWSLogsClient;
import com.amazonaws.services.logs.AWSLogsClientBuilder;
import com.amazonaws.services.logs.model.GetQueryResultsRequest;
import com.amazonaws.services.logs.model.StartQueryRequest;
import com.amazonaws.services.logs.model.StartQueryResult;
import com.google.common.util.concurrent.Uninterruptibles;

import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.TimeUnit;

    String awsCloudLogGroupName="/aws/lambda/testawssns";
    AWSLogsClient awsLogsClient = (AWSLogsClient) AWSLogsClientBuilder.standard()
                .withRegion(Regions.US_EAST_2).build();
        StartQueryRequest startQueryRequest = new StartQueryRequest();
        String query = "fields @timestamp, @message " +
                "| sort @timestamp desc " +
                "| limit 20";
        startQueryRequest.setLogGroupName(awsCloudLogGroupName);
        long epocSecStartTime = LocalDateTime.now().minusHours(2).toEpochSecond(ZoneOffset.UTC);//last 2 hour
        startQueryRequest.setStartTime(epocSecStartTime);
        startQueryRequest.setEndTime(System.currentTimeMillis());
        startQueryRequest.setQueryString(query);
        StartQueryResult startQueryResult = awsLogsClient.startQuery(startQueryRequest);
        GetQueryResultsRequest getQueryResultsRequest = new GetQueryResultsRequest();
        getQueryResultsRequest.withQueryId(startQueryResult.getQueryId());
        List list = new ArrayList();
        int attempts = 0;
        while (attempts++ < 10) {
            Uninterruptibles.sleepUninterruptibly(1, TimeUnit.SECONDS);
            list = awsLogsClient.getQueryResults(getQueryResultsRequest).getResults();
            System.out.println(list);
            if (!list.isEmpty()) {
                break;
            }
        }
    }

 

3d) Send email to api-support@equinix.com  to request for the client secret file “client_secrets.json” for read access.

 


body: 

Step 4: Retrieve the near real-time feeds 

Retrieve the near real-time feeds using the subscription URL and the consumer created above.

 


body: 

Via Azure Service Bus


body: 

Step 1: Create a near real-time channel subscription

1a) Authenticate

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

 

Refer Generating Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer 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. 

 

1b) Get a subscription

The first step is to create a subscription.

 

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

 


body: 

Step 2: Authenticate with Azure Service Bus

Authenticate with Azure Service Bus using the access token and subscription URL from the previous step.


body: 

Step 3: Setup and configuration

3 a) Download and setup NearRealTime feed consumer code.

 

3 b) Configure the following ENV variable while running the code. GOOGLE_APPLICATION_CREDENTIALS=/localpath/client_secrets.json

 

3 c) Execute the class com.equinix.dcim.subscriber.FeedTest with method init

 

AZURE_AUTH_LOCATION=/Users/apps/my.azureauth.cred
import com.microsoft.azure.servicebus.*;
import com.microsoft.azure.servicebus.primitives.ConnectionStringBuilder;
import com.microsoft.azure.servicebus.primitives.ServiceBusException;

import java.time.Duration;
import java.util.concurrent.CompletableFuture;
import java.util.function.Consumer;
import java.util.function.Function;
 
String subscriptionName="TOPIC_AZURE_7786/subscriptions/TOPIC_AZURE_7786_subscriber";
String  connectionString="Endpoint=sb://equinix.servicebus.windows.net/;SharedAccessKeyName=READ_ONLY_RULE;SharedAccessKey=mWiElYxO+GU3iyoS0wCnKaGT9vhc93sB4WmIzLyBQQY=;EntityPath=TOPIC_AZURE_7786";
 
SubscriptionClient azureClient = new SubscriptionClient
        (new ConnectionStringBuilder(connectionString, subscriptionName), ReceiveMode.PEEKLOCK);
IMessageHandler messageHandler = new IMessageHandler() {
    public CompletableFuture onMessageAsync(IMessage message) {
        if (message.getContentType().contentEquals("application/json")) {
            System.out.println("received : " + new String(message.getBody()));
        }
        return azureClient.completeAsync(message.getLockToken());
    }

    public void notifyException(Throwable throwable, ExceptionPhase exceptionPhase) {
        System.out.printf(exceptionPhase + "-" + throwable.getMessage());
    }
};

try {
    azureClient.registerMessageHandler(
            messageHandler,
            new MessageHandlerOptions(10, false, Duration.ofMinutes(1)));
} catch (InterruptedException e) {
    e.printStackTrace();
} catch (ServiceBusException e) {
    e.printStackTrace();
}

 

3 d) Send email to api-support@equinix.com  to request for the client secret file “client_secrets.json” for read access.

 


body: 

Step 4: Retrieve the real-time feeds 

Retrieve the near real-time feeds using the subscription URL that the consumer had created in Step 3.

 

 


body: 

Alarm APIs

 


body: 

Get Active Alarms

GET /alarms/v1/smartview/alarms

 Method  GET
 URL or End Point  /alarms/v1/smartview/alarms
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx
 Body  Not applicable

 

Given a customer account, retrieve all the active alarms. A total count specifying the number of alarms and a list of alarms is returned. If groupByIBX was set to true, then a list of alarm groups is returned. The assetClassification, timeProcessed, conditionName, assetType, tagId, timeNormalProcessed and assetId are returned.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get all active alarms and a JSON response containing the result. 

 

curl -X 

GET "https://api.equinix.com/alarm/v1/smartview/alarms?accountNo=1&limit=10"     

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

limit N integer 0   Specifies the number of records to be retreived.
offset N integer 0   Specifies the index of the starting record.
groupByIBX N boolean true false, true Indicates if the alarms should be grouped by IBX.

 

{
    "alarms": [
        {
            "ibx": "DC5",
            "accountNo": "1",
            "assetId": "DC5.UPS-R1",
            "assetType": "UPS",
            "assetClassification": "Electrical",
            "conditionName": "Alarm",
            "severity": "Urgent",
            "status": true,
            "ack": true,
            "tagId": "DC5.UPS-R1:alarm",
            "customerId": "ALL",
            "timeProcessed": 1550519327497,
            "timeTrigerred": 1546510663707,
            "timeNormalProcessed": 0,
            "customerassets": []
        },
        {
            "ibx": "CH3",
            "accountNo": "1",
            "assetId": "CH3.PDU-A3.A5",
            "assetType": "PDU",
            "assetClassification": "Electrical",
            "conditionName": "Alarm",
            "severity": "Urgent",
            "status": true,
            "ack": true,
            "tagId": "CH3.PDU-A3.A5:alarm",
            "customerId": "ALL",
            "timeProcessed": 1550322722748,
            "timeTrigerred": 1550071367746,
            "timeNormalProcessed": 0,
            "customerassets": []
        },
        {
            "ibx": "CH3",
            "accountNo": "1",
            "assetId": "CH3.STS-B1.A5",
            "assetType": "ASTS",
            "assetClassification": "Electrical",
            "conditionName": "Alarm",
            "severity": "Urgent",
            "status": false,
            "ack": false,
            "tagId": "CH3.STS-B1.A5:alarm",
            "customerId": "ALL",
            "timeProcessed": 1550509311772,
            "timeTrigerred": 1546342538650,
            "timeNormalProcessed": 1550509435530,
            "customerassets": []
        }
    ],
    "groupedAlarms": null,
    "totalCount": 2389
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
alarms array   Array of alarms.
accountNo string 1234 Customer account number.
assetId string CH1.FC2 Indicates the unique identifier for the asset.
assetType string

cooling  

Indicates the template name for the asset.
assetClassificastion string Environmental The class of assets this asset belongs to.
conditionName string High Name given to the alarm condition.
ibx string CH1 The IBX at which the alarm occured.
status boolean true Alarm status.
tagId string CH1.Chiller1:evapleavingwatertemperature Unique identifier for the tag point.
timeProcessed string

Aug 21,2017 04:38 AM

Date-time at which the alarm was processed at tbe IBX.
timeNormalProcessed string

Aug 21,2017 05:52 AM

Date-time at which the normal condition was restored at the IBX.
totalCount integer 10 Total number of alarms

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Asset APIs


body: 

Get Asset list

GET /asset/v1/list

 Method  GET
 URL or End Point  /asset/v1/list
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx, classification cages
 Body  Not applicable

 

Given an account number, IBX code, cage and asset classification (Electrical, Mechanical), returns information about asset in a hierarchical structure comprising of the category, template and asset. Given a category and a template, a list of assets is returned. The response includes the assetId, IBX, alarmStatus, resiliencyStatus, alarmLastTriggeredTime, alarmLastClearedTime information for each asset.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get the assets list for account number 1 and a JSON response containing the result. 

 

curl -X 

GET "https://api.equinix.com/asset/v1/list?accountNo=1&ibx=CH1&classification=Mechanical"    -H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

classification Y string Electrical Electrical, Mechanical Enum value indication the asset classification for which to fetch the list.
cages N Array(string)

CH1:05:000550

 

An array of cage unique space id to be used to filter the assets list. Assumed to be all cage unique space id if no value is sent.

 

{
    "payLoad": {
        "classification": "Mechanical",
        "categories": [
            {
                "templates": [
                    {
                        "assets": [
                            {
                                "assetId": "CH1.FC 2",
                                "ibx": "CH1",
                                "alarmStatus": "OK",
                                "resiliencyStatus": "Resiliency Not Configured",
                                "alarmLastTriggeredTime": null,
                                "alarmLastClearedTime": null
                            }
                        ],
                        "templateId": "Fan Coil"
                    },
                    {
                        "assets": [],
                        "templateId": "Fans"
                    },
                    {
                        "assets": [],
                        "templateId": "Humidifier"
                    },
                    {
                        "assets": [],
                        "templateId": "RAH with Chilled Water"
                    }
                ],
                "categoryName": "Air Handling"
            },
            {
                "templates": [
                    {
                        "assets": [],
                        "templateId": "Chiller Air Cooled"
                    },
                    {
                        "assets": [
                            {
                                "assetId": "CH1.Lead Chilled Water Manager",
                                "ibx": "CH1",
                                "alarmStatus": "NOT OK",
                                "resiliencyStatus": "Resiliency Not Configured",
                                "alarmLastTriggeredTime": "Feb 15,2019 02:59 AM",
                                "alarmLastClearedTime": "Currently Active"
                            }
                        ],
                        "templateId": "Cooling Plant"
                    }
                ],
                "categoryName": "Cooling"
            },
            {
                "templates": [
                    {
                        "assets": [
                            {
                                "assetId": "CH1.VESDA",
                                "ibx": "CH1",
                                "alarmStatus": "OK",
                                "resiliencyStatus": "Resiliency Not Configured",
                                "alarmLastTriggeredTime": "Aug 21,2018 10:52 AM",
                                "alarmLastClearedTime": "Aug 21,2018 01:52 PM"
                            }
                        ],
                        "templateId": "Early Smoke Detection"
                    },
                    {
                        "assets": [
                            {
                                "assetId": "CH1.Fire Alarm System",
                                "ibx": "CH1",
                                "alarmStatus": "OK",
                                "resiliencyStatus": "Resiliency Not Configured",
                                "alarmLastTriggeredTime": "Feb 01,2019 11:25 AM",
                                "alarmLastClearedTime": "Feb 01,2019 12:25 PM"
                            }
                        ],
                        "templateId": "Fire Alarm"
                    }
                ],
                "categoryName": "Fire, Smoke Detection"
            },
            {
                "templates": [
                    {
                        "assets": [],
                        "templateId": "Leak Detection"
                    }
                ],
                "categoryName": "Leak Detection"
            }
        ]
    },
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
 classification string Electrical, Mechanical Indicates the asset classification for the Electrical and mechanical assets.
categories an array of a category object   Indicates the category of the specified asset classification.
templates array of a category object   Template specifies the blueprint of an asset.
categoryName string Air Handling, Cooling, Fire smoke detection, Leak detection Indicates the category name of the specified asset classification.
assets array of a category object    
templateId string Fans, Fan coil, Humdifer Unique identifier for the template
assetId string CH1.FC2 Unique identifier for the template
ibx string CH1 IBX code for the IBX in which the asset is located.
alarmStatus string OK

Alarm status for the asset.

assets.resiliencyStatus string Resilency not configued Resiliency status for the asset.
assets.alarmLastTriggeredTime string null, "Feb 15,2019 02:59 AM" Date-time when the latest alarm on the asset was triggered.
assets.alarmLastClearedTime string null, "Currently active", "Feb 15,2019 02:59 AM" Date-time when the latest alarm on the asset was cleared.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Get Asset details

GET /asset/v1/details

 Method  GET
 URL or End Point  /asset/v1/details
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx, classification assetId
 Body  Not applicable

 

Given an account number, IBX code, asset classification (Electrical, Mechanical), and assetId asset details including tag points list. The response includes the assetId, IBX, alarmStatus, resiliencyStatus, alarmLastTriggeredTime, alarmLastClearedTime information for each asset.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get assets details for the account number 1 and a JSON response containing result. 

 

curl -X 

GET "https://api.equinix.com/asset/v1/details?accountNo=1&ibx=CH1&assetId=CH1.FC%202&classification=Mechanical"     

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

classification Y string Mechanical Electical, Mechanical Enum value indication the asset classification for which to fetch the list for.
assetId Y string AB2.FC1   Unique identifier for the asset.

 

{
    "payLoad": {
        "assetId": "CH1.FC 2",
        "assetType": "",
        "userPrefTimeZone": "America/New_York",
        "tags": [],
        "lastMaintenanceDate": "Dec 19,2018",
        "manufacturerName": "",
        "equipmentModelNumber": "",
        "equipmentSerialNumber": "",
        "alarmLastTriggeredTime": null,
        "alarmLastProcessedTime": null
    },
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
 assetId string CH1.FC2 Indicates the unique identifier for the asset.
assetType string

cooling  

Indicates the template name for the asset.
userPrefTimeZone string "America/New_York" Timezone for the user.
tags array of tag object   Specifies the list of tag points for the asset.
value string 4.9 The current data value for the tag point.
tagId string CH1.Chiller1:evapleavingwatertemperature Unique identifier for the tag point.
tagDisplayName string Evaporator leaving water temperature The display name for the tag point.
uom string oC Unit of measure for the tag point data value.
alarmStatus string OK

Alarm status for the tag point.

readingTime string

20170907060449

Date-time when the tag point value was read from the device.
lastMaintenanceDate string "Dec 19,2018" Date-time when the asset had its last maintenance.
manufacturerName string SMARDT Asset manufacturer name.
equipmentModelNumber string

SACAC110-3EXX-2A1-16A-010

Equipment model number.
equipmentSerialNumber string

FF0010I233Q1276

Equipment serial number.
alarmLastTriggeredTime string Aug 21,2017 04:38 AM Date-time when the latest alarm was triggered on the asset.
alarmLastProcessedTime string

Aug 21,2017 05:52 AM

Date-time when the latest alarm was processed on the asset.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Post Asset details

POST /asset/v1/details

 Method  POST
 URL or End Point  /asset/v1/details
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  accountNo, ibx, classification, assetId list

 

Given an account number, IBX code, asset classification (Electrical, Mechanical), and assetId list, return the asset details including tag points list for each asset. The response includes the assetId, IBX, alarmStatus, resiliencyStatus, alarmLastTriggeredTime, alarmLastClearedTime information for each asset. 

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get assets details for the account number 1 and a JSON response containing result. 

 

curl -X 

POST "https://api.equinix.com/asset/v1/details -H 'Authorization: Bearer 21T65PfrRgJK5guVYceyLnSLRl1s" 
-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

-d '{
  "accountNo": "1",
  "ibx": "CH1",
  "assetIds": [
    "CH1.FC 2",
    "CH1.Lead Chilled Water Manager"
  ],
  "classification":"Mechanical"
}'

 

The description of the request payload is as follows:

 

Body Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

classification Y string Mechanical Electical, Mechanical Enum value indication the asset classification for which to fetch the list for.
assetIds Y array of assetid's AB2.FC1   Unique identifier for the asset.

 

{
    "payLoad": {
        "totalCount": 2,
        "assetDetails": [
            {
                "assetId": "CH1.FC 2",
                "assetType": "",
                "userPrefTimeZone": "America/New_York",
                "tags": [],
                "lastMaintenanceDate": "Dec 19,2018",
                "manufacturerName": "",
                "equipmentModelNumber": "",
                "equipmentSerialNumber": "",
                "alarmLastTriggeredTime": null,
                "alarmLastProcessedTime": null
            },
            {
                "assetId": "CH1.Lead Chilled Water Manager",
                "assetType": "",
                "userPrefTimeZone": "America/New_York",
                "tags": [
                    {
                        "value": "42.26",
                        "tagId": "CH1.Lead Chilled Water Manager:primarychilledwatersupplytemperature",
                        "tagDisplayName": "Primary Chilled Water Supply Temperature",
                        "uom": "°F",
                        "alarmStatus": "NOT OK",
                        "readingTime": "20190218205638"
                    }
                ],
                "lastMaintenanceDate": "",
                "manufacturerName": "",
                "equipmentModelNumber": "",
                "equipmentSerialNumber": "",
                "alarmLastTriggeredTime": "Dec 31,1969 07:00 PM",
                "alarmLastProcessedTime": "Currently Active"
            }
        ]
    },
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
totalCount number 2 Total number of assets that match the request.
assetDetails array of assetdetails object   Asset details, including the tag points with data for the asset.
 assetId string CH1.FC2 Indicates the unique identifier for the asset.
assetType string

cooling  

Indicates the template name for the asset.
userPrefTimeZone string "America/New_York" Timezone for the user.
tags array of tag object   Specifies the list of tag points for the asset.
tags.value string 4.9 Current data value for the tag point.
tags.tagId string CH1.Chiller1:evapleavingwatertemperature Unique identifier for the tag point.
tags.tagDisplayName string Evaporator leaving water temperature Display name for the tag point.
tags.uom string oC Unit of measure for the tag point data value.
tags.alarmStatus string OK

Alarm status for the tag point.

tags.readingTime string

20170907060449

Date-time when the tag point value was read from the device.
lastMaintenanceDate string "Dec 19,2018" Date-time when the asset had its last maintenance.
manufacturerName string SMARDT Asset manufacturer name.
equipmentModelNumber string

SACAC110-3EXX-2A1-16A-010

Equipment model number.
equipmentSerialNumber string

FF0010I233Q1276

Equipment serial number.
alarmLastTriggeredTime string Aug 21,2017 04:38 AM Date-time when the latest alarm was triggered on the asset.
alarmLastProcessedTime string

Aug 21,2017 05:52 AM

Date-time when the latest alarm was processed on the asset.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Get affected locations for a given assets

GET /asset/v1/tagpoint/affected-assets

 Method  GET
 URL or End Point  /asset/v1/tagpoint/affected-assets
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx, classification assetId
 Body  Not applicable

 

Given an account number, IBX code, and an assetId, return the corresponding locations hierarchy of related assets.

 

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get assets location hierarchy details for the account number 1 and a JSON response containing result. 

 

 

curl -X 

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

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

classification Y string Mechanical Electical, Mechanical Enum value indication the asset classification for which to fetch the list for.
assetId Y string AB2.FC1   Unique identifier for the asset.

 

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

 

The description of the response payload is as follows:

 

Field name Type Example Description
cages array of Cages object    
name string CH1:05:FE00021 Cage unique space identifier.
type string cage Type of the space asset.
cabinets array of Cabinet objects    
cabinets.name string CH1:05:FE00021.0101 Cabinet name.
cabinets.type string cabinet Type of the space asset.
cabinets.circuits array of Circuits objects    
cabinets.circuits.name string 15137957

Circuit name.

cabinets.circuits.type string circuit Type of the space asset.
circuits array of CircuitsMapWithCage object    
circuits.name string 877484 Circuit name.
circuits.type string

circuit

Type of the space asset.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Get asset tag point

GET /asset/v1/tagpoint/current

 Method  GET
 URL or End Point  /asset/v1/tagpoint/current
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx, tagId
 Body  Not applicable

 

Given an account number, IBX code, and asset tag point, return its latest value.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get asset tagpoint and a JSON response containing result. 

 

curl -X 

GET "https://api.equinix.com/asset/v1/tagpoint/current?accountNo=1&ibx=CH1&tagId=CH1.Lead%20Chilled%20Water%20Manager:primarychilledwatersupplytemperature"     

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string CH1  

Name of the IBX for which data is being requested.

tagId Y string CH1.Lead Chilled Water Manager:primarychilledwatersupplytemperature   Unique identifier for the tagpoint.

 

{
    "payLoad": [
        {
            "value": "5.7",
            "tagId": "CH1.Lead Chilled Water Manager:primarychilledwatersupplytemperature",
            "tagDisplayName": "Primary Chilled Water Supply Temperature",
            "uom": "°C",
            "readingTime": "20190218225701"
        }
    ],
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
value string 4.9 Current data value for the tag point.
tagId string CH1.Chiller1:evapleavingwatertemperature Unique identifier for the tag point.
tagDisplayName string Evaporator leaving water temperature Display name for the tag point.
uom string oC Unit of measure for the tag point data value.
alarmStatus string OK

Alarm status for the tag point.

readingTime string

20170907060449

Date-time when the tag point value was read from the device.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

POST asset tagpoints

POST /asset/v1/tagpoint/current

 Method  POST
 URL or End Point  /asset/v1/tagpoint/current
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  accountNo, ibx, tagId

 

Given an account number, IBX code, and asset tag point, return its latest value.

 

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get asset tagpoint and a JSON response containing result. 

 

 

curl -X 

POST https://api.equinix.com/asset/v1/tagpoint/current

-H 'content-type: application/json' 

-H 'authorization: Bearer jBilbaA9AAdePnHhQLC29ZK7fj5b' 

-d '{
  "accountNo": "1",
  "tagIds": [
    "CH1.Lead Chilled Water Manager:primarychilledwatersupplytemperature",
    "CH1.UPS-5:batterytimeremaining"
  ],
  "ibx": "CH1"
}'

 

The description of the request payload is as follows:

 

 

Body Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string CH1  

Name of the IBX for which data is being requested.

tagIds Y string CH1.Lead Chilled Water Manager:primarychilledwatersupplytemperature, CH1.UPS-5:batterytimeremaining   Unique identifier list for the tagpoints.

 

{
    "payLoad": [
        {
            "value": "AVAILABLE DURING DISCHARGE",
            "tagId": "CH1.UPS-5:batterytimeremaining",
            "tagDisplayName": "Battery Time Remaining",
            "uom": "",
            "readingTime": "20190218233515"
        },
        {
            "value": "5.7",
            "tagId": "CH1.Lead Chilled Water Manager:primarychilledwatersupplytemperature",
            "tagDisplayName": "Primary Chilled Water Supply Temperature",
            "uom": "°C",
            "readingTime": "20190218225701"
        }
    ],
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
value string 4.9 Current data value for the tag point.
tagId string CH1.Chiller1:evapleavingwatertemperature Unique identifier for the tag point.
tagDisplayName string Evaporator leaving water temperature Display name for the tag point.
uom string oC Unit of measure for the tag point data value.
alarmStatus string OK

Alarm status for the tag point.

readingTime string

20170907060449

Date-time when the tag point value was read from the device.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Environment APIs


body: 

GET Environment for a level

GET /environment/v1/current

 Method  GET
 URL or End Point  /environment/v1/current
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx, levelType, levelValue
 Body  Not applicable

 

Given an account number, IBX code, get current environment data for a single level value. returns environment info ( temperature and humidity ) for input IBX, zone, cage, sensor. 

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get assets details for the account number 1 and a JSON response containing the result. 

 

curl -X 

GET  'https://api.equinix.com/environment/v1/current?accountNo=1&ibx=CH1&levelType=IBX&levelValue=CH1'
-H 'Authorization: Bearer vtIPc5PfMDw1mML4WzHEhb10e6V9'
-H 'Content-Type: application/json'

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example values Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

levelType Y string IBX IBX, ZONE, CAGE, SENSOR Enum value indication the level type for which to fetch the list for.
levelValue Y levelValue AB2   Unique identifier for the type is ibxCode, zoneUsID, cageUsID, sensorid for
levelType ibx, zone, cage, sensor respectively.

 

{
    "payLoad": {
        "ibx": "CH1",
        "accountNo": "1",
        "zone": "ALL",
        "cage": "ALL",
        "cabinet": "ALL",
        "sensor": "ALL",
        "temperature": "21.0",
        "humidity": "35.78",
        "timestamp": "1552275932446",
        "temperatureUom": "°C",
        "humidityUom": "%"
    },
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
ibx string CH1 Name of the IBX.
accountNumber number 1234 Customer account number.
 zone string

CH1:1:05:ColoArea:2

Zone unique space identifier.
cage string

CH1:05:000550  

Cage unique space identifier.
cabinet string CH1:05:000550:0105 Cabinet unique space identifier.
sensor string CH1.Colo.CH1_05_000550_0105 Sensor unique identifier.
temperature string 20.0 Current temperature.
humidity string 60.0 Current humidity.
timestamp string 1506665106579 Epoch timestamp when the current reading was read.
temperatureUom string oC

Unit of measure for temperature values.

humidityUom string

%

Unit of measure for humifity values.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

GET Environment for a level type

GET /environment/v1/listCurrent

 Method  GET
 URL or End Point  /environment/v1/listCurrent
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx, levelType
 Body  Not applicable

 

Given an account number, IBX code, get current environment data for all level values for a level type. returns environment info ( temperature and humidity ) for input ibx, zone, cage, sensor

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get assets details for the account number 1 and a JSON response containing result. 

 

curl -X 

GET  'https://api.equinix.com/environment/v1/listCurrent?accountNo=1&ibx=CH1&levelType=IBX'
-H 'Authorization: Bearer vtIPc5PfMDw1mML4WzHEhb10e6V9'
-H 'Content-Type: application/json'

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example values Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

levelType Y string IBX IBX, ZONE, CAGE, SENSOR Enum value indication the level type for which to fetch the list for.

 

{
    "payLoad": {
        "totalCount": 2,
        "data": [
            {
                "ibx": "CH1",
                "accountNo": "1",
                "zone": "CH1:1:05:ColoArea:2",
                "cage": "ALL",
                "cabinet": "ALL",
                "sensor": "ALL",
                "temperature": "21.1",
                "humidity": "35.50",
                "timestamp": "1552277740599",
                "temperatureUom": "°C",
                "humidityUom": "%"
            },
            {
                "ibx": "CH1",
                "accountNo": "1",
                "zone": "CH1:1:05:ColoArea:3",
                "cage": "ALL",
                "cabinet": "ALL",
                "sensor": "ALL",
                "temperature": "20.7",
                "humidity": "28.80",
                "timestamp": "1552277787927",
                "temperatureUom": "°C",
                "humidityUom": "%"
            }
        ]
    },
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
totalCount integer 2 Total number of data values.
data array list   Array of all level values.
ibx string CH1 Name of the IBX.
accountNumber number 1234 Customer account number.
 zone string

CH1:1:05:ColoArea:2

Zone unique space identifier.
cage string

CH1:05:000550  

Cage unique space identifier.
cabinet string CH1:05:000550:0105 Cabinet unique space identifier.
sensor string CH1.Colo.CH1_05_000550_0105 Sensor unique identifier.
temperature string 20.0 Current temperature.
humidity string 60.0 Current humidity.
timestamp string 1506665106579 Epoch timestamp when the current reading was read.
temperatureUom string oC

Unit of measure for temperature values.

humidityUom string

%

Unit of measure for humidity values.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Power APIs

 


body: 

Get Power data

GET /power/v1/current

 Method  GET
 URL or End Point  /power/v1/current
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx, levelType, levelValue
 Body  Not applicable

 

The Get Power Current API, returns the power consumption info for all level values, given a customer account number, IBX and level type of ibx, cage, cabinet or circuit.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to obtain designated ports and a JSON response containing details of port information. 

 

curl -X

GET "https://api.equinix.com/power/v1/current?accountNo=1&ibx=CH1&levelType=IBX&levelValue=CH1"

-H "accept: application/json"

-H "Authorization: Bearer PMQuChryibV7JFRfNuA3fLV8Hw1x"

 

The description of the query parameters is as follows:

 

Query Parameter Name

Mandatory

Type

Example

Applicable values

Description

accountNo

Y

string

1234

 

Customer account number.

ibx

Y

string

CH1  

Name of the IBX for which data is being requested.

levelType

Y

string

IBX

IBX, CAGE, CABINET, CIRCUIT

 Indicates which of the level types.

LevelValue

Y

string

CH1

 

Indicates the level value corresponding to the levelType - ibx code, cage unique space id, cabinet unique space id, serial number for levelType ibx, cage, cabinet, circuit respectively.

 

{
  "payLoad": {
    "ibx": "CH1",
    "accountNo": "1",
    "levelType": "IBX",
    "levelValue": "CH1",
    "isAlarm": null,
    "kva": 175.334,
    "amps": null,
    "soldKva": 1370.285,
    "cabinetRating": null,
    "contractualKva": 373.9,
    "percentageKva": 46.893,
    "comparisonData": {
      "datapoint": "percentageKva",
      "yesterday": -0.106,
      "lastweek": -0.034,
      "lastmonth": 2.379,
      "lastquarter": 2.964
    },
   "peakKvaLastSevenDays": 176.195,
    "peakKvaLastSevenDaysPercentage": 47.123,
    "peakKvaLastSevenDaysContractualKva": 373.899,
    "peakKvaLastSevenDaysTime": null,
    "soldAmps": null,
    "primaryKva": 111.586,
    "redundantKva": 63.747,
    "kw": "NA",
    "powerFactor": "NA",
    "readingTime": "1550379600000",
    "lastUpdatedTime": "1550379960000",
    "customerName": "EQUINIX"
  },
  "status": {
    "type": "INFO",
    "statuscode": "1000",
    "msg": "OK"
  }
}

 

The description of the response payload is as follows:

 

Field Name 

Type

Example

Description

 ibx

string

ABC

IBX code

accountNumber

string

ABC

Customer account number

levelType

string

ibx 

Enum:

Array [4]

Power hierarchy node levelType, linked to the power data.

levelValue

string

ABC

Power hierarchy node levelValue, linked to the power data

isAlarm

string

true

Boolean based on breaker tip alarm

kva

number

54.402

Power consumption in kva

amps

number

123

Instantaneous current amp reading on circuits

soldKva

number

598.349

Maximum amp draw, allowable on a circuit

cabinetRating

number

341.54

Maximum kVA draw allowed for the cabinet, when the levelType is cabinet. Null otherwise.

contractualKva

number

341.54

Maximum power draw contractually allowable in a private cage.

percentageKva

number

341.54

Calculated field kva divided by contractualKva

comparisonData

object

 

ComparisonData{...}

peakKvaLastSevenDays

number

55.296

 

peakKvaLastSevenDaysPercentage

number

55.296

 

peakKvaLastSevenDaysContractualKva

number

55.296

 

peakKvaLastSevenDaysTime

integer

55.296

 

soldAmps

integer

123

Circuit description when the levelType is circuit. Null otherwise.

primaryKva

number

28.31

Sum of instantaneous power draw reading on all the primary circuits within the levelType.

redundantKva

number

26.092

Sum of instantaneous power draw reading on all the redundant circuits within the levelType.

kw

string

NA

Measure of real power expressed in KiloWatt. Applicable for IBXs
that have capability of energy meter reading. The value will be “NA” for AMER and APAC regions

powerFactor

string

NA

Ratio between real power and apparent power in a circuit.(kW/kVA)|value will be “NA” for AMER and APAC regions

readingTime

string

1497410400000

Date-time when the latest value was read in (epoc - milliseconds).

lastUpdatedTime

string

1497410520000

Date-time when the latest value was updated (epoc - milliseconds).

customerName

string

ABC

 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Post Power data for a given level type

POST /power/v1/current

 Method  POST
 URL or End Point  /power/v1/current
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  accountNo, ibx, levelType

 

Given a customer account number, IBX and level type of ibx, cage, cabinet or circuit, returns the power consumption info for all level values.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to obtain power data for the account number 1 and a JSON response containing power data. 

 

curl -X 

POST "https://api.equinix.com/power/v1/current  

-H "content-type: application/json"
-H "authorization: Bearer R2KsiEM1ATlhBr8YdJqkHhbqZfdq"  
-d '{
     "accountNo": "1",
     "ibx": "CH1",
     "levelType": "IBX"
}'

 

The description of the request payload is as follows:

 

Body Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

levelType Y string IBX IBX, CAGE, CABINET, CIRCUIT Indicates which of the following level types.

 

 

{
    "payLoad": {
        "data": [
            {
                "ibx": "CH1",
                "accountNo": "1",
                "levelType": "IBX",
                "levelValue": "CH1",
                "isAlarm": null,
                "kva": 175.951,
                "amps": null,
                "soldKva": 1370.285,
                "cabinetRating": null,
                "contractualKva": 373.9,
                "percentageKva": 47.058,
                "comparisonData": {
                    "datapoint": "percentageKva",
                    "yesterday": 0.213,
                    "lastweek": 0.497,
                    "lastmonth": 2.751,
                    "lastquarter": 3.049
                },
                "peakKvaLastSevenDays": 176.195,
                "peakKvaLastSevenDaysPercentage": 47.123,
                "peakKvaLastSevenDaysContractualKva": 373.899,
                "peakKvaLastSevenDaysTime": null,
                "soldAmps": null,
                "primaryKva": 111.794,
                "redundantKva": 64.157,
                "kw": "NA",
                "powerFactor": "NA",
                "readingTime": "1550506500000",
                "lastUpdatedTime": "1550506860000",
                "customerName": "EQUINIX"
            }
        ]
    },
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
 ibx string AB1 IBX code
accountNo string 123 Customer account number
levelType string IBX Indicates the level type.
levelValue string AB1 Indicates the level value for the given level type.
isAlarm string true, false Boolean based on breaker trip alarm.
kva number 54.402 Power consumption in KVA
amps number 123 Instantaneous current amp reading on circuits.
soldKva number 598.349 Maximum amp draw, allowable on a circuit.
cabinetRating number 341.54

Maximum kVA draw allowed for the cabinet, when the level type is cabinet. Null otherwise.

contractualKva number 341.54 Maximum power draw contractually allowable in a power cage.
percentageKva number 341.54 Calculated field kVA divided by the contractual kVA.
comparisionData object   comparisonData{...}
peakKvaLastSevenDays number 55.296  
PeakKvaLastSevenDaysPercentage number 55.296  
PeakKvaLastSevenDaysContractualKva number 55.296  
PeakKvaLastSevenDaysTime number 55.296  
soldAmps number 123 Circuit description when the level type is circuit. Null otherwise.
primaryKva number 28.31 Sum of instantaneous power draw reading on all the primary circuits within the level type.
redundantKva number 26.092 Sum of instantaneous power draw reading on all the redundant circuits within the level type.
kw string NA Measure of real power expressed in KiloWatt. Applicable to IBXs that have the capability of energy meter reading. The value will be "NA" for AMER and APAC regions.
powerFactor string NA Ratio between the real power and apparent power in a circuit (KW/KVA). Value will be "NA" for AMER and APAC regions.
readingTime string 1497410400 Date-time when the latest value was read in (epoc - milliseconds).
lastUpdatedTime string 1497410400 Date-time when the latest value was updated in (epoc - milliseconds).
customerName string ABC Name of the customer.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Hierarchy APIs

 


body: 

Get Location hierarchy

GET /hierarchy/v1/location

 Method  GET
 URL or End Point  /hierarchy/v1/location
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx
 Body  Not applicable

 

Given an account number, IBX code, and an assetId, return the corresponding locations hierarchy of related assets.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get location hierarchy details for the given account number and IBX and a JSON response containing result. 

 

curl -X 

GET "https://api.equinix.com/hierarchy/v1/location?accountNo=123&ibx=SV4"    

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

 

[
  {
    "levelType": "IBX",
    "levelValue": "SV4",
    "label": "SV4",
    "children": [
      {
        "levelType": "ZONE",
        "levelValue": "SV4:1:01:ColoA:1",
        "label": "SV4:1:01:ColoA:1",
        "children": [
          {
            "levelType": "CAGE",
            "levelValue": "1852",
            "label": "SV4:01:001150",
            "children": [
              {
                "levelType": "CABINET",
                "levelValue": "138094",
                "label": "SV4:01:001150:0000",
                "children": []
              },
              {
                "levelType": "CABINET",
                "levelValue": "74147",
                "label": "SV4:01:001150:0101",
                "children": []
              }
            ]
          }
        ]
      },
      {
        "levelType": "ZONE",
        "levelValue": "SV4:1:01:ColoB:2",
        "label": "SV4:1:01:ColoB:2",
        "children": [
          {
            "levelType": "CAGE",
            "levelValue": "1948",
            "label": "SV4:01:002100",
            "children": [
              {
                "levelType": "CABINET",
                "levelValue": "139474",
                "label": "SV4:01:002100:0000",
                "children": []
              },
              {
                "levelType": "CABINET",
                "levelValue": "78970",
                "label": "SV4:01:002100:0102",
                "children": []
              }
            ]
          },
          {
            "levelType": "CAGE",
            "levelValue": "2053",
            "label": "SV4:01:002520",
            "children": [
              {
                "levelType": "CABINET",
                "levelValue": "137692",
                "label": "SV4:01:002520:0000",
                "children": []
              }
            ]
          }
        ]
      }
    ]
  }
]

 

The description of the response payload is as follows:

Field name Type Example Description
levelType string ibx, zone, cage, cabinet, sensor Indicates the level at which a node in the location hierarchy belongs to.
levelValue string SV4 Indicates the concrete name of the level type such as the IBX code, zone usId, cage usId, cabinet usId, sensor number.
label string cage Type of the space asset.
children list of ordered map with children   See example JSON response above.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Get Power hierarchy

GET /hierarchy/v1/power

 Method  GET
 URL or End Point  /hierarchy/v1/power
 Headers  Authorization, Content-Type
 Query Parameters  accountNo, ibx
 Body  Not applicable

 

Given an account number, IBX code, and an assetId, return the corresponding power hierarchy of related assets.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get power hierarchy details for the given account number and IBX and a JSON response containing result. 

 

curl -X 

GET "https://api.equinix.com/hierarchy/v1/power?accountNo=123&ibx=SV4"     

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

The description of the query parameters is as follows:

 

Query Parameter Name Mandatory Type Example Applicable values Description
accountNo Y string 1234   Customer account number
ibx Y string AB2  

Name of the IBX for which data is being requested.

 

[
    {
        "levelType": "IBX",
        "levelValue": "SV4",
        "label": "SV4",
        "children": [
            {
                "levelType": "CAGE",
                "levelValue": "1844",
                "label": "SV4:01:000120",
                "children": [
                    {
                        "levelType": "CABINET",
                        "levelValue": "74006",
                        "label": "SV4:01:000120:0101",
                        "children": [
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "20853717",
                                "label": "120V 20A 1Ph Red (3717)",
                                "children": []
                            },
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "20853716",
                                "label": "120V 20A 1Ph Pri (3716)",
                                "children": []
                            }
                        ]
                    },
                    {
                        "levelType": "CABINET",
                        "levelValue": "74007",
                        "label": "SV4:01:000120:0103",
                        "children": [
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "20853719",
                                "label": "120V 20A 1Ph Red (3719)",
                                "children": []
                            },
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "14158128",
                                "label": "120V 20A 1Ph Pri (8128)",
                                "children": []
                            }
                        ]
                    }
                ]
            },
            {
                "levelType": "CAGE",
                "levelValue": "6451",
                "label": "SV4:01:000130",
                "children": [
                    {
                        "levelType": "CABINET",
                        "levelValue": "102831",
                        "label": "SV4:01:000130:0101",
                        "children": [
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "865343",
                                "label": "120V 20A 1Ph Pri (5343)",
                                "children": []
                            },
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "865335",
                                "label": "120V 20A 1Ph Pri (5335)",
                                "children": []
                            }
                        ]
                    },
                    {
                        "levelType": "CABINET",
                        "levelValue": "102832",
                        "label": "SV4:01:000130:0102",
                        "children": [
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "1129134",
                                "label": "120V 20A 1Ph Red (9134)",
                                "children": []
                            },
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "1129133",
                                "label": "120V 20A 1Ph Pri (9133)",
                                "children": []
                            }
                        ]
                    }
                ]
            },
            {
                "levelType": "CAGE",
                "levelValue": "104154",
                "label": "SV4:01:VBCM000-1-271",
                "children": [
                    {
                        "levelType": "CABINET",
                        "levelValue": "104158",
                        "label": "SV4:01:VBCM000-1-271:V9999",
                        "children": [
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "818563",
                                "label": "120V 20A 1Ph Red (8563)",
                                "children": []
                            },
                            {
                                "levelType": "CIRCUIT",
                                "levelValue": "20184661",
                                "label": "120V 20A 1Ph Pri (4661)",
                                "children": []
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

 

The description of the response payload is as follows:

Field name Type Example Description
levelType string IBX Indicates the level at which a node in the location hierarchy belongs to. Applicable values are - IBX, CAGE, CABINET, CIRCUIT
levelValue string SV4 Indicates the concrete name of the level type such as the IBX code, cage usId, cabinet usId, circuit usId
label string cage Type of the space asset.
children list of ordered map with children   See example JSON response above.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Subscriptions APIs

 


body: 

Get subscriptions

GET /feedsubscriptions/v1/subscribe

 Method  GET
 URL or End Point  /feedsubscription/v1/subscribe
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

It allows users to view their resp. real-time feeds subscription with details. Lists events currently subscribed to. Returns subscription details with a subscription ID. It includes the Power, Asset Tag, and Config information. The subscription config allows you to specify the provider [ GOOGLE, AZURE, AWS, ORACLE, PRIVATE], the method [PUSH, PULL] and a push URL if the method of choice is PUSH.

 

The provider supports only PULL method. PUSH method and URL are currently not implemented.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get the subscriptions list for the user and a JSON response containing the result. 

 

curl -X 

GET "https://api.equinix.com/registration/v1/subscribe"

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

{
    "power": [
        {
            "ucmId": null,
            "accountNo": "1",
            "ibx": "CH1"
        }
    ],
    "asset": [],
    "alarm": [],
    "alert": [],
    "environment": [],
    "subscriptionId": "5c509e8aabe10e6cda419128",
    "subscriptionName": "projects/equinix-dcim-feeds/subscriptions/joe23%40abc.com",
    "status": "OK",
    "errors": [],
    "config": {
        "method": "PULL",
        "provider": "GOOGLE"
    }
}

 

The description of the response payload is as follows:

Field name Type Example Description
 power object   Power events subscription details. 
accountNo string 123 Customer account number.
ibx string AB2 IBX code
asset object   Assets events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alarm object   Alarms events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alert object   Alerts events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
environment object   Environments events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
subscriptionId number 1234 Unique identifier for the subscription
subscriptionName string   Unique subscription name
status string CH1 IBX code for the IBX in which the asset is located.
config object  

Cloud agnostic, Pub/Sub provider information.

provider string GOOGLE, AZURE, AWS, ORACLE, PRIVATE

Pub/Sub implementation to be used for consuming real-time events.

Note: Only GOOGLE is supported currently.

method string PULL, PUSH

Subscription method.

Note: Only PULL is supported currently.

pushurl string  

Push URL, this is mandatory when the method is PUSH.

Note: Not Supported currently.

status string OK, PARTIAL, SUCCESS, ERROR Response status.
error object   API error.

 

If you get the “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Get subscriptions by Id

GET /feedsubscriptions/v1/subscribe/{subscriptionId}

 Method  GET
 URL or End Point  /feedsubscription/v1/subscribe/{subscriptionId}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

 

It allows users to view their resp. real-time feeds subscription details. Lists events currently subscribed to.

 

Note: The provider supports only PULL method. PUSH method and URL are currently not implemented.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to get an existing subscription for the user and a JSON response containing the result. 

 

curl -X 

GET "https://api.equinix.com/registration/v1/subscribe/5c4f7103ce9a9d4903419128"

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

{
    "power": [
        {
            "ucmId": null,
            "accountNo": "1",
            "ibx": "CH1"
        }
    ],
    "asset": [
        {
            "ucmId": null,
            "accountNo": "1",
            "ibx": "CH1"
        }
    ],
    "alarm": [],
    "alert": [],
    "environment": [],
    "subscriptionId": "5c509e8aabe10e6cda419128",
    "subscriptionName": "projects/equinix-dcim-feeds/subscriptions/joe23%40abc.com",
    "status": "OK",
    "errors": [],
    "config": {
        "method": "PULL",
        "provider": "GOOGLE"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
 power object   Power events subscription details. 
accountNo string 123 Customer account number.
ibx string AB2 IBX code
asset object   Assets events subscription details.
accountNo string 123 Customer account number.
asset.ibx string AB2 IBX code
alarm object   Alarms events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alert object   Alerts events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
environment object   Environments events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
subscriptionId number 1234 Unique identifier for the subscription
subscriptionName string   Unique subscription name
status string CH1 IBX code for the IBX in which the asset is located.
config object  

Cloud agnostic, Pub/Sub provider information.

provider string GOOGLE, AZURE, AWS, ORACLE, PRIVATE

Pub/Sub implementation to be used for consuming real-time events.

Note: Please contact us for PRIVATE option.

method string PULL, PUSH

Subscription method.

Note: Only PULL is supported currently.

pushurl string  

Push URL, this is mandatory when the method is PUSH.

Note: Not Supported currently.

status string OK, PARTIAL, SUCCESS, ERROR Response status.
error object   API error.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Post subscriptions

POST /feedsubscriptions/v1/subscribe

 Method  POST
 URL or End Point  /feedsubscription/v1/subscribe
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

It allows users to register for real-time feeds.

  • User will have the ability to specify the events for each account, IBX - which will be available as real-time feeds
  • Depending on the mechanism selected for the real-time feed integration user will have to specify configuration parameters.

 

It includes the Power, Asset Tag, and Config information. The subscription config allows you to specify the provider [ GOOGLE, AZURE, AWS, ORACLE, PRIVATE], the method [PUSH, PULL] and a push URL if the method of choice is PUSH.

 

Note: The provider supports only PULL method. PUSH method and URL are currently not implemented.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to create a new subscription for the user and a JSON response containing the result. 

 

curl -X 

POST https://api.equinix.com/registration/v1/subscribe 

-H 'content-type: application/json' 

-H 'authorization: Bearer ea28LIRkdIEjIDpIHo9B40seYIWs' 
-d '{
    "power": [
    {
      "accountNo": "1",
      "ibx": "CH1"
    }
  ],
  "config": {
    "provider": "GOOGLE",
    "method": "PULL"
  }
}'                     

 

 

The description of the request payload is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
power N object     Power events subscription details.
accountNo N string   123 Customer account number
ibx N string   AB2

Name of the IBX for which data is being requested.

asset N object     Assets events subscription details.
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
alarm N object     Alarms events subscription details.
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
alert N object     Alerts events subscription details.
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
environment N object      
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
config Y object     Subscription configuration.
provider Y string   GOOGLE, AZURE, AWS, ORACLE, PRIVATE

Pub/Sub implementation to be used for consuming real-time events.

Note: Contact us for the PRIVATE option.

method Y string   PULL, PUSH

Subscription method.

Note: Only PULL is supported currently.

pushurl N string    

Push URL, this is mandatory when the method is PUSH.

Note: Not Supported currently.

 

 

{
    "power": [
        {
            "ucmId": null,
            "accountNo": "1",
            "ibx": "CH1"
        }
    ],
    "asset": [],
    "alarm": [],
    "alert": [],
    "environment": [],
    "subscriptionId": "5c509e8aabe10e6cda419128",
    "subscriptionName": "projects/equinix-dcim-feeds/subscriptions/joe23%40abc.com",
    "status": "OK",
    "errors": [],
    "config": {
        "method": "PULL",
        "provider": "GOOGLE"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
 power object   Power events subscription details. 
accountNo string 123 Customer account number.
ibx string AB2 IBX code
asset object   Assets events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alarm object   Alarms events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alert object   Alerts events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
environment object   Environments events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
subscriptionId number 1234 Unique identifier for the subscription
subscriptionName string   Unique subscription name
status string CH1 IBX code for the IBX in which the asset is located.
config object  

Cloud agnostic, Pub/Sub provider information.

provider string GOOGLE, AZURE, AWS, ORACLE, PRIVATE

Pub/Sub implementation to be used for consuming real-time events.

Note: Only GOOGLE is supported currently.

method string PULL, PUSH

Subscription method.

Note: Only PULL is supported currently.

pushurl string  

Push URL, this is mandatory when the method is PUSH.

Note: Not Supported currently.

status string OK, PARTIAL, SUCCESS, ERROR Response status.
error object   API error.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Put subscriptions

PUT /feedsubscriptions/v1/subscribe

 Method  PUT
 URL or End Point  /feedsubscription/v1/subscribe
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

It allows users to update an existing subscription to real-time feed to add or remove events. It includes the Power, Asset Tag, and Config information.

The subscription config allows you to specify the provider [ GOOGLE, AZURE, AWS, ORACLE, PRIVATE], the method [PUSH, PULL] and a push URL if the method of choice is PUSH.

 

Note: The provider supports only PULL method. PUSH method and URL are currently not implemented.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to update an existing subscription for the user and a JSON response containing the result. 

 

curl -X 

PUT https://api.equinix.com/registration/v1/subscribe/5c4f7103ce9a9d4903419128 

-H 'content-type: application/json' 

-H 'authorization: Bearer ea28LIRkdIEjIDpIHo9B40seYIWs' 
-d '{
  "power": [
  {
  "accountNo": "1",
  "ibx": "CH1"
  }
  ],
  "asset": [
  {
  "accountNo": "1",
  "ibx": "CH1"
  }
  ],
  "config": {
  "method": "PULL",
  "provider": "GOOGLE"
  }
}'
         

 

The description of the request payload is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
power N object     Power events subscription details.
accountNo N string   123 Customer account number
ibx N string   AB2

Name of the IBX for which data is being requested.

asset N object     Assets events subscription details.
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
alarm N object     Alarms events subscription details.
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
alert N object     Alerts events subscription details.
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
environment N object      
accountNo N string   123 Customer account number.
ibx N string   AB2 Name of the IBX for which data is being requested.
config Y object     Subscription configuration.
provider Y string   GOOGLE, AZURE, AWS, ORACLE, PRIVATE

Pub/Sub implementation to be used for consuming real-time events.

Note: For the PRIVATE method please contact us.

method Y string   PULL, PUSH

Subscription method.

Note: Only PULL is supported currently.

pushurl N string    

Push URL, this is mandatory when the method is PUSH.

Note: Not Supported currently.

 

{
    "power": [
        {
            "ucmId": null,
            "accountNo": "1",
            "ibx": "CH1"
        }
    ],
    "asset": [
        {
            "ucmId": null,
            "accountNo": "1",
            "ibx": "CH1"
        }
    ],
    "alarm": [],
    "alert": [],
    "environment": [],
    "subscriptionId": "5c509e8aabe10e6cda419128",
    "subscriptionName": "projects/equinix-dcim-feeds/subscriptions/joe23%40abc.com",
    "status": "OK",
    "errors": [],
    "config": {
        "method": "PULL",
        "provider": "GOOGLE"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
 power object   Power events subscription details. 
accountNo string 123 Customer account number.
ibx string AB2 IBX code
asset object   Assets events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alarm object   Alarms events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alert object   Alerts events subscription details.
accountNo string 123 Customer account number.
alert.ibx string AB2 IBX code
environment object   Environments events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
subscriptionId number 1234 Unique identifier for the subscription
subscriptionName string   Unique subscription name
status string CH1 IBX code for the IBX in which the asset is located.
config object  

Cloud agnostic, Pub/Sub provider information.

provider string GOOGLE, AZURE, AWS, ORACLE, PRIVATE

Pub/Sub implementation to be used for consuming the real time events.

Note: Only GOOGLE is supported currently.

method string PULL, PUSH

Subscription method.

Note: Only PULL is supported currently.

pushurl string  

Push URL, this is mandatory when the method is PUSH.

Note: Not Supported currently.

status string OK, PARTIAL, SUCCESS, ERROR Response status.
error object   API error.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Delete subscriptions

DELETE /feedsubscriptions/v1/subscribe

 Method  DELETE
 URL or End Point  /feedsubscription/v1/subscribe
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The API allows users to delete their near real-time feeds subscription. 

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to delete the subscriptions list for the user and a JSON response containing the result. 

 

curl -X 

DELETE "https://api.equinix.com/registration/v1/subscribe"

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

 

{
    "power": [
        {
            "ucmId": null,
            "accountNo": "1",
            "ibx": "CH1"
        }
    ],
    "asset": [],
    "alarm": [],
    "alert": [],
    "environment": [],
    "subscriptionId": "5c509e8aabe10e6cda419128",
    "subscriptionName": "projects/equinix-dcim-feeds/subscriptions/joe23%40abc.com",
    "status": "OK",
    "errors": [],
    "config": {
        "method": "PULL",
        "provider": "GOOGLE"
    }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
 power object   Power events subscription details. 
accountNo string 123 Customer account number.
ibx string AB2 IBX code
asset object   Assets events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alarm object   Alarms events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
alert object   Alerts events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
environment object   Environments events subscription details.
accountNo string 123 Customer account number.
ibx string AB2 IBX code
subscriptionId number 1234 Unique identifier for the subscription
subscriptionName string   Unique subscription name
status string CH1 IBX code for the IBX in which the asset is located.
config object  

Cloud agnostic, Pub/Sub provider information.

provider string GOOGLE, AZURE, AWS, ORACLE, PRIVATE

Pub/Sub implementation to be used for consuming real-time events.

Note: For PRIVATE option please contact us.

method string PULL, PUSH

Subscription method.

Note: Only PULL is supported currently.

pushurl string  

Push URL, this is mandatory when the method is PUSH.

Note: Not Supported currently.

status string OK, PARTIAL, SUCCESS, ERROR Response status.
error object   API error.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix IBX SmartView Portal access.

 


body: 

Real-time feeds

 


body: 

Event Types


body: 
alarm_updated

An alarm was updated. The alarm_active event is sent when an alarm is activated. It is sent to all user - accounts connected to the alarm. The alarm property is an alarm object containing information about the alarm.

 

{

 

   "name": "alarm_active",

        "alarm" : { ... }

}

 


body: 
environment_updated

Environment Data was updated / received.

The environment_updated event is sent when environment data is updated or calculated. It is visible to the all accounts which have cage / cabinet in the location related to the environment information.

The environmentData property is a EnvironmentData object containing the environment information.

 

{

        "name":"environment_updated",

        "data": { ... }

}

 


body: 
power_updated

Power Consumption Data was updated / received.

The power_updated event is sent when power consumption data is received or calculated. It is visible to the user who has access to accounts that own the circuits to which the power consumption data is related to.

The powerData property is a PowerData object containing the power consumption information

 

{

    "name":"power_updated",

    "data": { ... }

}

 


body: 
tagpoint_updated

A tagpoint value was updated.

tagpoint_updated event is sent when a tagpoint data is updated. It is sent to all users who have visibility to the tagpoint.

The tagPointData property is a TagPointData object containing latest information about the tagPoint.

 

{

        "name":"tagpoint_updated",

        "data":{ ... }

}

 


body: 

Object Types


body: 
Alarm

{

    "type": "object",

    "description": "alarm object - properties of the alarm",

    "properties": {

        "timetriggered": {

            "type": "string",

            "description": "time when the criteria for the alarm was met, in epoch (ms)"

        },

        "valuetype": {

            "type": "string",

            "description": "data type for the alarm data point value",

            "enum": [

                "Float",

                "Bool",

                "Int"

            ]

        },

        "severity": {

            "type": "integer",

            "description": "integer value which describes the severity of the alarm. higher values indicate higher severity\n• 800-899 – Urgent\n• 600-699 – High \n• 400-499 – Low \n• 200-299 – Informational\n"

        },

        "timenormalprocessed": {

            "type": "string",

            "description": "time alarm was cleared in the system. \n"

        },

        "circuit": {

            "type": "string",

            "description": "circuit number applicable to power alarms"

        },

        "alarmtype": {

            "type": "string",

            "description": "alarm type indicates the type of alarm",

            "enum": [

                "digital",

                "absolute",

                "deviation",

                "multi-state"

            ]

        },

        "tagid": {

            "type": "string",

            "description": "tag id linked to the alarm. available for alarms on infra assets. unique identifier for the tag\n"

        },

        "uom": {

            "type": "string",

            "description": "unit of measure for the alarm value"

        },

        "cage": {

            "type": "string",

            "description": "cage us id linked to the alarm. available with power alarms or environmental alarms\n"

        },

        "timeprocessed": {

            "type": "string",

            "description": "time when the alarm was created in the system."

        },

        "assetid": {

            "type": "string",

            "description": "asset id linked to the alarm"

        },

        "metro": {

            "type": "string",

            "description": "metro id linked to the alarm"

        },

        "accountno": {

            "type": "string",

            "description": "customer account number"

        },

        "conditionname": {

            "type": "string",

            "description": "condition name for the alarm"

        },

        "region": {

            "type": "string",

            "description": "region linked to the alarm"

        },

        "value": {

            "type": "string",

            "description": "data point value at which the alarm was triggered"

        },

        "cabinet": {

            "type": "string",

            "description": "cabinet us id. applicable for power alarms"

        },

        "assettype": {

            "type": "string",

            "description": "Will contain\n• template name for alarms linked to infra assets.\n• \"environmental\" for environmental alarms.\n• \"CIRCUIT\" for power alarms \n"

        },

        "ibx": {

            "type": "string",

            "description": "ibx code"

        },

        "status": {

            "type": "boolean",

            "description": "indicator whether an alarm is active"

        },

        "assetclassification": {

            "type": "string",

            "description": "asset classification",

            "enum": [

                "Electrical",

                "Mechanical",

                "Environmental",

                "Power"

            ]

        }

    }

}

 


body: 
Alert

"AlertCondition": {

    "type": "object",

    "properties": {

        "affectedCustomerAsset": {

            "type": "null"

        },

        "alertType": {

            "type": "null"

        },

        "asset": {

            "type": "string"

        },

        "assetname": {

            "type": "string"

        },

        "assettype": {

            "type": "string"

        },

        "condalerttypeid": {

            "type": "string"

        },

        "condassetclassification": {

            "type": "string"

        },

        "condassetid": {

            "type": "string"

        },

        "condcurrentvalue": {

            "type": "string"

        },

        "condeventtype": {

            "type": "string"

        },

        "condtagid": {

            "type": "string"

        },

        "customerAssets": {

            "type": "null"

        },

        "ibx": {

            "type": "string"

        },

        "infraAssets": {

            "type": "null"

        },

        "measurementType": {

            "type": "null"

        },

        "region": {

            "type": "null"

        },

        "section": {

            "type": "string"

        },

        "thresholdUnit": {

            "type": "string"

        },

        "thresholdValue": {

            "type": "string"

        },

        "thresholdValueMax": {

            "type": "string"

        },

        "thresholdValueMin": {

            "type": "string"

        },

        "uom": {

            "type": "string"

        }

    }

},

"AlertType": {

    "type": "object",

    "properties": {

        "defaultValue": {

            "type": "null"

        },

        "eventType": {

            "type": "string"

        },

        "id": {

            "type": "string"

        },

        "tagId": {

            "type": "null"

        },

        "type": {

            "type": "string"

        },

        "unit": {

            "type": "string"

        },

        "value": {

            "type": "string"

        }

    }

},

"Alert": {

    "type": "object",

    "properties": {

        "accountNo": {

            "type": "string"

        },

        "acknowledge": {

            "type": "boolean"

        },

        "affectedCustomerAsset": {

            "type": "null"

        },

        "alertType": {

            "": "#/definitions/AlertType"

        },

        "alertTypeName": {

            "type": "string"

        },

        "asset": {

            "type": "string"

        },

        "assetclassification": {

            "type": "string"

        },

        "assetname": {

            "type": "string"

        },

        "assettype": {

            "type": "string"

        },

        "conditionalAlert": {

            "": "#/definitions/AlertCondition"

        },

        "country": {

            "type": "string"

        },

        "createdOn": {

            "type": "null"

        },

        "currentvalue": {

            "type": "string"

        },

        "eventtype": {

            "type": "string"

        },

        "ibx": {

            "type": "string"

        },

        "id": {

            "type": "string"

        },

        "lastmaintenance": {

            "type": "string"

        },

        "metro": {

            "type": "string"

        },

        "modifiedOn": {

            "type": "null"

        },

        "notificationType": {

            "type": "string"

        },

        "region": {

            "type": "string"

        },

        "relatedincidents": {

            "type": "string"

        },

        "resiliency": {

            "type": "string"

        },

        "section": {

            "type": "string"

        },

        "severity": {

            "type": "string"

        },

        "tagid": {

            "type": "string"

        },

        "thresholdUnit": {

            "type": "string"

        },

        "thresholdValue": {

            "type": "string"

        },

        "thresholdValueMax": {

            "type": "string"

        },

        "thresholdValueMin": {

            "type": "string"

        },

        "timeZone": {

            "type": "string"

        },

        "timeacknowledged": {

            "type": "string"

        },

        "timeprocessed": {

            "type": "string"

        },

        "timetriggeredMilisec": {

            "type": "string"

        },

        "triggeredOn": {

            "type": "integer"

        },

        "type": {

            "type": "string"

        },

        "uom": {

            "type": "string"

        },

        "year": {

            "type": "string"

        }

    }

}

 


body: 
EnvironmentData

"EnvironmentData": {

    "type": "object",

    "properties": {

        "ibx": {

            "type": "string",

            "description": "ibx code"

        },

        "accountNo": {

            "type": "string",

            "description": "account number"

        },

        "zone": {

            "type": "string",

            "description": "zone unique space id"

        },

        "cage": {

            "type": "string",

            "description": "cage unique space id"

        },

        "cabinet": {

            "type": "string",

            "description": "cabinet unique space id"

        },

        "sensor": {

            "type": "string",

            "description": "sensor id"

        },

        "temperature": {

            "type": "string",

            "description": "current temperature"

        },

        "humidity": {

            "type": "string",

            "description": "current humidity"

        },

        "timestamp": {

            "type": "string",

            "description": "epoch timestamp when the current reading was read"

        },

        "temperatureUom": {

            "type": "string",

            "description": "unit of measure for temperature values"

        },

        "humidityUom": {

            "type": "string",

            "description": "unit of measure for humidity"

        },

        "minTemperature": {

            "type": "string",

            "description": "minimum temperature for last x(?) hours"

        },

        "maxTemperature": {

            "type": "string",

            "description": "maximum temperature for last x(?) hours"

        },

        "minHumidity": {

            "type": "string",

            "description": "minimum humidity for last x(?) hours"

        },

        "maxHumidity": {

            "type": "string",

            "description": "maximum humidity for last x(?) hours"

        }

    }

}

 


body: 
PowerData

"PowerData": {

    "type": "object",

    "properties": {

        "ibx": {

            "type": "string",

            "description": "ibx code"

        },

        "accountNo": {

            "type": "string",

            "description": "customer account number"

        },

        "levelType": {

            "type": "string",

            "description": "power hierarchy node levelType linked to the power data",

            "enum": [

                "ibx",

                "cage",

                "cabinet",

                "circuit"

            ]

        },

        "levelValue": {

            "type": "string",

            "description": "power hierarchy node levelValue linked to the power data. ibx code, \ncage unique space id, cabinet unique space id and circuit id for \nlevelType ibx, cage, cabinet, circuit resp.\n"

        },

        "isAlarm": {

            "type": "string"

        },

        "kva": {

            "type": "number",

            "description": "power consumption in kva"

        },

        "amps": {

            "type": "number",

            "description": "instantaneous current amp reading on circuits"

        },

        "cage": {

            "type": "string",

            "description": "cage unique space id"

        },

        "cabinet": {

            "type": "string",

            "description": "cabinet unique space id"

        },

        "soldKva": {

            "type": "number",

            "description": "maximum amp draw allowable on a circuit"

        },

        "cabinetRating": {

            "type": "number",

            "description": "maximum kVA draw allowed for the cabinet"

        },

        "contractualKva": {

            "type": "number",

            "description": "The maximum power draw contractually allowable in a \nprivate cage. \n"

        },

        "percentageKva": {

            "type": "number",

            "description": "calculated field kva / contractualKva"

        },

        "peakKvaLastSevenDays": {

            "type": "number"

        },

        "peakKvaLastSevenDaysPercentage": {

            "type": "number"

        },

        "peakKvaLastSevenDaysContractualKva": {

            "type": "number"

        },

        "peakKvaLastSevenDaysTime": {

            "type": "integer"

        },

        "type": {

            "type": "string",

            "description": "value to be IBX, CAGE, CABINET, primary or redundant for levelType\nibx, cage, cabinet, circuit resp.\n",

            "enum": [

                "IBX",

                "CAGE",

                "CABINET",

                "primary",

                "redundant"

            ]

        },

        "description": {

            "type": "string",

            "description": "circuit description when the levelType is circuit. null otherwise. \n"

        },

        "soldAmps": {

            "type": "integer"

        },

        "primaryKva": {

            "type": "number",

            "description": "the sum of instantaneous power draw reading on all the primary \ncircuits within the levelType.\n"

        },

        "redundantKva": {

            "type": "number",

            "description": "the sum of instantaneous power draw reading on all the redundant \ncircuits within the levelType.\n"

        },

        "kw": {

            "type": "string",

            "description": "measure of real power expressed in kilowatt applicable for ibxs\nthat have capability of energy meter reading\n"

        },

        "powerFactor": {

            "type": "string",

            "description": "The ratio between real power and apparent power in a circuit.(kW/kVA)\n"

        },

        "readingTime": {

            "type": "string",

            "description": "date-time when the latest value was read in (epoc - milliseconds). \n"

        },

        "lastUpdatedTime": {

            "type": "string",

            "description": "date-time when the latest value was updated (epoc - milliseconds).\n"

        },

        "customerName": {

            "type": "string"

        }

    }

}

 


body: 
TagPointData

"TagPointData": {

    "type": "object",

    "description": "Tag Point is a property of the Asset it is linked to.\n",

    "properties": {

        "value": {

            "type": "string",

            "description": "Current data value for the tag point\n"

        },

        "tagId": {

            "type": "string",

            "description": "ID for the tagPoint - Unique Identifier for the Tag Point\n"

        },

        "tagDisplayName": {

            "type": "string",

            "description": "Generic label for the tag point\n"

        },

        "uom": {

            "type": "string",

            "description": "Unit of measure for the data value for the tag point\n"

        },

        "alarmStatus": {

            "type": "string",

            "description": "Indicates whether there are any alarms currently active for the tag\npoint\n"

        },

        "readingTime": {

            "type": "string",

            "format": "date-time",

            "description": "date time when the tag point value was read from the device. \n"

        }

    }

}

 


body: 

Sample Code

 


body: 

IBX SmartView APIs

Refer IBX SmartView sample to download the sample code for the following APIS:

 

1. Alarms

2. Assets

3. Environments

4. Power

5. Hierarchy

6. Subscriptions 

 

Follow the instructions provided in the README.md for instructions on how to set up and configure the project. If you have trouble downloading the code, post the issue on our forum or contact api-support@equinix.com.

 


body: 

Status codes, Error codes & Troubleshooting tips

This section provides an overview of the common error codes as well as general guidance on how to troubleshoot and handle errors.

 


body: 

200: Success

The 200 (Success) status code indicates that the HTTP request was successful. In a GET request, the response will contain an entity corresponding to the requested resource whereas, in a POST request, the response will contain an entity describing or containing the result of the action.

 

Code 200
Description Success.

 

curl -X 

GET "https://api.equinix.com/asset/v1/tagpoint/current?accountNo=1&ibx=CH1&tagId=CH1.Lead%20Chilled%20Water%20Manager:primarychilledwatersupplytemperature"     

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 

This is an example of a success message.

 

{
    "payLoad": [
        {
            "value": "5.7",
            "tagId": "CH1.Lead Chilled Water Manager:primarychilledwatersupplytemperature",
            "tagDisplayName": "Primary Chilled Water Supply Temperature",
            "uom": "°C",
            "readingTime": "20190218225701"
        }
    ],
    "status": {
        "type": "INFO",
        "statuscode": "1000",
        "msg": "OK"
    }
}

 


body: 

400: Bad Request

The 400 (Bad request) status code indicates that server cannot process the request due to something that is perceived to be a client error (e.g. malformed request syntax, invalid request message framing, or deceptive request routing).

 

Code 400
Description Validation Error.
Generic Cause Malformed request due to field or business validation.
Quick Fix Ensure the payload sent adheres to the parameter requirements.

 

There are different types of Validation errors and this section provides sample scenarios with validation errors as well as tips on how to identify them.

 


body: 

401: Unauthorized

The 401 (Unauthorized) status code indicates that the authentication credentials received are not authorized. The user may repeat the request with a new or replaced Authorization header field. 

 

Code 401
Description Authentication Error.
Generic Cause Unauthorized authentication token.
Quick Fix Verify whether an authentication token is obtained and ensure to provide this with each request.

 

There are different types of Authentication errors and this section provides sample scenarios of authentication errors as well as tips on how to identify them.

 


body: 

404: Resource not found 

The 404 (Resource not found) status code indicates that the server cannot find the requested resource but may be available in the future.

 

Code 404
Description Resource not found.
Generic Cause Resource is invalid or unavailable.
Quick Fix Verify end-point URL and resource info.

 


body: 

404 - Invalid Endpoint

Code 404
Description Not Found
Generic Cause Invalid API path in URL or payload.
Quick Fix Verify the end-point information submitted.

 

   Error scenario example

ERROR   

CODE:       "404"
MESSAGE:    "Not Found - No message available"

PATH        "/feedsubscription/v1/subscribed"

TIMESTAMP   "1544951546619"

 

Verify end-point URL.

 

The end-point URL is incorrect. Replace endpoint subscribed with subscribe.

curl -X
GET "http://api.equinix.com/feedsubscription/v1/subscribe"

-H "accept: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 


body: 

415: Unsupported media type 

The 415 (Unsupported media type) status code indicates that the request has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.

 

 

Code 415
Description Unsupported media type.
Generic Cause Server is refusing to service the request because the payload is in a format not supported by this method on the target resource.
Quick Fix Verify request payload.

 


body: 

500: Internal Server Error 

The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

 

Code 500
Description Internal server error.
Generic Cause System encountered an unexpected problem and is being tracked.
Quick Fix Try again or or post the issue on our forum or contact api-support@equinix.com.

 


body: 

429: Too many request Error

The 429 (Too many requests) status code indicates that the user has sent too many requests in a given amount of time.

 

Code 429
Description Internal server error.
Generic Cause Request rejected due to rate limiting (number of requests exceeded for the given time).
Quick Fix Try again later or post the issue on our forum or contact api-support@equinix.com .

 


body: 

503: Service unavailable

The 503 (Service unavailable) status code indicates that the server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

 

Code 503
Description Service unavailable.
Generic Cause Service unavailable due to temporary overload or scheduled maintenance and is likely be alleviated after some delay.
Quick Fix Try again or post the issue on our forum or contact api-support@equinix.com.
 

 


body: 

Equinix IBX SmartView error codes

 


body: 

3001: Invalid Level Type

Error Code

3001

Description

Invalid Level Type.

Generic Cause

The levelType specified in the request in not one of the valid values.

Quick Fix Try again by changing the levelType to one of the valid values - IBX, CAGE, CABINET, CIRCUIT. If it does not work, post the issue on our forum or contact api-support@equinix.com. 

 

    Error scenario example

{
    "payLoad": {},
    "status": {
        "type": "ERROR",
        "statuscode": "3001",
        "msg": "Invalid Level Type"
    }
}

 

Retry calling the API URL.

 

curl -X 

The levelType is incorrect. Replace with the correct type.

GET "https://api.equinix.com/environment/v1/current/?accountNo=1&ibx=CH1&levelType=ibc&levelValue=CH1"     

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2' 

 


body: 

4000: Internal Error

Error Code

4000

Description

Internal error.

Generic Cause

The request is missing a key input parameter.

Quick Fix Try again by reviewing the required parameters and, post the issue on our forum or contact api-support@equinix.com. 

 

    Error scenario example

{
    "payLoad": {},
    "status": {
        "type": "ERROR",
        "statuscode": "4000",
        "msg": "INTERNAL_ERROR"
    }
}

 

Retry calling the API URL.

 

curl -X 

The ibx is missing in the URL. Add the value '&ibx=CH1' and try again

 

GET "https://api.equinix.com/environment/v1/current/?accountNo=1&levelType=ibx&levelValue=CH1"  

-H "content-type: application/json"

-H "authorization: Bearer asxQMSbBwc

 


body: 

Don't Like Reading?


body: 

How about a short video? 

Equinix IBX SmartView API Overview

 

 

Calling OAuth API

 

 


body: 

Take a shot at our forum

Equinix IBX SmartView Forum

 


body: 

Glossary

 

Access Token

A credential used to communicate with the API

Cage

A custom build (as per customer’s requirement) and secured mesh enclosure to house multiple cabinets in it.

IBX

Equinix International Business Exchange

OAuth

 

OAuth (Open Authorization) is an open standard for token-based authentication and authorization on the Internet.

 

Rack

A physical enclosure to hold IT equipment, also called a Cabinet.

 

Refresh Token

 

A token that contains the information required to obtain a new Access Token.

 

 


body: 

Style guide and References

Additional information

 

 

Tips and recommendation 

 

 

Critical information 

 

 

Code snippet

 

 

Output snippet 

 

 

Error information

 

 

Internal Links

 

External Links

 

References Links
AWS AWS icons
Azure Azure logo
Google Google icons    Google logo
Oracle Oracle logo

 


body: 

 

 

 Contact us

If you have any questions or comments regarding Equinix APIs, please contact api-support@equinix.com


Twitter Feed

About Equinix

Equinix connects the world's leading businesses to their customers, employees and partners inside the world's most connected data centers in 44 markets across five continents. In the United States, Equinix operates data centers in Atlanta, Boston, Chicago, Dallas, Denver, Los Angeles, Miami, New York, Philadelphia, Seattle, Silicon Valley and Washington D.C.

Developer Platform - Key Highlights

  • Explore, Subscribe & Connect to Equinix API Ecosystem​
  • Test Drive Equinix APIs using our Playground
  • Start your journey with Getting Started Guide

Recent News