Jump to

• Request
• Response

Get Daily Interval Usage

get

/apis/usage-v1/usage/day/{utilityCode}/{utilityCustomerId}/{fuelType}

Returns the AMI usage data for the given time period, aggregated by day. Daily data can be returned for up to 45 days in a single request. Days run from midnight to midnight in the local timezone of the site or service point. If the active utility account is associated with multiple service points of the same fuel type usage data per service point is returned.

Request

Path Parameters

• fuelType(required): string
  Fuel type to query for; ELECTRICITY or GAS
• id(required): integer
  The single-tenant id for the customer (e.g. `1`).
• utilityCode(required): string
  The 3 or 4 digit code for the utility company (e.g. `TEST`).

Query Parameters

• end(required): string
  End date in ISO-8601 format YYYY-MM-DD (example 2001-12-31) or YYYY-MM-DDThh:mm:ssTZD (example 2001-12-31T23:59:59-05:00) or YYYY-MM-DDThh:mm:ss.sTZD. Use -00:00 for UTC as Z is not currently supported. The + character is a reserved character in URIs, use its encoding %2B.
• start(required): string
  Start date in ISO-8601 format YYYY-MM-DD (example 2001-12-31) or YYYY-MM-DDThh:mm:ssTZD (example 2001-12-31T23:59:59-05:00) or YYYY-MM-DDThh:mm:ss.sTZD. Use -00:00 for UTC as Z is not currently supported. The + character is a reserved character in URIs, use its encoding %2B.

Header Parameters

• Authorization(required): string
  The authorization header (e.g. `Authorization: Bearer $YOUR_TOKEN`).

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful response

Body ()

Root Schema : DayUsageResponse

Type: object

Show Source

• end(required): string
  The end date in the request
• fuelType(required): string
  The fuel type in the request
• start(required): string
  The start date in the request
• streams(required): array streams
• timezone(required): string
  The time zone of the service point location, expressed in ISO-8601 format. The time zone is used to define the day ranges for energy use.
• unit(required): string
  The unit of measurement of all fuel usage values
• utilityCode(required): string
  The 3 or 4 character code for the utility company; for example util.
• utilityCustomerId(required): string
  The utility customer identifier in the request

{
    "type":"object",
    "required":[
        "utilityCode",
        "utilityCustomerId",
        "fuelType",
        "start",
        "end",
        "timezone",
        "unit",
        "streams"
    ],
    "properties":{
        "utilityCode":{
            "type":"string",
            "description":"The 3 or 4 character code for the utility company; for example util."
        },
        "utilityCustomerId":{
            "type":"string",
            "description":"The utility customer identifier in the request"
        },
        "fuelType":{
            "type":"string",
            "description":"The fuel type in the request"
        },
        "start":{
            "type":"string",
            "description":"The start date in the request"
        },
        "end":{
            "type":"string",
            "description":"The end date in the request"
        },
        "timezone":{
            "type":"string",
            "description":"The time zone of the service point location, expressed in ISO-8601 format. The time zone is used to define the day ranges for energy use."
        },
        "unit":{
            "type":"string",
            "description":"The unit of measurement of all fuel usage values"
        },
        "streams":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/AggregatedUsageStream"
            }
        }
    },
    "example":{
        "response":{
            "utilityCode":"util",
            "utilityCustomerId":"9999990000-9999990000",
            "fuelType":"ELECTRICITY",
            "start":"2017-08-01T00:00:00-06:00",
            "end":"2017-08-03T00:00:00-06:00",
            "timezone":"America/New_York",
            "unit":"KWH",
            "streams":[
                {
                    "utilityServicePointId":"12345001",
                    "intervals":[
                        {
                            "start":"2017-08-01T00:00:00-06:00",
                            "end":"2017-08-02T00:00:00-06:00",
                            "usage":24.1,
                            "actualReadsCount":91,
                            "estimatedReadsCount":3
                        },
                        {
                            "start":"2017-08-02T00:00:00-06:00",
                            "end":"2017-08-03T00:00:00-06:00",
                            "usage":23.8,
                            "actualReadsCount":94,
                            "estimatedReadsCount":0,
                            "selfReportedReadsCount":0,
                            "forecastReadsCount":0
                        }
                    ]
                }
            ]
        }
    }
}

Example:

{
    "response":{
        "utilityCode":"util",
        "utilityCustomerId":"9999990000-9999990000",
        "fuelType":"ELECTRICITY",
        "start":"2017-08-01T00:00:00-06:00",
        "end":"2017-08-03T00:00:00-06:00",
        "timezone":"America/New_York",
        "unit":"KWH",
        "streams":[
            {
                "utilityServicePointId":"12345001",
                "intervals":[
                    {
                        "start":"2017-08-01T00:00:00-06:00",
                        "end":"2017-08-02T00:00:00-06:00",
                        "usage":24.1,
                        "actualReadsCount":91,
                        "estimatedReadsCount":3
                    },
                    {
                        "start":"2017-08-02T00:00:00-06:00",
                        "end":"2017-08-03T00:00:00-06:00",
                        "usage":23.8,
                        "actualReadsCount":94,
                        "estimatedReadsCount":0,
                        "selfReportedReadsCount":0,
                        "forecastReadsCount":0
                    }
                ]
            }
        ]
    }
}

Nested Schema : streams

Type: array

Show Source

• Array of: object AggregatedUsageStream

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/AggregatedUsageStream"
    }
}

Nested Schema : AggregatedUsageStream

Type: object

Show Source

• intervals(required): array intervals
• utilityServicePointId(required): string

{
    "type":"object",
    "required":[
        "utilityServicePointId",
        "intervals"
    ],
    "properties":{
        "utilityServicePointId":{
            "type":"string"
        },
        "intervals":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/AggregateUsageInterval"
            }
        }
    }
}

Nested Schema : intervals

Type: array

Show Source

• Array of: object AggregateUsageInterval

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/AggregateUsageInterval"
    }
}

Nested Schema : AggregateUsageInterval

Type: object

Show Source

• actualReadsCount(required): integer
  The count of actual reads used in calculating the daily usage
• end(required): string
  The end of the day, a date/time Sstring in ISO8601 format
• estimatedReadsCount(required): integer
  The count of estimated reads used in calculating the daily usage
• forecastReadsCount(required): integer
  The count of forecast reads used in calculating the daily usage
• readType(required): string
  Allowed Values: [ "ACTUAL", "ESTIMATED", "SELF_REPORTED", "FORECAST" ]
• selfReportedReadsCount: integer
  The count of self-reported reads used in calculating the daily usage
• start(required): string
  The start of the day, a date/time String in ISO8601 format
• usage(required): number
  The total fuel usage for the day, in the chosen fuel type units.

{
    "type":"object",
    "required":[
        "start",
        "end",
        "usage",
        "readType",
        "actualReadsCount",
        "estimatedReadsCount",
        "selfReportedReads",
        "forecastReadsCount"
    ],
    "properties":{
        "start":{
            "type":"string",
            "description":"The start of the day, a date/time String in ISO8601 format"
        },
        "end":{
            "type":"string",
            "description":"The end of the day, a date/time Sstring in ISO8601 format"
        },
        "usage":{
            "type":"number",
            "description":"The total fuel usage for the day, in the chosen fuel type units."
        },
        "readType":{
            "$ref":"#/definitions/ReadType"
        },
        "actualReadsCount":{
            "type":"integer",
            "description":"The count of actual reads used in calculating the daily usage"
        },
        "estimatedReadsCount":{
            "type":"integer",
            "description":"The count of estimated reads used in calculating the daily usage"
        },
        "selfReportedReadsCount":{
            "type":"integer",
            "description":"The count of self-reported reads used in calculating the daily usage"
        },
        "forecastReadsCount":{
            "type":"integer",
            "description":"The count of forecast reads used in calculating the daily usage"
        }
    }
}

400 Response

Invalid request

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

401 Response

Unauthorized

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

403 Response

Forbidden

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

404 Response

Customer not found

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

500 Response

Internal error

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

503 Response

Service Unavailable

Body ()

Root Schema : ErrorResponse

Type: object

Show Source

• details: string
  Details about the error.
• errorMessage: string
  Short failure explanation.
• httpStatus: integer
  Minimum Value: 100

  Maximum Value: 600

  The HTTP status code for the error.
• serviceErrorCode: string
  An error code for the error.

{
    "type":"object",
    "properties":{
        "httpStatus":{
            "description":"The HTTP status code for the error.",
            "type":"integer",
            "minimum":100,
            "maximum":600
        },
        "serviceErrorCode":{
            "description":"An error code for the error.",
            "type":"string"
        },
        "errorMessage":{
            "description":"Short failure explanation.",
            "type":"string"
        },
        "details":{
            "description":"Details about the error.",
            "type":"string"
        }
    },
    "additionalProperties":false
}

Back to Top