Fetching Related Data
Certain Verdigris APIs allow users to fetch related data while querying endpoints. This convenience feature allows a single query to gather all the information related to the requested data. For example, if set of buildings is queried through the /buildings/ route , the panels, breakers and/or circuits in those buildings may also be returned.
By default, the object retrieved through the API will include the targeted objects and basic information of related objects. With the optional include parameter, more detailed information, including second and third order relationships can also be fetched in the same query.
Example using the Buildings route
When a Building is called, included objects will appear under an included object, parallel to the returned Buildings object. For example, if 5 panels were included in the query, 5 Panel objects will be returned within an array under the included key, parallel to 'data'.
In the example below, include=panels.breakers.circuits is used. The Panels objects in the included list will include the comprehensive set of panels belonging to the Building queried. The Breakers objects in the included list will include the comprehensive set of breakers belonging to all the panels of the Building queried and so on.
{
"data": [
{
"type": "buildings",
...
},
],
"included": [
{
"type": "panels",
...
},
...
{
"type": "breakers",
...
},
...
{
"type": "circuits",
...
},
...
]
}
Example of a full return from Buildings with no include parameter
{
"data": [
{
"attributes": {
"address": "1600 Pennslyvania Avenue",
"area": 200000,
"area-unit": "square_feet",
"created-at": "null",
"industry": null,
"latitude": 38.8977,
"longitude": 77.0365,
"name": "The White House",
"slug": "the-white-house",
"timezone": "America/New_York",
"updated-at": "null"
},
"id": "643",
"relationships": {
"account": {
"data": {
"id": "486",
"type": "accounts"
}
},
"controls": {
"data": [
{
"id": "1360",
"type": "controls"
}
]
},
"panels": {
"data": [
{
"id": "897",
"type": "panels"
},
{
"id": "900",
"type": "panels"
}
]
},
"rate-schedule": {
"data": {
"id": "67",
"type": "rate-schedules"
}
},
"users": {
"data": [
{
"id": "401",
"type": "users"
}
]
}
},
"type": "buildings"
}
]
}
Example of a full return from Buildings with parameters include=panels.breakers.circuits
{
"data": [
{
"attributes": {
"address": "1600 Pennslyvania Avenue",
"area": 200000,
"area-unit": "square_feet",
"created-at": "null",
"industry": null,
"latitude": 38.8977,
"longitude": 77.0365,
"name": "The White House",
"slug": "the-white-house",
"timezone": "America/New_York",
"updated-at": "null"
},
"id": "643",
"relationships": {
"account": {
"data": {
"id": "486",
"type": "accounts"
}
},
"controls": {
"data": [
{
"id": "1360",
"type": "controls"
}
]
},
"panels": {
"data": [
{
"id": "897",
"type": "panels"
},
{
"id": "900",
"type": "panels"
}
]
},
"rate-schedule": {
"data": {
"id": "67",
"type": "rate-schedules"
}
},
"users": {
"data": [
{
"id": "401",
"type": "users"
}
]
}
},
"type": "buildings"
}
],
"included": [
{
"attributes": {
"building": {
"id": 643
},
"created-at": "2021-12-15 21:36:21",
"earth-grounded-neutral": false,
"mains": [
{
"id": 50855,
"pivot": {
"circuit_id": 50855,
"panel_id": 897
}
},
{
"id": 50856,
"pivot": {
"circuit_id": 50856,
"panel_id": 897
}
},
{
"id": 50857,
"pivot": {
"circuit_id": 50857,
"panel_id": 897
}
}
],
"name": "Panel 897",
"phases": 3,
"updated-at": "2022-05-13 19:10:33",
"voltage": 480
},
"id": "897",
"relationships": {
"breakers": {
"data": [
{
"id": "123",
"type": "breakers"
},
{
"id": "456",
"type": "breakers"
}
]
}
},
"type": "panels"
},
{
"attributes": {
"building": {
"id": 643
},
"created-at": "2021-12-15 21:36:21",
"earth-grounded-neutral": false,
"mains": [],
"name": "Panel 900",
"phases": 3,
"updated-at": "2022-05-13 19:10:33",
"voltage": 480
},
"id": "900",
"relationships": {
"breakers": {
"data": [
{
"id": "789",
"type": "breakers"
},
{
"id": "999",
"type": "breakers"
}
]
}
},
"type": "panels"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"name": "Chiller",
"size": 100,
"updated-at": "2021-09-03 21:26:08"
},
"id": "123",
"relationships": {
"circuits": {
"data": [
{
"id": "11",
"type": "circuits"
}
]
}
},
"type": "breakers"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"name": "Recepticles",
"size": 100,
"updated-at": "2021-09-03 21:26:08"
},
"id": "456",
"relationships": {
"circuits": {
"data": [
{
"id": "22",
"type": "circuits"
}
]
}
},
"type": "breakers"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"name": "Refridgerator",
"size": 100,
"updated-at": "2021-09-03 21:26:08"
},
"id": "789",
"relationships": {
"circuits": {
"data": [
{
"id": "33",
"type": "circuits"
}
]
}
},
"type": "breakers"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"name": "Pump 1",
"size": 100,
"updated-at": "2021-09-03 21:26:08"
},
"id": "999",
"relationships": {
"circuits": {
"data": [
{
"id": "44",
"type": "circuits"
}
]
}
},
"type": "breakers"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"end-use": {
"id": 66
},
"name": "Chiller (A)",
"updated-at": "2022-02-18 00:30:26"
},
"id": "11",
"relationships": {
"breaker": {
"data": {
"id": "123",
"type": "breakers"
}
},
"channels": {
"data": [
{
"id": "1",
"type": "channels"
}
]
}
},
"type": "circuits"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"end-use": {
"id": 66
},
"name": "Chiller (B)",
"updated-at": "2022-02-18 00:30:26"
},
"id": "12",
"relationships": {
"breaker": {
"data": {
"id": "123",
"type": "breakers"
}
},
"channels": {
"data": [
{
"id": "2",
"type": "channels"
}
]
}
},
"type": "circuits"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"end-use": {
"id": 66
},
"name": "Chiller (C)",
"updated-at": "2022-02-18 00:30:26"
},
"id": "13",
"relationships": {
"breaker": {
"data": {
"id": "123",
"type": "breakers"
}
},
"channels": {
"data": [
{
"id": "3",
"type": "channels"
}
]
}
},
"type": "circuits"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"end-use": {
"id": 66
},
"name": "Receptacles (A)",
"updated-at": "2022-02-18 00:30:26"
},
"id": "22",
"relationships": {
"breaker": {
"data": {
"id": "456",
"type": "breakers"
}
},
"channels": {
"data": [
{
"id": "3",
"type": "channels"
}
]
}
},
"type": "circuits"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"end-use": {
"id": 66
},
"name": "Refridgerator (B)",
"updated-at": "2022-02-18 00:30:26"
},
"id": "33",
"relationships": {
"breaker": {
"data": {
"id": "789",
"type": "breakers"
}
},
"channels": {
"data": [
{
"id": "4",
"type": "channels"
}
]
}
},
"type": "circuits"
},
{
"attributes": {
"created-at": "2021-09-03 21:26:08",
"end-use": {
"id": 66
},
"name": "Pump 1 (C)",
"updated-at": "2022-02-18 00:30:26"
},
"id": "44",
"relationships": {
"breaker": {
"data": {
"id": "999",
"type": "breakers"
}
},
"channels": {
"data": [
{
"id": "5",
"type": "channels"
}
]
}
},
"type": "circuits"
}
]
}
Updated almost 2 years ago