> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/api-guides/configuration/unit-handling-service/api-reference/unit-conversion.md).

# Unit Conversion

Convert Units

## Fetching conversion factor

> Calculates conversion factor for the given pair of units.

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit conversion","description":"Convert Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}}},"schemas":{"ConversionFactorPayload":{"type":"object","properties":{"commandUuid":{"description":"Optional client-generated identifier used to correlate a conversion command across request, response, and logs.","type":"string"},"input":{"$ref":"#/components/schemas/ConversionFactorInput"}},"required":["input"]},"ConversionFactorInput":{"description":"The input is the conversion parameters object containing the source unit code, target unit code, and the amount to convert (amount required for convert-unit, optional for conversion-factor).","type":"object","properties":{"sourceUnitAmount":{"type":"number"},"sourceUnit":{"type":"string","description":"The source unit code."},"targetUnit":{"type":"string","description":"The target unit code."}},"required":["sourceUnit","targetUnit"]},"ConversionFactorResponse":{"type":"object","properties":{"commandUuid":{"type":"string"},"input":{"$ref":"#/components/schemas/ConversionFactorInput"},"output":{"$ref":"#/components/schemas/ConversionFactorOutput"}}},"ConversionFactorOutput":{"description":"Output payload","properties":{"conversionFactor":{"type":"number","description":"The conversion factor."}}},"BadConversionRequest400":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."}}},"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"NotFound404":{"properties":{"unitCode":{"type":"string","description":"The code of the requested unit."},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message."}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}},"responses":{"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}}},"paths":{"/unit-handling/{tenant}/units/conversion-factor-commands":{"put":{"tags":["Unit conversion"],"summary":"Fetching conversion factor","description":"Calculates conversion factor for the given pair of units.","parameters":[{"$ref":"#/components/parameters/tenant-path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionFactorPayload"}}}},"responses":{"201":{"description":"The factor has been successfully calculated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionFactorResponse"}}}},"400":{"description":"The conversion factor cannot be fetched due to wrong parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadConversionRequest400"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"404":{"description":"At least one of the specified units cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound404"}}}},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"PUT-unit-handling-calculate-conversion-factor"}}}}
```

## Converting unit

> Converts the source unit to a target unit.

```json
{"openapi":"3.0.0","info":{"title":"Unit Handling Service","version":"0.0.1"},"tags":[{"name":"Unit conversion","description":"Convert Units"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":[]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"unithandling.unit_manage":"Needed to manage measurement units."}}}}},"parameters":{"tenant-path":{"in":"path","name":"tenant","required":true,"description":"The tenant name.","schema":{"type":"string"}}},"schemas":{"ConversionPayload":{"type":"object","properties":{"commandUuid":{"type":"string"},"input":{"$ref":"#/components/schemas/ConversionInput"}},"required":["input"]},"ConversionInput":{"description":"The input payload for conversion. Contains the source unit code, target unit code, and optionally the source unit amount to convert.","type":"object","properties":{"sourceUnitAmount":{"type":"number","description":"The source unit quantity."},"sourceUnit":{"type":"string","description":"The source unit code."},"targetUnit":{"type":"string","description":"The target unit code."}},"required":["sourceUnit","targetUnit"]},"ConversionResponse":{"type":"object","properties":{"commandUuid":{"type":"string"},"input":{"$ref":"#/components/schemas/ConversionInput"},"output":{"$ref":"#/components/schemas/ConversionOutput"}}},"ConversionOutput":{"description":"Output payload. Contains the computed result of a conversion factor - conversionFactor (number) and unit conversion - targetUnitAmount (number) and targetUnit (string).","properties":{"targetUnitAmount":{"type":"number","description":"The amount in the target unit after conversion from the source unit."},"targetUnit":{"type":"string","description":"The target unit."}}},"BadConversionRequest400":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status Description."},"message":{"type":"string","description":"Error message."}}},"Unauthorized401":{"properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"NotFound404":{"properties":{"unitCode":{"type":"string","description":"The code of the requested unit."},"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message."}}},"UnexpectedError":{"properties":{"code":{"type":"integer","description":"HTTP Status Code."},"status":{"type":"string","description":"HTTP Status."},"message":{"type":"string","description":"Detailed error message"}}}},"responses":{"UnauthorizedResponse401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired.\n\nDetails will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized401"}}}},"ServerErrorResponse500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnexpectedError"}}}}}},"paths":{"/unit-handling/{tenant}/units/convert-unit-commands":{"put":{"tags":["Unit conversion"],"summary":"Converting unit","description":"Converts the source unit to a target unit.","parameters":[{"$ref":"#/components/parameters/tenant-path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionPayload"}}},"description":""},"responses":{"201":{"description":"The unit has ben successfully converted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionResponse"}}}},"400":{"description":"The unit cannot be converted due to wrong parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadConversionRequest400"}}}},"401":{"$ref":"#/components/responses/UnauthorizedResponse401"},"404":{"description":"At least one of the specified units cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFound404"}}}},"500":{"$ref":"#/components/responses/ServerErrorResponse500"}},"operationId":"PUT-unit-handling-convert-unit"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/api-references/api-guides/configuration/unit-handling-service/api-reference/unit-conversion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.