MapComplete/Docs/builtin_units.md

[//]: # (WARNING: this file is automatically generated. Please find the sources at the bottom and edit those sources)

# Units

## Table of contents

1. [Units](#units)
  - [How to use](#how-to-use)
2. [Rendering](#rendering)
3. [Usage](#usage)
  - [unit](#unit)
    + [power](#power)
       * [MW](#mw)
       * [kW](#kw)
       * [W](#w)
       * [GW](#gw)
    + [voltage](#voltage)
       * [V](#v)
    + [current](#current)
       * [A](#a)
    + [distance](#distance)
       * [m](#m)
       * [cm](#cm)
       * [mm](#mm)
       * [ft](#ft)
    + [speed](#speed)
       * [kmh](#kmh)
       * [mph](#mph)
    + [duration](#duration)
       * [minutes](#minutes)
       * [hours](#hours)
       * [days](#days)
       * [weeks](#weeks)
       * [months](#months)
       * [years](#years)

## How to use

In some cases, a value is represented in a certain unit (such as meters for heigt/distance/..., km/h for speed, ...)

Sometimes, multiple denominations are possible (e.g. km/h vs mile/h; megawatt vs kilowatt vs gigawatt for power generators, ...)

This brings in some troubles, as there are multiple ways to write it (no denomitation, 'm' vs 'meter' 'metre', ...)

Not only do we want to write consistent data to OSM, we also want to present this consistently to the user.
This is handled by defining units.

# Rendering

To render a value with long (human) denomination, use {canonical(key)}

# Usage

First of all, you define which keys have units applied, for example:

```
units: [
 appliesTo: ["maxspeed", "maxspeed:hgv", "maxspeed:bus"]
 applicableUnits: [
     ...
 ]
]
```

ApplicableUnits defines which is the canonical extension, how it is presented to the user, ...:

```
applicableUnits: [
{
    canonicalDenomination: "km/h",
    alternativeDenomination: ["km/u", "kmh", "kph"]
    default: true,
    human: {
        en: "kilometer/hour",
        nl: "kilometer/uur"
    },
    humanShort: {
        en: "km/h",
        nl: "km/u"
    }
},
{
    canoncialDenomination: "mph",
    ... similar for miles an hour ...
}
]
```

If this is defined, then every key which the denominations apply to (`maxspeed`, `maxspeed:hgv` and `maxspeed:bus`) will be rewritten at the metatagging stage:
every value will be parsed and the canonical extension will be added add presented to the other parts of the code.

Also, if a freeform text field is used, an extra dropdown with applicable denominations will be given

Units 

## unit

### power

#### MW

Validator is *float*

1MW = 1000000MW

Alternative denominations:

 - megawatts
 - megawatt

#### kW

Validator is *float*

1kW = 1000MW

Alternative denominations:

 - kilowatts
 - kilowatt

#### W

Validator is *float*

Alternative denominations:

 - watts
 - watt

#### GW

Validator is *float*

1GW = 1000000000MW

Alternative denominations:

 - gigawatts
 - gigawatt

### voltage

#### V

Validator is *float*

Alternative denominations:

 - v
 - volt
 - voltage
 - Volt

### current

#### A

Validator is *float*

Alternative denominations:

 - a
 - amp
 - amperage
 - A

### distance

#### m

Validator is *float*

*Default denomination*

Alternative denominations:

 - meter
 - meters

#### cm

Validator is *float*

1cm = 0.01m

Alternative denominations:

 - centimeter
 - centimeters
 - cms

#### mm

Validator is *float*

1mm = 0.001m

Alternative denominations:

 - millimeter
 - millimeters

#### ft

Validator is *float*

1ft = 0.3048m

Alternative denominations:

 - feet
 - voet

### speed

#### kmh

Validator is *float*

Alternative denominations:

 - km/u
 - km/h
 - kph

#### mph

Validator is *float*

Default denomination in the following countries:

 - gb
 - us

Alternative denominations:

 - m/u
 - mh
 - m/ph

### duration

#### minutes

Validator is *float*

Alternative denominations:

 - m
 - min
 - mins
 - minuten
 - mns

#### hours

Validator is *float*

Alternative denominations:

 - h
 - hrs
 - hours
 - u
 - uur
 - uren

#### days

Validator is *float*

Alternative denominations:

 - dys
 - dagen
 - dag

#### weeks

Validator is *float*

#### months

Validator is *float*

#### years

Validator is *float*


This document is autogenerated from [assets/layers/unit/unit.json](https://source.mapcomplete.org/MapComplete/MapComplete/src/branch/develop/assets/layers/unit/unit.json), [src/Models/ThemeConfig/Json/UnitConfigJson.ts](https://source.mapcomplete.org/MapComplete/MapComplete/src/branch/develop/src/Models/ThemeConfig/Json/UnitConfigJson.ts)