Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Enable external data sources to be added and accessed #188

Open
wants to merge 17 commits into
base: main
Choose a base branch
from
Open

Enable external data sources to be added and accessed #188

wants to merge 17 commits into from

Conversation

fershad
Copy link
Contributor

@fershad fershad commented Jan 28, 2024 •
edited
Loading

This PR adds the Electricity Maps API as an external data sources which can be accessed within CO2.js (#134).

This change adds a new DataSource class which is exposed to users. The class has as single function set() which is used to set the data source being used.

import { dataSources } from '@tgwf/co2';
const eMaps = new dataSources().set("electricityMapsApi");

eMaps.source.authToken = "MyAuthToken"

Each data source is its own class, and can contain any number of functions which map to the structure of the external API being queried.

In the case of Electricity Maps, we use the free API endpoint and expose three functions:

  • getLatest - returns the current grid intensity for the region (zone or lat+lon) from the Electricity Maps API.
  • getHistory - returns the last 24 hours grid intensity for the region (zone or lat+lon) from the Electricity Maps API.
  • getZones - returns a list of all available zones that can be queried from the Electricity Maps API.

For example, to get the latest grid intensity for Taiwan we can:

const taiwanZoneLatest = await eMaps.source.getLatest("TW");

const taiwanLatLonLatest = await eMaps.source.getLatest(undefined, "23.6978", "120.9605");

With this update, it will also be possible for additional data sources to be added. The kinds of data sources which could be added are not just limited to grid intensity either, meaning it could be possible to add an adaptor for connecting with a service like the Boavista API (for example) to return environmental impact data for hardware and cloud devices.

@fershad fershad linked an issue Jan 28, 2024 that may be closed by this pull request
Allow developers to access real-time grid intensity data through Electricity Maps #134
Open
@fershad fershad added this to the 0.15 milestone Jan 28, 2024
@fershad
Copy link
Contributor Author

fershad commented Jan 28, 2024 •
edited
Loading

@mrchrisadams 🎉 the main files to look at for this change are:

  • src/data.js
  • src/data/external/electricityMapsApi.js

I can show you an example of this in action if you want.

@fershad
Copy link
Contributor Author

fershad commented Feb 2, 2024 •
edited
Loading

One thing I might look to change here is to pass an options object into the getLatest and getHistory functions. Right now, passing in the zone variable as undefined doesn't feel great.

So instead of:

const taiwanZoneLatest = await eMaps.source.getLatest("TW");

const taiwanLatLonLatest = await eMaps.source.getLatest(undefined, "23.6978", "120.9605");

You'd have:

const taiwanZoneLatest = await eMaps.source.getLatest({ zone: "TW" });

const taiwanLatLonLatest = await eMaps.source.getLatest({ lat: "23.6978", lon: "120.9605" });

@fershad
Copy link
Contributor Author

fershad commented Feb 2, 2024

Probably also need someone from Electricity Maps to confirm the proper API base URL we should be using here for the free tier routes.

Is it https://api-access.electricitymaps.com/free-tier/ or https://api.electricitymap.org/?

@madsnedergaard
Copy link

Probably also need someone from Electricity Maps to confirm the proper API base URL we should be using here for the free tier routes.

Is it https://api-access.electricitymaps.com/free-tier/ or https://api.electricitymap.org/?

Hey @fershad, happy to quickly answer this one - and we'd also love to jump on a call together with you guys to give more details and context if required!

We are in the process of aligning everything under the https://api.electricitymap.org/ domain to simply things :) Right now api-access.electricitymaps.com is just redirecting, so it would be best to avoid using that.

Users can get a token to use for the free tier over at https://api-portal.electricitymaps.com/.
I've also been updating our API documentation recently to explain more about what endpoints are available for the free tier tokens (although it seems like I forgot about /zones, I'll get that one added to the docs soon!):

Screenshot 2024-02-07 at 16 15 34

@madsnedergaard
Copy link

madsnedergaard commented Feb 7, 2024 •
edited
Loading

PS. We're also thinking of building SDKs for interacting with the API - would you be interested in using that if we did, or do you prefer having your own code for this? :)

PPS. This is really cool and we're super excited that you're implementing this! 😍

madsnedergaard
madsnedergaard reviewed Feb 7, 2024
View reviewed changes
src/data/external/electricityMapsApi.js
Comment on lines +88 to +90
const query = `${lat ? `lat=${lat}&` : ""}${lon ? `lon=${lon}&` : ""}${
zone ? `zone=${zone}` : ""
}`;
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how big of a deal this is, but with this current usage it's possible to call the API with both a zone and coordinates. In this case the coordinates overrule on our end :)

@fershad fershad modified the milestones: 0.15, 0.17 Apr 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@madsnedergaard madsnedergaard madsnedergaard left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
0.17
Development

Successfully merging this pull request may close these issues.

Allow developers to access real-time grid intensity data through Electricity Maps
2 participants
@fershad @madsnedergaard