# Calculation criteria

The `criteria` object specifies the mathematical operation to perform and the input values to use in the operation.

The `Calculate` method supports the following operations:

- `FindDistance`

  This operation calculates the distance between two locations. The operation takes as input the coordinates of the source location and target location. The return value is the distance in meters.

- `FindBearingTo`

  This operation calculates the bearing to a target location from a source location. The operation takes as input the coordinates of the source location and target location. The return value is the bearing in degrees counting clockwise relative to true north.

- `MoveCoordinates`

  This operation calculates a new location based on movement from a source location. The operation takes as input the coordinates of the source location, the distance moved, and the direction of the movement. The return value consists of the coordinates of the new location.

The operations require different input parameters, as summarized in the following table. The properties that contain the input are described in detail in Table: Criteria object properties. The return values are described in section Calculation results.

Table: Supported operations and their input
Operation | Input
--- | ---
`FindDistance` | `DistanceParamSource` `DistanceParamDestination`
`FindBearingTo` | `DistanceParamSource` `DistanceParamDestination`
`MoveCoordinates` | `DistanceParamSource` `MoveByThisDistance` `MoveByThisBearing`

Note: If a longitude or latitude value in the input is outside the expected range (see the following table), the system attempts to correct the value automatically. For example, if longitude is set to +185 and latitude to +45, this is passed on as longitude -175 and latitude +45, since +185 is outside the expected longitude range of [+180.00, -180.00].

Moreover, if a latitude value is outside the expected range, the system may need to adjust both the latitude and longitude to arrive at the correct coordinates. For example, if longitude is set to +10 and latitude to +95, a point on the Western hemisphere near the North Pole, these are adjusted to longitude -170 and latitude +85. In this case, it is necessary to adjust both values to maintain the correct location, even though only the original latitude value is outside the expected range. If only the latitude value were adjusted, the coordinates (longitude +10, latitude +85) would point to a location on the Eastern hemisphere.

The following table describes the properties of the `criteria` object. Properties enclosed in brackets are optional.

Table: Criteria object properties
Property | Description | Type | Value
--- | --- | --- | ---
`criteria.MathRequest` | Specifies the mathematical operation to perform. | string | Possible values: `"FindDistance"` `"FindBearingTo"` `"MoveCoordinates"`
`criteria.DistanceParamSource` | Specifies the coordinates of the source location. Use the WGS 84 datum with decimal degree representation to reference coordinates. | object | Object with the properties specified below
`criteria.DistanceParamSource.Longitude` | Specifies the longitude coordinate of the source location. | number | [+180.00, -180.00]
`criteria.DistanceParamSource.Latitude` | Specifies the latitude coordinate of the source location. | number | [+90.00, -90.00]
`criteria.DistanceParamSource.Altitude` | Specifies the altitude coordinate of the source location. The altitude value does not affect the result of the calculation. It is included to maintain a uniform input argument. | number | Any integer or decimal
`[criteria.DistanceParamDestination]` | Specifies the coordinates of the target location. This property and its child properties are required when `MathRequest` is set to `FindDistance` or `FindBearingTo`. Use the WGS 84 datum with decimal degree representation to reference coordinates. | object | Object with the properties specified below
`[criteria.DistanceParamDestination.Longitude]` | Specifies the longitude coordinate of the target location. | number | [+180.00, -180.00]
`[criteria.DistanceParamDestination.Latitude]` | Specifies the latitude coordinate of the target location. | number | [+90.00, -90.00]
`[criteria.DistanceParamDestination.Altitude]` | Specifies the altitude coordinate of the target location. The altitude value does not affect the result of the calculation. It is included to maintain a uniform input argument. | number | Any integer or decimal
`[criteria.MoveByThisDistance]` | Specifies the distance moved, that is, the distance between the source location and the new location. The distance is in meters. This property is required when `MathRequest` is set to `MoveCoordinates`. | number | Any integer or decimal
`[criteria.MoveByThisBearing]` | Specifies the direction of movement from the source location. The direction is expressed in degrees counting clockwise relative to true north. This property is required when `MathRequest` is set to `MoveCoordinates`. | number | Any integer or decimal