Last updated 19 November 2012. Created on 7 January 2009.
Edited by raspberryman, LeeHunter, quicksketch, quantumized. Log in to edit this page.

Units API converts between various weights and measurements. The conversion uses the International System of Units (SI) conversion factors. Where possible, these conversion factors are those provided by the U.S. National Institute of Standards and Technology (NIST) Special Publication 811, 2008 Edition. If the NIST does not provide the conversion factor, other sources may be used as long as the work is GPL compatible.

The central API call, unitsapi_convert($value, $from, $to, $details = FALSE), returns the result of the conversion. By setting $default = TRUE, the result is an array that contains the converted value, plus the full name of the units involved in the conversion (singular or plural, depending on the result).

This module is only an API and does not have an user interface.


There are hundreds of measurement units found throughout the world, and this module does not intend to support them all. To determine which units should be supported, the module developers use their own best guess as to which units are most popular. If you would like a specific measurement unit supported, please submit a feature request with Units API.

A list of supported units, and the keys you need to pass to the unitsapi_convert() function, are available on the module's help page.


// Convert kilometer to feet
$result = unitsapi_convert(1.5, 'kilometer', 'foot');
// $result == 4921.259843

// Convert Fahrenheit to Kelvin
$result = unitsapi_convert(55, 'fahrenheit', 'kelvin');
// $result == 285.927778 

// Convert US liquid ounces to Imperial pints with a detailed array of the conversion
$result = unitsapi_convert(50, 'us fluid ounce', 'imperial pint', TRUE);
// $result == Array ([result] => 2.602107, [from] => US fluid ounces, [to] => Imperial pints)


Use hook_unitsapi($data) to make changes to the units array. For example:

 * Implementation of hook_unitsapi().
function mymodule_unitsapi() {
  $data['meter']['singular'] = 'metre';
  return $data;


Every measurement unit should have its own unit test using the assertion: $this->assertUnitConversion($value, $from, $to, $expected, $group). If you submit a new kind of unit, please also submit an example conversion for this test.

Looking for support? Visit the forums, or join #drupal-support in IRC.