{"openapi":"3.0.3","info":{"title":"Atmospore Pollen Forecast API","description":"Global pollen forecasts with species-level accuracy. 21 individual species, 14-day forecasts, area averages with min/max, and multilingual species metadata.","version":"1.0.0","contact":{"name":"Atmospore","url":"https://atmospore.com","email":"support@atmospore.com"},"termsOfService":"https://atmospore.com/terms-of-service"},"servers":[{"url":"https://pollenapi.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key from your Atmospore account settings"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"SpeciesData":{"type":"object","properties":{"value":{"type":"number","description":"Interpolated pollen concentration"},"risk_level":{"type":"string","enum":["low","moderate","high","very high"]},"display_name":{"type":"string","description":"Human-readable species name"},"category":{"type":"string","enum":["tree","grass","weed"]}}},"AreaSpeciesData":{"type":"object","properties":{"avg":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"},"risk_level":{"type":"string","enum":["low","moderate","high","very high"]},"display_name":{"type":"string"},"category":{"type":"string","enum":["tree","grass","weed"]}}},"TopSpeciesData":{"type":"object","properties":{"species":{"type":"string"},"display_name":{"type":"string"},"category":{"type":"string","enum":["tree","grass","weed"]},"max":{"type":"number"},"avg":{"type":"number"},"risk_level":{"type":"string","enum":["low","moderate","high","very high"]}}}},"parameters":{"lon":{"name":"lon","in":"query","required":true,"schema":{"type":"number"},"description":"Longitude coordinate"},"lat":{"name":"lat","in":"query","required":true,"schema":{"type":"number"},"description":"Latitude coordinate"},"dt":{"name":"dt","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Start date (YYYY-MM-DD)"},"forecast_days":{"name":"forecast_days","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":14},"description":"Number of forecast days"},"species":{"name":"species","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated species or groups (tree, grass, weed, all). Defaults to all."},"radius":{"name":"radius","in":"query","required":false,"schema":{"type":"integer","default":25000,"maximum":50000},"description":"Search radius in meters"}}},"paths":{"/v1/pollen":{"get":{"summary":"Pollen forecast at a point","description":"Interpolated pollen forecast at a specific coordinate. Returns species-level data with risk levels and an overall daily risk score.","operationId":"getPollenForecast","parameters":[{"$ref":"#/components/parameters/lon"},{"$ref":"#/components/parameters/lat"},{"$ref":"#/components/parameters/dt"},{"$ref":"#/components/parameters/forecast_days"},{"$ref":"#/components/parameters/species"}],"responses":{"200":{"description":"Forecast data","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"location":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"units":{"type":"string","example":"grains/m³"},"generated_at":{"type":"string","format":"date-time"}}},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"overall_risk":{"type":"string","enum":["low","moderate","high","very high"]},"species":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SpeciesData"}}}}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing API key"},"403":{"description":"Invalid API key"},"429":{"description":"Daily quota exceeded"}}}},"/v1/pollen-area":{"get":{"summary":"Area pollen averages","description":"Average, minimum, and maximum pollen levels across a configurable radius. Ideal for regional dashboards and area-wide risk assessment.","operationId":"getPollenArea","parameters":[{"$ref":"#/components/parameters/lon"},{"$ref":"#/components/parameters/lat"},{"$ref":"#/components/parameters/dt"},{"$ref":"#/components/parameters/forecast_days"},{"$ref":"#/components/parameters/species"},{"$ref":"#/components/parameters/radius"}],"responses":{"200":{"description":"Area forecast data with min/max/avg","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"location":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"radius":{"type":"integer"},"units":{"type":"string"},"generated_at":{"type":"string","format":"date-time"}}},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"overall_risk":{"type":"string"},"species":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AreaSpeciesData"}}}}}}}}}},"400":{"description":"Invalid parameters"},"429":{"description":"Daily quota exceeded"}}}},"/v1/pollen-top":{"get":{"summary":"Top pollen species","description":"Top contributing species in a date range, ranked by severity. Returns max and average values aggregated across the period.","operationId":"getPollenTop","parameters":[{"$ref":"#/components/parameters/lon"},{"$ref":"#/components/parameters/lat"},{"$ref":"#/components/parameters/dt"},{"$ref":"#/components/parameters/forecast_days"}],"responses":{"200":{"description":"Top species ranked by severity","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"location":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"units":{"type":"string"},"date_range":{"type":"array","items":{"type":"string","format":"date"}},"generated_at":{"type":"string","format":"date-time"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/TopSpeciesData"}}}}}}},"400":{"description":"Invalid parameters"},"429":{"description":"Daily quota exceeded"}}}},"/v1/species":{"get":{"summary":"Species metadata","description":"All supported pollen species with display names in multiple languages, categories, and risk thresholds. No authentication required. Cache this response client-side.","operationId":"getSpecies","security":[],"responses":{"200":{"description":"Species metadata","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"total_species":{"type":"integer"},"categories":{"type":"array","items":{"type":"string"}},"risk_levels":{"type":"array","items":{"type":"string"}},"units":{"type":"string"}}},"data":{"type":"object","additionalProperties":{"type":"object","properties":{"display_name":{"type":"string"},"category":{"type":"string"},"names":{"type":"object","additionalProperties":{"type":"string"}},"risk_thresholds":{"type":"array","items":{"type":"number"}}}}}}}}}}}}}}}