planet/docs/technical/en/location-pipeline-user.md

Earth Location Candidate Collection User Guide

Location candidate collection helps fill or verify coordinates for compute centers and BGP collectors on Earth. Users do not type coordinates by hand; the backend ranks source coordinates, open organization-registry results, and online geocoding results into a previewable candidate list.

Supported Entities

Currently supported:

• Compute centers: TOP500 supercomputers and Epoch AI GPU clusters.
• BGP collectors: RIPE RIS rrcXX collectors.

BGP events inherit the location of their owning collector. Events do not have a separate collection button yet; future ASN facility, prefix geography, or PeeringDB resolvers should use the same pipeline.

What Users See

Clicking a compute center or BGP collector on Earth opens a detail card with location fields:

Field	Meaning
Location precision	Precise coordinates, site-level, city-level, or unconfirmed
Location source	Source coordinates, ROR organization registry, Nominatim online search, or stored BGP collector locations
Location confidence	Relative confidence reported by the backend resolver
Verification status	Confirmed, estimated, or online result pending confirmation
Resolution reason	Why the location was selected
Matched location name	Canonical name from an open source, online result, or stored collector location
Verified at	Verification date for confirmed locations; online candidates are usually empty

Compute-center GeoJSON no longer renders country centroids, unknown locations, or [0, 0] placeholders. Records that cannot reach city-level precision are returned in the endpoint's unresolved list and can be improved through candidate collection.

A compute center with a ? marker on Earth is not unresolved. It already has coordinates, but the coordinates still need confirmation, either because needs_confirmation=true or because the source is online geocoding. Truly unresolved records have no trustworthy coordinates and are therefore absent from the globe.

Collect Candidates

1. Open http://localhost:3000/earth.
2. Enable the Compute centers or BGP observation layer.
3. Click an object to open its detail card.
4. Click 自动采集坐标候选 or 重新自动采集坐标.
5. Wait for up to five candidates to appear.
6. Click 预览 on a candidate row; Earth flies to that latitude and longitude.

Candidate rows show:

• Candidate name.
• Precision: precise, site, or city.
• Resolver source.
• Confidence.
• Coordinates.

Clicking 保存 on a candidate row writes the selected compute-center candidate into the location dimension table. After the save succeeds, the compute-center layer refreshes; if the record was previously in the unresolved queue, the unresolved count decreases.

Unresolved Queue And Adopt All

The notification badge on the compute-center layer row shows the current unresolved count. Clicking it opens a fixed queue beside the layer panel:

1. The queue contains only compute centers without trustworthy coordinates.
2. Row-level 采集 calls the candidate endpoint and shows up to five previewable candidates.
3. Header-level 一键采用 walks the list from top to bottom, chooses the highest-confidence candidate with valid coordinates, and saves it.
4. Each successful save immediately removes that row, renumbers the remaining rows, and updates the badge count.
5. When the batch completes, the frontend refreshes the compute-center layer so UI state and backend state converge.

If a record has no saveable candidate, the system does not invent a country centroid, vendor headquarters, or hard-coded hint. The row stays in the queue with the backend failure reason and attempted queries so an operator can supply better evidence later.

Backend APIs

The frontend buttons call:

POST /api/v1/visualization/compute-centers/{source_id}/collect-location
POST /api/v1/visualization/compute-centers/{source_id}/location
POST /api/v1/bgp/collectors/{collector_id}/collect-location

Both collect-location endpoints use the same response shape:

{
  "success": true,
  "candidates": [],
  "best_candidate": {},
  "attempted_queries": [],
  "context": {}
}

When no candidate reaches city-level precision, success is false and the response includes failure_reason plus the attempted queries. This helps distinguish missing source fields, open-source gaps, and online geocoding misses.

Registry Maintenance

Compute centers and BGP collectors no longer maintain local candidate registries. Compute-center accepted locations are stored in the compute_center_locations database dimension table keyed by (source, source_id). BGP collector current locations are stored in the bgp_collector_locations database dimension table; the old RIPE RIS city-level coordinates are used only as initialization seed data and still require confirmation.

For compute centers, prefer maintaining:

• source / source_id: for example top500 + top500_50.
• name / operator / site.
• city / country.
• latitude / longitude.
• precision: precise, site, or city.
• confidence: confidence from 0 to 1.
• location_source / source_url / source_note / raw_payload: evidence source.
• needs_confirmation / verification_status / verified_at: manual verification status and date.

For BGP collectors, prefer maintaining:

• collector_id: for example rrc12.
• site / operator: site and operator.
• city / country / region.
• latitude / longitude.
• precision: precise, site, or city.
• confidence: confidence from 0 to 1.
• source / source_url / raw_payload: evidence source.
• verification_status / verified_at: manual verification status and date.

If only the city is known, use city-level precision. Do not enter a precise-looking coordinate that has not been verified.

Common Questions

Why are some compute centers missing on Earth?

Earth only renders coordinates that reach city-level precision or better. If source data, verified storage, and online geocoding all fail, the record is returned as unresolved instead of being rendered at a misleading country center or [0, 0].

Why do online results need confirmation?

Nominatim/OpenStreetMap results may match same-name cities, organizations, or campuses. They are useful for previewing candidates, but should be manually confirmed before being persisted as verified locations.

Why do BGP events no longer all land in Amsterdam?

The old behavior could match common fields like operator="RIPE NCC" and incorrectly promote rrc00. BGP event inheritance now uses a strict owning-collector lookup in the DB-backed cache instead of registry fuzzy matching.