openapi: 3.0.1
info:
title: ESGx Buildings API
version: v0
description: '## Quick Start Guide
1. Authorize using your client credentials (key and secret)
2. Make a `POST /insights/v0/energy_estimates` request with at least one building
3. Take note of the `id` for the first estimate record
4. Check the status of the energy estimate with `GET /insights/v0/energy_estimates/{id}`
5. Keep polling until the status says `JOB_SUCCESS`
6. Check out the results of the estimate in the `absoluteEstimates` and `intensityEstimates` fields!
### Response Format
Each endpoint response complies with the [JSON-API Specification](https://jsonapi.org/) which has many available [client
libraries](https://jsonapi.org/implementations/#client-libraries).
'
components:
schemas:
json_api:
oneOf:
- $ref: '#/components/schemas/success'
- $ref: '#/components/schemas/failure'
- $ref: '#/components/schemas/info'
success:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/data'
included:
description: To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources
along with the requested primary resources. Such responses are called 'compound documents'.
type: array
items:
$ref: '#/components/schemas/resource'
uniqueItems: true
meta:
$ref: '#/components/schemas/meta'
links:
description: Link members related to the primary data.
allOf:
- $ref: '#/components/schemas/links'
- $ref: '#/components/schemas/pagination'
jsonapi:
$ref: '#/components/schemas/jsonapi'
additionalProperties: false
failure:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/error'
uniqueItems: true
meta:
$ref: '#/components/schemas/meta'
jsonapi:
$ref: '#/components/schemas/jsonapi'
links:
$ref: '#/components/schemas/links'
additionalProperties: false
info:
type: object
required:
- meta
properties:
meta:
$ref: '#/components/schemas/meta'
links:
$ref: '#/components/schemas/links'
jsonapi:
$ref: '#/components/schemas/jsonapi'
additionalProperties: false
meta:
description: Non-standard meta-information that can not be represented as an attribute or relationship.
type: object
additionalProperties: true
data:
description: The document's 'primary data' is a representation of the resource or collection of resources targeted by
a request.
anyOf:
- $ref: '#/components/schemas/resource'
- description: An array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests
that target resource collections.
type: array
items:
$ref: '#/components/schemas/resource'
uniqueItems: true
- description: null if the request is one that might correspond to a single resource, but doesn't currently.
nullable: true
resource:
description: '''Resource objects'' appear in a JSON:API document to represent resources.'
type: object
required:
- type
- id
properties:
type:
type: string
id:
type: string
attributes:
$ref: '#/components/schemas/attributes'
relationships:
$ref: '#/components/schemas/relationships'
links:
$ref: '#/components/schemas/links'
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
relationshipLinks:
description: A resource object **MAY** contain references to other resource objects ('relationships'). Relationships
may be to-one or to-many. Relationships can be specified by including a member in a resource's links object.
type: object
properties:
self:
$ref: '#/components/schemas/link'
related:
$ref: '#/components/schemas/link'
additionalProperties: true
links:
type: object
additionalProperties:
$ref: '#/components/schemas/link'
link:
description: 'A link **MUST** be represented as either: a string containing the link''s URL or a link object.'
oneOf:
- description: A string containing the link's URL.
type: string
format: uri-reference
nullable: true
- type: object
required:
- href
properties:
href:
description: A string containing the link's URL.
type: string
format: uri-reference
meta:
$ref: '#/components/schemas/meta'
attributes:
description: Members of the attributes object ('attributes') represent information about the resource object in which
it's defined.
type: object
additionalProperties: true
relationships:
description: Members of the relationships object ('relationships') represent references from the resource object in
which it's defined to other resource objects.
type: object
properties:
links:
$ref: '#/components/schemas/relationshipLinks'
data:
description: Member, whose value represents 'resource linkage'.
oneOf:
- $ref: '#/components/schemas/relationshipToOne'
- $ref: '#/components/schemas/relationshipToMany'
meta:
$ref: '#/components/schemas/meta'
additionalProperties: true
relationshipToOne:
description: References to other resource objects in a to-one ('relationship'). Relationships can be specified by including
a member in a resource's links object.
anyOf:
- $ref: '#/components/schemas/empty'
- $ref: '#/components/schemas/linkage'
relationshipToMany:
description: An array of objects each containing 'type' and 'id' members for to-many relationships.
type: array
items:
$ref: '#/components/schemas/linkage'
uniqueItems: true
empty:
description: Describes an empty to-one relationship.
nullable: true
linkage:
description: The 'type' and 'id' to non-empty members.
type: object
required:
- type
- id
properties:
type:
type: string
id:
type: string
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
pagination:
type: object
properties:
first:
description: The first page of data
type: string
format: uri-reference
x-nullable: true
last:
description: The last page of data
type: string
format: uri-reference
x-nullable: true
prev:
description: The previous page of data
type: string
format: uri-reference
x-nullable: true
next:
description: The next page of data
type: string
format: uri-reference
x-nullable: true
jsonapi:
description: An object describing the server's implementation
type: object
properties:
version:
type: string
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
error:
type: object
properties:
id:
description: A unique identifier for this particular occurrence of the problem.
type: string
links:
$ref: '#/components/schemas/links'
status:
description: The HTTP status code applicable to this problem, expressed as a string value.
type: string
code:
description: An application-specific error code, expressed as a string value.
type: string
title:
description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence
of the problem, except for purposes of localization.
type: string
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
source:
type: object
properties:
pointer:
description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. '/data' for a primary
data object, or '/data/attributes/title' for a specific attribute].
type: string
parameter:
description: A string indicating which query parameter caused the error.
type: string
meta:
$ref: '#/components/schemas/meta'
additionalProperties: false
request_body_msr_building_id:
type: object
properties:
building:
type: object
properties:
msrBuildingId:
type: string
request_body_coordinates_with_client_metadata:
type: object
properties:
building:
type: object
properties:
name:
type: string
primaryPropertyType:
type: string
yearBuilt:
type: integer
grossFloorArea:
type: integer
grossFloorAreaUnits:
type: string
enum:
- sf
- sm
latitude:
type: number
longitude:
type: number
clientMetadata:
type: object
request_body_building_info_with_client_metadata:
type: object
properties:
building:
type: object
properties:
name:
type: string
addressLine1:
type: string
addressLine2:
type: string
nullable: true
example: null
city:
type: string
stateOrProvince:
type: string
postalCode:
type: string
country:
type: string
primaryPropertyType:
type: string
yearBuilt:
type: integer
grossFloorArea:
type: integer
grossFloorAreaUnits:
type: string
enum:
- sf
- sm
latitude:
type: number
longitude:
type: number
clientMetadata:
type: object
request_body_building_custom_id:
type: object
properties:
building:
type: object
properties:
buildingCustomId:
type: string
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.measurabl.com/token
scopes: {}
paths:
/insights/v0/buildings:
post:
summary: Creates a building
description: 'Create a new building record. The response will include the created building record, including its ID.
The request body can include building information in one of two formats:
- Coordinates and additional building information (latitude, longitude, primaryPropertyType, yearBuilt, grossFloorArea,
grossFloorAreaUnits, buildingCustomId, buildingClientMetadata)
- Full address and additional building information (addressLine1, addressLine2, city, stateOrProvince, postalCode,
country, primaryPropertyType, yearBuilt, grossFloorArea, grossFloorAreaUnits, buildingCustomId, buildingClientMetadata)
The preferred method is to use coordinates if available. If coordinates are not available, use the full address data.
Optional fields:
- **buildingCustomId** is available for storing a custom identifier for the building; this allows storing identifiers
from your system as part of the building record.
- **buildingClientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from
your system and other metadata as part of the building record.
'
tags:
- Buildings
security:
- OAuth2: []
parameters: []
responses:
'201':
description: building created with coordinates
content:
application/vnd.api+json:
example:
data:
id: 7ab65f61-0925-4882-91ab-abeb418f683a
type: buildings
attributes:
primaryPropertyType: Food Sales & Service
yearBuilt: 1890
grossFloorAreaUnits: sq ft
createdAt: '2026-07-16T13:20:41.167Z'
updatedAt: '2026-07-16T13:20:41.167Z'
grossFloorAreaInSquareFeet: 3000
grossFloorAreaInSquareMeters: 279
buildingCustomId: '1234'
buildingClientMetadata:
project: Midwest Analysis
addressLine1: 29 East High St.
addressLine2: null
city: Lawrenceburg
stateOrProvince: IN
postalCode: '47025'
country: United States
formattedAddress: 1227 Coy Cove, New Sheldon, MN 61252, US
latitude: '49.8477807797'
longitude: '-138.4454553923'
schema:
$ref: '#/components/schemas/json_api'
examples:
With Full Address Data:
value:
data:
id: 305ea111-4199-42fc-a687-a3bd36f9ca57
type: buildings
attributes:
primaryPropertyType: Fitness Center/Health Club/Gym
yearBuilt: 2019
grossFloorAreaUnits: sq ft
createdAt: '2026-07-16T13:20:41.296Z'
updatedAt: '2026-07-16T13:20:41.296Z'
grossFloorAreaInSquareFeet: 12950
grossFloorAreaInSquareMeters: 1203
buildingCustomId: building-123456
buildingClientMetadata:
project: Midwest Analysis
addressLine1: 4460 Orkney Ave.
addressLine2: null
city: Cincinnati
stateOrProvince: OH
postalCode: '45209'
country: United States
formattedAddress: Apt. 601 790 Grady Roads, New Porter, AR 89627, US
latitude: '46.6895081745'
longitude: '-115.8225318748'
With Coordinates:
value:
data:
id: a9223351-18f4-49a1-9462-ae09bfd9905d
type: buildings
attributes:
primaryPropertyType: Office
yearBuilt: 2006
grossFloorAreaUnits: sq ft
createdAt: '2026-07-16T13:20:41.443Z'
updatedAt: '2026-07-16T13:20:41.443Z'
grossFloorAreaInSquareFeet: 703796
grossFloorAreaInSquareMeters: 65385
buildingCustomId: building-123456
buildingClientMetadata:
project: Midwest Analysis
addressLine1: null
addressLine2: null
city: null
stateOrProvince: null
postalCode: null
country: null
formattedAddress: Apt. 376 8715 Allison Views, Langworthfurt, ME 15140-9618, US
latitude: '-64.093401085'
longitude: '-134.5224904958'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/request_body_coordinates_with_client_metadata'
- $ref: '#/components/schemas/request_body_building_info_with_client_metadata'
examples:
With Full Address Data:
summary: With Full Address Data
value:
addressLine1: 4460 Orkney Ave.
addressLine2: null
city: Cincinnati
stateOrProvince: OH
postalCode: '45209'
country: United States
primaryPropertyType: Fitness Center/Health Club/Gym
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
buildingCustomId: building-123456
buildingClientMetadata:
project: Midwest Analysis
With Coordinates:
summary: With Coordinates
value:
latitude: 40.766276
longitude: -73.9834504
primaryPropertyType: Office
yearBuilt: 2006
grossFloorArea: 703796
grossFloorAreaUnits: sq ft
buildingCustomId: building-123456
buildingClientMetadata:
project: Midwest Analysis
get:
summary: Returns all buildings for an app
tags:
- Buildings
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
- name: buildingCustomId
in: query
required: false
schema:
type: string
- name: msrBuildingId
in: query
required: false
schema:
type: string
responses:
'200':
description: list of buildings
content:
application/vnd.api+json:
example:
data:
- id: a95c8339-76c9-4740-940d-822b3c407579
type: buildings
attributes:
primaryPropertyType: Residential
yearBuilt: 2002
grossFloorAreaUnits: square meters
createdAt: '2026-07-16T13:20:42.220Z'
updatedAt: '2026-07-16T13:20:42.220Z'
grossFloorAreaInSquareFeet: 45316
grossFloorAreaInSquareMeters: 4210
buildingCustomId: bdec10af-6411-4a38-953c-b739b5175980
buildingClientMetadata: null
addressLine1: 9319 Penelope Lake
addressLine2: null
city: Schuppeview
stateOrProvince: LA
postalCode: 98907-1215
country: United States
formattedAddress: 9319 Penelope Lake, Schuppeview, LA, 98907-1215, United States
latitude: '4.7200512514'
longitude: '89.925012978'
- id: 2ecdb44e-bc7e-45f0-b2cd-b3d39ea5adb6
type: buildings
attributes:
primaryPropertyType: Laboratory
yearBuilt: 1975
grossFloorAreaUnits: sq. ft.
createdAt: '2026-07-16T13:20:42.248Z'
updatedAt: '2026-07-16T13:20:42.248Z'
grossFloorAreaInSquareFeet: 14983
grossFloorAreaInSquareMeters: 1392
buildingCustomId: 1656fa92-1830-4ffe-891f-11240eea3e03
buildingClientMetadata: null
addressLine1: 973 Pennie Mews
addressLine2: Suite 258
city: Lake Casseymouth
stateOrProvince: KS
postalCode: 93479-1306
country: United States
formattedAddress: 973 Pennie Mews, Suite 258, Lake Casseymouth, KS, 93479-1306, United States
latitude: '-7.6642772154'
longitude: '-122.8447214664'
meta:
totalCount: 2
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 2
links:
self: /insights/v0/buildings?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/buildings/export:
post:
summary: Requests a CSV download for the current app
tags:
- Buildings
security:
- OAuth2: []
responses:
'200':
description: Export successfully created
content:
application/vnd.api+json:
example:
data:
id: 5f184ff6-7e2f-4354-a467-e69d1452bef0
type: exports
attributes:
status: PROCESSING
error: null
createdAt: '2026-07-16T13:20:41.985Z'
updatedAt: '2026-07-16T13:20:41.985Z'
permalink: http://localhost:3000/insights/v0/exports/5f184ff6-7e2f-4354-a467-e69d1452bef0/download
relationships: {}
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/carbon_estimate_batches:
get:
summary: Returns all carbon estimates batches
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of carbon estimate batches
content:
application/vnd.api+json:
example:
data:
- id: e9446651-d9d2-47cc-ab1f-c0f981ea7188
type: carbonEstimateBatches
attributes:
estimateType: carbon
status: STARTING
timePeriod: '2024'
errorMessage: null
createdAt: '2026-07-16T13:20:42.571Z'
updatedAt: '2026-07-16T13:20:42.571Z'
- id: 2a88af68-a543-47c3-a1ea-9e327de2f764
type: carbonEstimateBatches
attributes:
estimateType: carbon
status: STARTING
timePeriod: '2023'
errorMessage: null
createdAt: '2026-07-16T13:20:42.574Z'
updatedAt: '2026-07-16T13:20:42.574Z'
meta:
totalCount: 2
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 2
links:
self: /insights/v0/carbon_estimate_batches?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/certification_lookup_batches:
get:
summary: Returns all certification lookup batches
tags:
- Certification Lookups
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of certification lookup batches
content:
application/vnd.api+json:
example:
data:
- id: c4308483-7ff2-4014-8d09-bc3ba20d4de4
type: certificationLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:20:42.996Z'
updatedAt: '2026-07-16T13:20:42.996Z'
- id: 2d2ed3bb-4aa0-49f1-9880-109f28c6a739
type: certificationLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:20:43.000Z'
updatedAt: '2026-07-16T13:20:43.000Z'
meta:
totalCount: 2
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 2
links:
self: /insights/v0/certification_lookup_batches?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/energy_estimate_batches:
get:
summary: Returns all energy estimates batches
tags:
- Energy Estimates
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of energy estimate batches
content:
application/vnd.api+json:
example:
data:
- id: 737aa27d-d3d5-49c2-b5d3-2ea2c79fb787
type: energyEstimateBatches
attributes:
estimateType: energy
status: STARTING
timePeriod: '2021'
errorMessage: null
createdAt: '2026-07-16T13:20:43.414Z'
updatedAt: '2026-07-16T13:20:43.414Z'
- id: e690bc38-7d53-4662-9e74-12567242974c
type: energyEstimateBatches
attributes:
estimateType: energy
status: STARTING
timePeriod: '2025'
errorMessage: null
createdAt: '2026-07-16T13:20:43.416Z'
updatedAt: '2026-07-16T13:20:43.416Z'
meta:
totalCount: 2
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 2
links:
self: /insights/v0/energy_estimate_batches?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/ordinance_lookup_batches:
get:
summary: Returns all ordinance lookup batches
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of ordinance lookup batches
content:
application/vnd.api+json:
example:
data:
- id: 0194cb75-b59f-425e-b765-c4a8b3af6974
type: ordinanceLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:20:49.394Z'
updatedAt: '2026-07-16T13:20:49.394Z'
- id: 36709638-e341-4413-bc5b-a4b6a529b333
type: ordinanceLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:20:49.397Z'
updatedAt: '2026-07-16T13:20:49.397Z'
meta:
totalCount: 2
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 2
links:
self: /insights/v0/ordinance_lookup_batches?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/carbon_estimate_batches/{id}/carbon_estimates:
get:
summary: Returns all carbon estimates for a given batch
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: d271f75a-6d88-4344-a1cd-bfe6a82cb2a0'
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of carbon estimates
content:
application/vnd.api+json:
example:
data:
- id: cda747b1-74d3-4c46-b47d-e2767bc6cdbc
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:54.599Z'
updatedAt: '2026-07-16T13:20:54.599Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: f9a118a3-f02f-48c8-8660-3e83665541f1
type: carbonEstimateBatches
building:
data:
id: fb872ecf-b040-4749-8d6e-a24a02a0dd13
type: buildings
- id: d9cb138b-f954-45c4-b923-acdff9c7a66a
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:54.621Z'
updatedAt: '2026-07-16T13:20:54.621Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: f9a118a3-f02f-48c8-8660-3e83665541f1
type: carbonEstimateBatches
building:
data:
id: ff323d10-b7da-48e9-acd7-4de08cabc731
type: buildings
- id: a373cb31-f91c-43ff-84ab-3ed91342cfa2
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:54.643Z'
updatedAt: '2026-07-16T13:20:54.643Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: f9a118a3-f02f-48c8-8660-3e83665541f1
type: carbonEstimateBatches
building:
data:
id: dd5e6c91-eb01-4479-bad8-936ec7a29d3a
type: buildings
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/carbon_estimate_batches/f9a118a3-f02f-48c8-8660-3e83665541f1/carbon_estimates?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/carbon_estimate_batches/export:
post:
summary: Requests a CSV download for the given Carbon Estimate batches
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters:
- name: status
in: query
schema:
type: string
enum:
- JOB_SUCCESS
responses:
'200':
description: Export successfully created
content:
application/vnd.api+json:
example:
data:
id: 985ad29b-fce8-4fd5-9d77-ddc3d83db0db
type: exports
attributes:
status: PROCESSING
error: null
createdAt: '2026-07-16T13:20:55.222Z'
updatedAt: '2026-07-16T13:20:55.222Z'
permalink: http://localhost:3000/insights/v0/exports/0698b5d5-eac4-4865-92fc-760f1102e6cb/download
relationships:
estimateBatches:
data:
- id: 082caae3-203f-4dfb-b2d0-02e73f6598e3
type: energyEstimateBatches
- id: e9c74e65-00c9-40b4-8aff-1bea933c2b5e
type: energyEstimateBatches
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
batchIds:
type: array
items:
type: string
example:
- b0d6486a-9398-42c6-9182-14eaba92d739
- dacb11f7-3b69-409c-9565-ce05f9869cf1
/insights/v0/carbon_estimate_batches/{id}:
get:
summary: Returns carbon estimate batch
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: ee433e27-9d53-4c54-90c2-b57e3d2a6f98'
required: true
schema:
type: string
responses:
'200':
description: Carbon estimate batch record
content:
application/vnd.api+json:
example:
data:
id: c68303e8-418b-46ad-8b17-a91216563080
type: carbonEstimateBatches
attributes:
estimateType: carbon
status: STARTING
timePeriod: '2025'
errorMessage: null
createdAt: '2026-07-16T13:20:55.311Z'
updatedAt: '2026-07-16T13:20:55.311Z'
schema:
$ref: '#/components/schemas/json_api'
'404':
description: Carbon estimate batch record belonging to another app
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/carbon_estimate_batches/upload:
post:
summary: Uploads a file to create new carbon estimate(s)
description: 'Upload an Excel file of carbon estimate records to be processed.
'
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters:
- name: timePeriod
in: query
schema:
type: string
description: 'A timePeriod to apply for all estimates in the batch. The valid values for timePeriod are: ["T-12",
"2025", "2024", "2023", "2022", "2021"]''
'
enum:
- T-12
- '2025'
- '2024'
- '2023'
- '2022'
- '2021'
required: true
responses:
'200':
description: Carbon estimate batch successfully created
content:
application/vnd.api+json:
example:
data:
id: 45a13954-c7e2-4e55-8ef4-b4cb2667ed34
type: carbonEstimateBatches
attributes:
estimateType: carbon
status: STARTING
timePeriod: '2025'
errorMessage: null
createdAt: '2026-07-16T13:20:55.746Z'
updatedAt: '2026-07-16T13:20:55.756Z'
schema:
$ref: '#/components/schemas/json_api'
'400':
description: invalid time period
content:
application/vnd.api+json:
example:
errors:
- status: '400'
title: Bad Request
detail: 'Time period requested: 3023 is not included in the list T-12, 2025, 2024, 2023, 2022, 2021; Requesting
app: Bogisich and Sons'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
estimate_batch_file:
type: string
format: binary
description: 'An Excel XLSX file containing the buildings you would like carbon estimates for.
When requesting data on buildings for the first time, the Excel Worksheet must be named ''Buildings''.
Building information is required for each estimate. Other fields are optional.
The field ''clientMetadata'' is available for storing arbitrary JSON, this allows storing identifiers
from your system and other metadata as part of the carbon estimate record.
When requesting data on existing buildings i.e. you have the Building IDs, the Excel Worksheet must be
named ''MSR Building IDs'' and may only contain a single column named ''MSR Building ID''.
'
required: true
/insights/v0/carbon_estimates:
get:
summary: Returns all carbon estimates
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of carbon estimates
content:
application/vnd.api+json:
example:
data:
- id: 20f40e2c-913f-4ef0-8f2d-a73d5c47557b
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:56.183Z'
updatedAt: '2026-07-16T13:20:56.183Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: 9c5bfef5-31ec-42bd-b3d1-8afc5b390470
type: carbonEstimateBatches
building:
data:
id: 5c0e576c-d7f1-4341-8409-34227c624f6d
type: buildings
- id: 4b191a9f-01e4-46b6-9322-5d8efc893ee8
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:56.206Z'
updatedAt: '2026-07-16T13:20:56.206Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: edea9e73-561a-4434-b22d-93d25db8baf7
type: carbonEstimateBatches
building:
data:
id: 3517930d-53e9-409e-9611-e9c1c7dd15e0
type: buildings
- id: 7321a2c3-eaa3-43f4-8798-51e1776b7358
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:56.231Z'
updatedAt: '2026-07-16T13:20:56.231Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: bfbadd8e-157c-4750-a28b-88a11f0a8ed8
type: carbonEstimateBatches
building:
data:
id: 97c9d41a-f814-46a2-924a-b8392660716d
type: buildings
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/carbon_estimates?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
post:
summary: Creates new carbon estimate(s)
description: 'Create new carbon estimate records to be processed. The response will include those records, including
IDs that can be used to access the carbon estimate(s).
There is a limit of 100 buildings per request. If you have over 100 buildings, please create separate requests in
increments of 100 buildings or fewer.
Please note: You can process larger collections of Buildings via the file upload endpoint.
Coverage: Global
'
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters: []
responses:
'200':
description: Carbon estimate(s) successfully created
content:
application/vnd.api+json:
examples:
With MSR Building ID:
value:
data:
- id: a38c7f29-0720-47c7-baf4-5e87dfae91bb
type: carbonEstimates
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:57.548Z'
updatedAt: '2026-07-16T13:20:57.564Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: c6ca71ac-d497-4fca-af95-1f89917be2d1
type: carbonEstimateBatches
building:
data:
id: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
type: buildings
- id: 3a0c79cc-4e57-47c9-953b-ddc86d580504
type: carbonEstimates
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:57.548Z'
updatedAt: '2026-07-16T13:20:57.584Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: c6ca71ac-d497-4fca-af95-1f89917be2d1
type: carbonEstimateBatches
building:
data:
id: 7a0c1cb2-85bc-49b2-b61c-801e11659494
type: buildings
With Building Custom ID:
value:
data:
- id: c541cc4e-0f7e-410c-9228-cef5a084fc90
type: carbonEstimates
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:57.692Z'
updatedAt: '2026-07-16T13:20:57.710Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: dd4ad0c4-a2f6-436c-88d4-c4c6a5f266fd
type: carbonEstimateBatches
building:
data:
id: 353b286a-59be-4a3d-95c6-1203a6a91119
type: buildings
With Coordinates:
value:
data:
- id: 277ac81b-3ead-4ddb-b2f4-18f1f05fc115
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:57.797Z'
updatedAt: '2026-07-16T13:20:57.797Z'
requestedLatitude: '40.766276'
requestedLongitude: '-73.9834504'
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: a8f7b468-e8a3-4bed-aed8-5eef8784fa17
type: carbonEstimateBatches
building:
data: null
With Full Address Data:
value:
data:
- id: 23b11baa-5091-485b-aa8b-140d64330e80
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:20:57.899Z'
updatedAt: '2026-07-16T13:20:57.899Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: c606a079-a620-47fd-96d8-0a281e3844f2
type: carbonEstimateBatches
building:
data: null
- id: 2a233957-2d7a-4958-9974-b4880fb0c24c
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:20:57.899Z'
updatedAt: '2026-07-16T13:20:57.899Z'
requestedLatitude: '39.15600199'
requestedLongitude: '-84.4202312'
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: c606a079-a620-47fd-96d8-0a281e3844f2
type: carbonEstimateBatches
building:
data: null
- id: f14c0687-091e-4868-813c-843059c91223
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:20:57.899Z'
updatedAt: '2026-07-16T13:20:57.899Z'
requestedLatitude: '51.372512'
requestedLongitude: '-104.778923199'
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: c606a079-a620-47fd-96d8-0a281e3844f2
type: carbonEstimateBatches
building:
data: null
- id: 5151991f-37fe-4ec1-8872-7574cc988b3f
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:20:57.899Z'
updatedAt: '2026-07-16T13:20:57.899Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: c606a079-a620-47fd-96d8-0a281e3844f2
type: carbonEstimateBatches
building:
data: null
schema:
$ref: '#/components/schemas/json_api'
'413':
description: too many estimates in request
content:
application/vnd.api+json:
example:
errors:
- status: '413'
title: Payload too large
detail: Only 100 estimates can be created in a single request.
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
timePeriod:
type: string
enum:
- T-12
- '2025'
- '2024'
- '2023'
- '2022'
- '2021'
estimates:
type: array
items:
oneOf:
- $ref: '#/components/schemas/request_body_msr_building_id'
- $ref: '#/components/schemas/request_body_building_custom_id'
- $ref: '#/components/schemas/request_body_coordinates_with_client_metadata'
- $ref: '#/components/schemas/request_body_building_info_with_client_metadata'
examples:
With MSR Building ID:
summary: With MSR Building ID
value:
timePeriod: '2023'
estimates:
- building:
msrBuildingId: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
- building:
msrBuildingId: 7a0c1cb2-85bc-49b2-b61c-801e11659494
With Building Custom ID:
summary: With Building Custom ID
value:
timePeriod: '2023'
estimates:
- building:
buildingCustomId: your-custom-building-id
With Coordinates:
summary: With Coordinates
value:
timePeriod: '2023'
estimates:
- building:
latitude: 40.766276
longitude: -73.9834504
primaryPropertyType: Office
yearBuilt: 2006
grossFloorArea: 703796
grossFloorAreaUnits: sq ft
With Full Address Data:
summary: With Full Address Data
value:
estimates:
- building:
addressLine1: 29 East High St.
addressLine2: null
city: Lawrenceburg
stateOrProvince: IN
postalCode: '47025'
country: United States
primaryPropertyType: Food Sales & Service
yearBuilt: 1890
grossFloorArea: 3000
grossFloorAreaUnits: sq ft
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: 4460 Orkney Ave.
addressLine2: null
city: Cincinnati
stateOrProvince: OH
postalCode: '45209'
country: United States
primaryPropertyType: Fitness Center/Health Club/Gym
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
longitude: -84.4202312
latitude: 39.15600199
buildingCustomId: building-123456
buildingClientMetadata:
foo: bar
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: null
addressLine2: null
city: Centennial
stateOrProvince: CO
postalCode: '80112'
country: United States
primaryPropertyType: Warehouse/Storage - Other
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
latitude: 51.372512
longitude: -104.778923199
clientMetadata:
project: Midwest Analysis
- building:
msrBuildingId: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
addressLine1: null
addressLine2: null
city: Centennial
stateOrProvince: CO
postalCode: '80112'
country: United States
primaryPropertyType: Warehouse/Storage - Other
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
clientMetadata:
project: Midwest Analysis
timePeriod: '2023'
description: 'The carbon estimates to be created.
Time Period is required for each request and must be a valid year.
The valid values for timePeriod are: T-12, 2025, 2024, 2023, 2022, 2021.
Building information is required for each estimate and can be provided in one of four ways:
- Building UUID (msrBuildingId)
- Building Custom ID (buildingCustomId)
- Coordinates and additional building information (latitude, longitude, primaryPropertyType, yearBuilt, grossFloorArea,
grossFloorAreaUnits)
- Full address and additional building information (addressLine1, city, stateOrProvince, postalCode, country, primaryPropertyType,
yearBuilt, grossFloorArea, grossFloorAreaUnits)
The preferred method is to use the msrBuildingId or buildingCustomId if available. If neither is available, using
coordinates is preferred over full address data.
Optional fields:
- **customId** is available for storing a custom identifier for the estimate; this allows storing identifiers from
your system as part of the carbon _estimate_ record.
- **buildingCustomId** is available for storing a custom identifier for the building; this allows storing identifiers
from your system as part of the _building_ record.
- **clientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from your
system and other metadata as part of the carbon _estimate_ record.
- **buildingClientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from
your system and other metadata as part of the _building_ record.
'
/insights/v0/carbon_estimates/{id}:
get:
summary: Retrieves an existing carbon estimate
description: 'Provides access to the data for the carbon estimate record once it completes processing. It can be polled
while processing to see the current status.
'
tags:
- Carbon Estimates
security:
- OAuth2: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Carbon estimate with scope breakout (PCAF)
content:
application/vnd.api+json:
example:
data:
id: a3b6f063-a9a0-4cf5-b786-73aeaa62c3aa
type: carbonEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:58.151Z'
updatedAt: '2026-07-16T13:20:58.151Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
annualAbsoluteEstimate: null
absoluteEstimateUnits: null
annualIntensityEstimate: null
confidenceLabel: high
confidenceDescription: Eius et velit dolor.
intensityEstimateUnits: kgCO₂e/ft²
requestedAddressLine1: ''
requestedAddressLine2: ''
requestedCity: ''
requestedStateOrProvince: ''
requestedPostalCode: ''
requestedCountry: ''
requestedPropertyType: ''
latitude: '-37.7281491018'
longitude: '11.1867735462'
appliedPropertyType: null
monthlyIntensityEstimates: null
monthlyAbsoluteEstimates: null
relationships:
estimateBatch:
data:
id: 7ce373e2-7228-49f0-9728-2e09141c20f9
type: carbonEstimateBatches
building:
data:
id: cbfdc2cf-4b1e-4b63-8dca-7a32a0513772
type: buildings
benchmarkLookup:
data: null
included: []
schema:
$ref: '#/components/schemas/json_api'
examples:
Processed Successfully:
value:
data:
id: 8e05412f-8612-4853-96ff-6c92c7ede4d9
type: carbonEstimates
attributes:
status: SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:58.298Z'
updatedAt: '2026-07-16T13:20:58.298Z'
requestedLatitude: '20.4037051189'
requestedLongitude: '102.9261258963'
startingMonth: 2025-07
endingMonth: 2026-06
annualAbsoluteEstimate: 5989853.1656163
absoluteEstimateUnits: MTCO2e
annualIntensityEstimate: 367.160302
confidenceLabel: moderate
confidenceDescription: The carbon estimate is generated from an energy estimate. The average energy
estimate error for properties in this category is anticipated to be <= 26.1%.
intensityEstimateUnits: kgCO₂e/m²
requestedAddressLine1: 859 Collier Valleys
requestedAddressLine2: null
requestedCity: East Dannie
requestedStateOrProvince: OH
requestedPostalCode: 17167-2243
requestedCountry: United States
requestedPropertyType: Other
latitude: '-67.7322022672'
longitude: '101.6989310822'
appliedPropertyType: Other
buildingCustomId: '123456'
buildingClientMetadata:
foo: bar
monthlyIntensityEstimates:
- 51.3742537
- 3.4910418
- 51.2088552
- 14.9580159
- 16.3058606
- 44.4497757
- 28.5284252
- 35.377119
- 35.3827679
- 1.0180275
- 39.0797122
- 45.9864473
monthlyAbsoluteEstimates:
- 838119.5751964
- 56952.8552047
- 835421.2631273
- 244025.0719785
- 266013.8099372
- 725153.6401976
- 465412.7291333
- 577142.3185582
- 577234.4758508
- 16608.1007114
- 637546.4243986
- 750222.9013223
relationships:
estimateBatch:
data:
id: 8a4b7d27-c197-4a70-a77c-10f78dad3ef3
type: carbonEstimateBatches
building:
data:
id: c29fb66d-bce4-4c9f-9ce8-ac2580d077d0
type: buildings
benchmarkLookup:
data:
id: 574a296f-4908-49a3-ad5d-3f24870b167e
type: benchmarkLookup
included:
- id: 574a296f-4908-49a3-ad5d-3f24870b167e
type: benchmarkLookups
attributes:
createdAt: '2026-07-16T13:20:58.290Z'
updatedAt: '2026-07-16T13:20:58.290Z'
year: '2021'
benchmarkPropertyType: Other
continent: North America
continentSubregion: North America
countryCode: US
countrySubregion: Midwest
stateProvincePrefecture: OH
intensityBenchmarkUnits: kgCO2e/ft2
globalMeanIntensity: '59.1213640087'
globalFirstQuartileIntensity: '51.5780079466'
globalSecondQuartileIntensity: '66.0082069498'
globalThirdQuartileIntensity: '15.6099215614'
globalFifteenthPercentileIntensity: '98.1957488025'
globalThirtiethPercentileIntensity: '13.7919010834'
continentMeanIntensity: '24.1126239524'
continentFirstQuartileIntensity: '54.3227645265'
continentSecondQuartileIntensity: '23.4587919961'
continentThirdQuartileIntensity: '29.6685324229'
continentFifteenthPercentileIntensity: '12.6527137247'
continentThirtiethPercentileIntensity: '97.8989195096'
continentSubregionMeanIntensity: '99.6500319679'
continentSubregionFirstQuartileIntensity: '82.3162300723'
continentSubregionSecondQuartileIntensity: '64.3273640944'
continentSubregionThirdQuartileIntensity: '64.4597524189'
continentSubregionFifteenthPercentileIntensity: There is not enough data to benchmark your building
at this level
continentSubregionThirtiethPercentileIntensity: There is not enough data to benchmark your building
at this level
countryMeanIntensity: '67.9262876003'
countryFirstQuartileIntensity: '87.5738884609'
countrySecondQuartileIntensity: '60.6487769469'
countryThirdQuartileIntensity: '34.8267964329'
countryFifteenthPercentileIntensity: '52.0805053426'
countryThirtiethPercentileIntensity: '54.2959516903'
countrySubregionMeanIntensity: '96.7847776442'
countrySubregionFirstQuartileIntensity: '33.6941583229'
countrySubregionSecondQuartileIntensity: '23.6838199776'
countrySubregionThirdQuartileIntensity: '56.1516076842'
countrySubregionFifteenthPercentileIntensity: '97.3401936293'
countrySubregionThirtiethPercentileIntensity: '79.0814333006'
stateProvincePrefectureMeanIntensity: There is not enough data to benchmark your building at this
level
stateProvincePrefectureFirstQuartileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureSecondQuartileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureThirdQuartileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureFifteenthPercentileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureThirtiethPercentileIntensity: There is not enough data to benchmark your building
at this level
With Scope Breakout:
value:
data:
id: 5033b7b4-c4f6-4584-845f-dd083b831bb0
type: carbonEstimates
attributes:
status: SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:58.454Z'
updatedAt: '2026-07-16T13:20:58.454Z'
requestedLatitude: '68.7204095361'
requestedLongitude: '-87.0101971648'
startingMonth: 2025-07
endingMonth: 2026-06
annualAbsoluteEstimate: 5077342.4890783
absoluteEstimateUnits: MTCO2e
annualIntensityEstimate: 55.199905
confidenceLabel: moderate
confidenceDescription: The carbon estimate is generated from an energy estimate. The average energy
estimate error for properties in this category is anticipated to be <= 26.1%.
intensityEstimateUnits: kgCO₂e/m²
requestedAddressLine1: 9152 Brekke Springs
requestedAddressLine2: Suite 367
requestedCity: South Lavonne
requestedStateOrProvince: OH
requestedPostalCode: '99718'
requestedCountry: United States
requestedPropertyType: Other
latitude: '-81.28161459'
longitude: '43.5839098672'
appliedPropertyType: Other
buildingCustomId: '123456'
buildingClientMetadata:
foo: bar
monthlyIntensityEstimates:
- 0.7783039
- 6.4920187
- 10.673097
- 1.0213827
- 1.9915122
- 6.1162558
- 7.9956969
- 3.6042791
- 4.2376421
- 0.4258364
- 8.0814159
- 3.7824643
monthlyAbsoluteEstimates:
- 71589.1697188
- 597142.3747067
- 981722.1385105
- 93947.8027503
- 183181.2865839
- 562579.3289485
- 735452.1992025
- 331525.199615
- 389782.5556493
- 39168.8621793
- 743336.7203789
- 347914.8508346
pcafDataQualityScore: 3
annualIntensityCarbonEstimateScope1: 45.0591748
annualIntensityCarbonEstimateScope2: 234.4178383
annualIntensityCarbonEstimateScope3: 129.7005571
annualAbsoluteCarbonEstimateScope1: 685.4418114
annualAbsoluteCarbonEstimateScope2: 3355.6624943
annualAbsoluteCarbonEstimateScope3: 1409.2791645
relationships:
estimateBatch:
data:
id: 3e82ad32-4f03-4c5e-8af0-1227d0971918
type: carbonEstimateBatches
building:
data:
id: 0f69d67c-3704-4066-b75f-8b4787e6dc82
type: buildings
benchmarkLookup:
data:
id: 7673257e-9bf5-4a6d-8aff-493fdde91561
type: benchmarkLookup
included:
- id: 7673257e-9bf5-4a6d-8aff-493fdde91561
type: benchmarkLookups
attributes:
createdAt: '2026-07-16T13:20:58.445Z'
updatedAt: '2026-07-16T13:20:58.445Z'
year: '2021'
benchmarkPropertyType: Other
continent: North America
continentSubregion: North America
countryCode: US
countrySubregion: Midwest
stateProvincePrefecture: OH
intensityBenchmarkUnits: kgCO2e/ft2
globalMeanIntensity: '66.1196019227'
globalFirstQuartileIntensity: '43.6415872479'
globalSecondQuartileIntensity: '15.1747317742'
globalThirdQuartileIntensity: '34.6838775526'
globalFifteenthPercentileIntensity: '19.9082711743'
globalThirtiethPercentileIntensity: '23.1461691872'
continentMeanIntensity: '48.3969105136'
continentFirstQuartileIntensity: '50.6172983326'
continentSecondQuartileIntensity: '18.8675357232'
continentThirdQuartileIntensity: '34.6029161641'
continentFifteenthPercentileIntensity: '18.5751413259'
continentThirtiethPercentileIntensity: '36.1115111716'
continentSubregionMeanIntensity: '57.0959452459'
continentSubregionFirstQuartileIntensity: '80.0399452631'
continentSubregionSecondQuartileIntensity: '41.9887561228'
continentSubregionThirdQuartileIntensity: '85.6321068975'
continentSubregionFifteenthPercentileIntensity: There is not enough data to benchmark your building
at this level
continentSubregionThirtiethPercentileIntensity: There is not enough data to benchmark your building
at this level
countryMeanIntensity: '10.6699696172'
countryFirstQuartileIntensity: '24.7894590626'
countrySecondQuartileIntensity: '29.0601504093'
countryThirdQuartileIntensity: '25.5754582429'
countryFifteenthPercentileIntensity: '87.5617981631'
countryThirtiethPercentileIntensity: '76.1024595523'
countrySubregionMeanIntensity: '52.0352592017'
countrySubregionFirstQuartileIntensity: '94.8303945762'
countrySubregionSecondQuartileIntensity: '25.8413873128'
countrySubregionThirdQuartileIntensity: '34.0300207469'
countrySubregionFifteenthPercentileIntensity: '83.9136517546'
countrySubregionThirtiethPercentileIntensity: '20.2436485747'
stateProvincePrefectureMeanIntensity: There is not enough data to benchmark your building at this
level
stateProvincePrefectureFirstQuartileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureSecondQuartileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureThirdQuartileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureFifteenthPercentileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureThirtiethPercentileIntensity: There is not enough data to benchmark your building
at this level
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
'404':
description: ID is not found
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/certification_lookup_batches/{id}/certification_lookups:
get:
summary: Returns all certification lookups for a given batch
description: 'Provides access to the data for all the certification lookups in a given certification lookup batch record
once it completes processing. It can be polled while processing to see the current status.
'
tags:
- Certification Lookups
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: d271f75a-6d88-4344-a1cd-bfe6a82cb2a0'
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of certification lookups
content:
application/vnd.api+json:
example:
data:
- id: dab479f4-41e0-4a4c-b3f7-6daef91e59e3
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:58.923Z'
updatedAt: '2026-07-16T13:20:58.923Z'
requestedLatitude: null
requestedLongitude: null
statuses: {}
relationships:
certificationLookupBatch:
data:
id: 8bfd9af5-1a75-450d-8a4a-dd9902577ee9
type: certificationLookupBatches
building:
data:
id: 63a7d9e0-663b-40d8-8961-ecff073f6231
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: ce0ba04d-6c6e-4019-bcdd-b1427abfd9bd
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:58.947Z'
updatedAt: '2026-07-16T13:20:58.947Z'
requestedLatitude: null
requestedLongitude: null
statuses: {}
relationships:
certificationLookupBatch:
data:
id: 8bfd9af5-1a75-450d-8a4a-dd9902577ee9
type: certificationLookupBatches
building:
data:
id: e89c2a18-07e1-40d8-b07f-a18ab9ca6db1
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: 7d203e9b-1e7a-4865-bed3-13c8f29b8f2d
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:20:58.970Z'
updatedAt: '2026-07-16T13:20:58.970Z'
requestedLatitude: null
requestedLongitude: null
statuses: {}
relationships:
certificationLookupBatch:
data:
id: 8bfd9af5-1a75-450d-8a4a-dd9902577ee9
type: certificationLookupBatches
building:
data:
id: 73bf2c72-9464-463c-a112-cb667ac4b2c1
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/certification_lookup_batches/8bfd9af5-1a75-450d-8a4a-dd9902577ee9/certification_lookups?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/certification_lookup_batches/export:
post:
summary: Requests a CSV download for the given Certification Lookups batches
tags:
- Certification Lookups
security:
- OAuth2: []
parameters:
- name: status
in: query
schema:
type: string
enum:
- JOB_SUCCESS
responses:
'200':
description: Export successfully created
content:
application/vnd.api+json:
example:
data:
id: 57a10d6e-8171-470f-a19a-909c1d62a83e
type: exports
attributes:
status: PROCESSING
error: null
createdAt: '2026-07-16T13:20:59.683Z'
updatedAt: '2026-07-16T13:20:59.683Z'
permalink: http://localhost:3000/insights/v0/exports/57a10d6e-8171-470f-a19a-909c1d62a83e/download
relationships:
certificationLookupBatches:
data:
- id: 99b48b5f-930e-40d1-bb3f-3be7e9944ff7
type: certificationLookupBatches
- id: 1d79694b-5556-4a2d-b2d3-759f03fe7252
type: certificationLookupBatches
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
batchIds:
type: array
items:
type: string
example:
- b0d6486a-9398-42c6-9182-14eaba92d739
- dacb11f7-3b69-409c-9565-ce05f9869cf1
/insights/v0/certification_lookup_batches/{id}:
get:
summary: Returns certification lookup batch
description: 'Provides access to the data for the certification lookup batch record once it completes processing. It
can be polled while processing to see the current status.
'
tags:
- Certification Lookups
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: ee433e27-9d53-4c54-90c2-b57e3d2a6f98'
required: true
schema:
type: string
responses:
'200':
description: Certification Lookup batch record
content:
application/vnd.api+json:
example:
data:
id: 7c301d2c-d9ef-43b6-8e92-1ae49b8c3aad
type: certificationLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:20:59.765Z'
updatedAt: '2026-07-16T13:20:59.765Z'
schema:
$ref: '#/components/schemas/json_api'
'404':
description: Certification Lookup batch record belonging to another app
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/certification_lookup_batches/upload:
post:
summary: Uploads a file to create new certification lookup(s)
description: 'Upload an Excel file of certification lookup records to be processed.
'
tags:
- Certification Lookups
security:
- OAuth2: []
parameters: []
responses:
'200':
description: Certification lookup batch successfully created
content:
application/vnd.api+json:
example:
data:
id: 223ed5f8-19ae-40fa-845b-0e115afc3863
type: certificationLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:21:00.129Z'
updatedAt: '2026-07-16T13:21:00.138Z'
schema:
$ref: '#/components/schemas/json_api'
'400':
description: missing file upload
content:
application/vnd.api+json:
example:
errors:
- status: '400'
title: Bad Request
detail: 'Excel file required in certification_lookup_batch_file
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
certification_lookup_batch_file:
type: string
format: binary
description: 'An Excel XLSX file containing the buildings you would like certification lookups for.
When requesting data on buildings for the first time, the Excel Worksheet must be named ''Buildings''.
Building information is required for each certification lookup. Other fields are optional.
The field ''clientMetadata'' is available for storing arbitrary JSON, this allows storing identifiers
from your system and other metadata as part of the certification lookup record.
When requesting data on existing buildings i.e. you have the Building IDs, the Excel Worksheet must be
named ''MSR Building IDs'' and may only contain a single column named ''MSR Building ID''.
'
required: true
/insights/v0/certification_lookups:
post:
summary: Creates new certification lookup(s)
description: 'Create new certification lookup records to be processed. The response will include those records, including
IDs that can be used to access the certification lookup(s).
There is a limit of 100 buildings per request. If you have over 100 buildings, please create separate requests in
increments of 100 buildings or fewer.
Please note: You can process larger collections of Buildings via the file upload endpoint.
Coverage: Global
'
tags:
- Certification Lookups
security:
- OAuth2: []
parameters: []
responses:
'200':
description: Certification Lookups(s) successfully created
content:
application/vnd.api+json:
examples:
With MSR Building ID:
value:
data:
- id: a8101b97-e8a2-4d2d-af95-a75e6f0c59f0
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:06.119Z'
updatedAt: '2026-07-16T13:21:06.134Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: GEOLOCATION_SUCCEEDED
casbeeCertifications:
status: GEOLOCATION_SUCCEEDED
greenStarCertifications:
status: GEOLOCATION_SUCCEEDED
leedCertifications:
status: SKIPPED
relationships:
certificationLookupBatch:
data:
id: a8f4d599-f782-4b6b-9fe1-de78a6771d59
type: certificationLookupBatches
building:
data:
id: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: ba4a332a-7ed7-453d-8d07-a8c24bac9749
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:06.119Z'
updatedAt: '2026-07-16T13:21:06.196Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: GEOLOCATION_SUCCEEDED
casbeeCertifications:
status: GEOLOCATION_SUCCEEDED
greenStarCertifications:
status: GEOLOCATION_SUCCEEDED
leedCertifications:
status: SKIPPED
relationships:
certificationLookupBatch:
data:
id: a8f4d599-f782-4b6b-9fe1-de78a6771d59
type: certificationLookupBatches
building:
data:
id: 041cd656-eda8-47aa-9c5a-cc0cdbd13f87
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
With Building Custom ID:
value:
data:
- id: c1e55d95-c1d8-4a52-b4c0-2a0077c9b60e
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:06.360Z'
updatedAt: '2026-07-16T13:21:06.377Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: GEOLOCATION_SUCCEEDED
casbeeCertifications:
status: GEOLOCATION_SUCCEEDED
greenStarCertifications:
status: GEOLOCATION_SUCCEEDED
leedCertifications:
status: SKIPPED
relationships:
certificationLookupBatch:
data:
id: f993033e-89a8-4a98-b7a5-4e35d48b5169
type: certificationLookupBatches
building:
data:
id: a4228677-1a46-4828-9825-71653e33a2d8
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
With Coordinates:
value:
data:
- id: 05d847c6-42e2-46ec-8b84-4f490d2742eb
type: certificationLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:06.528Z'
updatedAt: '2026-07-16T13:21:06.528Z'
requestedLatitude: '40.766276'
requestedLongitude: '-73.9834504'
statuses:
breeamCertifications:
status: PROCESSING
casbeeCertifications:
status: PROCESSING
greenStarCertifications:
status: PROCESSING
leedCertifications:
status: PROCESSING
relationships:
certificationLookupBatch:
data:
id: 29cdad73-c502-4e84-9b8f-8c111b134343
type: certificationLookupBatches
building:
data: null
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
With Full Address Data:
value:
data:
- id: f7f27d4f-c232-4c68-9d1c-aa8786f59f11
type: certificationLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:21:06.706Z'
updatedAt: '2026-07-16T13:21:06.706Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: PROCESSING
casbeeCertifications:
status: PROCESSING
greenStarCertifications:
status: PROCESSING
leedCertifications:
status: PROCESSING
relationships:
certificationLookupBatch:
data:
id: 38744a92-9824-4bae-9cf4-78b4a5aed847
type: certificationLookupBatches
building:
data: null
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: bbde30d6-56fe-4852-90b4-17d08838df1f
type: certificationLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:21:06.706Z'
updatedAt: '2026-07-16T13:21:06.706Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: PROCESSING
casbeeCertifications:
status: PROCESSING
greenStarCertifications:
status: PROCESSING
leedCertifications:
status: PROCESSING
relationships:
certificationLookupBatch:
data:
id: 38744a92-9824-4bae-9cf4-78b4a5aed847
type: certificationLookupBatches
building:
data: null
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: baef12df-feaf-4338-8f6f-144e23136d78
type: certificationLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: LEXINGTON REALTY TRUST
createdAt: '2026-07-16T13:21:06.706Z'
updatedAt: '2026-07-16T13:21:06.706Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: PROCESSING
casbeeCertifications:
status: PROCESSING
greenStarCertifications:
status: PROCESSING
leedCertifications:
status: PROCESSING
relationships:
certificationLookupBatch:
data:
id: 38744a92-9824-4bae-9cf4-78b4a5aed847
type: certificationLookupBatches
building:
data: null
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: 7911c23a-b517-43d8-8311-e71d04e021eb
type: certificationLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: LEXINGTON REALTY TRUST
createdAt: '2026-07-16T13:21:06.706Z'
updatedAt: '2026-07-16T13:21:06.706Z'
requestedLatitude: '39.7512621258'
requestedLongitude: '-104.9983851568'
statuses:
breeamCertifications:
status: PROCESSING
casbeeCertifications:
status: PROCESSING
greenStarCertifications:
status: PROCESSING
leedCertifications:
status: PROCESSING
relationships:
certificationLookupBatch:
data:
id: 38744a92-9824-4bae-9cf4-78b4a5aed847
type: certificationLookupBatches
building:
data: null
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: 5c6a987e-bd07-4c5c-8359-31dacb1b5ce9
type: certificationLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: LEXINGTON REALTY TRUST
createdAt: '2026-07-16T13:21:06.706Z'
updatedAt: '2026-07-16T13:21:06.706Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: PROCESSING
casbeeCertifications:
status: PROCESSING
greenStarCertifications:
status: PROCESSING
leedCertifications:
status: PROCESSING
relationships:
certificationLookupBatch:
data:
id: 38744a92-9824-4bae-9cf4-78b4a5aed847
type: certificationLookupBatches
building:
data: null
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
schema:
$ref: '#/components/schemas/json_api'
'413':
description: too many certification lookups in request
content:
application/vnd.api+json:
example:
errors:
- status: '413'
title: Payload too large
detail: Only 100 certification lookups can be created in a single request.
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
certificationLookups:
type: array
items:
oneOf:
- $ref: '#/components/schemas/request_body_msr_building_id'
- $ref: '#/components/schemas/request_body_building_custom_id'
- $ref: '#/components/schemas/request_body_coordinates_with_client_metadata'
- $ref: '#/components/schemas/request_body_building_info_with_client_metadata'
examples:
With MSR Building ID:
summary: With MSR Building ID
value:
certificationLookups:
- building:
msrBuildingId: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
- building:
msrBuildingId: 041cd656-eda8-47aa-9c5a-cc0cdbd13f87
With Building Custom ID:
summary: With Building Custom ID
value:
certificationLookups:
- building:
buildingCustomId: your-custom-building-id
With Coordinates:
summary: With Coordinates
value:
certificationLookups:
- building:
latitude: 40.766276
longitude: -73.9834504
primaryPropertyType: Office
yearBuilt: 2006
grossFloorArea: 703796
grossFloorAreaUnits: sq ft
With Full Address Data:
summary: With Full Address Data
value:
certificationLookups:
- building:
addressLine1: 29 East High St.
addressLine2: null
city: Lawrenceburg
stateOrProvince: IN
postalCode: '47025'
country: United States
primaryPropertyType: Other - Other
yearBuilt: 1890
grossFloorArea: 3000
grossFloorAreaUnits: sq ft
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: 4460 Orkney Ave.
addressLine2: null
city: Cincinnati
stateOrProvince: OH
postalCode: '45209'
country: United States
primaryPropertyType: Fitness Center/Health Club/Gym
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
buildingCustomId: building-123456
buildingClientMetadata:
foo: bar
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: 1021 Tyger Lake Road
addressLine2: null
city: Spartanburg
stateOrProvince: SC
postalCode: '29301'
country: United States
primaryPropertyType: Other
yearBuilt: 2019
grossFloorArea: 213200
grossFloorAreaUnits: sq ft
clientMetadata:
project: LEXINGTON REALTY TRUST
- building:
addressLine1: null
addressLine2: null
city: Littleton
stateOrProvince: CO
postalCode: '80127'
country: United States
primaryPropertyType: Warehouse/Storage - Self-Storage Facility
yearBuilt: 2019
grossFloorArea: 213200
grossFloorAreaUnits: sq ft
latitude: 39.7512621258
longitude: -104.9983851568
clientMetadata:
project: LEXINGTON REALTY TRUST
- building:
msrBuildingId: 71bbbe33-4a5a-4a06-8ce4-85d41df042f9
addressLine1: null
addressLine2: null
city: Littleton
stateOrProvince: CO
postalCode: '80127'
country: United States
primaryPropertyType: Warehouse/Storage - Self-Storage Facility
yearBuilt: 2019
grossFloorArea: 213200
grossFloorAreaUnits: sq ft
clientMetadata:
project: LEXINGTON REALTY TRUST
description: 'The certification lookups to be created.
Building information is required for each certification lookup and can be provided in one of four ways:
- Building UUID (msrBuildingId)
- Building Custom ID (buildingCustomId)
- Coordinates and additional building information (latitude, longitude, primaryPropertyType, yearBuilt, grossFloorArea,
grossFloorAreaUnits)
- Full address and additional building information (addressLine1, city, stateOrProvince, postalCode, country, primaryPropertyType,
yearBuilt, grossFloorArea, grossFloorAreaUnits)
The preferred method is to use the msrBuildingId or buildingCustomId if available. If neither is available, using
coordinates is preferred over full address data.
Optional fields:
- **customId** is available for storing a custom identifier for the estimate; this allows storing identifiers from
your system as part of the certification _lookup_ record.
- **buildingCustomId** is available for storing a custom identifier for the building; this allows storing identifiers
from your system as part of the _building_ record.
- **clientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from your
system and other metadata as part of the certification _lookup_ record.
- **buildingClientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from
your system and other metadata as part of the _building_ record.
'
get:
summary: Returns all certification lookups
tags:
- Certification Lookups
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of certification lookups
content:
application/vnd.api+json:
example:
data:
- id: 32ba4df7-2d13-4c1c-a880-462daba96ef0
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:07.201Z'
updatedAt: '2026-07-16T13:21:07.201Z'
requestedLatitude: null
requestedLongitude: null
statuses: {}
relationships:
certificationLookupBatch:
data:
id: 57a689cb-135e-49f7-9148-042189dc7f71
type: certificationLookupBatches
building:
data:
id: 2c8d7358-fe6e-4c91-ad9a-dc01f134c74b
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: 04f40284-f9ab-43fa-ab42-98c60cced69f
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:07.225Z'
updatedAt: '2026-07-16T13:21:07.225Z'
requestedLatitude: null
requestedLongitude: null
statuses: {}
relationships:
certificationLookupBatch:
data:
id: a6e9ef08-aa02-4d9d-babf-46f6f81769dc
type: certificationLookupBatches
building:
data:
id: 04806f02-c7f5-4343-9a2e-e5f19297b004
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
- id: 55168d0c-40d0-4424-a562-4c75232ce932
type: certificationLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:07.249Z'
updatedAt: '2026-07-16T13:21:07.249Z'
requestedLatitude: null
requestedLongitude: null
statuses: {}
relationships:
certificationLookupBatch:
data:
id: 9590a259-94b4-498f-b88c-ba10461e2422
type: certificationLookupBatches
building:
data:
id: ec3a202d-fea3-4c40-89b1-fe36c1fded98
type: buildings
leedCertificationResponses:
data: []
breeamCertificationResponses:
data: []
casbeeCertificationResponses:
data: []
greenStarCertificationResponses:
data: []
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/certification_lookups?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/certification_lookups/{id}:
get:
summary: Retrieves an existing certification lookup
description: 'Provides access to the data for the certification lookup record once it completes processing. It can be
polled while processing to see the current status.
'
tags:
- Certification Lookups
security:
- OAuth2: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Certification Lookup has been processed successfully
content:
application/vnd.api+json:
example:
data:
id: 358d2fd5-0be2-44e3-b05f-020cbd73bbbc
type: certificationLookups
attributes:
status: JOB_SUCCESS
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:21:08.545Z'
updatedAt: '2026-07-16T13:21:08.545Z'
requestedLatitude: null
requestedLongitude: null
statuses:
breeamCertifications:
status: JOB_SUCCESS
casbeeCertifications:
status: JOB_SUCCESS
greenStarCertifications:
status: JOB_SUCCESS
leedCertifications:
status: JOB_SUCCESS
requestedAddressLine1: 696 Watsica Place
requestedAddressLine2: null
requestedCity: West Nathanael
requestedStateOrProvince: ID
requestedPostalCode: '36301'
requestedCountry: ''
latitude: '82.5130488945'
longitude: '-142.5493594743'
requestedPropertyType: Laboratory
buildingCustomId: '123456'
buildingClientMetadata:
foo: bar
relationships:
certificationLookupBatch:
data:
id: 3a3df06e-0d21-46a9-a3ed-48e1fe37b1cc
type: certificationLookupBatches
building:
data:
id: 7293b88e-e092-4707-bbdb-b4cf93b65658
type: buildings
leedCertificationResponses:
data:
- id: 0daf9680-2a36-45a3-ae94-98b9ea8e629e
type: leedCertificationResponses
breeamCertificationResponses:
data:
- id: 218db5b8-7494-49e9-80a6-53a3e8ecf79a
type: breeamCertificationResponses
casbeeCertificationResponses:
data:
- id: 80e560ad-0950-446a-a327-5c7173e063e1
type: casbeeCertificationResponses
greenStarCertificationResponses:
data:
- id: cba15cf0-bda3-4e18-8804-3177a785e1bf
type: greenStarCertificationResponses
included:
- id: 218db5b8-7494-49e9-80a6-53a3e8ecf79a
type: breeamCertificationResponses
attributes:
assessor: Shields LLC
buildingName: Paradise Place
certBody: BRE Global
certNo: BREEAM-0012-3456
city: North Quianaville
companyName: Farrell, Krajcik and Fritsch
contactEmailAddress: mae_robel@hermann-dibbert.example
country: China
county: ''
description: Residential
developer: Shields-Mraz
distance: 0
firstSubSectionNo: ''
latitude: '37.64929469854134'
longitude: '-122.41119418102008'
notes: 'Stage: Final
Score(%): 36.2
Cert. date: 10/11/2025'
postCode: '40264'
projectType: Other buildings/Mixed use
rating: Pass
regAddressLine1: 8860 Jaqueline Stream
regAddressLine2: Suite 211
regAddressLine3: ''
regContact: ''
regEmailAddress: long.schoen@lebsack-stoltenberg.test
regFaxNumber: 397-280-7141
regTelNumber: (473) 565 3229
regWebAddress: http://zulauf-hermiston.example/veta.carter
scheme: International
score: 39
stage: Interim
standard: '2013 New Construction: Offices'
createdAt: '2026-07-16T13:21:08.308Z'
updatedAt: '2026-07-16T13:21:08.560Z'
- id: cba15cf0-bda3-4e18-8804-3177a785e1bf
type: greenStarCertificationResponses
attributes:
greenStarBuildingName: null
applicantCompany: Lynch Inc
applicantsSector: Government
assessors: Wilson Beatty
assetType: Hotel
carbonPositive: true
finalRating: 4
finalScore: 67
localCouncil: Lavernton Council
milestoneStatus: Registered
projectNumber: '744165'
projectStatus: Completed
ratingTool: Green Star - Design & As Built
toolFamily: Green Star
totalGfa: '148995.0'
certificationDate: '2026-05-02'
expirationDate: '2028-11-05'
practicalCompletionDate: '2026-04-02'
registeredDate: '2026-02-14'
createdAt: '2026-07-16T13:21:08.539Z'
updatedAt: '2026-07-16T13:21:08.564Z'
- id: 0daf9680-2a36-45a3-ae94-98b9ea8e629e
type: leedCertificationResponses
attributes:
gbigBuildingId: 22907
gbigBuildingName: 2 Bryant St
activityName: Perkins+Will San Francisco Studio
certificationType: 2014 ENERGY STAR National Building Competition
level: Participant
buildingSizeInSquareFeet: 40095
projectSizeInSquareFeet: 44220
projectSpaceUse: Office
awardedDate: '2022-11-02'
registeredDate: null
createdAt: '2026-07-16T13:21:08.365Z'
updatedAt: '2026-07-16T13:21:08.566Z'
- id: 80e560ad-0950-446a-a327-5c7173e063e1
type: casbeeCertificationResponses
attributes:
casbeeId: '49444'
casbeeBuildingName: Weber and Sons
primaryPropertyType: Newspapers
certificationBody: Christiansen-Carroll
certificationNumber: '4012411128'
applicant: Swift, Pollich and Bernier
constructionSite: Suite 899 34242 Jacinto Forks, West Karrieshire, TX 71812
certificationType: 6th generation
rank: air traffic controller
distanceFromCoordinates: '56.485454'
grossFloorAreaInSquareFeet: null
certificationDate: '2026-04-05'
expirationDate: '2026-08-10'
createdAt: '2026-07-16T13:21:08.439Z'
updatedAt: '2026-07-16T13:21:08.562Z'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
'404':
description: ID is not found
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/crrem_lookup_batches/export: {}
/insights/v0/crrem_lookup_batches/{id}: {}
/insights/v0/crrem_lookup_batches/upload: {}
/insights/v0/crrem_lookups: {}
/insights/v0/crrem_lookup_batches/{id}/crrem_lookups: {}
/insights/v0/crrem_lookups/{id}: {}
/insights/v0/energy_estimate_batches/{id}/energy_estimates:
get:
summary: Returns all energy estimates for a given batch
description: 'Provides access to the data for all the energy estimates in a given energy estimate batch record once
it completes processing. It can be polled while processing to see the current status.
'
tags:
- Energy Estimates
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: d271f75a-6d88-4344-a1cd-bfe6a82cb2a0'
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of energy estimates
content:
application/vnd.api+json:
example:
data:
- id: 39fac5b9-1750-4218-beb9-d130e08dcd55
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:08.939Z'
updatedAt: '2026-07-16T13:22:08.939Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: 42411ce2-0412-4993-a1b4-8284e7724277
type: energyEstimateBatches
building:
data:
id: 05cb480e-43dd-4a46-afd0-032b1052c185
type: buildings
- id: dca6d477-e342-423b-9b96-f964eca74268
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:08.959Z'
updatedAt: '2026-07-16T13:22:08.959Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: 42411ce2-0412-4993-a1b4-8284e7724277
type: energyEstimateBatches
building:
data:
id: f03227d8-c31e-43cc-bffe-bcaecb5adfd9
type: buildings
- id: 6915621c-c343-49c7-b4b3-37faf0023302
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:08.980Z'
updatedAt: '2026-07-16T13:22:08.980Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: 42411ce2-0412-4993-a1b4-8284e7724277
type: energyEstimateBatches
building:
data:
id: 7276cd31-b52b-4e16-9546-c4ad10c0cbe3
type: buildings
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/energy_estimate_batches/42411ce2-0412-4993-a1b4-8284e7724277/energy_estimates?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/energy_estimate_batches/export:
post:
summary: Requests a CSV download for the given Energy Estimate batches
tags:
- Energy Estimates
security:
- OAuth2: []
parameters:
- name: status
in: query
schema:
type: string
enum:
- JOB_SUCCESS
responses:
'200':
description: Export successfully created
content:
application/vnd.api+json:
example:
data:
id: d8757b15-de6a-4660-a812-14bd1e2d8f69
type: exports
attributes:
status: PROCESSING
error: null
createdAt: '2026-07-16T13:22:09.527Z'
updatedAt: '2026-07-16T13:22:09.527Z'
permalink: http://localhost:3000/insights/v0/exports/5d75214d-a2c5-46cf-94dc-0677373a1974/download
relationships:
estimateBatches:
data:
- id: 94b96756-2f4b-4290-9aa7-3942ad920e30
type: energyEstimateBatches
- id: 16cc6239-c8eb-4f0a-930f-633ad8b43839
type: energyEstimateBatches
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
batchIds:
type: array
items:
type: string
example:
- b0d6486a-9398-42c6-9182-14eaba92d739
- dacb11f7-3b69-409c-9565-ce05f9869cf1
/insights/v0/energy_estimate_batches/{id}:
get:
summary: Returns energy estimate batch
description: 'Provides access to the data for the energy estimate batch record once it completes processing. It can
be polled while processing to see the current status.
'
tags:
- Energy Estimates
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: ee433e27-9d53-4c54-90c2-b57e3d2a6f98'
required: true
schema:
type: string
responses:
'200':
description: Energy estimate batch record
content:
application/vnd.api+json:
example:
data:
id: 25efef21-6bfd-4fa9-b785-72c1a17e7ca9
type: energyEstimateBatches
attributes:
estimateType: energy
status: STARTING
timePeriod: '2025'
errorMessage: null
createdAt: '2026-07-16T13:22:09.606Z'
updatedAt: '2026-07-16T13:22:09.606Z'
schema:
$ref: '#/components/schemas/json_api'
'404':
description: Energy estimate batch record belonging to another app
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/energy_estimate_batches/upload:
post:
summary: Uploads a file to create new energy estimate(s)
description: 'Upload an Excel file of energy estimate records to be processed. The response will include the estimate
batch record, including the ID that can be used to access the estimate batch or its energy estimates.
'
tags:
- Energy Estimates
security:
- OAuth2: []
parameters:
- name: timePeriod
in: query
schema:
type: string
description: 'A timePeriod to apply for all estimates in the batch. The valid values for timePeriod are: ["T-12",
"2025", "2024", "2023", "2022", "2021"]''
'
enum:
- T-12
- '2025'
- '2024'
- '2023'
- '2022'
- '2021'
required: true
responses:
'200':
description: Energy estimate batch successfully created
content:
application/vnd.api+json:
example:
data:
id: 5503b9b5-2dba-4d98-948b-2aab07e9b30e
type: energyEstimateBatches
attributes:
estimateType: energy
status: STARTING
timePeriod: '2025'
errorMessage: null
createdAt: '2026-07-16T13:22:09.957Z'
updatedAt: '2026-07-16T13:22:09.967Z'
schema:
$ref: '#/components/schemas/json_api'
'400':
description: invalid time period
content:
application/vnd.api+json:
example:
errors:
- status: '400'
title: Bad Request
detail: 'Time period requested: 3023 is not included in the list T-12, 2025, 2024, 2023, 2022, 2021; Requesting
app: Spencer, Gerhold and Beahan'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
estimate_batch_file:
type: string
format: binary
description: 'An Excel XLSX file containing the buildings you would like energy estimates for.
When requesting data on buildings for the first time, the Excel Worksheet must be named ''Buildings''.
Building information is required for each estimate. Other fields are optional.
The field ''clientMetadata'' is available for storing arbitrary JSON, this allows storing identifiers
from your system and other metadata as part of the energy estimate record.
When requesting data on existing buildings i.e. you have the Building IDs, the Excel Worksheet must be
named ''MSR Building IDs'' and may only contain a single column named ''MSR Building ID''.
'
required: true
/insights/v0/energy_estimates:
get:
summary: Returns all energy estimates
tags:
- Energy Estimates
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of energy estimates
content:
application/vnd.api+json:
example:
data:
- id: 11a69532-86a1-4754-9880-22372a20847d
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:10.424Z'
updatedAt: '2026-07-16T13:22:10.424Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: 3eb18d93-e346-460f-9283-46154681394a
type: energyEstimateBatches
building:
data:
id: db98a7b4-6133-47bb-8a37-b90c45208d28
type: buildings
- id: 21cdc528-76a3-4073-bc3e-3ca6520e0822
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:10.448Z'
updatedAt: '2026-07-16T13:22:10.448Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: 95667358-2d73-4451-b25f-a3e50fdb20d9
type: energyEstimateBatches
building:
data:
id: 19a5cfd5-2c90-437f-83b0-7a1fb58598f7
type: buildings
- id: 67f593c9-165d-427a-abb4-86e57d227e91
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:10.474Z'
updatedAt: '2026-07-16T13:22:10.474Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
relationships:
estimateBatch:
data:
id: 643171b3-df06-470f-814e-661d08502840
type: energyEstimateBatches
building:
data:
id: 528010fe-c6b9-45b8-a2c4-182686ba4e8e
type: buildings
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/energy_estimates?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
post:
summary: Creates new energy estimate(s)
description: 'Create new energy estimate records to be processed. The response will include those records, including
IDs that can be used to access the energy estimate(s).
There is a limit of 100 buildings per request. If you have over 100 buildings, please create separate requests in
increments of 100 buildings or fewer.
Please note: You can process larger collections of Buildings via the file upload endpoint.
Coverage: Global
'
tags:
- Energy Estimates
security:
- OAuth2: []
parameters: []
responses:
'200':
description: Energy estimate(s) successfully created
content:
application/vnd.api+json:
examples:
With MSR Building ID:
value:
data:
- id: c849d07d-bace-437c-b186-7f52677a436c
type: energyEstimates
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:11.780Z'
updatedAt: '2026-07-16T13:22:11.796Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: 3f3493da-a2e9-419d-8663-6899aa3320ec
type: energyEstimateBatches
building:
data:
id: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
type: buildings
- id: 93581db2-b517-487a-9489-c6cbb875ab53
type: energyEstimates
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:11.780Z'
updatedAt: '2026-07-16T13:22:11.812Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: 3f3493da-a2e9-419d-8663-6899aa3320ec
type: energyEstimateBatches
building:
data:
id: b76bce9f-09a5-4568-8567-dd7f1d9390af
type: buildings
With Building Custom ID:
value:
data:
- id: ea4fffb9-49c9-4545-92de-8bd7e82e8968
type: energyEstimates
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:11.927Z'
updatedAt: '2026-07-16T13:22:11.944Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: 96f7f1cc-9e7c-4da2-ba4c-e8404addf05a
type: energyEstimateBatches
building:
data:
id: 79936ea3-f62b-418b-862c-50cdad48b5fe
type: buildings
With Coordinates:
value:
data:
- id: ee33cea1-160e-45b3-aa72-304acebabc36
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:12.032Z'
updatedAt: '2026-07-16T13:22:12.032Z'
requestedLatitude: '40.766276'
requestedLongitude: '-73.9834504'
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: 7ec7b4ae-1027-45bf-a524-87e90e9374e6
type: energyEstimateBatches
building:
data: null
With Full Address Data:
value:
data:
- id: 3f3b39dc-ca00-46dc-9733-9e36943ad51e
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:12.135Z'
updatedAt: '2026-07-16T13:22:12.135Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: f3d86c4b-6f5b-45e7-b653-17286e7b48e9
type: energyEstimateBatches
building:
data: null
- id: 0bb6666c-632f-4314-8767-c3c5c578e350
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:12.135Z'
updatedAt: '2026-07-16T13:22:12.135Z'
requestedLatitude: '39.15600199'
requestedLongitude: '-84.4202312'
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: f3d86c4b-6f5b-45e7-b653-17286e7b48e9
type: energyEstimateBatches
building:
data: null
- id: 52a15083-127a-40b6-ba04-3561440602ed
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:12.135Z'
updatedAt: '2026-07-16T13:22:12.135Z'
requestedLatitude: '39.4861121'
requestedLongitude: '-104.7789231'
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: f3d86c4b-6f5b-45e7-b653-17286e7b48e9
type: energyEstimateBatches
building:
data: null
- id: 61158550-ae9b-460a-9676-77efcc3ff65a
type: energyEstimates
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:12.135Z'
updatedAt: '2026-07-16T13:22:12.135Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2023-01
endingMonth: 2023-12
relationships:
estimateBatch:
data:
id: f3d86c4b-6f5b-45e7-b653-17286e7b48e9
type: energyEstimateBatches
building:
data: null
schema:
$ref: '#/components/schemas/json_api'
'413':
description: too many estimates in request
content:
application/vnd.api+json:
example:
errors:
- status: '413'
title: Payload too large
detail: Only 100 estimates can be created in a single request.
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
timePeriod:
type: string
enum:
- T-12
- '2025'
- '2024'
- '2023'
- '2022'
- '2021'
estimates:
type: array
items:
oneOf:
- $ref: '#/components/schemas/request_body_msr_building_id'
- $ref: '#/components/schemas/request_body_building_custom_id'
- $ref: '#/components/schemas/request_body_coordinates_with_client_metadata'
- $ref: '#/components/schemas/request_body_building_info_with_client_metadata'
examples:
With MSR Building ID:
summary: With MSR Building ID
value:
timePeriod: '2023'
estimates:
- building:
msrBuildingId: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
- building:
msrBuildingId: b76bce9f-09a5-4568-8567-dd7f1d9390af
With Building Custom ID:
summary: With Building Custom ID
value:
timePeriod: '2023'
estimates:
- building:
buildingCustomId: your-custom-building-id
With Coordinates:
summary: With Coordinates
value:
timePeriod: '2023'
estimates:
- building:
latitude: 40.766276
longitude: -73.9834504
primaryPropertyType: Office
yearBuilt: 2006
grossFloorArea: 703796
grossFloorAreaUnits: sq ft
With Full Address Data:
summary: With Full Address Data
value:
estimates:
- building:
addressLine1: 29 East High St.
addressLine2: null
city: Lawrenceburg
stateOrProvince: IN
postalCode: '47025'
country: United States
primaryPropertyType: Food Sales & Service
yearBuilt: 1890
grossFloorArea: 3000
grossFloorAreaUnits: sq ft
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: 4460 Orkney Ave.
addressLine2: null
city: Cincinnati
stateOrProvince: OH
postalCode: '45209'
country: United States
primaryPropertyType: Fitness Center/Health Club/Gym
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
longitude: -84.4202312
latitude: 39.15600199
buildingCustomId: building-123456
buildingClientMetadata:
foo: bar
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: null
addressLine2: null
city: Denver
stateOrProvince: CO
postalCode: '80112'
country: United States
primaryPropertyType: Education - K-12 School - Other
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
latitude: 39.4861121
longitude: -104.7789231
clientMetadata:
project: Midwest Analysis
- building:
msrBuildingId: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
addressLine1: null
addressLine2: null
city: Centennial
stateOrProvince: CO
postalCode: '80112'
country: United States
primaryPropertyType: Warehouse/Storage - Other
yearBuilt: 2019
grossFloorArea: 12950
grossFloorAreaUnits: sq ft
clientMetadata:
project: Midwest Analysis
timePeriod: '2023'
description: 'The energy estimates to be created.
Time Period is required for each request and must be a valid year.
The valid values for timePeriod are: T-12, 2025, 2024, 2023, 2022, 2021.
Building information is required for each estimate and can be provided in one of four ways:
- Building UUID (msrBuildingId)
- Building Custom ID (buildingCustomId)
- Coordinates and additional building information (latitude, longitude, primaryPropertyType, yearBuilt, grossFloorArea,
grossFloorAreaUnits)
- Full address and additional building information (addressLine1, city, stateOrProvince, postalCode, country, primaryPropertyType,
yearBuilt, grossFloorArea, grossFloorAreaUnits)
The preferred method is to use the msrBuildingId or buildingCustomId if available. If neither is available, using
coordinates is preferred over full address data.
Optional fields:
- **customId** is available for storing a custom identifier for the estimate; this allows storing identifiers from
your system as part of the energy _estimate_ record.
- **buildingCustomId** is available for storing a custom identifier for the building; this allows storing identifiers
from your system as part of the _building_ record.
- **clientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from your
system and other metadata as part of the energy _estimate_ record.
- **buildingClientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from
your system and other metadata as part of the _building_ record.
'
/insights/v0/energy_estimates/{id}:
get:
summary: Retrieves an existing energy estimate
description: 'Provides access to the data for the energy estimate record once it completes processing. It can be polled
while processing to see the current status.
'
tags:
- Energy Estimates
security:
- OAuth2: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Energy estimate has been processed successfully
content:
application/vnd.api+json:
example:
data:
id: 2b11113e-5142-4872-8bd1-772f29554b4c
type: energyEstimates
attributes:
status: SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:12.481Z'
updatedAt: '2026-07-16T13:22:12.481Z'
requestedLatitude: null
requestedLongitude: null
startingMonth: 2025-07
endingMonth: 2026-06
annualAbsoluteEstimate: 6638225.3086223
absoluteEstimateUnits: MWh
annualIntensityEstimate: 5991.1780762
confidenceLabel: moderate
confidenceDescription: The average energy estimate error for properties in this category is anticipated
to be <= 26.1%.
intensityEstimateUnits: kWh/m²
requestedAddressLine1: 483 Monty Corner
requestedAddressLine2: Suite 418
requestedCity: North Wyatt
requestedStateOrProvince: OH
requestedPostalCode: 16132-0002
requestedCountry: United States
requestedPropertyType: Other
latitude: '6.3976680226'
longitude: '-166.0066488623'
appliedPropertyType: Other
monthlyIntensityEstimates:
- 429.1486005
- 449.5358834
- 529.1567854
- 757.9140643
- 127.265202
- 713.0481834
- 813.0989944
- 314.1621152
- 719.1475234
- 278.2691359
- 420.4973919
- 439.9341964
monthlyAbsoluteEstimates:
- 475496.6493603
- 498085.7588294
- 586305.7182521
- 839768.7832455
- 141009.8438419
- 790057.3872454
- 900913.685742
- 348091.6236805
- 796815.4559194
- 308322.202614
- 465911.1102489
- 487447.0896429
buildingCustomId: '123456'
buildingClientMetadata:
foo: bar
relationships:
estimateBatch:
data:
id: 16394827-2244-45b9-8782-35815d4c45ee
type: energyEstimateBatches
building:
data:
id: 84e1cddc-b94b-4155-b58d-0e6255fd3109
type: buildings
benchmarkLookup:
data:
id: 93b121c0-fdb1-4111-aa4d-2435b66e1050
type: benchmarkLookup
included:
- id: 93b121c0-fdb1-4111-aa4d-2435b66e1050
type: benchmarkLookups
attributes:
createdAt: '2026-07-16T13:22:12.474Z'
updatedAt: '2026-07-16T13:22:12.474Z'
year: '2021'
benchmarkPropertyType: Other
continent: North America
continentSubregion: North America
countryCode: US
countrySubregion: Midwest
stateProvincePrefecture: OH
intensityBenchmarkUnits: kWh/ft2
globalMeanIntensity: '70.4530825458'
globalFirstQuartileIntensity: '44.4565641824'
globalSecondQuartileIntensity: '62.5959501256'
globalThirdQuartileIntensity: '82.6533924736'
globalFifteenthPercentileIntensity: '82.5603853463'
globalThirtiethPercentileIntensity: '14.6752486281'
continentMeanIntensity: '41.2156206097'
continentFirstQuartileIntensity: '19.4822141919'
continentSecondQuartileIntensity: '45.0204358863'
continentThirdQuartileIntensity: '55.3480247168'
continentFifteenthPercentileIntensity: '94.5318690454'
continentThirtiethPercentileIntensity: '76.9414809162'
continentSubregionMeanIntensity: '59.1293557681'
continentSubregionFirstQuartileIntensity: '58.2413660351'
continentSubregionSecondQuartileIntensity: '78.3921061127'
continentSubregionThirdQuartileIntensity: '81.9305169374'
continentSubregionFifteenthPercentileIntensity: There is not enough data to benchmark your building at
this level
continentSubregionThirtiethPercentileIntensity: There is not enough data to benchmark your building at
this level
countryMeanIntensity: '10.2043517662'
countryFirstQuartileIntensity: '45.8830121812'
countrySecondQuartileIntensity: '94.2336275081'
countryThirdQuartileIntensity: '25.5848896659'
countryFifteenthPercentileIntensity: '97.2330732137'
countryThirtiethPercentileIntensity: '40.7855470335'
countrySubregionMeanIntensity: '62.4243716083'
countrySubregionFirstQuartileIntensity: '19.1356352731'
countrySubregionSecondQuartileIntensity: '97.5274040024'
countrySubregionThirdQuartileIntensity: '42.1057074687'
countrySubregionFifteenthPercentileIntensity: '51.5690554899'
countrySubregionThirtiethPercentileIntensity: '84.7705962491'
stateProvincePrefectureMeanIntensity: There is not enough data to benchmark your building at this level
stateProvincePrefectureFirstQuartileIntensity: There is not enough data to benchmark your building at
this level
stateProvincePrefectureSecondQuartileIntensity: There is not enough data to benchmark your building at
this level
stateProvincePrefectureThirdQuartileIntensity: There is not enough data to benchmark your building at
this level
stateProvincePrefectureFifteenthPercentileIntensity: There is not enough data to benchmark your building
at this level
stateProvincePrefectureThirtiethPercentileIntensity: There is not enough data to benchmark your building
at this level
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
'404':
description: ID is not found
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/exports/{id}/download:
get:
summary: Downloads the export file
description: 'Provides a redirect to download the export file.
The url in the redirect has an expiration, typically of 5 minutes.
'
tags:
- Exports
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: ee433e27-9d53-4c54-90c2-b57e3d2a6f98'
required: true
schema:
type: string
responses:
'302':
description: Export is downloaded via redirect to pre-signed URL
headers:
Location:
schema:
type: string
format: uri
description: The redirect URL location of the requested export file (pre-signed URL).
'200':
description: Export is not ready yet
content:
application/vnd.api+json:
example:
data:
id: 2962d854-8cd4-42a3-8554-95097ba33197
type: exports
attributes:
status: PROCESSING
error: null
createdAt: '2026-07-16T13:22:12.964Z'
updatedAt: '2026-07-16T13:22:12.964Z'
permalink: http://www.example.com/insights/v0/exports/2962d854-8cd4-42a3-8554-95097ba33197/download
relationships: {}
meta:
message: The export is not ready yet. Check the status with http://www.example.com/insights/v0/exports/2962d854-8cd4-42a3-8554-95097ba33197
/insights/v0/exports:
get:
summary: Returns all exports for an app
tags:
- Exports
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of exports
content:
application/vnd.api+json:
example:
data:
- id: 99911f2a-a358-44c5-89bc-1b1004a873bb
type: exports
attributes:
status: JOB_SUCCESS
error: null
createdAt: '2026-07-16T13:22:13.361Z'
updatedAt: '2026-07-16T13:22:13.361Z'
relationships:
estimateBatches:
data:
- id: b33dd758-5ec6-4352-b985-30a0d3966526
type: energyEstimateBatches
- id: 8e2a6b2d-50ad-482a-8176-3a92df3ccb10
type: energyEstimateBatches
- id: 775566a8-d8f1-4f7f-b8bb-5d20aaa3a181
type: energyEstimateBatches
- id: 9325c325-2878-411f-90fd-2b0c1d0e8c0e
type: exports
attributes:
status: JOB_SUCCESS
error: null
createdAt: '2026-07-16T13:22:13.386Z'
updatedAt: '2026-07-16T13:22:13.386Z'
relationships:
estimateBatches:
data:
- id: e19743ea-a0e8-47bf-8310-64d88a64c95c
type: energyEstimateBatches
- id: f0e929ea-5b01-4227-bbc1-9aeb26491645
type: energyEstimateBatches
- id: d610b3de-0344-4c15-96b5-75557faa72c5
type: energyEstimateBatches
meta:
totalCount: 2
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 2
links:
self: /insights/v0/exports?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/exports/{id}:
get:
summary: Retrieves an existing export
description: 'Provides access to the data for the ordinance lookup batch record once it completes processing. It can
be polled while processing to see the current status.
'
tags:
- Exports
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: ee433e27-9d53-4c54-90c2-b57e3d2a6f98'
required: true
schema:
type: string
responses:
'200':
description: Export record
content:
application/vnd.api+json:
example:
data:
id: dc3e88e4-18a9-4541-88e9-ff501ed0d830
type: exports
attributes:
status: PROCESSING
error: null
createdAt: '2026-07-16T13:22:13.763Z'
updatedAt: '2026-07-16T13:22:13.763Z'
permalink: http://www.example.com/insights/v0/exports/dc3e88e4-18a9-4541-88e9-ff501ed0d830/download
relationships: {}
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
'422':
description: Export record has batch records with different time periods
content:
application/vnd.api+json:
example:
errors:
- status: '422'
title: Unprocessable Entity
detail: 'All batches in export must have the same time period
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/ordinance_lookup_batches/export:
post:
summary: Requests a CSV download for the given Ordinance Lookup batches
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters:
- name: status
in: query
schema:
type: string
enum:
- JOB_SUCCESS
responses:
'200':
description: empty batch ids list
content:
application/vnd.api+json:
example:
data:
id: 50212abd-5e0f-4349-b6d6-947f26abac0c
type: exports
attributes:
status: JOB_SUCCESS
error: No batches found
createdAt: '2026-07-16T13:22:14.228Z'
updatedAt: '2026-07-16T13:22:14.231Z'
permalink: http://localhost:3000/insights/v0/exports/50212abd-5e0f-4349-b6d6-947f26abac0c/download
relationships: {}
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
batchIds:
type: array
items:
type: string
example:
- b0d6486a-9398-42c6-9182-14eaba92d739
- dacb11f7-3b69-409c-9565-ce05f9869cf1
/insights/v0/ordinance_lookup_batches/{id}/ordinance_lookups:
get:
summary: Returns all ordinance lookups for a given batch
description: 'Provides access to the data for all the ordinance lookups in a given ordinance lookup batch record once
it completes processing. It can be polled while processing to see the current status.
'
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: d271f75a-6d88-4344-a1cd-bfe6a82cb2a0'
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of ordinance lookups
content:
application/vnd.api+json:
example:
data:
- id: 81de1832-fec2-415f-89d8-08779355be6a
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:14.328Z'
updatedAt: '2026-07-16T13:22:14.328Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 7dd203ff-12ef-4687-8dcd-2f29ee44d178
type: ordinanceLookupBatches
building:
data:
id: 93adade5-c1d7-4b45-a058-60d42ebcd4d4
type: buildings
ordinanceResponses:
data: []
- id: 040b2f40-cf44-49f6-a69c-c698c8921cee
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:14.349Z'
updatedAt: '2026-07-16T13:22:14.349Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 7dd203ff-12ef-4687-8dcd-2f29ee44d178
type: ordinanceLookupBatches
building:
data:
id: f31677f1-af87-4e3a-88cd-f85eb995566e
type: buildings
ordinanceResponses:
data: []
- id: 710da4ec-44c5-4cef-be2c-e74ae2e614a4
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:14.371Z'
updatedAt: '2026-07-16T13:22:14.371Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 7dd203ff-12ef-4687-8dcd-2f29ee44d178
type: ordinanceLookupBatches
building:
data:
id: 31badbaa-4504-41e2-bcad-25335eb9ff4f
type: buildings
ordinanceResponses:
data: []
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/ordinance_lookup_batches/7dd203ff-12ef-4687-8dcd-2f29ee44d178/ordinance_lookups?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/ordinance_lookup_batches/{id}:
get:
summary: Returns ordinance lookup batch
description: 'Provides access to the data for the ordinance lookup batch record once it completes processing. It can
be polled while processing to see the current status.
'
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters:
- name: id
in: path
description: 'Example: ee433e27-9d53-4c54-90c2-b57e3d2a6f98'
required: true
schema:
type: string
responses:
'200':
description: Ordinance Lookup batch record
content:
application/vnd.api+json:
example:
data:
id: fc9af880-21af-4fd7-979d-8fa4a4848664
type: ordinanceLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:22:14.762Z'
updatedAt: '2026-07-16T13:22:14.762Z'
schema:
$ref: '#/components/schemas/json_api'
'404':
description: Ordinance Lookup batch record belonging to another app
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/ordinance_lookup_batches/upload:
post:
summary: Uploads a file to create new ordinance lookup(s)
description: 'Upload an Excel file of ordinance lookup records to be processed. The response will include the ordinance
lookup batch record, including the ID that can be used to access the ordinance lookup batch or its ordinance lookups.
'
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters: []
responses:
'200':
description: Ordinance lookup batch successfully created
content:
application/vnd.api+json:
example:
data:
id: 442482d9-a5d5-42e0-92e1-de7ff08a6f64
type: ordinanceLookupBatches
attributes:
status: STARTING
errorMessage: null
createdAt: '2026-07-16T13:22:15.130Z'
updatedAt: '2026-07-16T13:22:15.139Z'
schema:
$ref: '#/components/schemas/json_api'
'400':
description: missing file upload
content:
application/vnd.api+json:
example:
errors:
- status: '400'
title: Bad Request
detail: 'Excel file required in ordinance_lookup_batch_file
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
ordinance_lookup_batch_file:
type: string
format: binary
description: 'An Excel XLSX file containing the buildings you would like ordinance lookups for.
When requesting data on buildings for the first time, the Excel Worksheet must be named ''Buildings''.
Building information is required for each ordinance lookup. Other fields are optional.
The field ''clientMetadata'' is available for storing arbitrary JSON, this allows storing identifiers
from your system and other metadata as part of the ordinance lookup record.
When requesting data on existing buildings i.e. you have the Building IDs, the Excel Worksheet must be
named ''MSR Building IDs'' and may only contain a single column named ''MSR Building ID''.
'
required: true
/insights/v0/ordinance_lookups:
post:
summary: Creates new ordinance lookup(s)
description: 'Create new ordinance lookup records to be processed. The response will include those records, including
IDs that can be used to access the ordinance lookup(s).
There is a limit of 100 buildings per request. If you have over 100 buildings, please create separate requests in
increments of 100 buildings or fewer.
Please note: You can process larger collections of Buildings via the file upload endpoint.
Coverage: United States and Canada
'
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters: []
responses:
'200':
description: Ordinance Lookups(s) successfully created
content:
application/vnd.api+json:
examples:
With MSR Building ID:
value:
data:
- id: bb6e4bdb-1988-4411-afd1-d623994149a6
type: ordinanceLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:16.477Z'
updatedAt: '2026-07-16T13:22:16.490Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 72bd2b01-b3a0-4e1a-aec3-ec7738e4525a
type: ordinanceLookupBatches
building:
data:
id: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
type: buildings
ordinanceResponses:
data: []
- id: a747a93a-7058-43fd-b869-332e37bc2db1
type: ordinanceLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:16.477Z'
updatedAt: '2026-07-16T13:22:16.504Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 72bd2b01-b3a0-4e1a-aec3-ec7738e4525a
type: ordinanceLookupBatches
building:
data:
id: b4a87aea-bbd0-4d7b-a50e-b1f7861c511e
type: buildings
ordinanceResponses:
data: []
With Building Custom ID:
value:
data:
- id: 02f6f4dc-8827-4963-a7e2-6f78537cc56b
type: ordinanceLookups
attributes:
status: GEOLOCATION_SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:16.609Z'
updatedAt: '2026-07-16T13:22:16.626Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 7272b94c-985c-4189-9db9-773aa9fdc46f
type: ordinanceLookupBatches
building:
data:
id: e5d326bf-255a-464c-9e7b-1e9f1ee72984
type: buildings
ordinanceResponses:
data: []
With Coordinates:
value:
data:
- id: 7eea0b12-fec0-4ff2-a7fc-ced1a0d9123d
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:16.716Z'
updatedAt: '2026-07-16T13:22:16.716Z'
requestedLatitude: '40.766276'
requestedLongitude: '-73.9834504'
relationships:
ordinanceLookupBatch:
data:
id: f0319fd7-a0b1-4735-bc4e-1984a265da10
type: ordinanceLookupBatches
building:
data: null
ordinanceResponses:
data: []
With Full Address Data:
value:
data:
- id: 50f7795c-1d6f-4b76-86fe-ece43a6ae425
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:16.822Z'
updatedAt: '2026-07-16T13:22:16.822Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 9854df61-cd14-4799-ad61-8c1a7b7c0067
type: ordinanceLookupBatches
building:
data: null
ordinanceResponses:
data: []
- id: 11d238de-5b59-4719-b6da-0b01e5d317fb
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:16.822Z'
updatedAt: '2026-07-16T13:22:16.822Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 9854df61-cd14-4799-ad61-8c1a7b7c0067
type: ordinanceLookupBatches
building:
data: null
ordinanceResponses:
data: []
- id: 5c817073-ab4d-4c7b-a163-354c2551b78e
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:16.822Z'
updatedAt: '2026-07-16T13:22:16.822Z'
requestedLatitude: '39.751262'
requestedLongitude: '-104.998385'
relationships:
ordinanceLookupBatch:
data:
id: 9854df61-cd14-4799-ad61-8c1a7b7c0067
type: ordinanceLookupBatches
building:
data: null
ordinanceResponses:
data: []
- id: bc09ace4-fe8c-49df-81da-4b000824a194
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata:
project: Midwest Analysis
createdAt: '2026-07-16T13:22:16.822Z'
updatedAt: '2026-07-16T13:22:16.822Z'
requestedLatitude: '39.751262'
requestedLongitude: '-104.998385'
relationships:
ordinanceLookupBatch:
data:
id: 9854df61-cd14-4799-ad61-8c1a7b7c0067
type: ordinanceLookupBatches
building:
data: null
ordinanceResponses:
data: []
schema:
$ref: '#/components/schemas/json_api'
'413':
description: too many ordinance lookups in request
content:
application/vnd.api+json:
example:
errors:
- status: '413'
title: Payload too large
detail: Only 100 ordinance lookups can be created in a single request.
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
requestBody:
content:
application/json:
schema:
type: object
properties:
ordinanceLookups:
type: array
items:
oneOf:
- $ref: '#/components/schemas/request_body_msr_building_id'
- $ref: '#/components/schemas/request_body_building_custom_id'
- $ref: '#/components/schemas/request_body_coordinates_with_client_metadata'
- $ref: '#/components/schemas/request_body_building_info_with_client_metadata'
examples:
With MSR Building ID:
summary: With MSR Building ID
value:
ordinanceLookups:
- building:
msrBuildingId: 9dcccad0-4afe-4e65-88d7-63fda2bdc467
- building:
msrBuildingId: b4a87aea-bbd0-4d7b-a50e-b1f7861c511e
With Building Custom ID:
summary: With Building Custom ID
value:
ordinanceLookups:
- building:
buildingCustomId: your-custom-building-id
With Coordinates:
summary: With Coordinates
value:
ordinanceLookups:
- building:
latitude: 40.766276
longitude: -73.9834504
primaryPropertyType: Office
yearBuilt: 2006
grossFloorArea: 703796
grossFloorAreaUnits: sq ft
With Full Address Data:
summary: With Full Address Data
value:
ordinanceLookups:
- building:
addressLine1: 20 W 34th St
addressLine2: null
city: New York
stateOrProvince: NY
postalCode: '10001'
country: United States
primaryPropertyType: Other
yearBuilt: 1930
grossFloorArea: 2734030
grossFloorAreaUnits: sq ft
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: 200 East Colfax Ave
addressLine2: null
city: Denver
stateOrProvince: CO
postalCode: '80203'
country: United States
primaryPropertyType: Other
yearBuilt: 1901
grossFloorArea: 268806
grossFloorAreaUnits: sq ft
buildingCustomId: building-123456
buildingClientMetadata:
foo: bar
clientMetadata:
project: Midwest Analysis
- building:
addressLine1: null
addressLine2: null
city: Denver
stateOrProvince: CO
postalCode: '80202'
country: United States
primaryPropertyType: Retail - Other
yearBuilt: 2019
grossFloorArea: 10250
grossFloorAreaUnits: sq ft
latitude: 39.751262
longitude: -104.998385
clientMetadata:
project: Midwest Analysis
- building:
msrBuildingId: e413fe4d-9da0-4e5b-97cd-2f19009d057d
addressLine1: null
addressLine2: null
city: Denver
stateOrProvince: CO
postalCode: '80202'
country: United States
primaryPropertyType: Retail - Other
yearBuilt: 2019
grossFloorArea: 10250
grossFloorAreaUnits: sq ft
latitude: 39.751262
longitude: -104.998385
clientMetadata:
project: Midwest Analysis
description: 'The ordinance lookups to be created.
Building information is required for each ordinance lookup and can be provided in one of four ways:
- Building UUID (msrBuildingId)
- Building Custom ID (buildingCustomId)
- Coordinates and additional building information (latitude, longitude, primaryPropertyType, yearBuilt, grossFloorArea,
grossFloorAreaUnits)
- Full address and additional building information (addressLine1, city, stateOrProvince, postalCode, country, primaryPropertyType,
yearBuilt, grossFloorArea, grossFloorAreaUnits)
The preferred method is to use the msrBuildingId or buildingCustomId if available. If neither is available, using
coordinates is preferred over full address data.
Optional fields:
- **customId** is available for storing a custom identifier for the estimate; this allows storing identifiers from
your system as part of the ordinance _lookup_ record.
- **buildingCustomId** is available for storing a custom identifier for the building; this allows storing identifiers
from your system as part of the _building_ record.
- **clientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from your
system and other metadata as part of the ordinance _lookup_ record.
- **buildingClientMetadata** is available for storing arbitrary JSON metadata; this allows storing identifiers from
your system and other metadata as part of the _building_ record.
'
get:
summary: Returns all ordinance lookups
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters:
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: list of ordinance lookups
content:
application/vnd.api+json:
example:
data:
- id: a7188ed1-9952-4306-9434-174864203f6d
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:17.097Z'
updatedAt: '2026-07-16T13:22:17.097Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 29d21ea9-9a8c-4e6f-86e8-d4c1eff23189
type: ordinanceLookupBatches
building:
data:
id: cb998258-1c8b-47bb-ac53-385e565f17b9
type: buildings
ordinanceResponses:
data:
- id: c6322c1b-d956-5f65-8883-7b9bcf167838
type: ordinanceResponses
- id: a5ee21e2-adb8-4110-a4de-65862f38658b
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:17.134Z'
updatedAt: '2026-07-16T13:22:17.134Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: e0f9be8c-8098-4629-9915-8dbf610819b2
type: ordinanceLookupBatches
building:
data:
id: 578bf7d1-5f68-4e29-9b32-158ea7309871
type: buildings
ordinanceResponses:
data:
- id: b16e858d-fb62-5477-b467-1bf1e98ecb59
type: ordinanceResponses
- id: a482ca37-ba81-4066-a041-5521e2504960
type: ordinanceLookups
attributes:
status: PROCESSING
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:17.170Z'
updatedAt: '2026-07-16T13:22:17.170Z'
requestedLatitude: null
requestedLongitude: null
relationships:
ordinanceLookupBatch:
data:
id: 58cfc195-f5e5-4559-affc-e2c3e8e0d756
type: ordinanceLookupBatches
building:
data:
id: 32e10277-619d-4eef-9fdb-f15714cbe6be
type: buildings
ordinanceResponses:
data:
- id: a49c2bbb-84d2-548f-8211-fa9d91503304
type: ordinanceResponses
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/ordinance_lookups?page=1&pageSize=5
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'404':
description: when requesting an overflow page
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: 'The page requested was not found
The last page available is 1
'
schema:
$ref: '#/components/schemas/json_api'
'403':
description: unauthorized request
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: 'A valid auth token is required.
POST to ''/token'' with a valid ''key'' and ''secret'' to get an auth token.
'
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/ordinance_lookups/{id}:
get:
summary: Retrieves an existing ordinance lookup
description: 'Provides access to the data for the ordinance lookup record once it completes processing. It can be polled
while processing to see the current status.
'
tags:
- Ordinance Lookups
security:
- OAuth2: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Ordinance Lookup has been processed successfully
content:
application/vnd.api+json:
example:
data:
id: 8e16bf3c-9296-4bc3-a611-971fc1209fde
type: ordinanceLookups
attributes:
status: SUCCEEDED
error: null
customId: null
clientMetadata: null
createdAt: '2026-07-16T13:22:17.685Z'
updatedAt: '2026-07-16T13:22:17.685Z'
requestedLatitude: null
requestedLongitude: null
requestedAddressLine1: 48052 Strosin Ports
requestedAddressLine2: null
requestedCity: Kshlerinport
requestedStateOrProvince: MS
requestedPostalCode: '45776'
requestedCountry: United States
latitude: '-61.6281449309'
longitude: '-24.2378401825'
requestedPropertyType: Hotel
appliedPropertyType: Hotel
relationships:
ordinanceLookupBatch:
data:
id: bf373c93-ad48-477b-98c1-8abdd08bd6ac
type: ordinanceLookupBatches
building:
data:
id: 75b40dc6-a0f4-47f4-a2e5-62064de1c664
type: buildings
ordinanceResponses:
data:
- id: a9f9f753-6712-5256-b2bd-77c921bd173e
type: ordinanceResponses
included:
- id: a9f9f753-6712-5256-b2bd-77c921bd173e
type: ordinanceResponses
attributes:
stateOrProvince: WA
censusDivision: Seattle city
longName: Seattle Council Bill 116731
shortName: Seattle
url: http://www.seattle.gov/environment/buildings-and-energy/energy-benchmarking-and-reporting
minFloorAreaInSqFt: 20000
maxFloorAreaInSqFt: null
complianceType: PERFORMANCE
startYear: 2026
annualDueDate: '2026-07-01'
createdAt: '2026-07-16T13:22:17.666Z'
updatedAt: '2026-07-16T13:22:17.687Z'
relationships:
ordinanceLookup:
data:
id: 8e16bf3c-9296-4bc3-a611-971fc1209fde
type: ordinanceLookup
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'
'404':
description: ID is not found
content:
application/vnd.api+json:
example:
errors:
- status: '404'
title: Not Found
detail: Page not found
schema:
$ref: '#/components/schemas/json_api'
/insights/v0/ordinances:
get:
summary: Returns a list of ordinances
description: 'Returns a list of all ordinances.
Coverage: United States and Canada
'
tags:
- Ordinances
security:
- OAuth2: []
responses:
'200':
description: List of ordinances
content:
application/vnd.api+json:
example:
data:
- id: a9dc5e49-03c1-5586-a904-c6521b430e2c
type: ordinances
attributes:
stateOrProvince: CA
censusDivision: null
longName: California Assembly Bill 802 Energy Efficiency
shortName: AB802
url: http://www.energy.ca.gov/benchmarking/
minFloorAreaInSqFt: 50000
maxFloorAreaInSqFt: null
complianceType: ENVIRONMENTAL
startYear: N/A
annualDueDate: '2026-06-01'
- id: 41b83771-bb89-500b-8bd9-eafc26f888cb
type: ordinances
attributes:
stateOrProvince: TX
censusDivision: Austin city
longName: Austin Energy Conservation Audit and Disclosure
shortName: Austin Commercial
url: https://austinenergy.com/ae/energy-efficiency/ecad-ordinance/energy-conservation-audit-and-disclosure-ordinance
minFloorAreaInSqFt: 10000
maxFloorAreaInSqFt: null
complianceType: PERFORMANCE
startYear: N/A
annualDueDate: '2026-06-01'
- id: 46d90f05-dbfc-5066-9bc1-15b76bcfed03
type: ordinances
attributes:
stateOrProvince: MA
censusDivision: Boston city
longName: Boston Building Energy Reporting and Disclosure
shortName: Boston
url: http://www.cityofboston.gov/eeos/reporting/
minFloorAreaInSqFt: 35000
maxFloorAreaInSqFt: null
complianceType: DISCLOSURE
startYear: N/A
annualDueDate: '2026-05-15'
meta:
totalCount: 3
itemCount: 100
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /insights/v0/ordinances
prev: null
next: null
schema:
$ref: '#/components/schemas/json_api'
'502':
description: Internal server error
content:
application/vnd.api+json:
example:
errors:
- status: '502'
title: Bad Gateway
detail: A Measurabl Server is down, please try again later
schema:
$ref: '#/components/schemas/json_api'
'403':
description: when authenticated but not authorized
content:
application/vnd.api+json:
example:
errors:
- status: '403'
title: Forbidden
detail: Access Denied
schema:
$ref: '#/components/schemas/json_api'