Jump to

• Request
• Response

Get Raw Interval Usage

get

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

Returns the raw AMI usage data for the given time period. Raw data can be returned for up to 100 intervals in a single request. Data is available for last two years (730 days) preceding the time of the API request. 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 : UsageResponse

Type: object

Show Source

• end(required): string
  The end date in the request
• fuelType(required): string
  The fuel type in the request, for example, GAS
• start(required): string
  The start date in the request
• streams(required): array streams
• 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",
        "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, for example, GAS"
        },
        "start":{
            "type":"string",
            "description":"The start date in the request"
        },
        "end":{
            "type":"string",
            "description":"The end date in the request"
        },
        "unit":{
            "type":"string",
            "description":"The unit of measurement of all fuel usage values"
        },
        "streams":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/UsageStream"
            }
        }
    },
    "example":{
        "response":{
            "utilityCode":"util",
            "utilityCustomerId":"9999990000-9999990000",
            "fuelType":"ELECTRICITY",
            "start":"2017-09-01T00:00:00-06:00",
            "end":"2017-09-01T00:30:00-06:00",
            "unit":"KWH",
            "streams":[
                {
                    "utilityServicePointId":"12345001",
                    "intervals":[
                        {
                            "start":"2017-09-01T00:00:00-06:00",
                            "end":"2017-09-01T00:15:00-06:00",
                            "usage":0.14,
                            "readType":"ACTUAL"
                        },
                        {
                            "start":"2017-09-01T00:15:00-06:00",
                            "end":"2017-09-01T00:30:00-06:00",
                            "usage":0.19,
                            "readType":"ACTUAL"
                        }
                    ]
                }
            ]
        }
    }
}

Example:

{
    "response":{
        "utilityCode":"util",
        "utilityCustomerId":"9999990000-9999990000",
        "fuelType":"ELECTRICITY",
        "start":"2017-09-01T00:00:00-06:00",
        "end":"2017-09-01T00:30:00-06:00",
        "unit":"KWH",
        "streams":[
            {
                "utilityServicePointId":"12345001",
                "intervals":[
                    {
                        "start":"2017-09-01T00:00:00-06:00",
                        "end":"2017-09-01T00:15:00-06:00",
                        "usage":0.14,
                        "readType":"ACTUAL"
                    },
                    {
                        "start":"2017-09-01T00:15:00-06:00",
                        "end":"2017-09-01T00:30:00-06:00",
                        "usage":0.19,
                        "readType":"ACTUAL"
                    }
                ]
            }
        ]
    }
}

Nested Schema : streams

Type: array

Show Source

• Array of: object UsageStream

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

Nested Schema : UsageStream

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/UsageInterval"
            }
        }
    }
}

Nested Schema : intervals

Type: array

Show Source

• Array of: object UsageInterval

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

Nested Schema : UsageInterval

Type: object

Show Source

• end(required): string
  The end of the period. This is an exclusive date/time String in ISO8601 format.
• readType(required): string
  Allowed Values: [ "ACTUAL", "ESTIMATED", "SELF_REPORTED", "FORECAST" ]
• start(required): string
  The start of the period. This is an inclusive date/time String in ISO8601 format.
• usage(required): number
  The total energy use for the day, in the chosen fuel type units.

{
    "type":"object",
    "required":[
        "start",
        "end",
        "usage",
        "readType"
    ],
    "properties":{
        "start":{
            "type":"string",
            "description":"The start of the period. This is an inclusive date/time String in ISO8601 format."
        },
        "end":{
            "type":"string",
            "description":"The end of the period. This is an exclusive date/time String in ISO8601 format."
        },
        "usage":{
            "type":"number",
            "description":"The total energy use for the day, in the chosen fuel type units."
        },
        "readType":{
            "$ref":"#/definitions/ReadType"
        }
    }
}

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