Field Reduction

All EnergyCAP GET endpoints support field reduction. This lets you choose exactly which fields are returned in the response, reducing payload size and improving performance — especially on endpoints that return large or deeply nested objects like meters, bills, and accounts.

Why Use Field Reduction?

A typical meter response includes 20+ fields with nested objects (commodity, accounts, place, channels, etc.). If you only need the meter ID and code, you’re transferring far more data than necessary.

Scenario Without field reduction With field reduction
10,000 meters, all fields ~15 MB ~0.5 MB
Response time Slower Faster
Parsing complexity High Low

Syntax

Add the field query parameter with a comma-separated list of field names:

?field=field1,field2,field3

Example: Include Specific Fields

Without field reduction — a meter response returns everything:

curl -X GET "https://app.energycap.com/api/v3/meter" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "meterId": 1,
  "meterCode": "MTR-001",
  "meterInfo": "Main Building Electric",
  "meterType": {
    "meterTypeId": 1,
    "meterTypeCode": "STANDARD",
    "meterTypeInfo": "Standard Meter"
  },
  "commodity": {
    "commodityId": 1,
    "commodityCode": "ELECTRIC",
    "commodityInfo": "Electric"
  },
  "accounts": [
    {
      "accountMeterId": 1,
      "accountId": 100,
      "accountCode": "ACCT-100",
      "accountInfo": "Main Electric Account",
      "startDate": "2020-01-01",
      "endDate": null
    }
  ],
  "place": {
    "placeId": 10,
    "placeCode": "MAIN-BLDG",
    "placeInfo": "Main Building",
    "placeType": { "placeTypeId": 1, "placeTypeCode": "BUILDING", "placeTypeInfo": "Building" }
  },
  "city": "State College",
  "state": "PA",
  "postalCode": "16801",
  "createdBy": { "userId": 1, "userCode": "jsmith", "fullName": "John Smith" },
  "createdDate": "2020-01-15T10:30:00",
  "modifiedBy": { "userId": 1, "userCode": "jsmith", "fullName": "John Smith" },
  "modifiedDate": "2024-06-10T14:22:00",
  "includeInEnergyStar": true,
  "includeInCostAvoidance": true
}

With field reduction — request only what you need:

curl -X GET "https://app.energycap.com/api/v3/meter?field=meterId,meterCode,meterInfo" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "meterId": 1,
  "meterCode": "MTR-001",
  "meterInfo": "Main Building Electric"
}

Excluding Fields

By default, the field parameter specifies which fields to include. To flip the behavior and exclude specific fields instead, add fieldAction=exclude:

curl -X GET "https://app.energycap.com/api/v3/meter?field=properties,channels,createdBy,modifiedBy&fieldAction=exclude" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

This returns all fields except properties, channels, createdBy, and modifiedBy.

Parameter Value Behavior
fieldAction (omitted) Include only the fields listed in field
fieldAction exclude Return all fields except those listed in field
Tip
Use include when you need a small number of specific fields. Use exclude when you want most fields but need to drop a few large nested objects.

Nested Object Fields

You can include top-level nested objects by name. The entire nested object is returned:

?field=meterId,meterCode,commodity

{
  "meterId": 1,
  "meterCode": "MTR-001",
  "commodity": {
    "commodityId": 1,
    "commodityCode": "ELECTRIC",
    "commodityInfo": "Electric"
  }
}

Practical Examples

Build a dropdown list of accounts

Only need the ID and display name:

?field=accountId,accountCode,accountInfo

Export bill data with just financial fields

?field=billId,accountId,totalCost,totalUse,periodStart,periodEnd

Get meters with location info, skip audit fields

?field=createdBy,createdDate,modifiedBy,modifiedDate,properties&fieldAction=exclude

Combining with Filters and Pagination

Field reduction works alongside filters and pagination. Use all three together for optimal performance:

curl -X GET "https://app.energycap.com/api/v3/bill?filter=accountId equals '1234'&field=billId,totalCost,periodStart,periodEnd&pageSize=500" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

This request:

  1. Filters to only bills for account 1234
  2. Reduces each bill to four fields
  3. Pages at 500 items per request

Tips

  • Field names are case-sensitive — use the exact casing from the API documentation
  • Unknown field names are silently ignored — double-check your spelling if a field is missing from the response
  • Field reduction applies to every object in the response array, not just the first one
  • Start with the fields you need and add more as your integration evolves, rather than returning everything upfront