Hotel median or mean rate configuration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This guide provides information on the hotel median/mean rate policy used in the Spotnana platform. The policy replaces a fixed price cap for hotel bookings with a dynamic maximum in-policy amount that adjusts automatically to the traveler's destination and travel dates.

The calculation and policy are applied as follows:

1. An administrator uses a rule in the company policy to set the parameters that control which hotels are comparable (e.g., 3-5-star hotels within a 20-mile radius of the search location).
2. When a traveler searches for hotels, the platform calculates either the median or mean nightly rate (depending on how you configured the system) across the comparable hotels in the search results.
3. A buffer (a percentage or a fixed amount) is applied on top of the calculated rate. Any hotel rate above the resulting amount is marked as Out of Policy.

Configuring the policy

As an administrator, you can configure the rule when creating a company policy or updating a company policy. The rule is defined in the hotelPolicyRules > hotelMedianRateNightly > hotelMedianRateProps object. The following fields define which hotel characteristics are used to calculate the rate:

Here's a sample request for the update a company policy API containing the rule configuration:

// ... payload truncated for focus
{
  "hotelPolicyRules": {
    "hotelMedianRateNightly": {
      "hotelMedianRateProps": {
        "searchRadius": {
          "length": 20,
          "unit": "MILE"
        },
        "ratingRange": {
          "min": 3,
          "max": 5
        },
        "prepaidQualifier": "INCLUDE_PREPAID",
        "refundableOnly": false,
        "statisticalMethod": "MEDIAN",
        "hideRateStatistics": false
      }
    }
  }
}

In the example above, the median nightly rate is calculated using the rates of 3-star to 5-star hotels located within 20 miles of the traveler's search location. Prepaid rates are included in the calculation. Because refundableOnly is set to false, non-refundable rates are also included.

Choosing the statistical method

The statisticalMethod field in the update a company policy API determines how the reference rate is calculated from the comparable hotels:

Set the statisticalMethod field to MEDIAN when you want the policy to reflect what a typical hotel costs in the search area, unaffected by a small number of premium or budget properties. Use MEAN when you want every rate in the search to influence the policy budget.

Setting the budget buffer

The calculated rate on its own doesn't limit what a traveler can book. To enforce a maximum price, you must add a rule of type MAX_HOTEL_BOOKING_PRICE to the rules > ruleType array in the update policy API. This rule defines the buffer applied on top of the calculated rate using the following fields in the maxHotelBookingPriceProps object:

Here's a sample request containing the buffer rule in the update a company policy API:

// ... payload truncated for focus
{
  "rules": [
    {
      "ruleType": "MAX_HOTEL_BOOKING_PRICE",
      "policyValue": {
        "universalProps": {
          "maxHotelBookingPriceProps": {
            "difference": {
              "percentage": 15
            },
            "type": "MORE_THAN_MEDIAN",
            "isTaxIncluded": true
          }
        }
      }
    }
  ]
}

In the example above, assume the calculated median rate for a search is USD 850. With a buffer of 15% above the median, the maximum in-policy amount is USD 977.50. A room with a total rate of USD 950 would be displayed as In Policy, while a room with a total rate of USD 1000 would be displayed as Out of Policy.

Reading the calculated rate statistics

If you want to understand why a specific hotel rate is in-policy or out-of-policy, view the rate statistics calculated for the search. The get hotel search results endpoint returns the calculated values in the metadata > rateStatistics object. The get hotel details endpoint returns them in the rateStatistics object.

Here's a sample response from the get hotel search results endpoint containing the rate statistics:

// ... payload truncated for focus
{
  "metadata": {
    "rateStatistics": {
      "median": {
        "total": {
          "amount": 850.00,
          "currencyCode": "USD"
        },
        "base": {
          "amount": 772.50,
          "currencyCode": "USD"
        }
      },
      "mean": {
        "total": {
          "amount": 872.40,
          "currencyCode": "USD"
        },
        "base": {
          "amount": 794.10,
          "currencyCode": "USD"
        }
      },
      "sampleSize": 42,
      "policyType": "SET_BY_ADMIN",
      "statisticalMethod": "MEDIAN"
    }
  }
}

In the example above, the rate statistics are structured as follows:

• The median and mean objects contain the calculated nightly rates, each with a total (including taxes and fees) and a base (excluding taxes and fees) amount. The value used for policy evaluation depends on how the statisticalMethod and isTaxIncluded settings are configured in the applicable policy.
• The sampleSize field indicates the number of hotels used in the calculation. In this example, 42 comparable hotels were found within the configured search radius and rating range.
• The policyType field indicates how the calculation parameters were determined. The value SET_BY_ADMIN means the parameters configured in the company policy were used, while DEFAULT means the platform's default parameters were used because the applicable policy doesn't define them.
• The statisticalMethod field indicates whether the median or the mean value is used as the reference rate for the policy evaluation.

How policy compliance is determined

For every hotel rate returned in the search results, the platform compares the rate against the maximum in-policy amount (the calculated rate plus the buffer). The comparison uses the total rate when isTaxIncluded is set to true and the base rate when it's set to false.

When a rate exceeds the maximum in-policy amount, the violation is returned in the policyInfo > ruleResultInfos > violationInfos array. The violation contains the predicate MAX_HOTEL_BOOKING_PRICE_INCLUDING_TAX, or MAX_HOTEL_BOOKING_PRICE_EXCLUDING_TAX when isTaxIncluded is set to false. The expectedValue field contains the maximum in-policy amount. The actualValue field contains the actual rate of the room being evaluated.

Here's a sample response from the get hotel details endpoint containing a violation:

// ... payload truncated for focus
{
  "policyInfo": {
    "ruleResultInfos": [
      {
        "violationInfos": [
          {
            "predicate": "MAX_HOTEL_BOOKING_PRICE_INCLUDING_TAX",
            "expectedValue": {
              "money": {
                "amount": 977.50,
                "currencyCode": "USD"
              }
            },
            "actualValue": {
              "money": {
                "amount": 1000.00,
                "currencyCode": "USD"
              }
            }
          }
        ]
      }
    ]
  }
}

In the example above, the maximum in-policy amount was calculated as USD 977.50 (a median rate of USD 850 plus a 15% buffer). The room's rate of USD 1000 exceeds that amount, so the room will be marked as Out of Policy.

Limiting the calculation to preferred properties

By default, the rate statistics are calculated using all the comparable hotels returned in the search results (see Configuring the policy). However, if you want the calculated rate to only include the rates of company preferred properties then you can limit the calculation to preferred properties only.

When updating the company policy, use the hotelPolicyRules > hotelMedianRateNightly > hotelMedianRateProps > preferredPropertiesRateStatsLimit object to set the policy rate calculation to only use company-preferred properties.

To enable the preferredPropertiesRateStatsLimit object, you must set the following 2 fields:

The calculation then works as follows:

• If the number of preferred properties among the comparable hotels is greater than or equal to minimumPreferredPropertiesRequired, the rate statistics are calculated using only the preferred properties.
• If the number of preferred properties is less than minimumPreferredPropertiesRequired, the calculation uses all the comparable hotels.

This limit only changes the set of hotels used in the calculation. The type of statistical method (median or mean) you've chosen will still apply here.

Here's a sample request for the update a company policy API containing the limit configuration:

{
  "hotelPolicyRules": {
    "hotelMedianRateNightly": {
      "hotelMedianRateProps": {
        "searchRadius": {
          "length": 20,
          "unit": "MILE"
        },
        "ratingRange": {
          "min": 3,
          "max": 5
        },
        "statisticalMethod": "MEDIAN",
        "preferredPropertiesRateStatsLimit": {
          "limitCalculationToPreferredProperties": true,
          "minimumPreferredPropertiesRequired": 3
        }
      }
    }
  }
}

With the above policy configuration in place, assume a hotel search returns 12 comparable hotels, and 4 of them are preferred properties with nightly rates of USD 210, USD 230, USD 250, and USD 290. Because 4 preferred properties meet the configured minimum of 3, the median rate is calculated as USD 240 (the average of the two middle rates, USD 230 and USD 250). In the hotel search API, the metadata > rateStatistics > sampleSize field will return the value 4.

However, if the same search returned only 2 preferred properties, the calculation would fall back to all 12 comparable hotels as it doesn't meet the requirement of the "minimumPreferredPropertiesRequired": 3 setting. In that case the sampleSize field will return the value 12.