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.

NOTE: Only expect files directly linked in the API to work. There is no expectation of nomenclature for these files, so even if it looks like you can build links to links to raw files dynamically, it might change in the future. Always get raw or export file links from the API first! It is recommended that you don't store file links long term, but re-request the API endpoint to get updated file links in case they changed.

Examples

# 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'

Exports Object

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.

DEPRECATED: Expect this to be removed in future versions of the API. Use exports_list instead.

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

Exports List Object

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",
 } ...
]

Known Tariffs

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.

Supported Utilities

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/"`

HTTP Response Codes

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).