WELLPOINT Cloud API

Occupancy & CSV Download

---

Base URL

All API calls are handled via GET parameters.
There are no REST paths — everything is routed by the action parameter.

---

Authentication

Required parameter (ALL requests)

How it works:

• The access key identifies the device user

• If the key is missing or invalid:

  • The server waits ~3 seconds

  • Returns an HTML error message (not JSON)

  • HTTP status remains 200

Client rule:
If the response is not valid JSON or CSV, treat it as an authentication or permission error.

---

Device & Plan Access Rules (Server-Side)

All results are filtered automatically by the backend:

• Device must be assigned to the authenticated user

• Only root / linked devices are included

• Device plan must be active

• API access is allowed ONLY for PRO plan devices

• Technical rule enforced in backend:

  device_plan.plan_show_downloadlink = 'Y'

  


Clients cannot bypass these rules by passing device IDs.

---

Action: getoccupancy

Purpose

Returns current occupancy per device in JSON format.

• Occupancy is calculated as IN - OUT

• Negative values are automatically corrected to 0

---

Strong Recommendation (IMPORTANT)

You are strongly encouraged to:

• ✅ NOT send date_start

• ✅ NOT send time_start

Why this is better:

• The API automatically uses today

• Start time defaults to 00:00:00 (midnight)

• Prevents date/time mistakes

• Works correctly across timezones

You should send:

• ✅ timezoneshift_start

This tells the API what “your midnight” means
(especially important in Europe).

---

Request Parameters – getoccupancy

Required

---

Optional (safe defaults are applied)

---

Time Handling Explained (Important)

1. API builds a local datetime

   date_start + time_start

   


2. This datetime is converted to UTC using:

   timezoneshift_start

   


3. SQL then applies each device’s own timezone

Result:

• Correct “start of day”

• Correct per-device aggregation

• No negative occupancy

---

Example (RECOMMENDED – Simple)

Get today’s occupancy starting at local midnight

---

Example (Advanced – Custom Start Time)

Get occupancy since 08:30 local time on 2027.09.19

---

JSON Response Format

Content-Type

Example response

---

Field Definitions

meta.datetime_start

• Effective UTC start datetime after timezone conversion

meta.generated_utc

• UTC time when the response was generated

CorrectedOccupancy

• IN - OUT

• Minimum value is 0

---

Action: downloadcsv

Purpose

Downloads historical device data as a CSV file.

⚠️ Available ONLY for PRO plan devices
In mixed plans, only PRO devices are included in the CSV.

---

Request Parameters – downloadcsv

Required

---

Optional

---

Example – CSV Download

---

CSV Response

• Content-Type: text/csv

• Browser-triggered download

• Header row included

---

Error Handling (Current Behavior)

• Invalid key → HTML error message

• No PRO devices → empty CSV / empty JSON array

• Invalid date or time → defaults applied silently

---

Best Practice Summary

• ✔ API works only for PRO plan devices

• ✔ Mixed plans are supported (PRO devices only returned)

• ✔ Use getoccupancy without date and time

• ✔ Always send timezoneshift_start

• ✔ Let the API handle “today” and midnight

• ✔ Treat non-JSON responses as errors

• ✔ Do not rely on client-side device filtering

 

---

⚠️ IMPORTANT NOTICE – API AVAILABILITY (READ FIRST)

This API is available ONLY for devices on the PRO plan.

If a customer uses mixed plans, for example:

• 2 × LITE devices

• 4 × PLUS devices

• 12 × PRO devices

👉 The API will return data ONLY for the 12 PRO plan devices.
LITE and PLUS devices are automatically excluded, even if they belong to the same user account.

This behavior is enforced server-side and cannot be overridden.

---