Free, read-only JSON API for Bulgarian city air quality. Licensed CC-BY-4.0. Rate limit: 60 req/min per IP. AQI standard: US EPA 0–500.
The API is completely open — no API key required. Anyone can make requests without registration.
HTTP 429 with a Retry-After: 60 header.Access-Control-Allow-Origin: * — call from any frontend.Status
Free
Open access
Returned in the category field.
/api/v1/citiesList all monitored citiesReturns current AQI snapshots for all monitored Bulgarian cities, ordered by slug.
Responses
200Success429Rate limit exceeded. Retry after 60 seconds./api/v1/cities/{slug}Get single city snapshotReturns the current AQI snapshot and station list for a single city.
Parameters
slugpathrequiredURL-safe city identifier, e.g. `sofia`, `plovdiv`, `varna`.Responses
200Success404City not found429Rate limit exceeded./api/v1/cities/{slug}/icaliCal AQI > 100 alert feedReturns a standard `text/calendar` iCal feed with a VEVENT that is `STATUS:CONFIRMED` when the city's AQI exceeds 100, and `STATUS:CANCELLED` when it is safe. Subscribe in Google Calendar, Apple Calendar, or Outlook.
Parameters
slugpathrequiredResponses
200iCal feedAqiResultPollutantsCityRecordCityCityRowCitiesResponseCityResponsecurl
# List all cities
curl https://vuzduhbg.com/api/v1/cities
# Single city
curl https://vuzduhbg.com/api/v1/cities/sofia
# iCal AQI alert feed (subscribe in Google / Apple / Outlook Calendar)
curl https://vuzduhbg.com/api/v1/cities/sofia/ical
# Rate limit exceeded → HTTP 429
# Retry-After: 60JavaScript / TypeScript
// Fetch Sofia air quality — no auth, no key
const res = await fetch("https://vuzduhbg.com/api/v1/cities/sofia");
const { city, aqi, pollutants, updatedAt } = await res.json();
console.log(`${city.nameEn}: AQI ${aqi.aqi} (${aqi.category})`);
// → Sofia: AQI 78 (moderate)
// Poll all cities every 5 minutes
async function pollAqi() {
const { cities } = await fetch("https://vuzduhbg.com/api/v1/cities").then(r => r.json());
const worst = cities.reduce((a, b) => (a.aqi > b.aqi ? a : b));
console.log("Most polluted:", worst.nameEn, "AQI", worst.aqi);
setTimeout(pollAqi, 300_000);
}
pollAqi();Example response — GET /api/v1/cities/sofia
{
"generated": "2026-05-11T08:30:00.000Z",
"standard": "US EPA AQI (0–500)",
"documentation": "https://vuzduhbg.com/methodology",
"source": "OpenAQ v3 / ИАОС (Bulgarian EEA)",
"license": "CC-BY-4.0",
"city": {
"slug": "sofia",
"nameBg": "София",
"nameEn": "Sofia",
"lat": 42.6977,
"lon": 23.3219,
"population": 1307376
},
"aqi": {
"aqi": 78,
"category": "moderate",
"color": "#ffd166",
"rangeLabel": "51–100"
},
"pollutants": {
"pm25": 23.4,
"pm10": 41.2,
"no2": 18.1,
"o3": 55.0,
"so2": 8.3,
"co": 0.6
},
"stations": [
{ "name": "Sofia Center", "lat": 42.6977, "lon": 23.3219 },
{ "name": "Sofia North", "lat": 42.7227, "lon": 23.3039 }
],
"updatedAt": "2026-05-11T08:25:00.000Z",
"links": {
"cityPage": "https://vuzduhbg.com/city/sofia",
"widget": "https://vuzduhbg.com/widget/sofia",
"icalAlert": "https://vuzduhbg.com/api/v1/cities/sofia/ical"
}
}Display a live AQI badge on any web page or CMS using a plain <iframe>. No API key required.
<!-- Embed Sofia AQI badge -->
<iframe
src="https://vuzduhbg.com/embed/city/sofia"
width="260"
height="170"
frameborder="0"
scrolling="no"
title="Sofia air quality – VazdukhBG"
style="border-radius:16px;overflow:hidden;"
></iframe>
<!-- Available city slugs: sofia, plovdiv, varna, burgas, ruse, ... -->
<!-- Full list at /api/v1/cities -->Preview live at /embed/city/sofia. All city slugs are listed in /api/v1/cities.
Data: OpenAQ v3 / ИАОС · License: CC-BY-4.0 · Standard: US EPA AQI · ВъздухБГ