Asset-level building intelligence (the Insights surface): submit buildings by coordinates, address or Measurabl building id and receive modeled energy estimates, carbon estimates, green building certification lookups, local performance ordinance lookups and CRREM transition-risk lookups, individually or as asynchronous batches with CSV upload and bulk export/download.
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:
typ
# --- truncated at 32 KB (225 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/measurabl/refs/heads/main/openapi/measurabl-esgx-buildings-openapi.yml