Tips and recommendations

Once a user understands the impact of their carbon footprint, the natural next step is to act on it. The Connect Earth API provides personalised tips and recommendations based on a user's spend and any user habits they have submitted.

Two endpoints serve these:

1. /tips
2. /recommendations

Tips

The /tips endpoint returns personalised sustainability tips for a user over a specified time period. You can filter by group (e.g. Travel, Utilities).

Response format

Up to maxNumberOfTips (default: 3) are returned per group.

[
  {
    "group_name": "Test Group",
    "group_code": "02",
    "tips": [
      {
        "id": "ID_ELEC_3_1_3",
        "content": "When replacing an appliance, you can reduce your energy bill and carbon emissions by purchasing one with a high energy-efficiency rating.",
        "impact_rating": "Medium"
      }
    ]
  }
]

You can display the content string directly. We recommend maintaining a local copy of our tip library so you can customise the messaging for your users — use the id field to reference and retrieve tips from your system.

Impact rating

When relevant, impact_rating is one of High, Medium, or Low. Use this to give users a sense of how much impact each tip will have.

Recommendations

This endpoint works similarly to /tips but provides reasons alongside the tips. There are currently two comparison types you can request recommendations for.

The reason object contains enough information to construct informative insights in your application. The tips array contains the relevant tips.

Top emitting groups (topEmittingGroups)

Fetches the top 3 groups with the most kg CO2e over the months sent in the request.

Reason parameters:

Key	Description	Example
GROUP_NAME	The name of the group	"General Consumer Goods"
GROUP_CODE	The code of the group	"02"
MONTH	Months used in calculation (array, even for a single month)	["2024-01"]
KG_CO2E	CO2e in kg that this group emitted over the time frame	196.5
PERCENTAGE_OF_TOTAL_EMISSIONS	Percentage of total emissions this group represents	54.92

Example request / response

Request:

{
  "userId": "user-123",
  "maxNumberOfTips": 3,
  "reasons": {
    "topEmittingGroups": {
      "months": ["2024-12"]
    }
  }
}

Response (abridged):

{
  "top_emitting_groups": [
    {
      "reason_id": "first_highest_group",
      "reason_text": "The majority of your emissions in month(s) {MONTH} comes from {GROUP_NAME}",
      "reason_params": [
        { "key": "GROUP_NAME", "value": "General Consumer Goods" },
        { "key": "GROUP_CODE", "value": "02" },
        { "key": "MONTH", "value": ["2024-12"] },
        { "key": "KG_CO2E", "value": 196.5 },
        { "key": "PERCENTAGE_OF_TOTAL_EMISSIONS", "value": 54.92 }
      ],
      "tips": [
        {
          "id": "ID_MATE_1_1_1",
          "content": "Reducing your purchases of consumables can lead to long-term cost savings and a decrease in your emissions.",
          "impact_rating": "Medium"
        }
      ]
    }
  ]
}

Month comparison (timeComparisonAnalysis)

Fetches the 3 groups with the biggest percentage difference (positive or negative) over the 2 months sent in the request. The months don't need to be sequential — you can compare Feb 2025 to Jan 2025 or Feb 2024.

Reason parameters:

Key	Description	Example
GROUP_NAME	The name of the group	"General Consumer Goods"
GROUP_CODE	The code of the group	"02"
SELECTED_MONTH	Earliest month in the comparison	"2024-11"
SELECTED_MONTH_KG_CO2E	CO2e in the selected month	62.35
COMPARISON_MONTH	Latest month in the comparison	"2024-12"
COMPARISON_MONTH_KG_CO2E	CO2e in the comparison month	196.5
PERCENTAGE_CHANGE	(COMPARISON_MONTH_KG_CO2E - SELECTED_MONTH_KG_CO2E) * 100 / SELECTED_MONTH_KG_CO2E	215

Enter variables in the correct order: [COMPARISON_MONTH, SELECTED_MONTH].

"timeComparisonAnalysis": {
  "months": ["2024-12", "2024-11"]
}

Example request / response

Request:

{
  "userId": "user-123",
  "maxNumberOfTips": 3,
  "reasons": {
    "timeComparisonAnalysis": {
      "months": ["2024-12", "2024-11"]
    }
  }
}

Response (abridged):

{
  "time_comparison_analysis": [
    {
      "reason_id": "first_time_comparison_emissions",
      "reason_text": "Your ${GROUP_NAME} expenses in ${COMPARISON_MONTH} have increased by ${PERCENTAGE_CHANGE}% compared to the previous month.",
      "reason_params": [
        { "key": "GROUP_NAME", "value": "General Consumer Goods" },
        { "key": "SELECTED_MONTH", "value": "2024-11" },
        { "key": "SELECTED_MONTH_KG_CO2E", "value": 62.35 },
        { "key": "COMPARISON_MONTH", "value": "2024-12" },
        { "key": "COMPARISON_MONTH_KG_CO2E", "value": 196.5 },
        { "key": "PERCENTAGE_CHANGE", "value": 215 }
      ],
      "tips": [
        {
          "id": "ID_MATE_1_1_2",
          "content": "The emissions from disposing of an item are often tiny compared to the emissions generated during its production.",
          "impact_rating": "Medium"
        }
      ]
    }
  ]
}

Relevant tips

All tips provided by the API are relevant to the user, meaning:

1. The user has exceeded the carbon threshold for at least one linked category.
2. The tip is not excluded by the user's habits.

From the remaining relevant tips, a random selection is made up to the value specified in maximumNumberOfTips.

Carbon threshold

Each tip is linked to a category and has a minimum carbon threshold in kg CO2e (typically 0 or 10 kg CO2e). The user must exceed this threshold in the specified period for the tip to be considered.

Example — Travel transactions for two users over the past month:

User	Transaction	Category	Group	Amount	kg CO2e
A	British Airways	Flights	Travel	$100	200
A	Shell	Fuel	Travel	$5	5
B	Shell	Fuel	Travel	$50	70
B	MyBus	Public Transport	Travel	$20	20

When filtering by groupFilter=Travel:

• User A qualifies for tips related to air travel — 200 kg CO2e from flights, exceeding the minimum threshold.
• User B does not qualify for flight-related tips (no flight emissions).
• User B qualifies for fuel-related tips — 70 kg CO2e on fuel. User A (only 5 kg CO2e) does not.

User habits

If a user has submitted information via the questionnaire endpoint, we use it to filter out irrelevant tips. For example, if a user is vegetarian, we exclude tips related to reducing meat consumption.

Creating an ecosystem

One of the best ways to improve the offering is providing tips personalised for your region or ecosystem. We can add custom recommendations that link to assets you control, including:

1. Integrating existing relevant articles you have already created.
2. Suggesting relevant ESG products such as green finance or ESG pension pots.
3. Carbon credits — via a partner or your existing systems.

To customise recommendations for your users, contact Connect Earth to discuss the best implementation approach.