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: nominal.units.v1.json

Endpoints#

Get all units#

GET /units/v2/units

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

Request

No parameters and no body.

Response

unitsByProperty map of string to GetUnitsResponseUnitsByPropertyWrapper

Fields of GetUnitsResponseUnitsByPropertyWrapper

value 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

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

requests

import requests

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

httpx

import httpx

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

aiohttp

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/v2/units",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

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

Get batch units#

POST /units/v2/units/batch-get

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

Body

units array of string

Response

responses map of string 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

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

requests

import requests

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

httpx

import httpx

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

aiohttp

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/v2/units/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json={"units": ["<units>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

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

Get commensurable units#

POST /units/v2/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

unit string

Response

units 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

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

requests

import requests

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

httpx

import httpx

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

aiohttp

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/v2/units/commensurable-units",
            headers={"Authorization": "Bearer <api key>"},
            json={"unit": "<unit>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

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

Get unit#

POST /units/v2/units/get-unit

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

Body

unit string

Response

unit 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

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

requests

import requests

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

httpx

import httpx

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

aiohttp

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/v2/units/get-unit",
            headers={"Authorization": "Bearer <api key>"},
            json={"unit": "<unit>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

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

Errors#

Errors shows how these errors are sent.

Each error’s errorName is NominalUnitsV1: followed by its name below.

Status	Name	Notes
400	`ScoutErrorCannotDeserializeSearchToken`	CannotDeserializeSearchToken
400	`ScoutErrorInvalidRange`	The start time of the provided Range is greater than its end time.
400	`ScoutErrorRequestedPageSizeTooLarge`	RequestedPageSizeTooLarge

Types#

GetUnitsResponseUnitsByPropertyWrapper#

value array of Unit

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.
system string

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.