routemap-engine 0.2.0__py3-none-any.whl

routemap_engine/__about__.py

@@ -0,0 +1,12 @@
+"""The engine's own name and version. The desktop app and FalconEye name themselves."""
+
+NAME = "routemap-engine"
+REPO_SLUG = "osintph/routemap-engine"
+REPO_URL = f"https://github.com/{REPO_SLUG}"
+
+__version__ = "0.2.0"
+
+# Upstreams see this product token unless the caller passes its own User-Agent,
+# so a complaint about traffic reaches the project rather than nobody.
+USER_AGENT_PRODUCT = f"{NAME}/{__version__}"
+USER_AGENT = f"{USER_AGENT_PRODUCT} (+{REPO_URL})"

routemap_engine/__init__.py

@@ -0,0 +1,28 @@
+"""
+The Route Map engine. Pure Python: nothing in this package imports Qt.
+
+    from routemap_engine import analyse_sync, run_trace, TraceOptions
+
+    result = run_trace("heise.de", TraceOptions(on_line=print))
+    route = analyse_sync(result.text, origin=(14.6, 121.0))
+    route.to_dict()          # the JSON route model, see route.schema.json
+
+FalconEye imports this package for its Route Map tab, so anything added here
+ships to a web server as well as to the desktop app.
+"""
+from routemap_engine.cache import MemoryCache, NullCache, SqliteCache
+from routemap_engine.geo import OFFLINE, Sources, default_sources
+from routemap_engine.model import (Route, analyse, analyse_sync, normalise_origin,
+                                   origin_block, schema)
+from routemap_engine.parse import Hop, ParsedTrace, TraceParseError, parse_trace
+from routemap_engine.runner import (TraceOptions, TraceResult, TraceToolMissing,
+                                    available_tools, install_hint, run_trace)
+from routemap_engine.target import InvalidTarget, validate_target
+
+__all__ = [
+    "Hop", "InvalidTarget", "MemoryCache", "NullCache", "OFFLINE", "ParsedTrace",
+    "Route", "Sources", "SqliteCache", "TraceOptions", "TraceParseError",
+    "TraceResult", "TraceToolMissing", "analyse", "analyse_sync",
+    "available_tools", "default_sources", "install_hint", "normalise_origin",
+    "origin_block", "parse_trace", "run_trace", "schema", "validate_target",
+]

routemap_engine/atlas.py

@@ -0,0 +1,207 @@
+"""
+RIPE Atlas, with the user's own key: one traceroute from a probe near them.
+
+The desktop counterpart of FalconEye's Atlas client (app/routemap/atlas.py),
+with the server-only parts left there: no instance credit cap, no shared probe
+cache, no configuration read from the environment. The key is passed in.
+
+WHAT IS SENT TO RIPE, AND WHAT IS NOT
+-------------------------------------
+Sent: the target, in the measurement definition, and the probe selection
+criteria (an AS number, or a two-letter country code). The user's coordinates
+are never sent: there is deliberately no ``radius=`` probe filter, and the
+"distance from you" figure is computed here from the probe's own published
+coordinates.
+
+A measurement is PUBLIC. RIPE Atlas publishes one-off measurements, including
+the target, the probe and the result. The desktop app asks the user to
+acknowledge that before the first Atlas trace, and nothing here can make it
+untrue.
+
+RESULTS GO THROUGH THE PARSER
+-----------------------------
+A result is rendered as Unix traceroute text (:func:`to_trace_text`) and parsed
+like a pasted trace: one parser, one set of fixtures, one place for a format bug.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Callable
+
+import httpx
+
+from routemap_engine import geo
+from routemap_engine.logsafe import tag
+
+log = logging.getLogger("routemap_engine.atlas")
+
+BASE_URL = "https://atlas.ripe.net/api/v2"
+TRACEROUTE_CREDITS = 30
+DEFAULT_TIMEOUT_SECONDS = 150.0
+
+
+class AtlasUnavailable(Exception):
+    """Atlas cannot run this trace. ``kind``: auth | credits | noprobe | failed."""
+
+    def __init__(self, kind: str, message: str):
+        super().__init__(message)
+        self.kind = kind
+        self.message = message
+
+
+def to_trace_text(result: dict) -> str:
+    """Render one Atlas traceroute result as Unix traceroute output."""
+    target = result.get("dst_name") or result.get("dst_addr") or "target"
+    dst = result.get("dst_addr") or ""
+    lines = [f"traceroute to {target} ({dst}), 30 hops max, 60 byte packets"]
+    for hop in result.get("result") or []:
+        number = hop.get("hop")
+        if number is None:
+            continue
+        parts = []
+        for probe in hop.get("result") or []:
+            if "x" in probe:
+                parts.append("*")
+                continue
+            rtt, addr = probe.get("rtt"), probe.get("from")
+            if rtt is None or not addr:
+                parts.append("*")
+                continue
+            name = probe.get("name")
+            label = f"{name} ({addr})" if name and name != addr else addr
+            parts.append(f"{label}  {float(rtt):.3f} ms")
+        lines.append(f"{number:>2}  " + "  ".join(parts) if parts else f"{number:>2}  * * *")
+    return "\n".join(lines) + "\n"
+
+
+class Atlas:
+    def __init__(self, key: str, *, user_agent: str = geo.DEFAULT_USER_AGENT,
+                 base_url: str = BASE_URL, description: str = "routemap-engine traceroute"):
+        if not key or not key.strip():
+            raise AtlasUnavailable("auth", "No RIPE Atlas API key is set. Add one in Settings.")
+        self.key = key.strip()
+        self.user_agent = user_agent
+        self.base_url = base_url.rstrip("/")
+        # Published by RIPE with the measurement, so it names the tool, not the user.
+        self.description = description
+
+    def _client(self, authenticated: bool = True) -> httpx.AsyncClient:
+        headers = {"User-Agent": self.user_agent, "Accept": "application/json"}
+        if authenticated:
+            headers["Authorization"] = f"Key {self.key}"
+        return httpx.AsyncClient(base_url=self.base_url, headers=headers, timeout=20.0)
+
+    async def probes(self, params: dict) -> list[dict]:
+        # Probe lists are public; the key is not sent where it is not needed.
+        async with self._client(authenticated=False) as client:
+            response = await client.get("/probes/", params=params)
+        if response.status_code != 200:
+            return []
+        out = []
+        for item in (response.json() or {}).get("results") or []:
+            coords = (item.get("geometry") or {}).get("coordinates") or []
+            lat = lon = None
+            if len(coords) == 2:
+                try:
+                    lon, lat = float(coords[0]), float(coords[1])
+                except (TypeError, ValueError):
+                    lat = lon = None
+            out.append({"id": item.get("id"), "asn": item.get("asn_v4") or item.get("asn_v6"),
+                        "country": item.get("country_code"), "lat": lat, "lon": lon})
+        return [p for p in out if p.get("id")]
+
+    async def select_probe(self, asn: int | None, country: str | None,
+                           origin: tuple[float, float] | None) -> dict:
+        """The user's own network first, their country next; nearest first.
+
+        *origin* only ranks candidates, here. It is never sent.
+        """
+        candidates: list[dict] = []
+        if asn:
+            candidates = await self.probes({"asn_v4": asn, "status": 1, "page_size": 100})
+        if not candidates and country:
+            candidates = await self.probes({"country_code": country.upper(), "status": 1,
+                                            "page_size": 100})
+        if not candidates:
+            raise AtlasUnavailable(
+                "noprobe", "No connected RIPE Atlas probe was found on your network or in "
+                           "your country, so an Atlas trace would not describe your path.")
+        if origin is not None:
+            for probe in candidates:
+                probe["distance_km"] = (None if probe["lat"] is None else round(
+                    geo.haversine_km(origin[0], origin[1], probe["lat"], probe["lon"]), 1))
+            candidates.sort(key=lambda p: (p["distance_km"] is None, p["distance_km"] or 0.0))
+        return candidates[0]
+
+    async def balance(self) -> int | None:
+        try:
+            async with self._client() as client:
+                response = await client.get("/credits/")
+            if response.status_code != 200:
+                return None
+            return int((response.json() or {}).get("current_balance"))
+        except Exception:  # noqa: BLE001
+            return None
+
+    async def create(self, target: str, probe_id: int, af: int = 4) -> int:
+        body = {
+            "definitions": [{
+                "type": "traceroute", "af": af, "target": target,
+                "description": self.description, "protocol": "ICMP",
+                "resolve_on_probe": True, "paris": 0, "first_hop": 1, "max_hops": 30,
+                "packets": 3,
+            }],
+            "probes": [{"type": "probes", "value": str(probe_id), "requested": 1}],
+            "is_oneoff": True,
+        }
+        async with self._client() as client:
+            response = await client.post("/measurements/", json=body)
+        if response.status_code in (200, 201):
+            try:
+                measurement = int((response.json() or {}).get("measurements")[0])
+            except Exception as exc:
+                raise AtlasUnavailable("failed", "RIPE Atlas did not return a measurement id") from exc
+            log.info("event=atlas_measurement id=%s probe=%s target=%s",
+                     measurement, probe_id, tag(target))
+            return measurement
+        detail = ""
+        try:
+            detail = str((response.json() or {}).get("error") or "")[:200]
+        except Exception:  # noqa: BLE001
+            pass
+        lowered = detail.lower()
+        if response.status_code in (401, 403) and "credit" not in lowered and "balance" not in lowered:
+            raise AtlasUnavailable(
+                "auth", "RIPE Atlas refused the key. Check it in Settings: it needs the "
+                        "\"schedule a new measurement\" permission and must not have expired.")
+        if response.status_code in (402, 403):
+            raise AtlasUnavailable("credits", "RIPE Atlas refused the measurement; the account "
+                                              "is probably out of credits.")
+        raise AtlasUnavailable("failed", f"RIPE Atlas refused the measurement "
+                                         f"(HTTP {response.status_code}). {detail}".strip())
+
+    async def wait(self, measurement_id: int, timeout: float = DEFAULT_TIMEOUT_SECONDS,
+                   on_wait: Callable[[float], None] | None = None) -> str:
+        """Poll until the measurement has a result; return it as trace text."""
+        deadline = time.monotonic() + timeout
+        started = time.monotonic()
+        delay = 3.0
+        async with self._client(authenticated=False) as client:
+            while time.monotonic() < deadline:
+                await asyncio.sleep(delay)
+                delay = min(delay * 1.4, 10.0)
+                if on_wait is not None:
+                    try:
+                        on_wait(time.monotonic() - started)
+                    except Exception:  # noqa: BLE001
+                        pass
+                try:
+                    response = await client.get(f"/measurements/{measurement_id}/results/")
+                    results = response.json() if response.status_code == 200 else []
+                except Exception:  # noqa: BLE001
+                    continue
+                if results:
+                    return to_trace_text(results[0])
+        raise AtlasUnavailable("failed", "The Atlas measurement did not return a result in time.")

routemap_engine/cache.py

@@ -0,0 +1,139 @@
+"""
+Where the engine keeps answers it may reuse.
+
+Only one kind of answer is cached: what CAIDA Hoiho said about a router
+hostname. A hostname is cached whether or not it matched, because the misses
+are the common case and re-asking for them on every trace would be most of the
+traffic sent to CAIDA for no new information. Nothing else from a trace is
+stored by the engine: not the text, not the addresses, not the origin.
+
+The engine does not decide where the cache lives. A caller passes any object
+with ``get(key)`` and ``set(key, value)``; the TTL is the cache's business.
+Three are provided:
+
+  NullCache     nothing is kept (the default when no cache is passed)
+  MemoryCache   for one process, with a TTL
+  SqliteCache   one file on disk, with a TTL, for the desktop app's config dir
+
+FalconEye passes its own, backed by the application database, so its existing
+``route_map_hostname_cache`` table keeps working unchanged.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from typing import Protocol
+
+# Thirty days, the window Hoiho answers are trusted for. The ruleset itself is
+# dated (2024-08 at the time of writing) and changes rarely.
+DEFAULT_TTL_SECONDS = 30 * 24 * 3600
+
+
+class Cache(Protocol):
+    def get(self, key: str) -> dict | None: ...
+
+    def set(self, key: str, value: dict) -> None: ...
+
+
+class NullCache:
+    """Remembers nothing."""
+
+    def get(self, key: str) -> dict | None:
+        return None
+
+    def set(self, key: str, value: dict) -> None:
+        return None
+
+
+class MemoryCache:
+    """A dict with a TTL. Thread-safe, per instance, never global."""
+
+    def __init__(self, ttl_seconds: float = DEFAULT_TTL_SECONDS):
+        self.ttl_seconds = float(ttl_seconds)
+        self._lock = threading.Lock()
+        self._data: dict[str, tuple[float, str]] = {}
+
+    def get(self, key: str) -> dict | None:
+        with self._lock:
+            hit = self._data.get(key)
+            if hit is None:
+                return None
+            stored_at, blob = hit
+            if time.time() - stored_at > self.ttl_seconds:
+                del self._data[key]
+                return None
+        return json.loads(blob)
+
+    def set(self, key: str, value: dict) -> None:
+        # Stored serialised, so a caller mutating what it got back cannot
+        # change what the next caller gets.
+        blob = json.dumps(value)
+        with self._lock:
+            self._data[key] = (time.time(), blob)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._data.clear()
+
+
+class SqliteCache:
+    """One SQLite file, one table, a TTL enforced on read.
+
+    A connection per call: the desktop app reads this from a worker thread and
+    the CLI from the main one, and SQLite connections are not shareable across
+    threads by default.
+    """
+
+    TABLE = "hostname_cache"
+
+    def __init__(self, path: str | Path, ttl_seconds: float = DEFAULT_TTL_SECONDS):
+        self.path = Path(path)
+        self.ttl_seconds = float(ttl_seconds)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.execute(
+                f"CREATE TABLE IF NOT EXISTS {self.TABLE} ("
+                "key TEXT PRIMARY KEY, value TEXT NOT NULL, stored_at REAL NOT NULL)")
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.path, timeout=5.0)
+
+    def get(self, key: str) -> dict | None:
+        try:
+            with self._connect() as conn:
+                row = conn.execute(
+                    f"SELECT value, stored_at FROM {self.TABLE} WHERE key = ?",
+                    (key,)).fetchone()
+        except sqlite3.Error:
+            return None
+        if row is None or time.time() - row[1] > self.ttl_seconds:
+            return None
+        try:
+            return json.loads(row[0])
+        except ValueError:
+            return None
+
+    def set(self, key: str, value: dict) -> None:
+        try:
+            with self._connect() as conn:
+                conn.execute(
+                    f"INSERT OR REPLACE INTO {self.TABLE} (key, value, stored_at) "
+                    "VALUES (?, ?, ?)", (key, json.dumps(value), time.time()))
+        except sqlite3.Error:
+            # A cache that cannot be written is a cache miss next time, not a
+            # failed trace.
+            return None
+
+    def clear(self) -> int:
+        """Delete every entry. Returns how many there were."""
+        with self._connect() as conn:
+            count = conn.execute(f"SELECT COUNT(*) FROM {self.TABLE}").fetchone()[0]
+            conn.execute(f"DELETE FROM {self.TABLE}")
+        return int(count)
+
+    def __len__(self) -> int:
+        with self._connect() as conn:
+            return int(conn.execute(f"SELECT COUNT(*) FROM {self.TABLE}").fetchone()[0])

routemap_engine/cities.py

@@ -0,0 +1,239 @@
+"""
+The bundled offline city list, for the Route Map origin picker.
+
+WHAT IT IS AND WHERE IT CAME FROM
+---------------------------------
+``routemap_engine/data/cities.tsv`` is GeoNames' ``cities15000`` dump (every
+populated place above 15,000 people, 34,152 rows), trimmed to the seven columns
+this feature uses and with the coordinates rounded to two decimal places.
+
+Licence, checked against https://download.geonames.org/export/dump/readme.txt
+on 2026-10-03, which states: "This work is licensed under a Creative Commons
+Attribution 4.0 License, see https://creativecommons.org/licenses/by/4.0/".
+CC BY 4.0 permits redistribution and modification, including commercially, on
+condition of attribution. The attribution is carried in three places so it
+cannot be lost by touching only one of them: the header of the data file, the
+data-sources strip in the page footer, and the Acknowledgments section of the
+README.
+
+WHY IT IS BUNDLED AND NOT A SERVICE
+-----------------------------------
+The thing being resolved is the visitor's own location. Typing "Manila" into a
+geocoding API to find out where Manila is would mean telling a third party where
+the visitor is, to answer a question that has a fixed answer. A file in the
+repository answers it with no request leaving the box.
+
+MEMORY, AND WHY THE LOAD IS LAZY
+--------------------------------
+Parsed, the table is roughly 9 MB of Python objects per worker, which on a
+1 GB box with three workers is not free. It is therefore loaded on the first
+search and not at import: a worker that never serves the origin picker never
+pays for it, which on an instance where nobody opens the Route Map tab is every
+worker. :func:`loaded` exists so a test can assert that property rather than
+trust this comment.
+"""
+from __future__ import annotations
+
+import pathlib
+import re
+import threading
+import unicodedata
+
+DATA_FILE = pathlib.Path(__file__).resolve().parent / "data" / "cities.tsv"
+
+ATTRIBUTION = ("City list from GeoNames (cities15000), used under "
+               "Creative Commons Attribution 4.0.")
+ATTRIBUTION_URL = "https://www.geonames.org/"
+LICENCE_URL = "https://creativecommons.org/licenses/by/4.0/"
+
+# How many rows one search may return. The picker shows a short list; a query
+# like "san" matches hundreds and nobody scrolls them.
+MAX_RESULTS = 12
+
+_lock = threading.Lock()
+_rows: list[tuple] | None = None
+
+
+def _fold(text: str) -> str:
+    """Match key: accents stripped, lowercased, non-alphanumerics removed.
+
+    So "Sao Paulo" finds "Sao Paulo", and "ho chi minh" finds
+    "Ho Chi Minh City" through the prefix rule below.
+    """
+    decomposed = unicodedata.normalize("NFKD", text or "")
+    stripped = "".join(ch for ch in decomposed if not unicodedata.combining(ch))
+    return re.sub(r"[^a-z0-9]+", "", stripped.lower())
+
+
+def _load() -> list[tuple]:
+    """Parse the TSV into (key, name, cc, admin1, lat, lon, population).
+
+    The file is sorted by population descending when it is generated, so the
+    search can keep first-seen order and get "most likely city first" without
+    sorting 34,000 rows per query.
+    """
+    rows: list[tuple] = []
+    with DATA_FILE.open(encoding="utf-8") as handle:
+        for line in handle:
+            if line.startswith("#") or not line.strip():
+                continue
+            parts = line.rstrip("\n").split("\t")
+            if len(parts) != 7:
+                continue
+            name, ascii_name, cc, admin1, lat, lon, population = parts
+            try:
+                lat_f, lon_f, pop_i = float(lat), float(lon), int(population or 0)
+            except ValueError:
+                continue
+            key = _fold(name)
+            rows.append((key, name, cc, admin1, lat_f, lon_f, pop_i))
+            # A separate key for the ASCII spelling, where GeoNames gives one
+            # that differs, so a keyboard without diacritics still finds the
+            # city ("sao paulo" -> "Sao Paulo" -> "Sao Paulo"). Note this is
+            # transliteration only: the dump's alternate-names column, which is
+            # where an exonym like "Kiev" for "Kyiv" lives, is not bundled.
+            ascii_key = _fold(ascii_name) if ascii_name else ""
+            if ascii_key and ascii_key != key:
+                rows.append((ascii_key, name, cc, admin1, lat_f, lon_f, pop_i))
+    return rows
+
+
+def _table() -> list[tuple]:
+    global _rows
+    if _rows is None:
+        with _lock:
+            if _rows is None:
+                _rows = _load()
+    return _rows
+
+
+def loaded() -> bool:
+    """Whether the table is resident in this process yet."""
+    return _rows is not None
+
+
+def display(name: str, cc: str, admin1: str) -> str:
+    """How a city is labelled in the UI: "San Jose, CA, US", "Manila, PH"."""
+    parts = [name]
+    if admin1:
+        parts.append(admin1)
+    if cc:
+        parts.append(cc)
+    return ", ".join(parts)
+
+
+def _as_dict(row: tuple) -> dict:
+    _key, name, cc, admin1, lat, lon, population = row
+    return {"name": name, "cc": cc, "admin1": admin1, "lat": lat, "lon": lon,
+            "population": population, "display": display(name, cc, admin1)}
+
+
+def search(query: str, limit: int = MAX_RESULTS) -> list[dict]:
+    """Cities matching *query*, best first, de-duplicated by display name.
+
+    Ranked exact match, then prefix, then substring. Within a rank the file's
+    own population order decides, so "san jose" offers the Californian one
+    before the three in the Philippines.
+    """
+    key = _fold(query)
+    if len(key) < 2:
+        return []
+    limit = max(1, min(int(limit or MAX_RESULTS), MAX_RESULTS))
+
+    buckets: tuple[list[dict], list[dict], list[dict]] = ([], [], [])
+    seen: set[str] = set()
+    for row in _table():
+        row_key = row[0]
+        if key == row_key:
+            rank = 0
+        elif row_key.startswith(key):
+            rank = 1
+        elif key in row_key:
+            rank = 2
+        else:
+            continue
+        entry = _as_dict(row)
+        if entry["display"] in seen:
+            continue
+        seen.add(entry["display"])
+        buckets[rank].append(entry)
+        # Enough exact matches to fill the answer means nothing weaker can
+        # displace them, so the scan can stop.
+        if rank == 0 and len(buckets[0]) >= limit:
+            break
+
+    return (buckets[0] + buckets[1] + buckets[2])[:limit]
+
+
+def lookup(name: str) -> dict | None:
+    """The single best city for a typed name, or None.
+
+    Used when the origin arrives as a city string (the MCP tool, a scripted
+    call) rather than through the picker, which sends coordinates.
+    """
+    results = search(name, limit=1)
+    return results[0] if results else None
+
+
+def nearest(lat: float, lon: float, max_km: float = 250.0) -> dict | None:
+    """The bundled city that best labels (lat, lon), or None if nothing is near.
+
+    This is what turns a coordinate into the label the UI shows ("Manila, PH"
+    rather than "14.6, 121.0"). Coordinates stay as the secondary text, because
+    the city is a convenience and the coordinates are the actual origin.
+
+    Not simply the closest city. GeoNames' cities15000 contains city districts
+    as rows of their own, so the nearest row to central Manila is Paco and the
+    nearest to central Hannover is Nordstadt: both correct, both useless as a
+    label for where somebody is. The pick is therefore the most *significant*
+    nearby place, scoring population against distance:
+
+        score = population / (1 + distance_km) ** 1.5
+
+    which puts Manila (1.6M, 2 km) ahead of both Paco next door and Quezon City
+    (2.9M, 8 km), and is the answer a person would give.
+
+    ``max_km`` exists so a point in the middle of an ocean is reported honestly
+    as coordinates rather than attached to the nearest populated place 900 km
+    away. A full scan of 34,000 rows is a few milliseconds and happens once per
+    origin, so there is no index to keep correct.
+    """
+    import math
+
+    try:
+        lat, lon = float(lat), float(lon)
+    except (TypeError, ValueError):
+        return None
+    if not (-90.0 <= lat <= 90.0 and -180.0 <= lon <= 180.0):
+        return None
+
+    phi1 = math.radians(lat)
+    cos_phi1 = math.cos(phi1)
+    best = best_nearest = None
+    best_score, best_km = -1.0, float("inf")
+
+    for row in _table():
+        _key, name, cc, admin1, row_lat, row_lon, population = row
+        # Equirectangular approximation: accurate well inside the distances
+        # that matter here, and avoids 34,000 haversines per call.
+        dx = math.radians(row_lon - lon) * cos_phi1
+        dy = math.radians(row_lat - lat)
+        km = 6371.0088 * math.hypot(dx, dy)
+        if km > max_km:
+            continue
+        if km < best_km:
+            best_km, best_nearest = km, (name, cc, admin1, row_lat, row_lon, km)
+        score = population / (1.0 + km) ** 1.5
+        if score > best_score:
+            best_score, best = score, (name, cc, admin1, row_lat, row_lon, km)
+
+    # Every candidate had population 0, so significance cannot decide; fall
+    # back to plain proximity.
+    chosen = best if best_score > 0 else best_nearest
+    if chosen is None:
+        return None
+    name, cc, admin1, row_lat, row_lon, km = chosen
+    return {"name": name, "cc": cc, "admin1": admin1,
+            "lat": row_lat, "lon": row_lon,
+            "display": display(name, cc, admin1),
+            "distance_km": round(km, 1)}