Device ID

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
appIdstringOptional
appSecretstringOptional
Responses
200

OK

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

{
  "appId": "text",
  "appSecret": "text"
}
{
  "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
get
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.

PreviousDevelopers API

Last updated