Seasonality and Demand Controls Explained
Model controls change the strength of AirROI's date-specific effects. They do not enable custom pricing rules, change your base price, or establish price limits.
Compare sensitivity choices side by side
Same synthetic +20% seasonality and +10% demand, four sensitivity choices.
Sensitivity scales the distance from a neutral multiplier of 1, not the entire price. For a +20% model effect, 50% sensitivity gives a +10% effect. It does not halve the nightly rate.
What each switch does—and does not do
| Setting | Changes | Leaves untouched |
|---|---|---|
| seasonality_sensitivity_percent | Seasonal, modeled weekday, and holiday/event factors | Base price and your custom weekday policy |
| demand_sensitivity_percent | Market-demand effect, within its effective bounds | Your occupancy-pacing matrix |
| apply_negative_demand_adjustments: false | Suppresses negative model-demand adjustments | Negative seasonality and custom discounts |
At zero demand sensitivity, you remove that model effect. You do not create missing market evidence or turn off your own occupancy rule. Keep model-demand evidence warnings separate from calendar-evidence warnings in your integration.
Start with defaults
Both sensitivity controls default to 100%, meaning the model effect is used as supplied. Change a control only when you can explain which behavior you want to change; compare the resulting explanation lines before publishing.
The JSON below is an addition to this complete Calendar Prices request. Merge fields into one request; do not send a rule fragment by itself.
{
"location": {
"latitude": 25.7907,
"longitude": -80.13
},
"currency": "USD",
"base_price": 200
}
All worked prices use USD and start from a $200 base price before model effects, with no custom rules unless stated. They demonstrate arithmetic, not live forecasts.
Scale model effects
{
"advanced": {
"seasonality_sensitivity_percent": 50,
"demand_sensitivity_percent": 150,
"apply_negative_demand_adjustments": false
}
}
seasonality_sensitivity_percent scales seasonality, modeled weekday, and
holiday/event effects: at 50, a model +20% becomes +10%.
demand_sensitivity_percent scales demand: at 150, a model +10% becomes +15%.
Both accept 0–200 and default to 100; zero removes the corresponding effect.
For example, with only a +20% seasonal effect and +10% demand effect, these
settings give 200 × 1.10 × 1.15 = 253. The effective demand adjustment
is bounded to −15% / +400%. Setting apply_negative_demand_adjustments
to false suppresses negative demand effects and omits their explanation line;
the default is true. Increasing seasonal sensitivity above 100 can return
503 if a scaled model factor becomes zero or negative.
Compare the same synthetic model inputs
Assume a $200 base price, only a +20% seasonal effect and +10% demand effect, with no custom rules and default limits that do not affect these outcomes:
| Seasonal sensitivity | Demand sensitivity | Calculation | USD |
|---|---|---|---|
| 100 | 100 | 200 × 1.20 × 1.10 | 264 |
| 50 | 150 | 200 × 1.10 × 1.15 | 253 |
| 0 | 100 | 200 × 1.00 × 1.10 | 220 |
| 100 | 0 | 200 × 1.20 × 1.00 | 240 |
Negative demand is a separate choice
With a $200 running price and a −10% demand effect, the default behavior produces $180. Turning off negative demand adjustments keeps it at $200 and omits that demand contribution. It does not suppress negative seasonality or your custom discounts.
Unavailable demand evidence is different from choosing to disable negative demand: inspect response warnings. See warnings and recovery.
Change one control, then compare
Keep the base price and custom rules unchanged while comparing a model control with its default. Read the seasonal and demand contributions before judging the final rate; later rules and limits may change the result again. Use the calculation guide to follow that sequence.
Read small demand adjustments
Calendar Prices displays the market-demand percentage to one decimal place, for example +1.2% or −0.3%. The nightly price and currency contribution use the full published factor, so do not recalculate them from the rounded percentage. A factor small enough to display as 0.0% can still affect the returned price.
New demand scoring retains supported adjustments below 2%; evidence checks and factor limits still apply. Previously published calendars keep their original factors until the next pricing-data release. Removing the cutoff in code cannot recover values already replaced with neutral factors in an older release.
