5 Building Queries and Exploring Data
A demonstration area can be accessed at https://api.us.opower.com/util/graphql for users who have retrieved the required credentials and account-scoped access tokens as described in Requirements and Limitations. With Access to this GraphQL Integrated Development Environment (IDE), you can begin to build your queries or mutations, and explore the available data. Along with using the IDE, you can also use curl to query the GraphQL environment.
Note:
For more information on the GraphQL standard, refer to https://graphql.orgUsing the GraphiQL IDE
GraphiQL is the IDE available for reviewing and discovering the GraphQL APIs. For information on the user interface, the link in the top-right corner of the interface redirects to the applicable Github repository that includes documentation resources on GraphiQL.
Reviewing the Schema
From the GraphiQL IDE at https://api.us.opower.com/util/graphql, you can select to Show Documentation Explorer to review the schema definition. The Documentation Explorer allows you to traverse through the schema. A search field is also available to search for schema definitions of interest.
Note:
Schema definitions can include links to Oracle and third-party resources. Be aware that navigating to these resources can redirect your active window away from the GraphiQL IDE. You can use various methods to open these resources is separate browser windows and tabs to avoid this redirection.Building a Query
The GraphiQL IDE allows you to easily build a query and expand on the query to explore available data. You can select to Show GraphiQL Explorer to display the Explorer area. This area allows you to browse through the schema and select elements to add to your query.
For example, since all queries use the
billingAccountsConnection entry point, you can select
it to include it in a new query tab. This query creation can
continue by Reviewing the Schema to learn
about subfields to include in your query, and typing in the new
elements or selecting them from the Explorer.
As you continue to build your query, the IDE validates the syntax of your query. As you complete query definitions you can confirm that your query is valid by ensuring there are no syntax errors. The GraphQL protocol uses the concepts of edges and nodes to structure the queries. Refer to third-party GraphQL documentation if you are unfamiliar with query structure and design in GraphQL.
Building a Mutation
While queries in GraphQL allow for retrieving data, mutations provide the capability of modifying data. Be aware of the following GraphQL standards related to mutations:
- Mutations and queries cannot be included in a single request. Each style of request must be done separately.
- The order of your mutations impacts the processing of the mutation. While queries are executed in parallel, mutations are executed in series to avoid update race conditions.
You can build your mutation query by Reviewing the Schema to learn about subfields to include in your mutation, and typing in the new elements or selecting them from the Explorer. The IDE validates the syntax of your query. As you complete mutation definitions you can confirm that your mutation is valid by ensuring there are no syntax errors. Refer to third-party GraphQL documentation if you are unfamiliar with mutation structure and design in GraphQL.
Running a Query or Mutation
As part of running a query or mutation, you must supply the authorization context, which is accomplished through an access token which can be done using the following methods.
Running a Query or Mutation Using Account-Scoped Access Tokens
Request an account-scoped access token from Oracle Utilities
through a service request. After retrieving an access token, the
access token must be included in the HTTP header for authorization
purposes. You can include the access token in the Headers
area when building your query, using the following syntax and
replacing the access token in the AccessToken placeholder:
Note:
Be aware that access tokens expire and no longer provide access 60 minutes after their creation.{
"Authorization": "Bearer AccessToken"
}When you are ready to run your query, you can select the Execute query option. Results are displayed directly within the IDE. After you are able to validate expected results from the query you can integrate the query into your system as required.
Running a Query or Mutation Using Utility-Scoped Access Tokens
Complete the process described in Obtaining a Utility-Scoped Access Token. Be aware that when using utility-scoped tokens, an applicable utility code and account numbers must be supplied as parameters of the query. For mutations, an applicable urn must be supplied as parameters of the mutation. A valid urn for use in mutations can be retrieved through queries on the entity to modify with a mutation. These parameters are further described in Example Queries.
Be aware that while reviewing the schema and building queries using https://api.us.opower.com/util/graphql is open to all users, running queries in this location requires account-scoped access tokens. The schema review is identical regardless of the style of access token being used. Additionally, the queries used are also identical aside from the inclusion of a utility code and account numbers, or an urn for mutations, when using utility-code access tokens. For this reason, if you plan to use utility-scoped access tokens, you can use https://api.us.opower.com/util/graphql to review the schema and build your query. To successfully run a query with utility-scoped access tokens, you must do so from https://api.us.opower.com/graphql.
Using Curl
While the GraphiQL IDE provides an easy way to browse the schema and build queries or mutations, queries or mutations can also be run using curl. This can be helpful if you are building off of a known query or mutation, or sharing a query or mutation with a collaborator to test or confirm expected results.
The basic syntax for a curl command for GraphQL is as follows:
curl '[baseURL]' \
-X [method] \
-H '[header]' \
-d '{[query]}'
Where:
-
[baseURL]is the base URL to query the GraphQL resources. The demonstration area which supports account-scoped access tokens uses a base URL ofhttps://api.us.opower.com/util/graphql. For more information on constructing the base URL, refer to:- Utility-Scoped Access Token: Refer to Constructing the Base URL.
- Account-Scoped Access Token: Refer to Constructing the Base URL.
-
[method]is the method for the query, such as POST. -
[header]can include required header information, such as supplying an access token. For information on retrieving this required access token:- Utility-Scoped Access Token: Complete the process described in Obtaining a Utility-Scoped Access Token. Be aware that when using utility-scoped tokens, an applicable utility code and account numbers, or an urn for mutations, must be supplied as parameters of the query. These parameters are further described in Example Queries.
-
Account-Scoped Access Token: Request an account-scoped access token from Oracle Utilities through a service request.
-
[query]is the query or mutation to execute against the GraphQL environment. You can build a query or mutation from scratch or use the IDE as described in Using GraphiQL to build the query or mutation.
After you are able to validate expected results from the query you can integrate the query into your system as required.
Example Queries and Mutations
The data retrieved from queries or modified from mutations requires and is based on the supplied authorization context. Methods to supply the authorization context are described in Using the GraphiQL IDE and Using Curl above.
In addition to that authorization context, the following parameters are required when using utility-scoped access tokens:
- Queries:
- accountNumbers: This parameter is an array of one or more account numbers to retrieve data for using the query.
- utilityCode: This parameter is a three or four-character code that identifies the utility. The applicable value can be confirmed by your Delivery Team.
- Mutations:
- urn: This parameter is a Uniform Resource Name, which designates the customer or account-premise edge. Refer to the Documentation Explorer for specific syntax required for urn values. A valid urn for use in mutations can be retrieved through queries on the entity to modify with a mutation.
Billing Account Example
Billing Account includes details related to the customer account including a list of service agreements, associated service points, and premise details.
Query Using Account-Scoped Access Tokens
query GetPremiseAndServiceDetails {
billingAccountsConnection {
edges {
node {
serviceAgreements {
servicePointsConnection {
edges {
node {
premise {
address {
addressLines
country
postalCode
}
}
}
}
}
ratePlan {
code
}
serviceType
}
}
}
}
}Query Using Utility-Scoped Access Tokens
Note: You must replace the
accountNumbers value with a relevant account number
for the query to provide a valid response.
query GetPremiseAndServiceDetails {
billingAccountsConnection(
accountNumbers: ["123456"]
utilityCode: "util"
) {
edges {
node {
serviceAgreements {
servicePointsConnection {
edges {
node {
premise {
address {
addressLines
country
postalCode
}
}
}
}
}
ratePlan {
code
}
serviceType
}
}
}
}
}Response
The response includes data related to the service agreements, service points, rate plans, and service types.
{
"data": {
"billingAccountsConnection": {
"edges": [
{
"node": {
"serviceAgreements": [
{
"servicePointsConnection": {
"edges": [
{
"node": {
"premise": {
"address": {
"addressLines": [
"5933 Hackett BLVD"
],
"country": "US",
"postalCode": "21784"
}
}
}
}
]
},
"ratePlan": {
"code": "D"
},
"serviceType": "GAS"
},
{
"servicePointsConnection": {
"edges": [
{
"node": {
"premise": {
"address": {
"addressLines": [
"5933 Hackett BLVD"
],
"country": "US",
"postalCode": "21784"
}
}
}
}
]
},
"ratePlan": {
"code": "R_PTR"
},
"serviceType": "ELECTRICITY"
}
]
}
}
]
}
}
}Bill Example
Bill data includes the customer's utility bill and includes a breakdown of bill segments and bill line items. Billing data can be returned for up to 25 bills in a single request. Data is available for the last two years preceding the time of the API request. If the active utility account is associated with multiple service points of the same fuel type, billed usage per service point is returned.
Query Using Account-Scoped Access Tokens
The following query uses the last pagination
technique to return the last two available bills, which can also be
thought of as the most recently received two bills.
query GetLast2Bills {
billingAccountsConnection {
edges {
node {
bills(last: 2) {
billDate
segments {
lineItems {
calculatedAmount {
currency
value
}
}
serviceQuantities {
serviceQuantity {
unit
value
}
}
}
}
}
}
}
}Query Using Utility-Scoped Access Tokens
The following query uses the last pagination
technique to return the last two available bills, which can also be
thought of as the most recently received two bills.
Note:
You must replace theaccountNumbers value with a relevant account number for the query to provide a valid response.
query GetLast2Bills {
billingAccountsConnection(
accountNumbers: ["123456"]
utilityCode: "util"
) {
edges {
node {
bills(last: 2) {
billDate
segments {
lineItems {
calculatedAmount {
currency
value
}
}
serviceQuantities {
serviceQuantity {
unit
value
}
}
}
}
}
}
}
}Response
Data and information related to the two applicable bills are provided in the response.
{
"data": {
"billingAccountsConnection": {
"edges": [
{
"node": {
"bills": [
{
"billDate": 2023-03-24,
"segments": [
{
"lineItems": [
{
"calculatedAmount": {
"currency": "USD",
"value": 185.77
}
}
],
"serviceQuantities": [
{
"serviceQuantity": {
"unit": "KWH",
"value": 1150
}
}
]
},
{
"lineItems": [
{
"calculatedAmount": {
"currency": "USD",
"value": 28.75
}
}
],
"serviceQuantities": [
{
"serviceQuantity": {
"unit": "TH",
"value": 11
}
}
]
}
]
},
{
"billDate": 2023-02-23,
"segments": [
{
"lineItems": [
{
"calculatedAmount": {
"currency": "USD",
"value": 139.84
}
}
],
"serviceQuantities": [
{
"serviceQuantity": {
"unit": "KWH",
"value": 853
}
}
]
},
{
"lineItems": [
{
"calculatedAmount": {
"currency": "USD",
"value": 31.52
}
}
],
"serviceQuantities": [
{
"serviceQuantity": {
"unit": "TH",
"value": 14
}
}
]
}
]
}
]
}
}
]
}
}
}Utility Information Example
Utility information can be returned as part of a query.
Tips Examples
Energy saving tip information and actions are available through GraphQL APIs. This includes detailed information on available tips, along with the ability to modify tip status for customers through tip actions. The examples below demonstrate how to return various tip data and update tip actions.
Multiple Tips Query Using Utility-Scoped Access Tokens
The following query returns tip data and information for the first two tips related to the provided account number.
query getTipDetails {
billingAccountsConnection(
utilityCode: "util"
accountNumbers: ["ZWzgpeKL"]
) {
edges {
node {
premisesConnection {
edges {
urn
tipsConnection (first: 2) {
edges {
node {
name
costCategory
}
}
}
}
}
}
}
}
}Multiple Tips Response
The following response is the tip data and information for the first two tips related to the provided account number. Notice there is a name field which can be used to retrieve tip data and information on a specific tip.
{
"data": {
"billingAccountsConnection": {
"edges": [
{
"node": {
"premisesConnection": {
"edges": [
{
"urn": "urn:opower:v1:account-premise:util:uuids:b87dcb80-34a7-11ef-ab76-020017084ca7,71208d75-34a7-11ef-ab76-020017084hu9",
"tipsConnection": {
"edges": [
{
"node": {
"name": "tip545_smb_install_programmable_thermostat",
"costCategory": "SMART_PURCHASE"
}
},
{
"node": {
"name": "tip503_smb_install_window_treatments",
"costCategory": "SMART_PURCHASE"
}
}
]
}
},
{
"urn": "urn:opower:v1:account-premise:bce1:uuids:b87dcb80-34a7-11ef-ab76-020017084ca7,7120ad1a-34a7-11ef-ab76-020017084hu9",
"tipsConnection": {
"edges": [
{
"node": {
"name": "tip519_smb_buy_efficient_servers",
"costCategory": "GREAT_INVESTMENT"
}
},
{
"node": {
"name": "tip516_smb_buy_energy_star_computers",
"costCategory": "SMART_PURCHASE"
}
}
]
}
}
]
}
}
}
]
}
}
}Single Tip Query Query Using Utility-Scoped Access Tokens
The following query returns tip data and information for the specified tip related to the provided account number.
query TipDetails {
billingAccountsConnection (utilityCode: "util"
accountNumbers: ["6726308534"]) {
edges {
node {
premisesConnection {
edges {
tipsConnection(id: "tip162_EV_rates") {
edges {
node {
name
costCategory
}
}
}
}
}
}
}
}
}Single Tip Response
The following response is the tip data and information for the specified tip related to the provided account number.
{
"data": {
"billingAccountsConnection": {
"edges": [
{
"node": {
"premisesConnection": {
"edges": [
{
"tipsConnection": {
"edges": [
{
"node": {
"name": "tip162_EV_rates",
"costCategory": "FREE"
}
}
]
}
}
]
}
}
}
]
}
}
}Tip Mutation Using Utility-Scoped Access Tokens
The following mutation modifies the tip action state for a
specific tip and a specific customer based on the supplied urn
value. In the example below, the tip action is modified to the
ALREADY_DO_IT state. The required urn values can be
retrieved from queries that retrieve tip data.
mutation performAction{
performTipAction(urn: "urn:opower:v1:account-premise:util:uuids:b87dcb80-34a7-11ef-ab76-020017084ca7,7120ad1a-34a7-11ef-ab76-020017084ca7"
tipId: "tip545_smb_install_programmable_thermostat",
action: ALREADY_DO_IT){
isDone
isIgnored
isSaved
allowedActions
}
}Tip Mutation Response
The following response confirms the modifications completed for
the tip action definition for the tip. In this example, modifying a
tip to the ALREADY_DO_IT state marks the tip as
done, which is confirmed with the "isDone": true
response shown below.
{
"data": {
"performTipAction": {
"isDone": true,
"isIgnored": false,
"isSaved": false,
"allowedActions": [
"SAVE",
"UNDO"
]
}
}
}Disaggregation Analysis Examples
Dissaggregated energy use and associated costs information can be retrieved as shown in the following examples.
Most Recent Bill Query Using Account-Scoped Access Tokens
The following query retrieves the disaggregated energy use and associated costs during the most recent bill.
query GetBillDisaggregation {
billingAccountsConnection(first:10) {
edges {
cursor
node {
utilityId
uuid
customerClass
bills(last:1) {
timeInterval
billDateTime
consumptionCategories {
name
ratio
cost {value, currency}
usage {value, unit}
}
}
}
}
}
}Response
Disaggregated energy use and associated costs during the most recent bill are included in the response.
{
"data": {
"billingAccountsConnection": {
"edges": [
{
"cursor": "ZTYyYjIwZjQtMmI5ZS0xMWU2LTlhYmQtZDJhNDJhNzZiMGQ2",
"node": {
"utilityId": "123456",
"uuid": "e62b20f4-2b9e-11e6-9abd-d2a42a76b0d6",
"customerClass": "RESIDENTIAL",
"bills": [
{
"timeInterval": "2024-10-04T00:00:00-04:00/2024-11-05T00:00:00-05:00",
"billDateTime": "2024-11-04T00:00:00-05:00",
"consumptionCategories": [
{
"name": "APPLIANCES",
"ratio": 0.17,
"cost": {
"value": 17.17,
"currency": "USD"
},
"usage": {
"value": 83,
"unit": null
}
},
{
"name": "ELECTRONICS",
"ratio": 0.18,
"cost": {
"value": 18.76,
"currency": "USD"
},
"usage": {
"value": 91,
"unit": null
}
},
{
"name": "LIGHTING",
"ratio": 0.05,
"cost": {
"value": 5.33,
"currency": "USD"
},
"usage": {
"value": 26,
"unit": null
}
},
{
"name": "OTHER",
"ratio": 0.1,
"cost": {
"value": 10.36,
"currency": "USD"
},
"usage": {
"value": 50,
"unit": null
}
},
{
"name": "TOTAL",
"ratio": 1,
"cost": {
"value": 70.01,
"currency": "USD"
},
"usage": {
"value": 263,
"unit": null
}
},
{
"name": "WATER_HEATING",
"ratio": 0.5,
"cost": {
"value": 18.39,
"currency": "USD"
},
"usage": {
"value": 13,
"unit": null
}
}
]
}
]
}
}
]
}
}
}Yearly Query Using Account-Scoped Access Tokens
The following query retrieves disaggregated consumption categories between November 8, 2023 and November 8, 2024.
query GetDisaggregation {
billingAccountsConnection(first:10) {
edges {
node {
utilityId
serviceAgreementsConnection(first:10) {
edges {
node {
utilityId
serviceType
consumptionCategories(timeInterval: "2023-11-08T00:00:00Z/2024-11-08T00:00:00Z") {
name
ratio
cost {value, currency}
usage {value, unit}
}
}
}
}
}
}
}
}Response
The name of the category, the ratio of total usage attributed to that category, and the total cost and energy use attributed to that category are included in the response. The query also returns the ID of the billing account and service agreement.
{
"data": {
"billingAccountsConnection": {
"edges": [
{
"node": {
"utilityId": "123456",
"serviceAgreementsConnection": {
"edges": [
{
"node": {
"utilityId": "1614570777",
"serviceType": "ELECTRICITY",
"consumptionCategories": [
{
"name": "APPLIANCES",
"ratio": 0.16,
"cost": {
"value": 87.61,
"currency": "USD"
},
"usage": {
"value": 386,
"unit": "KWH"
}
},
{
"name": "COOLING",
"ratio": 0.13,
"cost": {
"value": 72.28,
"currency": "USD"
},
"usage": {
"value": 318,
"unit": "KWH"
}
},
{
"name": "ELECTRONICS",
"ratio": 0.36,
"cost": {
"value": 198.99,
"currency": "USD"
},
"usage": {
"value": 876,
"unit": "KWH"
}
},
{
"name": "LIGHTING",
"ratio": 0.1,
"cost": {
"value": 56.51,
"currency": "USD"
},
"usage": {
"value": 249,
"unit": "KWH"
}
},
{
"name": "OTHER",
"ratio": 0.25,
"cost": {
"value": 132.18,
"currency": "USD"
},
"usage": {
"value": 581,
"unit": "KWH"
}
},
{
"name": "REFRIGERATOR",
"ratio": 0.16,
"cost": {
"value": 87.61,
"currency": "USD"
},
"usage": {
"value": 386,
"unit": "KWH"
}
},
{
"name": "TOTAL",
"ratio": 1,
"cost": {
"value": 547.57,
"currency": "USD"
},
"usage": {
"value": 2410,
"unit": "KWH"
}
}
]
}
},
{
"node": {
"utilityId": "5441650371",
"serviceType": "GAS",
"consumptionCategories": [
{
"name": "TOTAL",
"ratio": 1,
"cost": {
"value": 210.99,
"currency": "USD"
},
"usage": {
"value": 19,
"unit": "TH"
}
},
{
"name": "WATER_HEATING",
"ratio": 1,
"cost": {
"value": 210.99,
"currency": "USD"
},
"usage": {
"value": 19,
"unit": "TH"
}
}
]
}
}
]
}
}
}
]
}
}
}Bill Forecast Example
Bill forecast information can be retrieved as shown in the following example.
Upcoming Bill Forecast Query Using Account-Scoped Access Tokens
The following query retrieves the upcoming bill forecast, including forecasts for the segments of the upcoming bill.
query GetBillForecast {
billingAccountsConnection(first:10) {
edges {
node {
utilityId
uuid
customerClass
billForecast {
timeInterval
currentDateTime
estimatedUsage {value, unit}
estimatedUsageCharges {value, currency}
estimatedUsageChargesUpperBound {value, currency}
soFarUsage {value, unit}
soFarUsageCharges {value, currency}
priorYearUsage {value, unit}
priorYearUsageCharges {value, currency}
segments {
serviceAgreement {
serviceType
}
estimatedUsage {value, unit}
estimatedUsageCharges {value, currency}
estimatedUsageChargesUpperBound {value, currency}
soFarUsage {value, unit}
soFarUsageCharges {value, currency}
priorYearUsage {value, unit}
priorYearUsageCharges {value, currency}
}
}
}
}
}
}Response
The response includes energy use and costs that have been incurred so far, and also estimated energy use and costs based on projected energy use through the remaining portion of the bill period. Historical energy use and costs for the bill that occurred during the same time period in the previous year is also included.
{
"data": {
"billingAccountsConnection": {
"edges": [
{
"node": {
"utilityId": "123456",
"uuid": "e62b20f4-2b9e-11e6-9abd-d2a42a76b0d6",
"customerClass": "RESIDENTIAL",
"billForecast": {
"timeInterval": "2024-11-05T00:00:00-05:00/2024-12-03T00:00:00-05:00",
"currentDateTime": "2024-11-23T00:00:00-05:00",
"estimatedUsage": {
"value": 225,
"unit": "EI"
},
"estimatedUsageCharges": {
"value": 33,
"currency": "USD"
},
"estimatedUsageChargesUpperBound": null,
"soFarUsage": {
"value": 122,
"unit": "EI"
},
"soFarUsageCharges": {
"value": 18,
"currency": "USD"
},
"priorYearUsage": {
"value": 129,
"unit": "EI"
},
"priorYearUsageCharges": {
"value": 43,
"currency": "USD"
},
"segments": [
{
"serviceAgreement": {
"serviceType": "ELECTRICITY"
},
"estimatedUsage": {
"value": 157,
"unit": "KWH"
},
"estimatedUsageCharges": {
"value": 25,
"currency": "USD"
},
"estimatedUsageChargesUpperBound": null,
"soFarUsage": {
"value": 98,
"unit": "KWH"
},
"soFarUsageCharges": {
"value": 15,
"currency": "USD"
},
"priorYearUsage": {
"value": 72,
"unit": "KWH"
},
"priorYearUsageCharges": {
"value": 20,
"currency": "USD"
}
},
{
"serviceAgreement": {
"serviceType": "GAS"
},
"estimatedUsage": {
"value": 8,
"unit": "TH"
},
"estimatedUsageCharges": {
"value": 8,
"currency": "USD"
},
"estimatedUsageChargesUpperBound": null,
"soFarUsage": {
"value": 3,
"unit": "TH"
},
"soFarUsageCharges": {
"value": 3,
"currency": "USD"
},
"priorYearUsage": {
"value": 6,
"unit": "TH"
},
"priorYearUsageCharges": {
"value": 23,
"currency": "USD"
}
}
]
}
}
}
]
}
}
}