World Happiness Report Rankings and Factors

Country rankings are easy to cite but awkward to use in a pipeline. This Actor returns the World Happiness Report's published rankings as one structured row per country and report edition.

Coverage: editions 2012–2026, 1,960 rows. The 13 editions are 2012 and 2015–2026. There was no 2014 report, and the 2013 report published no data file. Row counts range from 137 (2023) to 158 (2015).

What it does

• Returns rank, life-evaluation score, the six explained contributions, dystopia_residual, and an ISO3 country_code for each country in each edition. year is the publication edition. data_year is the last survey year in that edition's averaging window: the previous year, or 2011 for the 2012 edition (2005–2011).
• Fields such as gdp_per_capita are contributions to the score, not raw GDP, health, or survey measurements. A factor is null when that edition did not publish it. The 2012 report had no factor decomposition, and a few countries have empty cells in 2023–2026. A missing value is never filled from another edition.
• Adds country_code, the ISO 3166-1 alpha-3 code from a built-in table covering every spelling the report has used. Kosovo is XKX. Somaliland region and North(ern) Cyprus have no code and are null. Use it to join with other datasets.
• Country filters accept report names in any edition's spelling, or ISO3 codes. Czechia, Czech Republic and CZE all return the same country in every edition.
• Provides batch dataset output and Standby GET /query.
• Caches each edition: 7 days for the current-year edition, 30 days for older editions, which no longer change. A stale cache is refreshed; if the refresh fails, the run reports an error rather than quietly returning stale rows.

Input

Field	Meaning	Example
years	Report editions (2012, 2015–2026) or ["all"]	[2026], ["all"]
countries	Country names (any edition's spelling, case insensitive) or ISO3 codes; all for all	["Finland","ESP"]
topN	Optional rank cutoff, applied within each edition	10

Example batch inputs:

{"years":["all"],"countries":["Finland","Spain"]}
{"years":[2015],"countries":["all"],"topN":5}

Standby examples: /query?year=2026&country=Finland, /query?year=all&country=FIN (one row per edition), and /query?year=2015&topN=5. Repeat year or country for multiple values; comma-separated values also work. An unmatched country is a successful empty result. An edition that is not implemented, such as 2013, is HTTP 400.

AI agents can run the Actor in batch mode through Apify MCP and read its dataset. Use Standby GET /query for an immediate response.

Output

Example dataset rows (2026 and 2012 editions):

{"country":"Finland","country_code":"FIN","year":2026,"data_year":2025,"rank":1,"score":7.764,"gdp_per_capita":1.915,"social_support":1.638,"healthy_life_expectancy":0.939,"freedom":1.105,"generosity":0.093,"corruption_perception":0.491,"dystopia_residual":1.582,"source_url":"https://files.worldhappiness.report/WHR26_Data_Figure_2.1.xlsx"}
{"country":"Finland","country_code":"FIN","year":2012,"data_year":2011,"rank":2,"score":7.579009,"gdp_per_capita":null,"social_support":null,"healthy_life_expectancy":null,"freedom":null,"generosity":null,"corruption_perception":null,"dystopia_residual":null,"source_url":"https://files.worldhappiness.report/WHR12_Data.xlsx"}

Scores are the published values. Editions before 2025 store more digits, for example 7.5370001792907715. Rows are ordered newest edition first, then by rank.

OUTPUT contains the delivered rows, the match count from editions fetched before any spending cap stopped work, the stop reason, and per-edition file metadata (URL, layout, SHA-256, cache age) under sources. RUN_SUMMARY contains the counts, stop reason and the same metadata. If a spend cap is reached, only delivered rows appear. If an edition's data is unavailable or changes shape, the batch run fails and /query returns HTTP 503.

Pricing

You pay per row delivered, at the price shown on the Pricing tab. The Actor checks your remaining Max total charge before each row and before loading each edition, and serializes concurrent requests. A zero cap stops before any data is loaded.

Use cases

• Track one country's rank and score across every report edition since 2012.
• Join scores with other country datasets through country_code.
• Query a named country’s rank in any edition via Standby or batch.

FAQ

Is year: 2026 a 2026-only survey? No. It identifies the 2026 report edition. data_year: 2025 is the last year of the three-year average used in that edition.

Why is there no 2013 or 2014? The report was not published in 2014. The 2013 edition published only a PDF appendix, with no ranking data table.

Are ranks recomputed? No. The 2022, 2025 and 2026 files have a rank column. Other editions list countries in the published order, and rank is that position. The Actor checks that the order is non-increasing by score.

Are the six factor fields raw measurements? No. They are the published explained contributions to the ranking score.

Development

npm ci
npm run build
npm test
apify run --purge --input '{"years":["all"],"countries":["Finland","Spain"]}'

For Standby locally, set APIFY_META_ORIGIN=STANDBY and ACTOR_WEB_SERVER_PORT, then run npm run start:dev.