Field Reduction

All EnergyCAP GET APIs support field reduction. Field reduction allows the user to choose which fields are returned in the JSON response. This is most useful for endpoints that return large result sets, like the bill and meter APIs.

Syntax

The EnergyCAP API uses a custom syntax field reduction. The basic syntax is to supply a query parameter ‘field’ followed by a comma separated list of field names to include in the response. For example, a call to the GET meter endpoint without field reduction would use the following url:

/api/v2/meter

It could result in the following response:

[
  {
    "meterId": 1,
    "meterCode": "sample string 2",
    "meterInfo": "sample string 3",
    "meterType": {
      "meterTypeId": 1,
      "meterTypeCode": "sample string 2",
      "meterTypeInfo": "sample string 3"
    },
    "channels": [
      {
        "channelId": 1,
        "channelCode": "sample string 2"
      },
      {
        "channelId": 1,
        "channelCode": "sample string 2"
      }
    ],
    "accounts": [
      {
        "accountMeterId": 1,
        "accountId": 2,
        "accountCode": "sample string 3",
        "accountInfo": "sample string 4",
        "startDate": "2014-06-25T08:58:57.3042129-04:00",
        "endDate": "2014-06-25T08:58:57.3042129-04:00"
      },
      {
        "accountMeterId": 1,
        "accountId": 2,
        "accountCode": "sample string 3",
        "accountInfo": "sample string 4",
        "startDate": "2014-06-25T08:58:57.3042129-04:00",
        "endDate": "2014-06-25T08:58:57.3042129-04:00"
      }
    ],
    "commodity": {
      "commodityId": 1,
      "commodityCode": "sample string 2",
      "commodityInfo": "sample string 3"
    },
    "place": {
      "placeId": 1,
      "placeCode": "sample string 2",
      "placeInfo": "sample string 3",
      "placeType": {
        "placeTypeId": 1,
        "placeTypeCode": "sample string 2",
        "placeTypeInfo": "sample string 3"
      }
    },
    "postalCode": "sample string 4",
    "city": "sample string 5",
    "state": "sample string 6",
    "country": "sample string 7",
    "line1": "sample string 8",
    "line2": "sample string 9",
    "billEntryNote": "sample string 10",
    "includeInEnergyStar": true,
    "primaryUse": {
      "primaryUseId": 1,
      "primaryUseCode": "sample string 2",
      "primaryUseInfo": "sample string 3"
    },
    "createdBy": {
      "userId": 1,
      "userCode": "sample string 2",
      "fullName": "sample string 3"
    },
    "createdDate": "2014-06-25T08:58:57.3052121-04:00",
    "modifiedBy": {
      "userId": 1,
      "userCode": "sample string 2",
      "fullName": "sample string 3"
    },
    "modifiedDate": "2014-06-25T08:58:57.3052121-04:00",
    "properties": {
      "sample string 1": "sample string 2",
      "sample string 3": "sample string 4"
    },
    "includeInCostAvoidance": true
  }
]

When using field reduction to specify that only the meter identifier and meter code fields should be returned, the url becomes:

/api/v2/meter?field=meterId,meterCode

And the response becomes:

[
  {
    "meterId": 1,
    "meterCode": "sample string 2"
  }
]

Field Actions

The EnergyCAP API allows the user to either specify the fields to be included in the response or specify the fields to be excluded from the response. The default behavior, as seen in the example above, is to include only the specified fields. To exclude the specified fields, the url must include a ‘fieldAction’ parameter with the value of ‘exclude’ :

/api/v2/meter?field=meterId,meterCode&fieldAction=exclude