Developers API

API Documentation for Device Climate Status

Overview

This documentation provides guidelines for developers to integrate our APIs into their applications or games. These APIs allow developers to retrieve users' device climate status and incentivize climate-friendly actions through in-app or in-game rewards.

---

Base URL

The base URL for all API endpoints is:

https://api.umweltify.com

---

API 1: GetToken

Description

The GetToken API is used to obtain an authorization token. This token is required for making requests to other APIs and expires in 24 hours.

Endpoint

post

Authorizations

Body

application/jsontext/jsonapplication/*+json

appIdstringOptional

appSecretstringOptional

Responses

200

OK

application/json

401

Invalid App Id or secret.

post

HTTPcURLJavaScriptPython

POST /v1/Auth/GetToken HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "appId": "text",
  "appSecret": "text"
}

application/jsontext/jsonapplication/*+json

{
  "Data": "text",
  "Message": "text",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Request Parameters

Parameter	Type	Description
appId	string	The unique identifier for the developer's app in our developers portal.
appSecret	string	The secret key associated with the app.

Request Example

{
  "appId": "your-app-id",
  "appSecret": "your-app-secret"
}

Response Example

{
  "Data": "your-auth-token",
  "StatusCode": 200,
  "Message": "success"
}

Notes

• Developers can obtain their appId and appSecret by registering in our Developer Program.

• The token must be included as a Bearer token in the Authorization header for the ClimateStatus API request.

---

API 2: ClimateStatus

Description

The ClimateStatus API retrieves the climate status of a specific device. This status is returned as a number that corresponds to a predefined set of descriptions.

Endpoint

get

Authorizations

Query parameters

deviceIdstringOptional

Responses

200

OK

application/json

404

Specified device ID not found.

get

HTTPcURLJavaScriptPython

GET /v1/ClimateStatus HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*

{
  "Data": {
    "ClimateStatus": 1,
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "Message": "text",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Request Parameters

Parameter	Type	Description
deviceID	string	The unique identifier of the device.

Headers

Header	Description
Authorization	Bearer token obtained from GetToken

Query String Example

/v1/ClimateStatus?DeviceID=12345

Response Example

{
  "Data": {
    "ClimateStatus": 5
  },
  "StatusCode": 200,
  "Message": "Success"
}

Climate Status Descriptions

Climate Status Code	Description
0	The device climate status is not yet set.
1	Not Green: The device owner's home electricity source is not green.
2	Not Green: The device owner's station is not available.
3	Not Green: Generally not green.
4	Not Green: The device's carbon budget is used up.
5	Green: The device owner's home electricity source is green.
6	Green: The device owner's station carbon budget is available.
7	Green: Generally green.
8	Green: The device's carbon budget is still available.
9	Green: Certified green electricity source through EACs.

Notes

• Ensure that the deviceID provided is valid and registered in Umweltify.

• To register a device in Umweltify, users must first install the ThingsApp on their devices.

• This API requires a valid authorization token in the request headers.

• Interpret the ClimateStatus number using the description table above.

---

Authentication

The ClimateStatus API requires a valid authorization token in the request headers.

Authorization Header Example

Authorization: Bearer your-auth-token

---

Error Codes

Error Code	Description
400	Bad Request: Missing or invalid parameters.
401	Unauthorized: Invalid or expired authorization.
404	Not Found: Requested resource does not exist.
500	Internal Server Error: An unexpected error.

---

Contact

For additional support or inquiries, please submit a ticket in the developers' portal.