Measurabl Partner API
Partner-facing surface for integration partners acting on behalf of a Measurabl customer: list portfolios, list the buildings in a portfolio, and read monthly utility data for a building.
OpenAPI Specification
openapi: 3.0.1
info:
title: Partner API V0
version: v0
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
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.measurabl.com/token
scopes: {}
paths:
/partners/v0/portfolios/{portfolio_id}/buildings:
get:
summary: Returns buildings for a portfolio
tags:
- Buildings
security:
- OAuth2: []
parameters:
- name: portfolio_id
in: path
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: portfolio with buildings found
content:
application/vnd.api+json:
example:
data:
- id: 79bc3ff6e578ecbcfc25a72006b77a78
type: buildings
attributes:
name: Test Building
customId: A_Custom_Building_ID
addressLine1: 123 Elm St
addressLine2: A
addressCity: San Diego
addressState: CA
addressZip: '92101'
addressCountry: United States
addressProvince: ''
grossFloorArea:
units: Sq. Ft.
value: 248498.0
primaryType: Hotel
isActive: true
createdAt: '2018-10-12T21:49:44.000Z'
updatedAt: '2019-06-18T22:22:21.000Z'
- id: ffd569a02bf0b1e8c5b6ca4d1c8aaf41
type: buildings
attributes:
name: testasdf
customId: Custom-ID-e05c874c-39b5-4ca0-b7e5-a9ef24a5f5b1
addressLine1: test
addressLine2: ''
addressCity: test
addressState: ''
addressZip: '9999'
addressCountry: Belgium
addressProvince: somewhere
grossFloorArea:
units: Sq. Ft.
value: 248498.0
primaryType: Hotel
isActive: false
createdAt: '2018-10-12T21:49:46.000Z'
updatedAt: '2019-06-18T22:22:21.000Z'
- id: 7ec656ba99dce1a64d3069f4981d5476
type: buildings
attributes:
name: mock-building-27192
customId: null
addressLine1: 5150 sci-test
addressLine2: ''
addressCity: Telluride
addressState: CO
addressZip: '81435'
addressCountry: United States
addressProvince: null
grossFloorArea:
units: Sq. Ft.
value: 496996.0
primaryType: Laboratory
isActive: true
createdAt: '2019-03-21T18:21:34.000Z'
updatedAt: '2019-05-22T20:05:39.000Z'
meta:
totalCount: 3
itemCount: 5
pageCount: 1
currentPage: 1
prevPage: null
nextPage: null
lastPage: 1
fromRecord: 1
toRecord: 3
links:
self: /partners/v0/portfolios/caa54ae2405bb71d14a4c992b3864337/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'
'429':
description: Too Many Requests
content:
application/vnd.api+json:
example:
errors:
- status: '429'
title: Too Many Requests
detail: Rate Limit Exceeded
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'
/partners/v0/buildings/{building_id}/monthly_utility_data:
get:
summary: monthly utility data for a building
tags:
- Buildings
security:
- OAuth2: []
parameters:
- name: building_id
in: path
required: true
schema:
type: string
- name: startDate
in: query
format: date
schema:
type: string
- name: endDate
in: query
format: date
schema:
type: string
responses:
'200':
description: sandbox environments return canned fixture data
headers:
X-startDate-Requested:
type: string
description: the startDate sent as a URL parameter
X-startDate-Applied:
type: string
description: the startDate applied based on date range restriction rules
X-endDate-Requested:
type: string
description: the startDate sent as a URL parameter
X-endDate-Applied:
type: string
description: the endDate applied based on date range restriction rules
content:
application/vnd.api+json:
example:
electricity:
years:
- year: 2018
months:
- monthNumber: 6
monthName: Jun
utilityUsage: 1959.039
- monthNumber: 7
monthName: Jul
utilityUsage: 2035.921
- monthNumber: 8
monthName: Aug
utilityUsage: 2256.677
- monthNumber: 9
monthName: Sep
utilityUsage: 2389.4350000000004
- monthNumber: 10
monthName: Oct
utilityUsage: 2309.363
- monthNumber: 11
monthName: Nov
utilityUsage: 2353.23
- monthNumber: 12
monthName: Dec
utilityUsage: 1903.2830000000004
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 1984.4865000000002
- monthNumber: 2
monthName: Feb
utilityUsage: 1792.7989999999998
- monthNumber: 3
monthName: Mar
utilityUsage: 1860.903
- monthNumber: 4
monthName: Apr
utilityUsage: 1678.2685000000001
- monthNumber: 5
monthName: May
utilityUsage: 1656.5835000000002
usageUnit: MWH
onSiteRenewableElectric:
years:
- year: 2018
months:
- monthNumber: 6
monthName: Jun
utilityUsage: 114.111
- monthNumber: 7
monthName: Jul
utilityUsage: 115.001
- monthNumber: 8
monthName: Aug
utilityUsage: 115.717
- monthNumber: 9
monthName: Sep
utilityUsage: 105.675
- monthNumber: 10
monthName: Oct
utilityUsage: 84.083
- monthNumber: 11
monthName: Nov
utilityUsage: 61.35
- monthNumber: 12
monthName: Dec
utilityUsage: 43.163000000000004
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 53.6465
- monthNumber: 2
monthName: Feb
utilityUsage: 20.999
- monthNumber: 3
monthName: Mar
utilityUsage: 37.903
- monthNumber: 4
monthName: Apr
utilityUsage: 33.8685
- monthNumber: 5
monthName: May
utilityUsage: 50.743500000000004
usageUnit: MWH
offSiteRenewableElectric:
years:
- year: 2018
months:
- monthNumber: 6
monthName: Jun
utilityUsage: 126
- monthNumber: 7
monthName: Jul
utilityUsage: 129
- monthNumber: 8
monthName: Aug
utilityUsage: 162
- monthNumber: 9
monthName: Sep
utilityUsage: 138
- monthNumber: 10
monthName: Oct
utilityUsage: 138
- monthNumber: 11
monthName: Nov
utilityUsage: 147
- monthNumber: 12
monthName: Dec
utilityUsage: 117
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 123
- monthNumber: 2
monthName: Feb
utilityUsage: 99
- monthNumber: 3
monthName: Mar
utilityUsage: 111
usageUnit: MWH
naturalGas:
years:
- year: 2018
months:
- monthNumber: 6
monthName: Jun
utilityUsage: 9205
- monthNumber: 7
monthName: Jul
utilityUsage: 2009
- monthNumber: 8
monthName: Aug
utilityUsage: 203
- monthNumber: 9
monthName: Sep
utilityUsage: 0
- monthNumber: 10
monthName: Oct
utilityUsage: 1
- monthNumber: 11
monthName: Nov
utilityUsage: 3383.4117647058824
- monthNumber: 12
monthName: Dec
utilityUsage: 2544.697610294118
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 5435.374999999999
- monthNumber: 2
monthName: Feb
utilityUsage: 7907.662176724137
- monthNumber: 3
monthName: Mar
utilityUsage: 11661.822198275862
- monthNumber: 4
monthName: Apr
utilityUsage: 19615.45866935484
- monthNumber: 5
monthName: May
utilityUsage: 16644.010080645163
usageUnit: THERMS
fuelOilNo1:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 706.5573283561122
- monthNumber: 12
monthName: Dec
utilityUsage: 433.9029241174464
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 213.30595359945414
- monthNumber: 2
monthName: Feb
utilityUsage: 835.0327209731879
- monthNumber: 3
monthName: Mar
utilityUsage: 631.3024888528099
- monthNumber: 4
monthName: Apr
utilityUsage: 390.037675680435
- monthNumber: 5
monthName: May
utilityUsage: 677.365599652216
usageUnit: THERMS
fuelOilNo2:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 1035.0807393581792
- monthNumber: 12
monthName: Dec
utilityUsage: 489.49073454151363
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 727.755035823951
- monthNumber: 2
monthName: Feb
utilityUsage: 630.2589362227791
- monthNumber: 3
monthName: Mar
utilityUsage: 798.8726400310592
- monthNumber: 4
monthName: Apr
utilityUsage: 581.5027883250239
- monthNumber: 5
monthName: May
utilityUsage: 677.6429639779443
usageUnit: THERMS
fuelOilNo4:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 1125.0860376904088
- monthNumber: 12
monthName: Dec
utilityUsage: 298.84957515503646
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 771.495809877175
- monthNumber: 2
monthName: Feb
utilityUsage: 653.4839409875411
- monthNumber: 3
monthName: Mar
utilityUsage: 724.0652849592349
- monthNumber: 4
monthName: Apr
utilityUsage: 461.1879385132235
- monthNumber: 5
monthName: May
utilityUsage: 543.8743056014132
usageUnit: THERMS
fuelOilNo5or6:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 1172.3416621510428
- monthNumber: 12
monthName: Dec
utilityUsage: 311.40179144841153
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 803.9000127942683
- monthNumber: 2
monthName: Feb
utilityUsage: 680.9314344874646
- monthNumber: 3
monthName: Mar
utilityUsage: 754.4773210567182
- monthNumber: 4
monthName: Apr
utilityUsage: 480.5586562166386
- monthNumber: 5
monthName: May
utilityUsage: 566.717998508711
usageUnit: THERMS
propane:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 856.8267806610874
- monthNumber: 12
monthName: Dec
utilityUsage: 183.28222650370282
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 280.28774309109525
- monthNumber: 2
monthName: Feb
utilityUsage: 440.3533291568137
- monthNumber: 3
monthName: Mar
utilityUsage: 324.53305774185577
- monthNumber: 4
monthName: Apr
utilityUsage: 187.86587067058477
- monthNumber: 5
monthName: May
utilityUsage: 154.05634017895468
usageUnit: THERMS
diesel:
years: []
usageUnit: THERMS
compressedNaturalGas:
years:
- year: 2018
months:
- monthNumber: 6
monthName: Jun
utilityUsage: 9205
- monthNumber: 7
monthName: Jul
utilityUsage: 2009
- monthNumber: 8
monthName: Aug
utilityUsage: 203
- monthNumber: 9
monthName: Sep
utilityUsage: 0
- monthNumber: 10
monthName: Oct
utilityUsage: 1
- monthNumber: 11
monthName: Nov
utilityUsage: 3383.4117647058824
- monthNumber: 12
monthName: Dec
utilityUsage: 2544.697610294118
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 5435.374999999999
- monthNumber: 2
monthName: Feb
utilityUsage: 7907.662176724137
- monthNumber: 3
monthName: Mar
utilityUsage: 11661.822198275862
- monthNumber: 4
monthName: Apr
utilityUsage: 19615.45866935484
- monthNumber: 5
monthName: May
utilityUsage: 16644.010080645163
usageUnit: THERMS
liquifiedNaturalGas:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 768.4736914516587
- monthNumber: 12
monthName: Dec
utilityUsage: 296.69713635316464
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 278.7670261931359
- monthNumber: 2
monthName: Feb
utilityUsage: 320.46209839835944
- monthNumber: 3
monthName: Mar
utilityUsage: 162.00811766021587
- monthNumber: 4
monthName: Apr
utilityUsage: 121.22770051456183
- monthNumber: 5
monthName: May
utilityUsage: 502.1514747733956
usageUnit: THERMS
biodieselB100:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 670.0558071163023
- monthNumber: 12
monthName: Dec
utilityUsage: 390.08715700959317
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 487.9578600177413
- monthNumber: 2
monthName: Feb
utilityUsage: 320.0499103352157
- monthNumber: 3
monthName: Mar
utilityUsage: 756.7045678500454
- monthNumber: 4
monthName: Apr
utilityUsage: 717.9290896030419
- monthNumber: 5
monthName: May
utilityUsage: 471.22138228880374
usageUnit: THERMS
biodieselB20:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 1165.425050073093
- monthNumber: 12
monthName: Dec
utilityUsage: 729.888262020561
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 741.2302270855297
- monthNumber: 2
monthName: Feb
utilityUsage: 274.7703801930677
- monthNumber: 3
monthName: Mar
utilityUsage: 783.1268453116661
- monthNumber: 4
monthName: Apr
utilityUsage: 643.6411251154683
- monthNumber: 5
monthName: May
utilityUsage: 882.1839418000254
usageUnit: THERMS
renewableDiesel:
years:
- year: 2018
months:
- monthNumber: 11
monthName: Nov
utilityUsage: 1047.9099090854356
- monthNumber: 12
monthName: Dec
utilityUsage: 859.4079107712686
- year: 2019
months:
- monthNumber: 1
monthName: Jan
utilityUsage: 864.1911770726714
- monthNumber: 2
monthName: Feb
utilityUsage: 680.3717866092543
- monthNumber: 3
monthName: Mar
utilityUsage: 893.3538735749831
- monthNumber: 4
monthName: Apr
utilityUsage: 566.7314379106549
- monthNumber: 5
monthName: May
utilityUsage: 198.
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/measurabl/refs/heads/main/openapi/measurabl-partners-openapi.yml