The Enlighten Systems API

The Enlighten Systems API is a JSON-based API that provides access to performance data for a PV system. By using the Enlighten Systems API, you agree to the Enphase Energy API License Agreement.

Please note that the Enlighten Systems API does not provide performance data at a panel or microinverter level.

Versioning

API calls go to

https://api.enphaseenergy.com/api/v2

Enlighten supports up to two versions of the API at any given time. Compatible changes do not result in a change to the version number. New releases (due to incompatible changes) are communicated well in advance of removing the older one.

Throttling

All API requests, regardless of version, are throttled according to the limits of the application plan you chose when signing up for an account. If a request is rejected because one of these limits has been exceeded, the response includes information about why the request was rejected:

< HTTP/1.1 409 Conflict
< Content-Type: application/json; charset=utf-8
< Status: 409
< { "reason": "409", "message": ["Usage limit exceeded for plan Watt"], "period": "minute", "period_start": 1401742440, "period_end": 1401742500, "limit": 10}

“period” tells you how long to wait. Application plans have “minute” and “month” limits. “period_start” and “period_end” tell you when the minute (in this case) started and when it will end. After period_end, you can make another request. “limit” is how many requests are allowed per period.

In some extreme cases, you may receive a 503 error instead of a 409. This indicates that you have made too many concurrent requests. Reduce the number of concurrent threads in your application in order to avoid this response code.

Request Parameters

The API accepts a number of parameters. Parameter order does not matter in any request. Unrecognized parameters are ignored. Clients of the API are expected to do the same: Be order-agnostic, and ignore unknown response values.

The API Key and User ID

All API requests require your API key and a user_id. Examples in this documentation exclude the API key and the user_id for clarity. However, each request must include them both. For example, if your API key is 123ABC and you are making a request for user_id 4d6a51330a, your requests would look like the following:

https://api.enphaseenergy.com/api/v2/systems?key=123ABC&user_id=4d6a51330a
https://api.enphaseenergy.com/api/v2/systems/1657/energy_lifetime?start_date=2014-03-14&key=123ABC&user_id=4d6a51330a

To learn more about user_ids, see the Quick Start page.

Request Headers

The Enlighten Systems API returns JSON. If you do not want to accept all content types, specify JSON only:

Accept: application/json

Dates and Times in Requests and Responses

Endpoints that receive dates expect the format YYYY-mm-dd. All dates are in the timezone of the requested system. Attributes that are dates are named accordingly (e.g., “summary_date”, “start_date”, “end_date”).

Endpoints that receive times expect the time to be expressed in Unix epoch time. Attributes that are times are named accordingly (e.g., “operational_at”, “last_report_at”, “start_at”, “end_at”).

You may change the format of returned date and time values by passing the query parameter datetime_format on any endpoint that returns date or time values; for example,

https://api.enphaseenergy.com/api/v2/systems/123/stats?datetime_format=iso8601

Valid values for datetime_format are iso8601 and epoch. The iso8601 format returns all temporal values, whether dates or times, in an ISO 8601 time format including timezone offset; for example 2015-05-05T00:00:00-07:00 is midnight on 5 May, 2015, in Pacific Daylight Time. The epoch format returns all temporal values in Unix epoch time. For example, midnight on 5 May, 2015, in Pacific Daylight Time is 1430809200.

Callbacks

All requests support an optional “callback” parameter. When this parameter is provided, the returned JSON is wrapped in the callback. Examples in this document exclude the callback parameter for clarity. However, each request may optionally include it. For example, a request to

https://api.enphaseenergy.com/api/v2/systems?callback=my_method

would return

my_method(
  {"systems":[
    {"system_id":67,
     "system_name":"Eich Residence",
     "system_public_name":"Eich Residence",
     "status":"normal",
     "timezone":"America/Los_Angeles",
     "country":"US",
     "state":"CA",
     "city":"Sebastopol",
     "postal_code":"95472",
     "connection_type":"ethernet"},
    {"system_id":71,
     "system_name":"Sample Residence",
     "system_public_name":"Sample Residence",
     "status":"normal",
     "timezone":"America/Los_Angeles",
     "country":"US",
     "state":"CA",
     "city":"Los Altos",
     "postal_code":"94022",
     "connection_type":"ethernet"}]
  }
)

Attribution Requirements

If you have subscribed to a plan marked “Enphase attribution required”, you must meet the following requirements as explained in the Enphase API License Agreement. If you are not sure how to meet these requirements, please contact api@enphase.com before you launch anything. We are available to look at live beta sites, screenshots or ad-hoc apps to help guide your development.

  1. Wherever you display information from the API, you’ll also need to display the “Enphase Energy” logo in a location that makes it obvious that the information originates from Enphase Energy’s Enlighten software. Download the logo.
  2. Immediately to the left of or above the mark, you must display the words “Powered by” in a clear and conspicuous manner and in a minimum eight-point font.
  3. If your application does not allow for you to include an image, you must include the text “Powered by Enphase Energy”.
  4. The image or text must link to http://enphase.com.
  5. Do not “nofollow” your links to Enphase. Any link back to Enphase should be follow-able.
  6. Do not alter our logo and/or graphics.
  7. Do not violate the other restrictions described in the Enphase API License Agreement.

Systems API Calls

energy_lifetime

Returns a time series of energy produced on the system over its lifetime. All measurements are in Watt hours.

The time series includes one entry for each day from the start_date to the end_date. There are no gaps in the time series. If the response includes trailing zeroes, such as [909, 4970, 0, 0, 0], then no energy has been reported for the last days in the series. You can check the system’s status in the “meta” attribute of the response to determine when the system last reported and whether it has communication or production problems.

If the system has a meter, the time series includes data as measured by the microinverters until the first full day after the meter has been installed, when it switches to using the data as measured by the meter. This is called the “merged time series.” In addition, the response includes the attribute “meter_start_date”, to indicate where in the time series the meter measurements begin to be used. You can retrieve the complete time series from the meter and from the microinverters by adding the parameter production=all to the request.

Sample Requests

GET https://api.enphaseenergy.com/api/v2/systems/66/energy_lifetime
GET https://api.enphaseenergy.com/api/v2/systems/123/energy_lifetime?start_date=2013-01-01&end_date=2013-01-06
GET https://api.enphaseenergy.com/api/v2/systems/123/energy_lifetime?start_date=2013-01-01&end_date=2013-01-06&production=all
start_date
The date on which to start the time series. Defaults to the system’s operational date.
end_date
The last date to include in the time series. Defaults to yesterday or the last day the system reported, whichever is earlier.
production
When “all”, returns the merged time series plus the time series as reported by the microinverters and the meter on the system. Other values are ignored.

Sample Response

{
  "system_id": 66,
  "start_date": "2013-01-01",
  "meter_start_date": "2013-02-15",
  "production": [15422,15421,17118,18505,18511,18487,...],
  "meta": {"status": "normal", "last_report_at": 1445619615, "last_energy_at": 1445619033, "operational_at": 1357023600}
}
start_date
When no start_date parameter is specified on the request, this is the operational_date of the system. May be null if system has never produced. When a start_date parameter is included in the request, it is included here in the response.
system_id
The identifier of the system.
production
An array of production measurements, one for each day since the system started producing, or one for each day of the requested period. If the system has never produced energy, the array may be empty.
meter_start_date
The first day in the time series when measurements are taken from a meter instead of from microinverters. This field is not present unless the system has a meter.
meta
Information about the system that you can use to ascertain the timeliness of the production data included in the response.

When the query parameters include “production=all”, returns meter and microinverter-measured time series:

{
  "system_id": 66,
  "start_date": "2013-01-01",
  "meter_start_date": "2013-01-04",
  "production": [15422,15421,17118,18505,18511,18487,...],
  "micro_production": [15422,15421,17118,18513,18520,18494,...],
  "meter_production": [0,0,11388,18505,18511,18487,...],
  "meta": {"status": "normal", "last_report_at": 1445619615, "last_energy_at": 1445619033, "operational_at": 1357023600}
}

envoys

Returns a listing of all active Envoys currently deployed on the system.

Sample request

GET https://api.enphaseenergy.com/api/v2/systems/67/envoys
GET https://api.enphaseenergy.com/api/v2/systems/67/envoys?datetime_format=iso8601

Sample response

{
  "system_id": 67,
  "envoys": [
    {
      "envoy_id": 512,
      "last_report_at": 1308008107,
      "name": "Envoy 010731000003",
      "part_number": "800-00002-r00",
      "serial_number": "010731000003",
      "status": "normal"
    },
    {
      "envoy_id": 841,
      "last_report_at": null,
      "name": "Envoy 010814000001",
      "part_number": "910-10000-r01",
      "serial_number": "010814000001",
      "status": "normal"
    }
  ]
}

Each response includes the following:

system_id
The identifier of the system.
envoys
A list of active Envoys on this system.

Each envoys element includes the following:

envoy_id
The Enlighten ID of the Envoy.
last_report_at
The last time this Envoy submitted a report, by default expressed in Unix epoch time. When the datetime_format query parameter is iso8601, last_report_at is in ISO 8601 format.
If Enlighten has no record of a report from this Envoy, returns null.
name
The human-friendly name of this Envoy.
part_number
The Enphase part number of this Envoy.
serial_number
The serial number of this Envoy.
status
The current status of this Envoy. May be a) “normal” – the Envoy is operating normally or b) “comm” – The Envoy is not communicating to Enlighten.

index

Returns a list of systems for which the user can make API requests. There is a limit to the number of systems that can be returned at one time. If the first request does not return a full list, use the ‘next’ attribute in the response body to request the next page of systems. By default, systems are returned in batches of 100. The maximum page size is 1000.

You may pass a ‘limit’ parameter to the request, which sets the page size for that request. Example:

/api/v2/systems?next=4d5467784d5445770a&limit=10

It is possible to request a subset of the systems list. For example,

/api/v2/systems?status=power

returns systems that currently have production issues. You can include more than one value to search for:

/api/v2/systems?status[]=comm&status[]=micro

returns systems that currently have Envoy or microinverter communication issues. Note that the parameter name must include [] after it in order to indicate that it is a multi-valued query parameter. String attributes must be URL-encoded.

Filtered requests are also paginated:

/api/v2/systems?status[]=comm&status[]=micro&next=4d5467784d5445770a

You may filter on the following attributes: system_id, system_name, status, reference, installer, connection_type. When the filter is reference, both reference and other_references are searched.

When the filter is system_name, the results include all systems whose name includes the requested substring; for example, given the following system names

 
Smith Residence
John Doe Residence
Green Valley Community Center
John and Jane Green's PV Installation

The filter ?system_name=Green would return

 
Green Valley Community Center
John and Jane Green's PV Installation

Queries on system_name and reference are case-insensitive.

Sample request

GET https://api.enphaseenergy.com/api/v2/systems

Sample response

 
{
  "systems": [
    {
      "system_id": 67,
      "system_name": "Eich Residence",
      "system_public_name": "Eich Residence",
      "status": "normal",
      "timezone": "America/Los_Angeles",
      "country": "US",
      "state": "CA",
      "city": "Sebastopol",
      "postal_code": "95472",
      "connection_type": "ethernet",
      "meta": {"status": "normal", "last_report_at": 1445619615, "last_energy_at": 1445619033, "operational_at": 1357023600}
    },
    {
      "system_id": 72,
      "system_name": "Sample Residence",
      "system_public_name": "Sample Residence",
      "status": "normal",
      "timezone": "America/Los_Angeles",
      "country": "US",
      "state": "CA",
      "city": "Placerville",
      "postal_code": "95667",
      "connection_type": "ethernet",
      "meta": {"status": "comm", "last_report_at": 1449959488, "last_energy_at": 1449945104, "operational_at": 1418912581}
    }
  ],
  "next": "4e7a453d0a"
}

Each response includes the following:

systems
A list of systems.
next
The cursor into the next page of results, if any.

Each system element includes the following:

system_id
The Enlighten ID of the system.
system_name
The name of the system. Even if the system owner has indicated their site is anonymous for public lists, the actual system name is returned here for identification purposes.
system_public_name
The display name of the system. Use this when displaying the system name on a public list or view.
reference
If the calling user belongs to a company and that company has provided its own identifer for a system, that ID is included here. Otherwise, this attribute is not returned.
other_references
If any other companies have provided their own identifers for a system, those identifiers are included here. Otherwise, this attribute is not returned.
country
The two-letter code for the country where the system is located. See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for reference.
state
The two-letter code for the state where the system is located. See http://en.wikipedia.org/wiki/ISO_3166-2 for reference.
city
The name of the city where the system is located.
postal_code
The postal code where the system is located.
timezone
The timezone of the system.
connection_type
How the system is connected to the Internet. Possible values are “ethernet”, “cellular”, and “wifi”.
status
The current status of the system. DEPRECATED: You can find this and more in the “meta” property.
meta
Information about the system that you can use to ascertain the timeliness of the production data included in the response.

Return values for status include the following, and are listed in priority order:

comm
One or more Envoys on the system are not communicating to Enlighten.
power
There is a production issue on the system.
meter
There is a communication problem between an Envoy and a revenue-grade meter on the system.
meter_issue
One or more meters on the system are reporting unusual measurements.
micro
There is a communication problem between an Envoy and microinverters that it monitors.
battery
There is a communication problem between an Envoy and an AC battery on the system.
storage_idle
An AC battery on the system has not changed its state of charge for more than 72 hours.
normal
The system is operating normally.

inventory

Returns a listing of active devices on the given system. A device is considered active if it has not been retired in Enlighten. “Active” does not imply that the device is currently reporting, producing, or measuring energy.

Sample request

GET https://api.enphaseenergy.com/api/v2/systems/1765/inventory

Sample response

{ "system_id":1765,
  "inverters": [
     {"sn": "123456789123", "model": "M215"},
     {"sn": "123455589199", "model": "M215"}
  ],
  "meters": [
     {"sn": "999111222333", "manufacturer": "GE", "model": "I-210+"}
  ]
}

Response values

system_id
Enlighten ID for this system.
envoys
A list of Envoys on this system, including serial number.
inverters
A list of inverters on this system, including serial and model numbers.
meters
A list of meters on this system, including serial number, manufacturer, and model number.

Note: If a system does not include a given device type, that key is left out of the returned hash.

monthly_production

Returns the energy production of the system for the month starting on the given date. The start date must be at least one month ago. If a meter or meters are installed on the system, measurements come from the meter; otherwise, measurements come from the microinverters.

This endpoint can return a response of Data Temporarily Unavailable. In that case, the response code is 500 and the response body is

{'errorCode': 7, 'errorMessages':['Data temporarily unavailable.']}

Sample requests

GET https://api.enphaseenergy.com/api/v2/systems/66/monthly_production?start_date=2011-07-01
GET https://api.enphaseenergy.com/api/v2/systems/66/monthly_production?start_date=2011-06-20
GET https://api.enphaseenergy.com/api/v2/systems/66/monthly_production?start_date=2011-06-20&datetime_format=epoch
start_date
Start date for reporting period. The reporting period ends on the previous day of the next month; for example, a start_date of 2011-07-20 returns data through 2011-06-19. When the start_date is the first of a calendar month, the end end date is the last day of that month.

Sample response

{
  "system_id": 66,
  "start_date": "2011-07-01",
  "end_date": "2011-07-31",
  "production_wh": 208435,
  "meter_readings": [{"serial_number": "123123123123", "start": 196077, "end": 404512}],
  "meta": {"status": "normal", "last_report_at": 1445619615, "last_energy_at": 1445619033, "operational_at": 1357023600}
}
system_id
Enlighten ID for this system.
start_date
First day included in the reporting period. The format is YYYY-mm-dd unless you pass a datetime_format parameter as described here.
end_date
Last day included in the reporting period.
production_wh
Total production for the requested period in Watt hours.
meter_readings
If the system has any revenue-grade meters installed, the meter readings at the beginning and end of the reporting period are included here. Otherwise, the array is empty.
meta
Information about the system that you can use to ascertain the timeliness of the production data included in the response.

rgm_stats

Returns performance statistics as measured by the revenue-grade meters installed on the specified system. If the total duration requested is more than one month, returns one month of intervals. Intervals are 15 minutes in length and start at the top of the hour.

Requests for times that do not fall on the 15-minute marks are rounded down. For example, a request for 08:01, 08:08, 08:11, or 08:14 is treated as a request for 08:00. Intervals are listed by their end dates; therefore, the first interval returned is 15 minutes after the requested start date.

If the system doesn’t have any revenue-grade meters installed, the response includes an empty intervals array.

Under some conditions, data for a given period may be temporarily unavailable. When this condition is detected, the response code is 500 and the response body is:

{'errorCode': 7, 'errorMessages': ['Data temporarily unavailable.']}

Sample request

GET https://api.enphaseenergy.com/api/v2/systems/1765/rgm_stats
GET https://api.enphaseenergy.com/api/v2/systems/1765/rgm_stats?start_at=1381474800&end_at=1381561200
start_at
Start of period to report on in Unix epoch time. If no start is specified, the assumed start is midnight today, in the timezone of the system. If the start is earlier than one year ago, the response includes an empty intervals list. If the start is earlier than the system’s operational_date, the response data begins with the first interval of the operational_date.
end_at
End of reporting period in Unix epoch time. If no end is specified, defaults to the time of the request. If the end is later than the last reported interval the response data ends with the last reported interval.

Sample response

{
  "system_id": 1765, 
  "total_devices": 1, 
  "meta": {"status": "normal", "last_report_at": 1445619615, "last_energy_at": 1445619033, "operational_at": 1357023600},
  "intervals":[
    {"end_at": 1384122700, "wh_del": 0, "devices_reporting": 1},
    {"end_at": 1384123600, "wh_del": 0, "devices_reporting": 1},
    {"end_at": 1384124500, "wh_del": 15, "devices_reporting": 1},
    {"end_at": 1384125400, "wh_del": 21, "devices_reporting": 1},
    {"end_at": 1384126300, "wh_del": 34, "devices_reporting": 1}
  ]
}
system_id
Enlighten ID for this system.
total_devices
Number of active revenue-grade meters for this system.
meta
Information about the system that you can use to ascertain the timeliness the production data included in the response.
intervals
A list of intervals between the requested start and end times.

Each interval includes the following:

end_at
End of interval. The format is Unix epoch time unless you pass a datetime_format parameter as described here.
wh_del
Energy delivered during this interval, in Wh.
devices_reporting
Number of revenue-grade meters that reported data for this interval at the time of the request.

stats

Returns performance statistics for the specified system as reported by microinverters installed on the system. If the total duration requested is more than one day, returns one day of intervals. Intervals are 5 minutes in length and start at the top of the hour.

Requests for times that do not fall on the 5-minute marks are rounded down. For example, a request for 08:01, 08:02, 08:03, or 08:04 is treated as a request for 08:00. Intervals are listed by their end dates; therefore, the first interval returned is 5 minutes after the requested start date.

The response includes intervals that have been reported for the requested period. Gaps in reporting are not filled with 0-value intervals. The dark hours on a system are an example of such a gap, because the microinverters do not produce at night.

Sometimes a request cannot be processed because the requested dates are invalid for the the system in question. Examples include asking for stats starting at a time that is later than the system’s last reported interval, or asking for stats before a system has started production. In cases such as these, the response code is 422 and the response body includes an error reason as well as the parameters used to process the request.

If the system doesn’t have any microinverters installed, the response includes an empty intervals array. Under some conditions, data for a given period may be temporarily unavailable. When this condition is detected, the response code is 500 and the response body is:

{'errorCode': 7, 'errorMessages': ['Data temporarily unavailable.']}

Sample request

GET https://api.enphaseenergy.com/api/v2/systems/[system_id]/stats
GET https://api.enphaseenergy.com/api/v2/systems/[system_id]/stats?start_at=1381496100&end_at=1381497600
start_at
Start of reporting period in Unix epoch time. If no start is specified, defaults to midnight today, in the timezone of the system. If the start date is earlier than one year ago today, the response includes an empty intervals list. If the start is earlier than the system’s operational_date, the response data begins with the operational_date.
end_at
End of reporting period in Unix epoch time. If no end is specified, the assumed end is now. If the end is later than the last reporting interval the response data ends with the last reported interval.

Sample response

{
  "system_id":1765, 
  "total_devices":31, 
  "meta": {"status": "normal", "last_report_at": 1445619615, "last_energy_at": 1445619033, "operational_at": 1357023600},
  "intervals":[
    {"end_at":1381496400, "powr":173, "enwh":14, "devices_reporting":27},
    {"end_at":1381496700, "powr":258, "enwh":22, "devices_reporting":31},
    {"end_at":1381497000, "powr":308, "enwh":26, "devices_reporting":31},
    {"end_at":1381497300, "powr":386, "enwh":32, "devices_reporting":31},
    {"end_at":1381497600, "powr":476, "enwh":40, "devices_reporting":31}
  ]
}
system_id
Enlighten ID for this system.
total_devices
Number of active microinverters for this system.
meta
Information about the system that you can use to ascertain the timeliness the production data included in the response.
intervals
A list of intervals between the requested start and end times.

Each interval includes the following:

end_at
end date for interval. The format is Unix epoch time unless you pass a datetime_format parameter as described here.
powr
average power produced by microinverters during this interval, measured in Watts.
enwh
energy produced by microinverters during this interval, measured in Watt hours.
devices_reporting
number of microinverters that reported data for this interval at the time of the request.

summary

Returns summary information for the specified system.

Sample requests

GET https://api.enphaseenergy.com/api/v2/systems/[system_id]/summary
GET https://api.enphaseenergy.com/api/v2/systems/[system_id]/summary?summary_date=2010-09-17
summary_date
Start of reporting period. If no summary_date is provided, the start is the current day at midnight site-local time. Otherwise, the start is midnight site-local time of the requested day. If the requested date cannot be parsed or is in the future, the response includes an informative error message and 422 status.

Sample response

{
  "current_power": 3322,
  "energy_lifetime": 19050353,
  "energy_today": 25639,
  "last_interval_end_at": 1380632400,
  "last_report_at": 1380632791,
  "modules": 31,
  "operational_at": 1201362300,
  "size_w": 5250,
  "source": "microinverters",
  "status": "normal",
  "summary_date": "2014-01-06",
  "system_id": 123
}
current_power
Current power production, in Watts. For historical requests, returns 0.
energy_lifetime
Energy produced in the lifetime of the system, excluding the requested day, in Watt hours.
energy_today
Energy produced on the requested day, in Watt hours.
last_interval_end_at
The last known time that the system produced energy. When a system has not been communicating for a length of time, the last_report_at can be recent, whereas the last_interval_end_at may be further back.
last_report_at
The last time an Envoy on this system reported. The format is Unix epoch time unless you pass a datetime_format parameter as described here.
modules
Number of active (not retired) modules. For historical requests, returns 0.
operational_at
The time at which this system became operational. Corresponds to the system’s interconnect time, if one is specified. Otherwise, it is the system’s first interval end time. The format is Unix epoch time unless you pass a datetime_format parameter as described here.
size_w
The size of the system, measured in Watts. For historical requests, returns 0.
source
Indicates whether the production of this system is measured by its microinverters
(microinverters) or by revenue-grade meters (meter) installed on the system.
status
The current status of the system, even for historical requests.
summary_date
Effective date of the response. For historical requests, returns the date requested. For current requests, returns the current date. The format is YYYY-mm-dd unless you pass a datetime_format parameter as described here.
system_id
The Enlighten ID of the system.