sunshine-hours-by-city

Calibrated mean annual sunshine hours for 270 cities worldwide. Available as a tiny zero-dependency package for both JavaScript and Python, with the raw CSV bundled.

Data by GeoRank.place — see the interactive sunshine map. Licensed CC-BY-4.0.

Method

Values blend EUMETSAT CM SAF SARAH-3 satellite radiation (1991–2020) with ECMWF ERA5, bias-corrected against 56 WMO reference stations (actual ≈ 1.14 × ERA5 − 1,550, R² = 0.82, n = 56). Each city is snapped to the nearest cell of the calibrated grid. Full sources and licensing in ATTRIBUTION.md.

Install

npm install sunshine-hours-by-city      # JavaScript / TypeScript
pip install sunshine-hours-by-city      # Python

Usage

JavaScript / TypeScript

import { cities, byCity, byCountry } from "sunshine-hours-by-city";

byCity("Lisbon", "PT");   // { city: "Lisbon", countryIso2: "PT", annualHours: 2799, ... }
byCountry("ES");          // every Spanish city
cities().length;          // 270

Python

from sunshine_hours_by_city import cities, by_city, by_country

by_city("Lisbon", "PT")   # {"city": "Lisbon", "country_iso2": "PT", "annual_hours": 2799, ...}
by_country("ES")          # every Spanish city
len(cities())             # 270

Data schema

| Field | Type | Description | |-------|------|-------------| | city | string | City name | | countryIso2 / country_iso2 | string | ISO-3166 alpha-2 country code | | lat, lon | number | Coordinates (decimal degrees) | | annualHours / annual_hours | number | Calibrated mean annual sunshine hours | | calibrated | boolean | WMO-calibrated flag | | source | string | Methodology label |

The raw CSV ships in the package (sunshine_hours_by_city/sunshine-hours.csv).

Pairs well with

georank — rank these cities by weighted criteria (sunshine, cost, climate). See it live at georank.place.

License

Data: CC-BY-4.0 © GeoRank.place. Attribution required — see ATTRIBUTION.md. Package code: MIT.