What is an API and why should I use it?
Getting started with the API from scratch
An API (or an Application Programming Interface) is something that allows apps (ie different pieces of software connected via the internet) to talk to each other.
Modo Energy's API allows a user to connect to our database.
To access our data using the API, you need to use a program to retrieve our data in the way that you want it. For example:
- Microsoft Excel (running on Windows)
- Postman
- Terminal (on mac or linux), using
curl - Python, or another programming language - conda is a nice way to install it
Check out how to use our API with MS Excel here
Why? I prefer data downloads!
Using Modo's data downloads page can be a great way to get the data you need to do your job. But, if you need:
- lots of data
- to regularly pull data that gets updated
- to process that data (by merging with other datasets, or filtering rows out for example),
it can be much quicker and easier to use an API.
So, rather than manually downloading it from a data downloads page, limited by the number of records the page allows, you can automatically download all of the data you need into your analysis (or update it) with a single key stroke. You could even automate this, to pull the most up-to-date data every day, or week, or month.
How to find the data you need using the API
Under the "API reference" section, you can find the list of different datasets that we have on the left hand side. Choose the one you want.
You can see all of the endpoints we have, and depending on your subscription, you'll be able to access them to pull data.
They are grouped by the origin of the dataset - for example the "Sheffield Solar" section contains all the datasets (or endpoints) from Sheffield Solar.
To access the data, you need a URL and an X-token
A URL: on the page of the specific dataset you've chosen, there are fields that can be filled in, usually to specify the dates that you want the data for. As you fill in the required fields, a URL is produced on the right hand side that will ask - or call - the API for exactly what you want.
Automatically, the right hand box will show the python code needed to query the endpoint. It's the url= field that contains the url for the endpoint - it looks like a web address!
Try it!
To try it out this, you need your API key, or X-Token, which is your account's specific access to the data. This is found under your profile on the main site, under "Developers", here. Copy and paste the x-token (which looks like a long string of numbers and letters) into the 'Header' box on the right hand side of the page, just above the box with the code in it.
Then, hit the 'try it' button!
The response box underneath will show the result of the API call. This is usually in the format of a json file (containing a lot of curly braces, { and }), and you should be able to check the the API call has worked, and see some sensible data!
What's next?
From there, you need a program on your local computer to access the data. More information is found on the making your first call page. Below is a glossary of terms we use a lot when referring to the API.
| Term | Meaning |
|---|---|
| Endpoint | The point that you connect into to access the API. Each endpoint is specific to one dataset, which are all listed in the API reference section. |
| X-Token | Your personal pass to access data. Keep this safe! This can be refreshed on your profile on the main website if needs be. Also sometimes referred to as an API key. |
| Call | A call is the instantaneous act of accessing the data. If you "make a call" you are asking your program to access the data in the API. |
| Pagination | You can only access a certain number of rows of the data per call. Pagination allows you to call "pages" of data, by making multiple calls to consecutive sections of data to eventually gather all the data you would like. How to paginate in Python is stored in the recipes section. |
The documentation pages give example code snippets in a variety of languages
To make it as easy as possible, there are various options to get starter code snippets in Python, Shell, Node, Ruby, PHP, C, C#, C++, R, Go, HTTP, Java, Javascript, etc. Get the language you'd like, and copy and paste it into an environment that can run that code (like Jupyter notebooks, for example!)
Updated 4 months ago