API Documentation

Written by Brad Pirtle

Updated 4 weeks ago

Overview

This documentation explains how to integrate with SolarFax 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:

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"
      }, 
    }, 
  ], 
}

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
```
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
```
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)
link	link_reset, link_set, link_access	Return a link: Password Reset, Password Set, or Open Access. Used to send in an email to the user. Reset and Set must also pass enableAccess. These links expire in 14 days for security purposes.
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

Example response:

{
  "success": true, 
  "message": "User 'User Name' created", 
  "action": "created", 
  "account_id": ID, 
  "user_id": ID, 
  "company": "Company Name", 
}

Did this answer your question?