This guide will walk you through the technical details about the Asset Level Data API. It is designed to help you navigate through common queries, understand our API’s performance, and optimize your use of our data services.
Using Key/Secret & Access Token
To ensure secure access to our API, users are required to authenticate using a provided key and secret. Post-authentication, an access token is granted for API requests.
Note: The access token is valid for 24 hours and must be refreshed upon expiry to maintain uninterrupted access to the API. This ensures that your interactions with our platform are secure and your data remains protected.
When to Pull Estimates for the Prior Year
Optimal Timing: For the most accurate and comprehensive data, pull estimates for the prior year anytime after March 15th. This ensures you access the finalized data for your analysis and reporting needs.
Understanding Endpoint Latency
Service-Level Objectives (SLOs): While we aim for optimal performance, please note that our latency figures are targets within our Service-Level Objectives, not guarantees.
- Defined Internal SLOs:
Table illustrating our internal targets for different types of API calls
- Measured Latency Performance: Over the last 90 days, our performance metrics have consistently stayed within these SLOs, providing reliable data access.
Table showing measured latency from September 2023 to January 2024
Throughput of Processing Data Sets
Processing times vary by data set and load. Below are our estimated throughput to help you plan your data processing tasks:
| Data Set | Slow | Middle | Fast |
| Carbon Estimates | 40 / minute | 80 / minute | 150 / minute |
| Certification Lookups | 75 / hour | 150 / hour | 275 / hour |
| Energy Estimates | 40 / minute | 80 / minute | 150 / minute |
| Ordinance Lookups | 40 / minute | 60 / minute | 80 / minute |
Example Processing Time: For 100,000 buildings, estimated processing times range based on the dataset and processing speed.
| Data Set | Slow | Middle | Fast |
| Carbon Estimates | 1.75 Days | 21 Hours | 11.1 Hours |
| Certification Lookups | 55.5 Days | 27.7 Days | 15.2 Days |
| Energy Estimates | 1.75 Days | 21 Hours | 11.1 Hours |
| Ordinance Lookups | 1.75 Days | 1.15 Days | 21 Hours |
Certification Lookups
Ideal Timing: The most efficient period for running certification lookups is starting on the 5th day of each month, optimizing your workflow and data retrieval process.
API Rate Limits
To ensure equitable access and system stability, we enforce specific rate limits:
| Request Type | Limit | Time Period |
| GET | 1,000 | 5 minutes |
| All others | 200 | 5 minutes |
Table detailing the rate limits for GET requests and all other request types
Integration Testing
Testing Environment: Direct your integration testing towards our production environment. On request, we can provide a set of credentials with limited usage for testing purposes, allowing processing of up to 10 unique buildings before deactivation.
Updates to Methodology
Current Status: No changes to our methodology are expected in the near future. We commit to transparently communicating any future updates to ensure your continued success using our API.