# 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`](https://dev.nominal.io/api/_downloads/c9ea5fda0e52067317b25e4aabbdffc2/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`](https://dev.nominal.io/api/rest/units-service.md#getunitsresponseunitsbypropertywrapper)
:   ​

    Fields of `GetUnitsResponseUnitsByPropertyWrapper`

    `value` array of [`Unit`](https://dev.nominal.io/api/rest/units-service.md#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`](https://dev.nominal.io/api/rest/units-service.md#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**

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

**requests**

```python
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**

```python
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**

```python
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`

```json
{
  "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`](https://dev.nominal.io/api/rest/units-service.md#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`](https://dev.nominal.io/api/rest/units-service.md#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**

```shell
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**

```python
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**

```python
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**

```python
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`

```json
{
  "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`](https://dev.nominal.io/api/rest/units-service.md#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`](https://dev.nominal.io/api/rest/units-service.md#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**

```shell
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**

```python
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**

```python
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**

```python
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`

```json
{
  "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`](https://dev.nominal.io/api/rest/units-service.md#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`](https://dev.nominal.io/api/rest/units-service.md#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**

```shell
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**

```python
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**

```python
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**

```python
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`

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

## Errors

[Errors](https://dev.nominal.io/api.md#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`](https://dev.nominal.io/api/rest/units-service.md#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`](https://dev.nominal.io/api/rest/units-service.md#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](https://scalar.com), MIT License.