Quickstart

If you’re completely new to Clarity Grid APIs, this quickstart guide is the perfect starting point. It covers the essentials of acquiring credentials, submitting a request, and retrieving data. Let’s dive in and get started.

To get started with using these APIs, please follow these steps:

To ensure privacy and authentication of every request to Clarity Grid APIs, it’s crucial to create a User Account. This will enable us to identify who is making the call and keep your data confidential.

After contacting us to request your account, you can expect to receive an email containing your contract information. Once you have reviewed and submitted your contract, we will provide you with your API Key and technical support contacts so you can get started.

Try out the API Live Demo

The API live demo page provides detailed information on the API endpoints, query parameters, payload and response format, and error handling. You can access the API demo by visiting Api.Claritygrid.net 

Once you’ve read the API documentation, you can begin by authenticating your session by sending your unique UUID to our login endpoint using a post request (https://map.claritygrid.net/ecservice/login). Once you have the cookie returned from the API, you will be able to make subsequent requests to the API. The parameters for our login endpoint are as follows:

Sample Payload

Below is a sample payload required by this endpoint.

{

“uu_id“: “yourapikeyhere”,

“app_group“:”API”

}

Sample Python Code

Below is a sample of Python code that can be used to authenticate using the requests and simplejson Python Libraries.

# Tariff api sample cli using python requests library

# 

# For help : jdieter@claritygrid.net

# You will need some python libs installed to run this

#    pip3 install requests

#    pip3 install simplejson

#

 

import requests

import simplejson as json

 

host = ‘https://map.claritygrid.net’

 

#login to get session (authcookie) using your api secret

url = host + ‘/ecservice/login’ 

postbody = {“uu_id”:”yourApiSecretGoesHere”,”app_group”:”API”}

header = {“content-type”: “application/json”}

response = requests.post(url,data=json.dumps(postbody),headers=header, verify=True)

authcookie=response.cookies

 

# GET ALL DISTRIBUTOR(S) FOR ISO:

# *Note – ISO values are: 1-NEISO, 2-NYISO, 3-PJM, 4-MISO, 5-CAISO, 6-SPP, 7-ERCOT, 8-SERC, 9-WECC

url = host + ‘/ecservice/api/distributors?operator_id=5’ 

header = {“content-type”: “application/json”} 

response = requests.get(url,headers=header, verify=True, cookies=authcookie)

# the next line will fail with a 401 if the auth failed

 

rsp_json = response.json()

# Print all distributors

for dist in rsp_json:

    print(dist[“name”])

    print(dist[“id”])

Once you’ve read the API documentation, you can make your first request.

We hope that these APIs will help you build innovative energy apps and products that promote energy cost transparency and savings optimization. 

If you have any questions or issues while using these APIs, please don’t hesitate to reach out to our developer support team for assistance.

Understanding the Response

The responses from our API are all formatted using JSON, or Javascript Object Notation. A sample response is provided below.

{

  “zipcode“: “10002”,

  “city_name“: “New York”,

  “state_code“: “NY”,

  “latitude“: 40.71704,

  “longitude“: -73.987,

  “distributors“: [

    {

      “id“: 2298,

      “name“: “Consolidated Edison Co. Of NY-Zone J”,

      “operator_id“: 2,

      “tariffs“: [

        {

          “consumption_id“: 2,

          “consumption_name“: “Commercial”,

          “name“: “C-9 Gen Serv -Low Tension (NYC Zone J)”,

          “id“: 12138,

          “notes“: “Low Tension Service Light, heat, and power for general uses where the Customer’s initial requirements are expected to be in excess of 10 kilowatts subject to the Common Provisions and Special Provisions of this Service Classification. energy charge is an average estimate as it is not published in the tariff Energy- Market Supply Charge Cap-NYC ($/kwh)-0,0 Energy-Merchant Function Charge ($/kwh)-0,00135 Energy – Adj Factors ($/kwh)-0,0 Total Energy ($/kwh)- from Coose Energy”

        },

      ]

    }

  ]

}

 

 

HTTP Status Codes

Our API will return standard HTTP status codes to indicate success or failure of API calls. Here is a basic summary of what we will return.

200 (Successful): This indicates that the request was successfully received, understood, and accepted.

400 (Bad Request): This indicates that there was an error in the request, such as a bad request syntax or authentication failure.

401 (Unauthorized): This indicates that the request did not have valid authorization credentials.

403 (Forbidden): This indicates that the data is private you are not allowed to access.

404 (Not Found): This indicates that the URL is wrong, or the requested information does not exist.

500 (Server Error): This could be caused by a variety of reasons such as a programming error, a database connection failure, or server configuration problems. Please contact us for assistance.

503 (Service Unavailable): Our API is down.