ArealUnitConversionFactor

Summary

Returns the factor for converting an area measurement to a different areal unit.

Discussion

The area units supported by the function are the same units returned from the geoprocessing Area Units parameter data type with the exception of Unknown, in which only known units can be converted.

Learn more about geoprocessing units of measurement

Syntax

ArealUnitConversionFactor (from_unit, to_unit)
ParameterExplanationData Type
from_unit

The original or source areal unit.

  • SquareKilometersSquare kilometers
  • HectaresHectares
  • AresAres
  • SquareMetersSquare meters
  • SquareDecimetersSquare decimeters
  • SquareCentimetersSquare centimeters
  • SquareMillimetersSquare millimeters
  • SquareMilesIntSquare statute miles
  • AcresIntInternational acres
  • SquareYardsIntSquare international yards
  • SquareFeetIntSquare international feet
  • SquareInchesIntSquare international inches
  • SquareMilesUSSquare US survey miles
  • AcresUSSquare US survey acres
  • SquareYardsUSSquare US survey yards
  • SquareFeetUSSquare US survey feet
  • SquareInchesUSSquare US survey inches
String
to_unit

The destination areal unit.

  • SquareKilometersSquare kilometers
  • HectaresHectares
  • AresAres
  • SquareMetersSquare meters
  • SquareDecimetersSquare decimeters
  • SquareCentimetersSquare centimeters
  • SquareMillimetersSquare millimeters
  • SquareMilesIntSquare statute miles
  • AcresIntInternational acres
  • SquareYardsIntSquare international yards
  • SquareFeetIntSquare international feet
  • SquareInchesIntSquare international inches
  • SquareMilesUSSquare US survey miles
  • AcresUSSquare US survey acres
  • SquareYardsUSSquare US survey yards
  • SquareFeetUSSquare US survey feet
  • SquareInchesUSSquare US survey inches
String
Return Value
Data TypeExplanation
Double

The conversion factor for converting values between the two areal units.

Code sample

ArealUnitConversionFactor example 1

A simple use case for converting from hectare to square kilometers.

import arcpy

# Convert an area of 10000 Hectares to SquareKilometers 
area = 10000 * arcpy.ArealUnitConversionFactor(from_unit="Hectares", to_unit="SquareKilometers")

print(area)  # This will print a value of 100.0
ArealUnitConversionFactor example 2

Within a script tool, convert a specified value to square meters for processing.



import locale
import sys

area = arcpy.GetParameter(n)  # Update n to the parameter index

area_value, area_unit = area.split(" ")  # For example, "10 Acres"

# Convert the area into "SquareMeters" as needed later in this script
try:
    conv_factor = arcpy.ArealUnitConversionFactor(area_unit, "SquareMeters")
except ValueError as e:
    # If fails, the likely area; unit is "Unknown"
    # Add code to either deal with it or produce an appropriateerror  as shown below.
    arcpy.AddError(arcpy.GetIDMessage('Invalid areal unit type.))
    sys.exit()

# Apply the conv_factor to the supplied value
# locale.atof is required for locales that don't use a period as the separator
area_square_m = locale.atof(area_value) * conv_factor

Related topics