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 are INDEPENDENT sensors — infrared combustion power vs visible emitted light — so agreement between them (e.g. a FIRMS went_dark and a went_dark_lights at the same facility) is materially stronger evidence than either alone. Corroborate across both before characterising an outage.