Working with API and JSON in python

Python is great for automating boring, repetitive, or simple tasks. Many companies or providers offer API interfaces to help with automation or collection of large amounts of data. API stands for application programming interface. An API is basically a back end interface to a system’s data. You make a call (or request) to the system, it will will reply with an answer to your request. Every API is different and has different call formatting requirements, so review the documentation from your API provider on how to make requests.

In general, API interfaces will reply to your API request with JSON data. Again, every API is different and may use different formatting so read the documentation. JSON stands for Javascript Object Notation. JSON is just a method of formatting data. The format is designed to be both human and machine readable. You can think of it as being similar to a dictionary in python. We won’t go into the details of the formatting here, as most people really don’t need to know. There is a python library that is designed to make working with JSON data in python simple. We’ll take a look at it here.


In this tutorial we will look at interfacing with the Enphase Enlighten API to get daily solar production data from my solar panel array for the month of June 2020.

I suggest you take a quick look at the API quick start guide to get a basic overview or see the complete documentation. Making a request is simple, there is a URL defined by the API. You can make a request direct from your browser and see the result. This is helpful for getting started, figuring out the format, and troubleshooting your requests.

The lifetime energy request URL for the Enphase Enlighten API looks like this:

https://api.enphaseenergy.com/api/v2/systems/1234/energy_lifetime?start_date=2020-6-1&end_date=2020-6-30&key=XXX&user_id=YYY

In the above URL:

  • 1234 represents the solar system number. This is a unique number assigned to every Enphase solar system.
  • XXX represents the API key which is assigned to you when you sign up for an API account.
  • YYY represents your user ID for the solar system.

This is what a successful request looks like (JSON formatted):

{"system_id":1234,"start_date":"2020-06-01","production":[54029,56908,46062,26456,49264,55299,57445,57571,50769,34858,51638,58292,34013,40347,33826,52775,44136,31049,45797,55327,43593,38744,30217,42105,46967,44221,22826,37465,53342,45210],"meter_start_date":"2020-01-30","meta":{"status":"normal","last_report_at":1593609753,"last_energy_at":1593601495,"operational_at":1580399592}}

Above, we can see the system ID in the response, the start date of the data we requested, then a list of solar production (in Watt-hours) for each date in our request range. At the end there is some meta data about the system – what the operating status is, times for the last report dat and energy report date, and operational time.

If you screw up your request or the API doesn’t have the data needed, you’ll get something similar to this response:

{"reason":"401","message":["Not authorized to access requested resource."]}

Every API has it’s own error codes, so look up the error code in the API documentation if you’re having trouble.


So now we know how to make an API request using our browser, which is great and helpful, but how do we do it with python? We use the requests library.

import requests
sysID = 1234    # Replace with your system ID
startDate = '2020-6-1'
endDate = '2020-6-30'
key = XXX    # Replace with your API key
userID = YYY    # Replace with your user ID
energy = 'https://api.enphaseenergy.com/api/v2/systems/%s/energy_lifetime?start_date=%s&end_date=%s&key=%s&user_id=%s' % (sysID, startDate, endDate, key, userID)
solarData = requests.get(energy)

In the above code, we import the request library, assign the request URL to variable energy. In the URL string we use the %s placeholder for the values we need to enter. After we close the string, we use % () to tell python which strings to use in each place.

When then make the request via request.get(energy). The response is stored in the solarData variable.

That’s it, you just make an API request using python!


We now have a variable that contains the JSON data for our request. How do we easily get the data we want from the JSON info? We use the json python library.

import json
productionData = json.loads(solarData)
print(productionData)

Above, we import the json module, then use json.loads(solarData) to load the API JSON response into a python-formatted variable productionData. The result of the print command looks like this:

{'system_id': 1234, 'start_date': '2020-06-01', 'production': [54029, 56908, 46062, 26456, 49264, 55299, 57445, 57571, 50769, 34858, 51638, 58292, 34013, 40347, 33826, 52775, 44136, 31049, 45797, 55327, 43593, 38744, 30217, 42105, 46967, 44221, 22826, 37465, 53342, 45210], 'meter_start_date': '2020-01-30', 'meta': {'status': 'normal', 'last_report_at': 1593609753, 'last_energy_at': 1593601495, 'operational_at': 1580399592}}

You see it is the same data from the API JSON response, but it is formated like a python dictionary. We can access the production data using dictionary formatting:

print(productionData['production'])

Which shows us all the production data for the month of June. We can now iterate over this list, sum it, or assign it to another variable to work with.

[54029, 56908, 46062, 26456, 49264, 55299, 57445, 57571, 50769, 34858, 51638, 58292, 34013, 40347, 33826, 52775, 44136, 31049, 45797, 55327, 43593, 38744, 30217, 42105, 46967, 44221, 22826, 37465, 53342, 45210]

Here is the complete code for our python API and JSON request program:

import requests, json
sysID = 1234    # Replace with your system ID
startDate = '2020-6-1'
endDate = '2020-6-30'
key = XXX    # Replace with your API key
userID = YYY    # Replace with your user ID
energy = 'https://api.enphaseenergy.com/api/v2/systems/%s/energy_lifetime?start_date=%s&end_date=%s&key=%s&user_id=%s' % (sysID, startDate, endDate, key, userID)
solarData = requests.get(energy)
productionData = json.loads(solarData) # Now you have the data in python!

That’s it! Isn’t python great? In just a few lines of code we made a request to an API system, received in the resulting JSON data, and formatted it into something we can actually use.

You can set the above code into a for loop to iterate through each month, day, or year or modify for your own API requests.

Be careful with how quickly you make requests to the API system. Most APIs have a limit on the number requests you can make per minute and/or per month. Often, there are paid accounts for the API that allow you to make more requests.

John

Leave a Reply

Your email address will not be published. Required fields are marked *