WIP: feat: add /v1/geo-breakdown endpoint for geographic CWV breakdown

[alonkochba]

Companion to HTTPArchive/httparchive.org#1220, implementing HTTPArchive/httparchive.org#1146.

Summary

Adds a new /v1/geo-breakdown endpoint that returns Core Web Vitals data for all geographies for a given technology. Unlike /v1/cwv, this endpoint omits the geo filter so callers can build a geographic breakdown chart without issuing one request per country.

Changes

• src/controllers/geoBreakdownController.js — new controller; queries core_web_vitals without a geo filter, includes geo in the field projection
• src/index.js — wires up GET /v1/geo-breakdown

API

GET /v1/geo-breakdown?technology=Wix&rank=ALL&start=latest

Parameters mirror /v1/cwv except geo is not accepted (all geographies are returned):

Param	Default	Description
technology	ALL	Technology name(s), comma-separated
rank	ALL	Rank filter
start	—	Date range start (YYYY-MM-DD or latest)
end	—	Date range end (YYYY-MM-DD)

Response format is identical to /v1/cwv with an additional geo field per record.

[tunetheweb]

@max-ostapenko could you give you opinion on this before @alonkochba takes it much further?

I like the idea, and landing the API first will allow the front-end changes to be tested.

Questions I have are:

• Code - looks fine to me from a quick glance but I don't know this well enough!
• Test cases?
• Any capacity concerns? We already get a lot of 403s from these APIs (especially on CrUX release day - presumably cause a lot of people hit it at once?) so adding to that wouldn't be great. Though I think this should only be called on a single technology page, rather than the comparison screens (would be too noisy there!) so maybe that's not as big a concern after all because of that?

[alonkochba]

Maybe it doesn’t make sense to support this. It should be according to a single month of data and not multiple months probably.

[max-ostapenko]

Based on your visualization example it seems that a single monthly snapshot is sufficient.
1 month of CWV data is 15Kb btw.

[max-ostapenko]

@alonkochba let's add the cross-geo implementation to the existing createReportController.

Define and verify the parameter combinations definition (in order to have a bounded set of results):

1. metric time series (current behaviour): technology + geo + rank are required
2. cross-geo snapshot: technology + rank + start date + end date (point-in-time) are required

This will allow to later extend the visualization with any of the existing metrics.

[max-ostapenko]

All data required is already available in database, so it's a matter of adding an endpoint.

[alonkochba]

Thanks, updating. Is it really a good idea to make start/end required though? and the default is usually 7 years of data (start is 2020, end is latest), seems like a waste to serve this API for all period for now if we only display last month

Updated suggestion to only use end date (or latest if not given) for now wdyt?