GET /variable/get-variable-filter-data — Variable Filter Options

This page documents the shape given in the source spec as-is. Several details aren’t finalized — see the callout at the bottom of this page.

Endpoint

GET /variable/get-variable-filter-data

Returns the set of filter facets available for narrowing a variable listing — organizations, resource types, variable (point) types, metered entity types, individual metered entities, status, and data reception — scoped to the organization(s) in orgIds. Unlike the rest of the Data API, this path is singular and verb-shaped (/variable/get-variable-filter-data) rather than the plural, resource-shaped convention used elsewhere (/organizations, /variables, /metered-entities). Treat the path itself as directional pending confirmation.

Parameters

Parameter	Description
`orgIds`	One or more organization `id` values to scope the returned facets to. The encoding for multiple values (repeated `orgIds=` params vs. a comma-separated list) isn’t confirmed — see below.

Example request

curl "https://api.communityhub.cloud/dh/public/v1/variable/get-variable-filter-data?orgIds=9d2e77b4" \
  -H "Authorization: Bearer <token>"

Response shape

The response is an array of facet groups, one per filterable dimension:

[
  {
    "id": "organizations",
    "label": "Organization",
    "default": "3f8c1a02",
    "children": [
      { "id": "3f8c1a02", "label": "City of Cleveland" },
      { "id": "9d2e77b4", "label": "City of Oberlin" }
    ]
  },
  {
    "id": "resourceType",
    "label": "Resource",
    "children": [
      { "id": "a2f51c8e", "label": "Electricity" },
      { "id": "d39b0f74", "label": "Water" }
    ]
  },
  {
    "id": "pointType",
    "label": "Variable Type",
    "children": [
      { "id": "totalizer", "label": "Totalizer" },
      { "id": "average-rate", "label": "Average Rate" }
    ]
  },
  {
    "id": "buildingType",
    "label": "Metered Entity Type",
    "children": [
      { "id": "c7e4a280", "label": "Building" }
    ]
  },
  {
    "id": "building",
    "label": "Metered Entity",
    "children": [
      { "id": "5b1d9e3f", "label": "Oberlin Public Library", "children": [] }
    ]
  },
  {
    "id": "status",
    "label": "Status",
    "children": [
      { "id": "enabled", "label": "Enabled" }
    ]
  },
  {
    "id": "dataReception",
    "label": "Data Reception",
    "children": [
      { "id": "online", "label": "Online" }
    ]
  }
]

Field	Type	Description
`id`	string	The facet’s key. One of `organizations`, `resourceType`, `pointType`, `buildingType`, `building`, `status`, `dataReception`.
`label`	string	Display label for the facet (for example, “Organization”, “Resource”).
`default`	string	Present only on the `organizations` facet in the source example. An 8-character hex string matching one of the children’s `id` values. Whether this represents a default-selected child or something else isn’t confirmed.
`children`	array	The selectable options for this facet — see below.

Child (option) fields

Field	Type	Description
`id`	string	The option’s identifier. An 8-character hex string for `organizations`, `resourceType`, `buildingType`, and `building` (for example `"3f8c1a02"`); a semantic string for `pointType`, `status`, and `dataReception` (for example `"totalizer"`, `"enabled"`, `"online"`).
`label`	string	Display label for the option.
`children`	array	Only observed on the `building` facet’s options, and empty in every example. Suggests metered entities may nest (for example sub-metering), but this isn’t confirmed.

Using the result to filter variables

The likely intent is that a UI renders one control per facet group (using label for the control’s title and each child’s label as an option), and the selected child ids are then sent to GET /variables as filters — for example resourceType, pointType, status, and dataReception as query parameters matching the facet id. This isn’t confirmed in the source spec; GET /variables’ own filter design is still open (see Discovery Endpoints).

Open — not fully decided:

Encoding for multiple orgIds values (repeated param vs. comma-separated).
What default: 1 on the organizations facet means.
Whether facet ids (resourceType, pointType, etc.) are literally the query parameter names accepted by GET /variables, or map to different parameter names.
Whether building children can have non-empty nested children in practice, and what that would represent.
Whether facets are always returned in the same order and whether any can be empty (for example, an org with no offline variables might still return an empty dataReception → offline option, or omit it — unconfirmed).

See Organizations for the id values valid in orgIds, and Discovery Endpoints for how the filtered results are ultimately retrieved.

Try it live

Fetch these facets live and build a real GET /variables request from your selections, right in the browser.

Overview

Data Ingestion (Not Available)

Retrieving Data

Webhooks (Not Available)

Sample Code (No SDKs)

GET /variable/get-variable-filter-data — Variable Filter Options

Endpoint

Parameters

Example request

Response shape

Facet group fields

Child (option) fields

Using the result to filter variables

Try it live

​Endpoint

​Parameters

​Example request

​Response shape

​Facet group fields

​Child (option) fields

​Using the result to filter variables

Try it live

Endpoint

Parameters

Example request

Response shape

Facet group fields

Child (option) fields

Using the result to filter variables