Thumbnail image and map coordinates are not tied to the same country for transnational/serial properties

[zigzagdev]

Description

Follow-up (backend side) of zigzagdev/world-heritage-frontend#387.

For transnational/serial World Heritage properties (one property spread across multiple countries), getHeritageById/getAllHeritages currently expose:

• a single (latitude, longitude) pair per site,
• a single main_image_url / per-image list with no country information attached.

Neither is linked to state_party_codes / primary_state_party_code, so the thumbnail image and the map pin can end up depicting different countries, and neither necessarily matches the displayed primary country.

Example: id 1321 ("The Architectural Work of Le Corbusier..."), 7 countries (ARG, BEL, CHE, DEU, FRA, IND, JPN):

• main_image_url → depicts the Curutchet House in La Plata, Argentina.
• latitude/longitude → 46.4684139, 6.8293361, which points to Switzerland.
• primary_state_party_code → IND (India).

Three different countries depending on which field is read.

Root cause

UNESCO's source dataset stores exactly one (latitude, longitude) pair per heritage site record, even for serial/transnational properties spanning many countries and physical locations (see world_heritage_sites table — single latitude/longitude columns). Per-image data (world_heritage_site_images) has no country_code column, so there's no way to know which country a given image belongs to, or to pick an image consistent with a given coordinate (or vice versa).

Suggested direction (needs a decision before implementing)

1. Minimal fix: keep a single stored coordinate per site, but change main_image_url/thumbnail selection logic to prefer an image known to be from primary_state_party_code. Coordinate itself stays as-is (still potentially "wrong" relative to the primary country, but at least the thumbnail and the country label agree).
2. Fuller fix: extend the schema — add a country_code (or state_party_code) column to world_heritage_site_images, and/or store per-sub-site coordinates for serial properties — then expose enough of that in the API response for the frontend to pick a coordinate/image pair that's mutually consistent.

Acceptance Criteria

• Decide between the minimal fix and the fuller schema fix (or a staged approach: minimal first, fuller later).
• Whichever is chosen, the country implied by main_image_url/thumbnail and the country implied by latitude/longitude are consistent with primary_state_party_code for serial/transnational properties.
• Audit other multi-country serial properties (not just id 1321) once the fix lands.

Related: zigzagdev/world-heritage-frontend#387

[zigzagdev]

Decision: go with multi-pin display, not a single "primary country" pin

After digging into the raw UNESCO dump shape (world-heritage-sites.json, pre-split), here's what's actually available and why this changes the plan:

• date_inscribed / secondary_dates are site-level only (or, at best, a list of distinct event years with no link back to a specific country/component). For id 1321 (Le Corbusier, 7 countries), all 7 were inscribed simultaneously in 2016 — there is no per-country year to rank by. So "primary country = earliest-inscribed country" is not reliably derivable from this data source and is dropped as an option.
• However, the raw dump's components_list field gives an exact (latitude, longitude) per physical component/sub-site (e.g. for id 1321, all 17 sub-sites have their own coordinates — "Complexe du Capitole" in India, "Maison du docteur Curutchet" in Argentina, etc.). This data is currently discarded during import — only one (latitude, longitude) ends up on world_heritage_sites.

Given this app's persona (world heritage certification exam study tool — README), showing only one pin for a 7-country serial property hides exactly the kind of fact the exam tests (how many countries / which countries a property spans). So:

Direction: render one pin per component/sub-site on the map, instead of collapsing to a single "primary" country pin.

This means:

• Import: capture components_list (name + lat/lng per sub-site) during the split/normalize step instead of discarding it; store it as a new table (e.g. world_heritage_site_components) linked to world_heritage_sites.
• API: expose a components/locations array (id, name, latitude, longitude) in the heritage detail response, in addition to (or instead of relying solely on) the single latitude/longitude.
• Country tagging per component is a nice-to-have (could reverse-geocode coordinates later) but isn't required to ship multi-pin rendering — components can be plotted without a country label initially.
• main_image_url/thumbnail selection is a separate concern (still tracked in this issue) and doesn't need to block the map work.

Frontend follow-up tracked in zigzagdev/world-heritage-frontend#387 (map needs to render multiple markers instead of one).