National Grid New York

Description: National Grid New York is part of the investor-owned utility National Grid servicing electric and gas customers in New York state.

Website: https://greenbutton.nationalgrid.com/

Utility ID: NGNY (this is the utility identifier you use in our API)

In order for you to request data from National Grid NY customers, you must register with National Grid as a third party company.

As part of their Green Button Connect My Data (GBCMD) program, National Grid is using UtilityAPI's EE/DER Engagement Platform to allow third-party companies to request data access from National Grid NY customers. Authorizations use the Green Button OAuth process, which means that third-parties have to be pre-registered with National Grid so they can be assigned a client_id.

NOTE: When you register, you will be automatically put into "sandbox" mode. This means you can only request data from test accounts, not real National Grid NY customers. After you register, National Grid will review your registration and switch you to "live" mode (you will get an email when this happens).
Register as a Third Party
(Note: National Grid's GBCMD is currently in beta)

After registering with National Grid as a third party, to request authorizations from National Grid NY customers and test accounts, you can use any of these methods:

Once a customer has authorized, you will see an Authorization appear on your dashboard and via both our JSON API and Green Button API.

When your first register as a third party, your registration status is set to Sandbox mode. This means you can only request data from test accounts, so you can try it out or start building an integration, but real customers won't be able to authorize data sharing with you yet. National Grid will review your registration, then you'll get an email letting you know that you can now switch your status to Live mode in your settings.

During the OAuth authorization flow, we by default try to authenticate National Grid NY customers via "Single Sign-On" (SSO). However, since third parties may not have a real customer account when they start, we also offer a "test account" option. Third parties can pre-select which option (SSO or test) they want their OAuth authorize request to default to by their preferred authentication choice to the scope string. In general, you'll probably only find this useful for automated testing with test accounts, since the default (SSO) is what you probably want to use for real Nation Grid customers.

Scope parameter format:
auth-{type}[-{value}]

Full scope string example with authentication option (percent encoded):
scope=FB%3D4_16_51%3BAdditionalScope%3Dauth-test-residential

Type Can Have Value? Description Scope String Example
sso No

Try to use single sign-on (OpenIDConnect) to authenticate the customer. This is the default option.

If you don't want us to automatically trying to see if the user is logged in to their National Grid account, add prompt=on to your OAuth authorize url (e.g. ...?prompt=on&client_id=...) and we'll show a screen explicitly asking the user to log in first.

auth-sso
test Yes Authenticate using a specific test scenario. auth-test-residential

Since the National Grid NY OAuth authorization flow uses their SSO system by default, that means you can't use UtilityAPI's default test usernames to manually simulate a test scenario. Instead, below we have created a special test account input page you can simulate authenticating as an National Grid NY user under various test scenarios.

When you use these test accounts, you won't get redirected to National Grid's SSO system, but instead be automatically authenticated as a test account and go straight to the OAuth authorization page.

Try one with your National Grid NY data share link
(you aren't logged into an account that has a registered National Grid NY client)

Test Account Equivalent Test Scenario Description
test_residential residential A residential customer with 2 services (both electric and gas).
test_commercial commercial A commercial customer with 4 services (both electric and gas).
test_empty empty Act as if the customer doesn't have any accounts in upstate New York
test_error utilityerror Act as if the system encountered an unexpected error

To demonstrate how you can integrate the GBC OAuth authorization process into your apps and websites, we offer a demo third party website that can be configured with any GBC client, so long as it has a specific redirect_uri added. We have also created public, sandbox-only GBC clients that you can try out (see table below).

Client ID Company Name Pre-configured Demo Link
NGNY_ccccccccc Test Company Link