ATMOS DOCS

API Reference

Getting Started

ATMOS is distributed on RapidAPI. Subscribe to a plan (BASIC is free — 100 calls a month, no card), then call the endpoints through the RapidAPI gateway with your X-RapidAPI-Key. All endpoints are GET and return JSON. Every data endpoint takes either lat + lon or a free-text location.

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/air/current?location=Port%20of%20Spain' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

Authentication

All access is through RapidAPI. Send your X-RapidAPI-Key and X-RapidAPI-Host headers with every request. RapidAPI forwards a proxy secret to the origin, which rejects any un-proxied call with a 403 — so you always route through RapidAPI (only /health is open).

Air Quality

Current conditions, 5-day forecast, and historical air quality by location.

GET/v1/air/current

Current AQI (US + European), pollutants, dominant pollutant, and health guidance — nearest OpenAQ station blended with the Open-Meteo CAMS model.

Parameters

Param	Type	Required	Description
location	string	optional	Free-text place name (geocoded & cached). Use this OR lat + lon.e.g. Port of Spain
lat	number	optional	Latitude (use with lon).e.g. 10.6667
lon	number	optional	Longitude (use with lat).e.g. -61.5189

Response

{
  "status": "ok",
  "location": { "name": "Port of Spain, TT", "lat": 10.6667, "lon": -61.5189 },
  "data": {
    "aqi_us": 42,
    "aqi_eu": 2,
    "category": "Good",
    "dominant_pollutant": "pm25",
    "pollutants": { "pm25": 9.4, "pm10": 16.1, "o3": 61.2, "no2": 22.8, "so2": 1.1, "co": 210 },
    "health_guidance": "Air quality is good — ideal for outdoor activity.",
    "measurement_type": "station"
  },
  "sources": ["openaq", "open-meteo"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/air/current?location=Port%20of%20Spain' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

GET/v1/air/forecast

5-day air-quality forecast — daily max AQI and pollutant breakdown (AirNow for US locations).

Parameters

Param	Type	Required	Description
location	string	optional	Free-text place name (geocoded & cached). Use this OR lat + lon.e.g. Port of Spain
lat	number	optional	Latitude (use with lon).e.g. 10.6667
lon	number	optional	Longitude (use with lat).e.g. -61.5189

Response

{
  "status": "ok",
  "location": { "name": "Phoenix, US", "lat": 33.45, "lon": -112.07 },
  "data": {
    "forecast": [
      { "date": "2026-07-19", "aqi_us_max": 78, "category": "Moderate", "dominant_pollutant": "o3", "pm25": 18.9 },
      { "date": "2026-07-20", "aqi_us_max": 92, "category": "Moderate", "dominant_pollutant": "o3", "pm25": 24.1 },
      { "date": "2026-07-21", "aqi_us_max": 105, "category": "Unhealthy (SG)", "dominant_pollutant": "pm25", "pm25": 31.5 }
    ]
  },
  "sources": ["open-meteo", "airnow"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/air/forecast?location=Phoenix' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

GET/v1/air/history

Historical AQI/PM2.5 averages, unhealthy-day count, and trend over a chosen window.

Parameters

Param	Type	Required	Description
location	string	optional	Free-text place name (geocoded & cached). Use this OR lat + lon.e.g. Port of Spain
lat	number	optional	Latitude (use with lon).e.g. 10.6667
lon	number	optional	Longitude (use with lat).e.g. -61.5189
days	integer	optional	Look-back window, 7–365. Default 30.e.g. 90

Response

{
  "status": "ok",
  "location": { "name": "London, GB", "lat": 51.5074, "lon": -0.1278 },
  "data": {
    "days": 90,
    "avg_aqi_us": 48,
    "avg_pm25": 11.7,
    "unhealthy_days": 4,
    "trend": "improving",
    "series": [
      { "date": "2026-04-20", "aqi_us": 52, "pm25": 12.9 },
      { "date": "2026-04-21", "aqi_us": 45, "pm25": 10.4 }
    ]
  },
  "sources": ["openaq"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/air/history?location=London&days=90' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

Climate

Current weather, decades of history, and computed climate trends.

GET/v1/climate/current

Current weather — temperature, feels-like, humidity, wind, precipitation, and UV index.

Parameters

Param	Type	Required	Description
location	string	optional	Free-text place name (geocoded & cached). Use this OR lat + lon.e.g. Port of Spain
lat	number	optional	Latitude (use with lon).e.g. 10.6667
lon	number	optional	Longitude (use with lat).e.g. -61.5189

Response

{
  "status": "ok",
  "location": { "name": "Port of Spain, TT", "lat": 10.6667, "lon": -61.5189 },
  "data": {
    "temperature_c": 30.4,
    "feels_like_c": 34.1,
    "humidity_pct": 78,
    "wind_speed_kmh": 12.5,
    "precipitation_mm": 0.0,
    "uv_index": 9.2
  },
  "sources": ["open-meteo"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/climate/current?location=Port%20of%20Spain' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

GET/v1/climate/history

Per-year temperature, precipitation, and extreme-heat aggregates (1970–present, ≤30-year span).

Parameters

Param	Type	Required	Description
location	string	optional	Free-text place name (geocoded & cached). Use this OR lat + lon.e.g. Port of Spain
lat	number	optional	Latitude (use with lon).e.g. 10.6667
lon	number	optional	Longitude (use with lat).e.g. -61.5189
start_year	integer	required	First year (≥ 1970).e.g. 2000
end_year	integer	required	Last year. Span must be ≤ 30 years.e.g. 2020

Response

{
  "status": "ok",
  "location": { "name": "Phoenix, US", "lat": 33.45, "lon": -112.07 },
  "data": {
    "start_year": 2000,
    "end_year": 2020,
    "annual": [
      { "year": 2000, "tmax_mean_c": 30.9, "tmin_mean_c": 16.1, "precip_mm": 210, "extreme_heat_days": 108 },
      { "year": 2020, "tmax_mean_c": 32.4, "tmin_mean_c": 17.8, "precip_mm": 142, "extreme_heat_days": 145 }
    ]
  },
  "sources": ["open-meteo"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/climate/history?lat=33.45&lon=-112.07&start_year=2000&end_year=2020' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

GET/v1/climate/trends

Warming (°C/decade), precipitation, and extreme-heat-day trends, with a confidence note.

Parameters

Param	Type	Required	Description
location	string	optional	Free-text place name (geocoded & cached). Use this OR lat + lon.e.g. Port of Spain
lat	number	optional	Latitude (use with lon).e.g. 10.6667
lon	number	optional	Longitude (use with lat).e.g. -61.5189

Response

{
  "status": "ok",
  "location": { "name": "Phoenix, US", "lat": 33.45, "lon": -112.07 },
  "data": {
    "warming_c_per_decade": 0.48,
    "precipitation_trend_mm_per_decade": -34,
    "extreme_heat_days_trend_per_decade": 6.2,
    "baseline_period": "2005-2024",
    "confidence": "high"
  },
  "sources": ["open-meteo"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/climate/trends?location=Phoenix' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

Risk

The signature composite risk score, and side-by-side location comparison.

GET/v1/risk/score

Composite 0–100 climate risk with heat / air-quality / precipitation subscores, each graded A–F and explained.

Parameters

Param	Type	Required	Description
location	string	optional	Free-text place name (geocoded & cached). Use this OR lat + lon.e.g. Port of Spain
lat	number	optional	Latitude (use with lon).e.g. 10.6667
lon	number	optional	Longitude (use with lat).e.g. -61.5189

Response

{
  "status": "ok",
  "location": { "name": "Phoenix, US", "lat": 33.45, "lon": -112.07 },
  "data": {
    "score": 68,
    "grade": "D",
    "subscores": {
      "heat_risk": { "score": 74, "grade": "D", "explanation": "Averages 61 extreme-heat days/yr with a 0.48 °C/decade warming trend." },
      "air_quality_risk": { "score": 66, "grade": "D", "explanation": "Mean US AQI of 96 over the last 12 months; unhealthy on 14% of days." },
      "precipitation_volatility": { "score": 61, "grade": "D", "explanation": "Annual precipitation varies with a coefficient of variation of 0.34." }
    },
    "formula": "0.40*heat + 0.35*air + 0.25*precip"
  },
  "sources": ["open-meteo", "openaq"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/risk/score?location=Phoenix' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

GET/v1/compare

Compare current AQI and risk score across 2–5 locations, side by side.

Parameters

Param	Type	Required	Description
locations	string	required	2–5 comma-separated place names.e.g. Phoenix,London,Tokyo

Response

{
  "status": "ok",
  "location": null,
  "data": {
    "comparison": [
      { "name": "Phoenix, US", "aqi_us": 66, "risk_score": 68, "grade": "D" },
      { "name": "London, GB", "aqi_us": 42, "risk_score": 38, "grade": "B" },
      { "name": "Tokyo, JP", "aqi_us": 51, "risk_score": 45, "grade": "C" }
    ]
  },
  "sources": ["open-meteo", "openaq"],
  "generated_at": "2026-07-18T14:00:00Z"
}

Request

curl --request GET \
  --url 'https://atmos-climate-air-quality-intelligence.p.rapidapi.com/v1/compare?locations=Phoenix,London,Tokyo' \
  --header 'X-RapidAPI-Key: YOUR_KEY' \
  --header 'X-RapidAPI-Host: atmos-climate-air-quality-intelligence.p.rapidapi.com'

Errors

ATMOS uses standard HTTP status codes. Error responses include a JSON body with error and message fields.

Code	Meaning
200	OK — standard envelope: { status, location, data, sources, generated_at }.
422	Invalid input — e.g. a year span over 30 years. Returns { status: "error", error }.
403	Missing or incorrect proxy secret — the request didn't come through RapidAPI.
503	Upstream is down and there's no cached data. ATMOS never fabricates numbers.

Quotas & caching

Your monthly request quota is set by your RapidAPI plan — 100 (BASIC), 10k (PRO), 100k (ULTRA), or 1M (MEGA) — and RapidAPI enforces it. Responses are cached (current conditions 15 min, forecasts 1 hour, history / trends / risk 24 hours), so repeat calls are fast and don't re-hit upstream. Two headers help you debug:

X-ATMOS-Cache: hit        # hit | miss | n-a
X-ATMOS-Latency-ms: 142

Changelog

v1.0.0Initial public release — 9 endpoints across Air Quality, Climate, Risk, and Meta.

API Reference

Getting Started

Authentication

Air Quality

Parameters

Response

Request

Parameters

Response

Request

Parameters

Response

Request

Climate

Parameters

Response

Request

Parameters

Response

Request

Parameters

Response

Request

Risk

Parameters

Response

Request

Parameters

Response

Request

Meta

Response

Request

Errors

Quotas & caching

Changelog