Endpoint
GET https://www.getclimetry.com/api/tools/humidity?units=si&air_temperature=22&relative_humidity=60
Give the air temperature and exactly one of relative humidity or dew point. Inputs are named numbers in the unit system you choose; natural-language questions are not interpreted. Machine-readable description: OpenAPI 3.1.
Parameters
| Name | Use | Meaning and limits |
|---|---|---|
units | required | si or us. si: °C, kPa, g/kg, g/m³. us: °F, inHg, gr/lb, gr/ft³. Applies to all inputs and outputs; RH is always %. |
air_temperature | required | Dry-bulb air temperature, 0.01 to 60 °C · 32.02 to 140 °F. |
relative_humidity | one of | RH over liquid water, 1 to 100 %. |
dew_point | one of | Dew point, 0.01 °C (32.02 °F) up to the air temperature. |
surface_temperature | optional | Surface for the condensation check, -40 to 80 °C · -40 to 176 °F. |
pressure | optional | Air pressure, 50 to 110 kPa · 14.77 to 32.48 inHg. Default 101.325 kPa (29.92 inHg). |
Numbers use a dot as decimal separator, for example -3.5.
Response
Every quantity has value (unrounded, in the chosen units), unit and display (rounded as on the page). A quantity that does not exist for this air, such as the dew point of very dry air, has value: null and a reason; the API never returns NaN, Infinity or a substitute value. model names the equations and the model version; warnings lists assumptions that apply to this result, such as the default pressure or the frost-point case.
RH is defined over liquid water. Saturation over water follows IAPWS SR1-86, over ice IAPWS R14-08; the enhancement factor is not applied. Details and sources are on the calculator page.
Examples
Dew point from temperature and RH (SI)
curl "https://www.getclimetry.com/api/tools/humidity?units=si&air_temperature=22&relative_humidity=60"HTTP 200:
{
"model": {
"id": "climetry-moist-air",
"version": "1.0.0",
"api_version": "1",
"saturation_over_water": "IAPWS SR1-86(1992), eq. (1)",
"saturation_over_ice": "IAPWS R14-08(2011), eq. (6)",
"molar_masses": "CIPM-2007 (Picard et al. 2008)",
"relative_humidity_reference": "liquid water",
"enhancement_factor": "not applied (f = 1); humidity ratio and vapour pressure can be about 0.4 % lower than with it at 20 °C and 101.325 kPa",
"gas_model": "ideal mixture"
},
"units": "si",
"mode": "rh-to-dew-point",
"inputs": {
"air_temperature": {
"value": 22,
"unit": "°C"
},
"relative_humidity": {
"value": 60,
"unit": "%"
},
"pressure": {
"value": 101.325,
"unit": "kPa",
"source": "default"
},
"surface_temperature": null
},
"results": {
"relative_humidity": {
"value": 60,
"unit": "%",
"display": "60.0"
},
"dew_point": {
"value": 13.886541634658888,
"unit": "°C",
"display": "13.9"
},
"frost_point": {
"value": null,
"unit": "°C",
"display": null,
"reason": "Not reported: the air has a dew point at or above 0.01 °C. A frost point is given only when the water vapour pressure is below 611.657 Pa."
},
"vapour_pressure": {
"value": 1.5871338766240604,
"unit": "kPa",
"display": "1.587"
},
"humidity_ratio": {
"value": 9.897239410156567,
"unit": "g/kg",
"display": "9.90"
},
"absolute_humidity": {
"value": 11.651386405916266,
"unit": "g/m³",
"display": "11.65"
}
},
"surface": null,
"warnings": [
"No pressure given: standard sea-level pressure (101.325 kPa, 29.92 inHg) was used. It affects humidity ratio, not RH or dew point."
]
}RH from dew point with a surface check (US)
curl "https://www.getclimetry.com/api/tools/humidity?units=us&air_temperature=75&dew_point=55&surface_temperature=50&pressure=29.5"HTTP 200:
{
"model": {
"id": "climetry-moist-air",
"version": "1.0.0",
"api_version": "1",
"saturation_over_water": "IAPWS SR1-86(1992), eq. (1)",
"saturation_over_ice": "IAPWS R14-08(2011), eq. (6)",
"molar_masses": "CIPM-2007 (Picard et al. 2008)",
"relative_humidity_reference": "liquid water",
"enhancement_factor": "not applied (f = 1); humidity ratio and vapour pressure can be about 0.4 % lower than with it at 20 °C and 101.325 kPa",
"gas_model": "ideal mixture"
},
"units": "us",
"mode": "dew-point-to-rh",
"inputs": {
"air_temperature": {
"value": 75,
"unit": "°F"
},
"dew_point": {
"value": 55,
"unit": "°F"
},
"pressure": {
"value": 29.5,
"unit": "inHg",
"source": "input"
},
"surface_temperature": {
"value": 50,
"unit": "°F"
}
},
"results": {
"relative_humidity": {
"value": 49.77880134960698,
"unit": "%",
"display": "49.8"
},
"dew_point": {
"value": 55,
"unit": "°F",
"display": "55.0"
},
"frost_point": {
"value": null,
"unit": "°F",
"display": null,
"reason": "Not reported: the air has a dew point at or above 0.01 °C. A frost point is given only when the water vapour pressure is below 611.657 Pa."
},
"vapour_pressure": {
"value": 0.4359650284539331,
"unit": "inHg",
"display": "0.436"
},
"humidity_ratio": {
"value": 65.30619372335217,
"unit": "gr/lb",
"display": "65.3"
},
"absolute_humidity": {
"value": 4.706078910550021,
"unit": "gr/ft³",
"display": "4.71"
}
},
"surface": {
"reference": "dew point",
"reference_temperature": {
"value": 55,
"unit": "°F",
"display": "55.0"
},
"margin": {
"value": -5.000000000000002,
"unit": "°F",
"display": "−5.0"
},
"reaches_reference": true,
"surface_below_freezing": false
},
"warnings": [
"The surface check compares two temperatures. It does not include sensor uncertainty, the air layer next to the surface or temperature differences across a part, and it is not a safe margin."
]
}Very dry air: no dew point, a frost point instead
curl "https://www.getclimetry.com/api/tools/humidity?units=si&air_temperature=30&relative_humidity=3"HTTP 200:
{
"model": {
"id": "climetry-moist-air",
"version": "1.0.0",
"api_version": "1",
"saturation_over_water": "IAPWS SR1-86(1992), eq. (1)",
"saturation_over_ice": "IAPWS R14-08(2011), eq. (6)",
"molar_masses": "CIPM-2007 (Picard et al. 2008)",
"relative_humidity_reference": "liquid water",
"enhancement_factor": "not applied (f = 1); humidity ratio and vapour pressure can be about 0.4 % lower than with it at 20 °C and 101.325 kPa",
"gas_model": "ideal mixture"
},
"units": "si",
"mode": "rh-to-dew-point",
"inputs": {
"air_temperature": {
"value": 30,
"unit": "°C"
},
"relative_humidity": {
"value": 3,
"unit": "%"
},
"pressure": {
"value": 101.325,
"unit": "kPa",
"source": "default"
},
"surface_temperature": null
},
"results": {
"relative_humidity": {
"value": 3,
"unit": "%",
"display": "3.0"
},
"dew_point": {
"value": null,
"unit": "°C",
"display": null,
"reason": "No dew point at or above 0.01 °C: the water vapour pressure is below 611.657 Pa (triple point), so water vapour from this air deposits as frost. See frost_point."
},
"frost_point": {
"value": -17.78917869106796,
"unit": "°C",
"display": "−17.8"
},
"vapour_pressure": {
"value": 0.12740759781456373,
"unit": "kPa",
"display": "0.127"
},
"humidity_ratio": {
"value": 0.7830432202669809,
"unit": "g/kg",
"display": "0.78"
},
"absolute_humidity": {
"value": 0.9106355200557099,
"unit": "g/m³",
"display": "0.91"
}
},
"surface": null,
"warnings": [
"No pressure given: standard sea-level pressure (101.325 kPa, 29.92 inHg) was used. It affects humidity ratio, not RH or dew point.",
"This air has a frost point instead of a dew point above 0.01 °C. It cannot be entered in dew_point mode; use relative_humidity."
]
}Error: dew point above the air temperature
curl "https://www.getclimetry.com/api/tools/humidity?units=si&air_temperature=22&dew_point=25"HTTP 400:
{
"error": {
"code": "invalid_input",
"message": "One or more inputs are outside the supported range or inconsistent.",
"fields": {
"dew_point": "The dew point cannot be higher than the air temperature: such air would hold more water vapour than it can at saturation."
}
},
"model": {
"id": "climetry-moist-air",
"version": "1.0.0",
"api_version": "1",
"saturation_over_water": "IAPWS SR1-86(1992), eq. (1)",
"saturation_over_ice": "IAPWS R14-08(2011), eq. (6)",
"molar_masses": "CIPM-2007 (Picard et al. 2008)",
"relative_humidity_reference": "liquid water",
"enhancement_factor": "not applied (f = 1); humidity ratio and vapour pressure can be about 0.4 % lower than with it at 20 °C and 101.325 kPa",
"gas_model": "ideal mixture"
},
"documentation": "https://www.getclimetry.com/tools/relative-humidity-calculator/api"
}Errors
Errors return HTTP 400 (414 for an overlong query) with error.code, error.message and, where it applies, error.fields with an explanation per parameter in the requested units.
| Code | When |
|---|---|
unknown_parameter | A parameter not listed above, including free text such as q=. |
duplicate_parameter | The same parameter twice. |
missing_parameter | units, air_temperature, or both relative_humidity and dew_point missing. |
invalid_units | units is not si or us. |
conflicting_parameters | Both relative_humidity and dew_point given. |
invalid_number | Not a plain decimal number (comma, exponent, unit, NaN, empty). |
invalid_input | Outside the range above, or dew point above the air temperature. error.fields explains each parameter. |
query_too_long | Query string longer than 1024 characters (HTTP 414). |
Use and limits
The endpoint only calculates: it reads no cookies, needs no account and stores nothing. Responses depend only on the query and may be cached for a day. Any website may call it from the browser (CORS). There is no service-level guarantee, and there is no per-client rate limit of its own beyond the hosting platform's protection; please cache results instead of repeating identical requests.
It evaluates one air state that you give it. It has no site or weather data; for climatic humidity exposure at a location, see site analysis.