query_nightlights
Query NASA Black Marble night-lights (VIIRS VNP46A2, ~500 m): moonlight/atmosphere-corrected nighttime radiance sampled nightly at every FIRMS-watched facility, plus significance events judged against each facility's OWN clear-night baseline. Two modes. mode="events" (default) reads SITE-LEVEL significance events — went_dark_lights (a habitually-lit facility dark across several consecutive CLEAR nights: the outage signal), surge (materially brighter than its own norm), first_light (a reliably-dark facility lights up). Use it for "which power stations went dark last week", "unusual lighting activity in Kuwait". mode="radiance" reads the per-facility nightly radiance rollup — use it for baseline questions ("how bright is Bandar Abbas at night", "clear-night trend at Az Zour"). CRITICAL INTERPRETATION RULES — RADIANCE IS NOT POWER STATE. A dark pixel is not a confirmed outage: cloud, snow, moon geometry and the ~500 m footprint all hide light, so went_dark_lights requires SUSTAINED absence across multiple confidently-CLEAR nights and is still an inference, never a verdict. Judgements use confident_clear observations ONLY (cloud scatters city light back at the sensor — cloudy readings average ~100x brighter and would fake both surges and collapses). ABSENCE OF A ROW IS ABSENCE OF A LOOK, never darkness. Counts are per PHYSICAL SITE, not per registry row (one plant = many generating-unit rows at identical coordinates). LATENCY: NASA publishes VNP46A2 in stages, typically ~1-2 WEEKS behind — every response carries a coverage block with newest_night and lag_days; answers describe that week, NOT last night, and you must say so. Thermal (FIRMS) and night-lights measure DIFFERENT PHYSICS — infrared heat vs visible emitted light — but they are NOT independent sensors: both are NASA VIIRS-family, and the same clouds and overpass timing blind both. Agreement between them (e.g. a FIRMS went_dark and a went_dark_lights at the same facility) is stronger evidence than either alone, never independent confirmation. Check both before characterising an outage.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days ENDING AT THE NEWEST DATA NIGHT (not today — see coverage.lag_days). Default 14, max 60. | |
| mode | No | "events" (default, site-level significance) | "radiance" (per-facility nightly rollup). | |
| limit | No | Default 50, max 500. | |
| country | No | Country-name substring (e.g. "Kuwait", "Saudi"). NOTE: attribution is dense for power plants but sparse for refineries — prefer facility_name for refineries. | |
| event_type | No | events mode: went_dark_lights | surge | first_light. Filter optional. | |
| facility_name | No | Facility/site-name substring (e.g. "Az Zour", "Bandar Abbas"). Filter optional. | |
| facility_type | No | radiance mode: refinery | power_plant. Filter optional. |