API Documentation

Written by Brad Pirtle
Updated 7 months ago

Overview

This documentation explains how to integrate with Know True-Up using our API.

Technology

Our API is RESTful using JSON.  All endpoints have a base URL of:
https://api.solardatapros.com/api/v1/

Authentication

To use our API, you need to request an Api-Key and Access-Token pair from support.  These are sent with each API endpoint as headers.  If your keys are compromised, contact support for replacements.

Example usage:

curl -H 'Api-Key: KEY' -H 'Access-Token: TOKEN' 'https://api.solardatapros.com/api/v1/accounts

Formats

Responses

All responses return success which is true or false.  Additional information will be returned as message.  Example:

{"success":false,"message":"invalid api_key: KEY"}

Timestamps

All date and datetime fields will be in ISO 8601 format.  Example:
2011-11-04
2011-11-04T00:05:23


API Endpoints

GET accounts - search accounts

There are four ways to search accounts:

  1. Text based search.  The fields that are searched are: user.full_name and address.address_one.
    Example request:
    accounts?search_term=123+East+St
    Example response:
    {
      "success": true,
      "message": "", 
      "company": "Company Name", 
      "count": 1, 
      "accounts": [
        {
          "id": 0, 
          "inverter": "SolarEdge", 
          "utility": "PG&E"
          "address": {
            "address_one": "123 Easy St", 
            "address_two": "", 
            "city": "Mountain View", 
            "state": "CA", 
            "zip_code": "94043",
            "latitude": 37.3927515, 
            "longitude": -122.0682099, 
          }, 
          "user": {
            "id": 4, 
            "first_name": "Adam", 
            "last_name": "Ant", 
            "email": "easy@email.com", 
            "phone": "408-555-5555"
          }, 
        }, 
      ], 
    }
  2. Geolocation based search via latitude/longitude.  Provide a latitude/longitude pair and a distance (in miles) and we return accounts within that parameter.
    Added response include distance and geocode.
    Example request:
    accounts?geocode=37.3927515,-122.0682099&distance=2
  3. Geolocation based search via address.  Provide address (like google map search) and a distance (in miles) and we return accounts within that parameter.
    Added response include distance and geocode.
    Example request:
    accounts?address=123+Easy+St,+Mountain+View,+CA+94043&distance=2
  4. ID lookup.  This lets you get a specific account.
    Example request:
    accounts?id=0
GET intervals - get interval data for an account

Parameters: 

account_id ID of the account
date_start Start of the date range (ISO 8601
date_end End of the date range (ISO 8601, inclusive)
interval Interval length (minutes, 15 or 60)
max Return max interval only (boolean, 0 or 1)

Restrictions: supports up to 12 months per call

Example request:

intervals?account_id=0&date_start=5/1/2023&date_end=5/1/2023

Example response:

{
  "success": true, 
  "message": "", 
  "company": "Company Name", 
  "account": {
    "date_data_first": "2015-05-05T00:00:00", 
    "date_data_last": "2023-05-31T23:45:00", 
    "id": 0
  }, 
  "user": {
    "first_name": First", 
    "last_name": "Last", 
    "id": 0
  }, 
  "date_end": "2023-05-01", 
  "date_start": "2023-05-01", 
  "type": "Electricity", 
  "units": "uWh"
  "count": 24, 
  "intervals": [
    {
      "date": "2023-05-01", 
      "time_end": "01:00", 
      "time_start": "00:00", 
      "usage_in": 421200, 
      "usage_out": 0,
      "usage_net": 421200, 
    }, 
    {
      "date": "2023-05-01", 
      "time_end": "02:00", 
      "time_start": "01:00", 
      "usage_in": 402400, 
      "usage_out": 0,
      "usage_net": 402400, 
    }, 
...
    {
      "date": "2023-05-01", 
      "time_end": "00:00", 
      "time_start": "23:00", 
      "usage_in": 681300, 
      "usage_out": 0,
      "usage_net": 681300, 
    }
  ], 
}

Example "max interval" request:

intervals?account_id=0&date_start=5/1/2023&date_end=5/1/2023&max=1

Example "max interval" response:

{
  "success": true, 
  "message": "", 
  "company": "Company Name", 
  "account": {
    "date_data_first": "2015-05-05T00:00:00", 
    "date_data_last": "2023-05-31T23:45:00", 
    "id": 0
  }, 
  "user": {
    "first_name": First", 
    "last_name": "Last", 
    "id": 0
  }, 
  "date_end": "2023-05-01", 
  "date_start": "2023-05-01", 
  "type": "Electricity", 
  "units": "uWh"
  "max": {
    "value": 1940000, 
    "date": "2023-05-31T07:00:00", 
    "duration": 15
  }, 
}

Note that the max interval (minutes) is returned with whatever duration the interval data is, which is typically 15 minutes 1 hour.  To convert to "max hour":

value = (value / duration) * 60

POST users - create a user

Parameters: JSON object data

Fields:

user firstName

User first name

lastName

User last name

email

User email address

enableAccess

Allow the user to login.  A random password is auto-generated.

enableEmails

Enable weekly emails sent to user.

account phone

Account phone

addressOne

Account address one

city

Account city

state

Account state

zip

Account zip

isLead

Account is a lead (vs customer)

test 0,1

Test mode, does not create a user just returns a response

Example request:

curl -H 'Content-Type: application/json' -H 'Api-Key: KEY' -H 'Access-Token: TOKEN' -X POST -d '{"user": {"firstName": "fname", "lastName": "lname", "email": "x@t.com", "enableAccess": "0", "enableEmails": "0"}, "account": {"phone": "PHONE", "addressOne": "STREET", "city": "CITY", "state": "STATE", "zip": "ZIP", "isLead": "0"}, "test": "1"}' https://api.solardatapros.com/api/v1/users
Did this answer your question?