Badge request: Offset Earth for carbon offset/trees

[owenvoke]

:clipboard: Description

I was thinking of opening a pull request for Offset Earth badges. I know that they are not currently a service that is used widely by developers, however with projects such as Treeware I think that this may become more popular.

I was thinking that to start with this could be two badges, one for the Carbon Offset in tonnes, and one for the number of Trees for an account.

Badge previews (plain text):

• carbon offset | 5.2 tonnes
• trees | 250

Badge previews (image):

:link: Data

The data can be retrieved from their API, however I am awaiting confirmation whether this is ok to use from their developers on Twitter.

The requests do not require an API key, and there don't appear to be docs (although I think there are for businesses?).

:microphone: Motivation

I think that this would be beneficial for companies and users who support Treeware or want to help the environment in general.

I have already created the necessary services for this on a development branch, if people are interested in adding these badges I will open a PR. https://github.com/badges/shields/compare/master...owenvoke:feature/offset-earth

[PyvesB]

Hi @owenvoke , thanks for opening this issue on the repository. Our badge guidelines do state the following:

Shields.io hosts integrations for services which are primarily used by developers or which are widely used by developers

However, as said on Twitter, I think we should consider your suggestion anyway. Given the negative impact that part of our industry is having, I like the idea of Shields supporting some more socially responsible initiatives. We've already got a great example of this in our codebase, i.e. our Wheelmap badges.

What do other maintainers think? Should we make another exception here?

[paulmelnikow]

A rationale for including Wheelmap is that it can be used for developer events. Can we say something similar here? e.g. can Offset Earth be used on software projects?

[alexpricedev]

Hello! Alex here from Offset Earth 👋

Just thought I'd chime in and say that it's all good to use our API. Here are the three endpoints I suspect you'll be interested in:

Tree total

GET https://public.offset.earth/users/<username>/trees
=> JSON { total: number }

Carbon offset total

GET https://public.offset.earth/users/<username>/carbon-offset
=> JSON { total: number }

Both trees & carbon offset

GET https://public.offset.earth/users/<username>/impact
=> JSON { trees: number, carbonOffset: number }

You can use my username alex to test if you need. Hope that helps!

[owenvoke]

Aha! Brilliant, I did find a /trees endpoint before but it just returned 0, so I thought I'd use /profile.

I've refactored the code to use those endpoints, which simplifies the code a lot as there is no longer a nested loop. Thank you @remotealex 😀

[owenvoke]

I've just realised that this can be quite easily done using the custom endpoint badges, but the built in badge URIs are obviously much nearer.

• 
• 

Maybe that would be better. 🤔

[PyvesB]

A rationale for including Wheelmap is that it can be used for developer events. Can we say something similar here? e.g. can Offset Earth be used on software projects?

@owenvoke linked to Treeware in the initial post, which is basically "software distributed on the condition that you buy a tree through Offset Earth". I'm wondering whether there are other initiatives like this?

https://github.com/freshbitsweb/laravel-log-enhancer uses Treeware for example. @owenvoke do you know if there's a way to determine how many trees that specific software package has planted?

[alexpricedev]

@PyvesB We (Offset Earth) are currently working with @jamesmills (Treeware), to find a simple way for each package to have it's own "total number of trees planted". We've got a few good ideas, I'm not sure how long it will take to get them into prod. Maybe sometime next week.

[jamesmills]

Howdy people!

I’m absolutely over the moon that this conversation is happen.

I’m the maintainer of https://treeware.earth and my initial attempt at a badge was to just come up with some sort of hacked together badge. My dream was always to have this badge with a tree count so thank you all for working to make my dream come true!

I’m currently thinking of a way for us to track the number of trees a specific package has contributed to the Treeware forest on Offset Earth. We have a few ideas and I’m hoping to hack on them this week.

The ideal would be to offer the maintainers of the packages the ability to add a badge to show the number of trees their specific package has contributed. Maybe there would also be a total treeware.earth count available too? I’m just not sure how to do it right now.

My current thinking is to track links to Offset Earth through treeware.earth/click and send a hashed vendor & package name through to Offset Earth as a referrer reference. I guess we could also look at using this for the badges for Treeware packages.

I can add more info/links etc to the website as needed.

Would welcome your thoughts.

[PyvesB]

The ideal would be to offer the maintainers of the packages the ability to add a badge to show the number of trees their specific package has contributed.

Definitely. Such a badge would fit within our guidelines and would be a good candidate for Shields IMO.

Maybe there would also be a total treeware.earth count available too? I’m just not sure how to do it right now.

That's already possible through the API described by @remotealex (https://public.offset.earth/users/treeware/trees) and you can actually already hit the endpoint badge as pointed out by @owenvoke: https://img.shields.io/badge/dynamic/json?color=brightgreen&label=trees&query=%24.total&url=https%3A%2F%2Fpublic.offset.earth%2Fusers%2Ftreeware%2Ftrees

My current thinking is to track links to Offset Earth through treeware.earth/click and send a hashed vendor & package name through to Offset Earth as a referrer reference. I guess we could also look at using this for the badges for Treeware packages.

This sounds like a good idea! If we can then query the Offset Earth API using that referrer reference, it should be easy to tweak @owenvoke's existing work and we can then integrate it in Shield's main codebase, rather than going through the endpoint badge mentioned above.

[calebcartwright]

I'm a 👍 on including these badges within Shields since there's a connection and relevance for developers/technologists

[owenvoke]

If this API is implemented, I'd love to update the work I've done so far. 👍 That would be great.

[jamesmills]

Offset Earth Shield

@owenvoke I think what you have done for Offset Earth is great.

I think you could merge that into Shields now and people could make use of that. I will be able to communicate to the people who use Treeware so they can use it on their README if they want to show the total number of trees the Treeware community have planted.

/offset-earth/trees/:owner -> /offset-earth/trees/treeware

I am sure that @remotealex would also love to be able to share this with the Offset Earth community as I am sure there are some people who are planting trees to their personal profile and not currently using Treeware.

Treeware Shield

With regards to Treeware. I would love to come up with something similar to what you have done for Offset.

/treeware/trees/:user/:repo

For this to work, I will need to continue discussions with @remotealex. We would need to be able to pass the :user and :repo through to their website so that if/when people buy trees we would have a way to attribute those to the repo. We would then need them to open up a new API endpoint for us to be able to get the tree count.

[philsturgeon]

This would be great!! 🥳

[jamesmills]

@owenvoke, thank you for your time on this so far. I really appreciate it and I think we are close to something final now.

You have already detailed information about an Offset Earth badge in your initial comment on this issue. Everything you have there can remain the same.

In addition, we have now done some work for Treeware so that we can track the number of trees which have come from referral links from specific packages.

It would be amazing to have a badge like this /treeware/trees/:owner/:package and you can get the tree count for that package by calling https://public.offset.earth/users/treeware/trees?ref={hash} where the {hash} is md5(Str::lower($owner . '/' . $package)))

Would this work?

[owenvoke]

Sorry for the delayed reply. That sounds great, and I'd be happy to implement this if you'd like? 🤔

[jamesmills]

Yes please! The Offset.Earth API is now live and our tracking URL’s are live.

[owenvoke]

@jamesmills, is there a package that has some trees that I can test this on? 🙂

Here's what I've done so far, but currently the test for the tree value is failing because it is 0. https://github.com/badges/shields/compare/master...owenvoke:feature/treeware

Need to decide what to do with that. 👍

[jamesmills]

Hi @owenvoke

Yes, you can use this package reference https://github.com/stoplightio/spectral which has 250 Trees

You md5('stoplightio/spectral') to get 65c6e3e942e7464b4591e0c8b70d11d5 and can then call https://public.offset.earth/users/treeware/trees?ref=65c6e3e942e7464b4591e0c8b70d11d5 to get the Tree count for that package.

Hope that helps.

[owenvoke]

That's perfect! Updated to use that now, all tests passing, and the badge looks good.

Screenshots of how it looks in the web interface

 

---

I'm happy to open a PR for both of these badge sets if the maintainers of Shields are ok with it. I'll wait for an update. 👍

[jamesmills]

Thank you @owenvoke

I'll keep watch on this to see when we get maintainer approval for PR.

[calebcartwright]

Please feel free to open a PR

[owenvoke]

Opened PRs https://github.com/badges/shields/pull/4814 and https://github.com/badges/shields/pull/4815 for Treeware and Offset Earth respectively. 👍

Thank you everyone for all your help.

[owenvoke]

As these badges have now been implemented, I think it's fine to close this issue. Thanks everyone! 🎉

[jamesmills]

Thank you @owenvoke and everyone else who supported getting this live.

Much love! Stay safe.