# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.