# 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`](https://dev.nominal.io/api/_downloads/6872ecfe46e46791dc91dd08aa1e0668/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`](https://dev.nominal.io/api/legacy/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/legacy/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/v1/units" \
  -H "Authorization: Bearer <api key>"
```

**requests**

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

**httpx**

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

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

asyncio.run(main())
```

Response: `200`

```json
{
  "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`](https://dev.nominal.io/api/legacy/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
:   ​

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

Request

**curl**

```shell
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>"'
```

**requests**

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

**httpx**

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

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

```json
{
  "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`](https://dev.nominal.io/api/legacy/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/legacy/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/v1/units/get-batch-units" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "<unit symbol>"
]'
```

**requests**

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

**httpx**

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

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

```json
{
  "<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`](https://dev.nominal.io/api/legacy/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/legacy/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/v1/units/commensurable-units" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '"<unit symbol>"'
```

**requests**

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

**httpx**

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

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

```json
[
  {
    "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`](https://dev.nominal.io/api/legacy/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 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](https://scalar.com), MIT License.