List Units (Legacy)

Get the unit catalog through the legacy API, optionally filtered by the type stored with each unit

GET /api/v1/units

List Units (Legacy)

JavaScript

const options = {
  method: 'GET',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>'
  }
};

fetch('https://api.dcycle.io/api/v1/units', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "[]": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    }
  ]
}

Legacy API. This page documents the previous version of the API. For new integrations use List Units (GET /v2/units) instead: it does not need x-user-id, and its type parameter returns the units the Dcycle app offers in each form.

Retrieve the measurement units available in Dcycle. Their ids are what you send as unit_id when you create invoices, purchases and other consumption records.

Units are reference data maintained by Dcycle. You cannot create or modify units through the API - this endpoint is read-only.

Request

Headers

x-api-key · string · required

Your API key. You can send it as Authorization: Bearer <key> instead, as the examples below do. It must be an active key of the organization in x-organization-id.

Format: Your API key string

x-organization-id · string · required

Your organization UUID

Format: UUID

x-user-id · string · required

UUID of a user with an active membership in that organization

Format: UUID

Query Parameters

type · string

Return only the units whose stored type is exactly this value. It is free text, not a list of options: a value no unit has returns 200 with an empty array, not an error. Omit it to get the whole catalog.

The stored type is a legacy classification, and it is not consistent: kilogram_(kg) is solid, cubic_metre_(m3) and kilometer_(km) are gas, and imperial_gallon_(gal_imp) is mass. Values in use include fiat_currency, mass, energy, volume, ghgemissions, gas, liquid, solid, time, area and several waste_water_treatment_* values. The filter is dependable for fiat_currency, which returns the currencies; for physical units, pick them by exact name from the whole catalog instead.

Example: fiat_currency

Response

Returns an array of unit objects, not paginated. Without type it is ordered by name; with type the order is not guaranteed.

[] · array

Array of unit objects

Unit Object Fields:

id · string

Unit id (UUID). This is the value to send as unit_id.

name · string

Unit name, in snake_case with its symbol or ISO code in parentheses: kilowatt_hour_(kwh), litre_(l), euros_(eur)

type · string

Legacy classification stored with the unit (see the type parameter above)

Example

cURL

curl -X GET "https://api.dcycle.io/api/v1/units?type=fiat_currency" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

Successful Response

Returns 200 OK with the unit array. An excerpt of ?type=fiat_currency:

[
  {
    "id": "d3e37f2b-0fc3-4532-82f8-3890ab56ad37",
    "name": "euros_(eur)",
    "type": "fiat_currency"
  },
  {
    "id": "16101563-71ac-4215-a372-8ac6713f1fbe",
    "name": "us_dollar_(usd)",
    "type": "fiat_currency"
  },
  {
    "id": "108c1de7-8d6f-4fda-ac38-ec042a5a71b4",
    "name": "british_pound_(gbp)",
    "type": "fiat_currency"
  }
]

A type that no unit has, such as ?type=kWh, also returns 200 OK:

[]

Common Errors

The authentication errors of this endpoint have a bare JSON string as body, not an object. They are checked in this order: organization, user, membership, and finally the API key.

401 Unauthorized

Cause: No API key was sent, or the key is not an active key of the organization in x-organization-id.

"Invalid Credentials"

403 Forbidden

Cause: No organization has the id in x-organization-id.

"Organization Not Found"

Cause: No user has the id in x-user-id.

"User Not Found"

Cause: The user in x-user-id has no active membership in the organization.

"Membership Not Found"

422 Unprocessable Entity

Cause: x-organization-id or x-user-id is missing.

{
  "detail": [
    {
      "loc": ["header", "x-user-id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Use Cases

Find a Unit by Exact Name

Request the whole catalog and index it by name. Compare exact names, never a prefix: many names start with kilogram (kilogram_(kg), kilogram_(kg) material, kilograms_co2_(kg_co2), …).

response = requests.get(
    "https://api.dcycle.io/api/v1/units",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
units_by_name = {unit["name"]: unit for unit in response.json()}

kwh_unit_id = units_by_name["kilowatt_hour_(kwh)"]["id"]  # ba80e6cb-86a4-4bb1-a0c5-8104365d523c
m3_unit_id = units_by_name["cubic_metre_(m3)"]["id"]  # 2a09be22-a6e2-4317-a680-94aaa1048765

A few names belong to two units (kilogram_day_(kg_day) is one). For those, the dictionary keeps only one of them, so use the id.

Store Unit IDs in Configuration

Unit ids do not change, so you can keep the ones you use in your configuration instead of requesting the catalog on every run:

# config.py
UNIT_IDS = {
    "kilowatt_hour_(kwh)": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",
    "megawatt_hour_(mwh)": "45f61d28-93a8-4312-9c55-f2b65814aebc",
    "cubic_metre_(m3)": "2a09be22-a6e2-4317-a680-94aaa1048765",
    "litre_(l)": "54a709bf-79fe-4acb-ab85-5e1d7cd26eb4",
    "kilogram_(kg)": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
    "euros_(eur)": "d3e37f2b-0fc3-4532-82f8-3890ab56ad37",
}

Related Endpoints

List Units

Current API: no x-user-id, and the units the app offers in each form

Create Invoice

Create invoices using unit IDs

List Suppliers

Get suppliers for invoices

Authentication

Learn about API authentication