# 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, online geocoding results, and, when needed, LLM factcheck fallback 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, LLM factcheck fallback, 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 |

Nominatim here means the online geocoding service from the OpenStreetMap ecosystem. It converts place names, cities, countries, organizations, or campus/facility queries into possible coordinate candidates, but it can match same-name places or broad administrative areas. The UI therefore treats these results as pending confirmation.

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:

```http
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:

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

When regular candidates are empty, the endpoint asks the current default AI Provider for one LLM factcheck fallback. LLM candidates always require human confirmation and are never saved automatically; only strict JSON results with city-or-better precision, non-zero coordinates, and sufficient confidence appear in the candidate list. When no candidate reaches city-level precision, `success` is `false` and the response includes `failure_reason`, `llm_failure_reason`, and attempted queries. This helps distinguish missing source fields, open-source gaps, online geocoding misses, and unusable LLM responses.

## 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.

### Can the LLM fallback change the map directly?

No. The LLM runs only after a user clicks candidate collection and regular sources have no candidates. It returns confirmation-required candidates only. Earth startup GeoJSON, scheduled collection, and batch rendering do not call the LLM automatically; a location affects future rendering only after a user saves the candidate into the dimension table.

### 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.