Files

This is an open-ended endpoint that is a catchall for raw files and export downloads that are linked in the normal API endpoints. Files under this endpoint must be accessed directly (i.e. you can't list files visible to you). These requests are still authenticated, which means they require an api token.

# Raw bill pdf
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/files/pdf_bill?uid=1231243343'
# CSV export of bills for an authorization
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/files/csv/3248578394ijsfhu4789hrutg78u893kesyh8934rj'

The exports object on the Authorization and Meter objects contain links to various export formats that can be helpful to people manually processing data collected via UtilityAPI. These links are mainly used in our dashboard on our website (since we use our own API) for non-API users. If you are using the API, please avoid relying on files linked in the exports object since they are not documented and may change without notice.

// Example exports object
{
    "bills_csv": "https://utilityapi.com/api/v2/files/1238333328334323.csv",
    "bills_zip": "https://utilityapi.com/api/v2/files/18334323.zip",
    "latest_pdf": "https://utilityapi.com/api/v2/files/latest_pdf?meter=12314",
    "intervals_csv": "https://utilityapi.com/api/v2/files/1238333328334323i.csv",
    "intervals_xml": "https://utilityapi.com/api/v2/files/1238333328334323000.xml"
}

The exports list object on the Authorization and Meter objects contain name and links to various export formats that can be helpful to people manually processing data collected via UtilityAPI. These links are mainly used in our dashboard on our website (since we use our own API) for non-API users. If you are using the API, please avoid relying on files linked in the exports list object since they are not documented and may change without notice.

// Example exports list object
[{
    "name": "Bills: all bills [csv]",
    "link": "https://utilityapi.com/api/v2/files/1238333328334323.csv",
 },
 {
    "name": "Bills: all pdfs [zip]",
    "link": "https://utilityapi.com/api/v2/files/18334323.zip",
 } ...
]

GET /files/known_tariffs_json

Each utility has a unique list of tariffs, so we created an endpoint that lists the vast majority of the tariffs you can expect to see in Base Meter Block service_tariff and Base Bill Block service_tariff values. Since this is a documented endpoint, the url won't change for this tariffs list.

GET /files/supported_utilities_json

This endpoint provides a list of utilities we support. We add support for requesting data from new utilities pretty regularly, so if you want to dynamically load a list of our currently supported utilities, use this endpoint. Information provided for each utility includes:

Attribute Format Description Example
documentation URL Documentation for the utility. "https://utilityapi.com/docs/utilities/ace"
id String Utility ID (this is the utility identifier you use in our API). "ACE"
name String or null The name of the utility. "Atlantic City Electric"
website URL or null Utility website. "https://www.atlanticcityelectric.com/"
Code Response Format Description
200 Various Successful request. The file format varies based on which file you are downloading, so check the Content-Type response header for the format type.
202 Empty Request is too large to be synchronous, so building a cache asynchronously. See Retry-After header for how long to wait before trying again.
400 Error The query parameters included are malformed. Check the error in the response for the type of error:
  • invalid_param - One of the query parameters was invalid. Check the error description for more info.
We may add more error types in the future, so be able to handle unknown types.
401 Error Invalid or missing access_token. See our docs on Authentication for how to properly use your access_token.
429 N/A The request was rate limited. Check the Retry-After response header for how long to wait until retrying the request. Do not expect any specific response format for this error (could be html, json, or nothing).
500 N/A Internal server error. Do not expect any specific response format for this error (could be html, json, or nothing). This error is logged and will be fixed by our engineers.
503 N/A Site is currently down for maintenance. Do not expect any specific response format for this error (could be html, json, or nothing).
504 N/A We tried to build this request but timed out. Please try again later. Do not expect any specific response format for this error (could be html, json, or nothing).