Units service#

The Units Service serves as a comprehensive catalog of the units of measurement supported by Nominal. Units, by default, follow the UCUM convention for representation.

OpenAPI file: UnitsService.json

Endpoints#

Get all units#

GET /units/v1/units

Returns all known units, grouped by the physical property they measure.

Request

No parameters and no body.

Response

unitsByProperty map of UnitProperty to array of Unit

​

Fields of Unit
name string

​

symbol string

​

property string

Empty if no property is available. If two units measure different properties, it is not possible to convert between them.

dimension UnitDimension

The physical dimensions in terms of the base units of the system. It is only possible to convert units if they have the same dimension. Empty if the unit is a base unit.

Fields of UnitDimension
baseDimensions map of string to integer

​

system string

​

Request

curl "https://api.gov.nominal.io/api/units/v1/units" \
  -H "Authorization: Bearer <api key>"

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/units/v1/units",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/units/v1/units",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/units/v1/units",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "unitsByProperty": {
    "<key>": [
      {
        "name": "<unit name>",
        "symbol": "<unit symbol>",
        "property": "<unit property>",
        "dimension": {
          "baseDimensions": {
            "<key>": 1
          }
        },
        "system": "<unit system>"
      }
    ]
  }
}

Get unit#

POST /units/v1/units/get-unit

Returns information for a unit symbol if available. Returns as empty if the provided symbol cannot be parsed.

Body

The body is a string.

Response

name string

​

symbol string

​

property string

Empty if no property is available. If two units measure different properties, it is not possible to convert between them.

dimension UnitDimension

The physical dimensions in terms of the base units of the system. It is only possible to convert units if they have the same dimension. Empty if the unit is a base unit.

Fields of UnitDimension
baseDimensions map of string to integer

​

system string

​

When there is nothing to return, the response is HTTP 204 with no body.

Request

curl -X POST "https://api.gov.nominal.io/api/units/v1/units/get-unit" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '"<unit symbol>"'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/units/v1/units/get-unit",
    headers={"Authorization": "Bearer <api key>"},
    json="<unit symbol>",
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/units/v1/units/get-unit",
    headers={"Authorization": "Bearer <api key>"},
    json="<unit symbol>",
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/units/v1/units/get-unit",
            headers={"Authorization": "Bearer <api key>"},
            json="<unit symbol>",
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "name": "<unit name>",
  "symbol": "<unit symbol>",
  "property": "<unit property>",
  "dimension": {
    "baseDimensions": {
      "<key>": 1
    }
  },
  "system": "<unit system>"
}

Get batch units#

POST /units/v1/units/get-batch-units

Returns information for the unit symbols if available. If the provided symbol cannot be parsed, it will be omitted from the map.

Body

The body is an array of string.

Response

The body is a map of UnitSymbol to Unit.

Fields of Unit
name string

​

symbol string

​

property string

Empty if no property is available. If two units measure different properties, it is not possible to convert between them.

dimension UnitDimension

The physical dimensions in terms of the base units of the system. It is only possible to convert units if they have the same dimension. Empty if the unit is a base unit.

Fields of UnitDimension
baseDimensions map of string to integer

​

system string

​

Request

curl -X POST "https://api.gov.nominal.io/api/units/v1/units/get-batch-units" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "<unit symbol>"
]'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/units/v1/units/get-batch-units",
    headers={"Authorization": "Bearer <api key>"},
    json=["<unit symbol>"],
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/units/v1/units/get-batch-units",
    headers={"Authorization": "Bearer <api key>"},
    json=["<unit symbol>"],
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/units/v1/units/get-batch-units",
            headers={"Authorization": "Bearer <api key>"},
            json=["<unit symbol>"],
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "<key>": {
    "name": "<unit name>",
    "symbol": "<unit symbol>",
    "property": "<unit property>",
    "dimension": {
      "baseDimensions": {
        "<key>": 1
      }
    },
    "system": "<unit system>"
  }
}

Get commensurable units#

POST /units/v1/units/commensurable-units

Returns the set of cataloged units that can be converted to and from the given unit. No commensurable units does not imply the unit is invalid. Use /get-unit to check for validity.

Body

The body is a string.

Response

The body is an array of Unit.

Fields of Unit
name string

​

symbol string

​

property string

Empty if no property is available. If two units measure different properties, it is not possible to convert between them.

dimension UnitDimension

The physical dimensions in terms of the base units of the system. It is only possible to convert units if they have the same dimension. Empty if the unit is a base unit.

Fields of UnitDimension
baseDimensions map of string to integer

​

system string

​

Request

curl -X POST "https://api.gov.nominal.io/api/units/v1/units/commensurable-units" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '"<unit symbol>"'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/units/v1/units/commensurable-units",
    headers={"Authorization": "Bearer <api key>"},
    json="<unit symbol>",
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/units/v1/units/commensurable-units",
    headers={"Authorization": "Bearer <api key>"},
    json="<unit symbol>",
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/units/v1/units/commensurable-units",
            headers={"Authorization": "Bearer <api key>"},
            json="<unit symbol>",
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

[
  {
    "name": "<unit name>",
    "symbol": "<unit symbol>",
    "property": "<unit property>",
    "dimension": {
      "baseDimensions": {
        "<key>": 1
      }
    },
    "system": "<unit system>"
  }
]

Types#

Unit#

name string

​

symbol string required

​

property string

Empty if no property is available. If two units measure different properties, it is not possible to convert between them.

dimension UnitDimension

The physical dimensions in terms of the base units of the system. It is only possible to convert units if they have the same dimension. Empty if the unit is a base unit.

system string required

​

UnitDimension#

The fundamental base dimensions and their exponents, whose product compose a unit.

baseDimensions map of string to integer

​

Page design based on Scalar, MIT License.