feat(add-data): geocode delimited-text addresses at import time (#1604)

* feat(add-data): geocode delimited-text addresses at import time

Adds an "Addresses (geocode)" import mode to the Delimited Text Layer
panel alongside the existing coordinate-column mode: pick one or more
columns to concatenate into an address and each row is geocoded
through the project's configured provider. Matched rows become points
stamped with geocode_provider/geocode_status; unmatched rows are kept
as null-geometry features (geocode_status: "unmatched") instead of
being silently dropped, so they stay visible and fixable in the
attribute table.

* style: auto-format (ruff + oxfmt) [pre-commit.ci]

* fix(add-data): address CSV-geocode review findings

- Distinguish a batch cancelled before any row completed from a
  completed run with zero matches, so the thrown error doesn't
  misreport "No rows could be geocoded" for a cancellation.
- Persist geocodeSkippedEmpty/geocodeCancelled on the layer alongside
  the existing geocodeMatched/geocodeUnmatched metadata, so a
  cancelled or partially-skipped run isn't silently indistinguishable
  from a complete one after the fact.
- Give the address-columns empty-state hint its own i18n string
  instead of reusing the "Retrieve columns" button label as body copy.
- Apply the unmatched-rows attribute filter after addAndClose selects
  the new layer, not before.

* fix(add-data): fail fast on a missing API key, style geocoded points

- Check geocoderNeedsApiKey before starting the batch, mirroring
  GeocodeDialog's guard, instead of paying a full paced loop of
  requests that are all doomed to fail with a keyed provider that has
  no key configured.
- Pass the matched-feature collection as createBaseLayer's vector
  option so a geocoded address layer gets the as-added palette color
  and point sizing (#1519) like every other point-producing import
  path, instead of always rendering flat DEFAULT_LAYER_STYLE. An
  all-unmatched run (nothing to draw) keeps the flat defaults, mirroring
  the coordinate-mode attribute-table branch.

* fix(add-data): preserve row order and stop stale address columns

- Build the geocoded FeatureCollection in original CSV row order
  instead of grouping every matched point before every unmatched row,
  so the attribute table lines up with the source file. matchedFeatures
  now feeds the as-added style inference on its own, not the mixed
  collection.
- Give the address-columns checklist its own field list derived only
  from the retrieved header, instead of reusing the coordinate-mode
  Select's field options, which always carries non-blank "longitude"/
  "latitude" defaults and both hid the "retrieve columns first" empty
  state and could offer columns the file doesn't have.
- Clear delimitedTextAddressColumns whenever the header resets (new
  file, delimiter change, mode switch) so a selection can't outlive
  the header it was picked against, and drop any stale selection that
  still slips through right before building geocode requests.

* style: auto-format (ruff + oxfmt) [pre-commit.ci]

* fix(add-data): clear the stale unmatched attribute filter

setAttributeFilter was only ever set to "unmatched", never cleared, so
a prior geocode run that left the global filter on "unmatched" stayed
active and hid every row of a later, fully-matched layer. Always set
it (to "unmatched" or "") after addAndClose selects the new layer.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: shima78

apps/geolibre-desktop/src/components/layout/add-data/sources/DelimitedTextSource.tsx

@@ -28,3 +28,5 @@ export type GpxLayerKind = "waypoints" | "tracks" | "trackPoints" | "routes" | "
 export type GeoRssMode = FeedMode;
 export type DelimitedTextMode = FeedMode;
 export type DelimitedTextDelimiter = "comma" | "tab" | "semicolon" | "pipe" | "custom";
+/** Whether the delimited-text source builds points from coordinate columns or by geocoding addresses. */
+export type DelimitedTextImportMode = "coordinates" | "addresses";

apps/geolibre-desktop/src/components/layout/add-data/types.ts

@@ -283,7 +283,7 @@
       },
       "delimitedText": {
         "label": "Add Delimited Text Layer",
-        "description": "Add a delimited text file or URL as a point layer using longitude and latitude fields, or as a non-spatial attribute table when no coordinates are available."
+        "description": "Add a delimited text file or URL as a point layer using longitude and latitude fields, by geocoding an address column, or as a non-spatial attribute table when no coordinates are available."
       },
       "cad": {
         "label": "Add CAD (DXF/DWG) Layer",
@@ -579,7 +579,15 @@
       "crs": "Coordinate system",
       "crsPlaceholder": "e.g. EPSG:32643",
       "crsPresetLabel": "Common coordinate systems...",
-      "crsHelp": "Leave blank if the coordinates are already longitude/latitude (WGS84). Otherwise enter the EPSG code of the coordinate columns and the points will be reprojected to WGS84. For a projected CRS, the longitude and latitude fields select the X (easting) and Y (northing) columns."
+      "crsHelp": "Leave blank if the coordinates are already longitude/latitude (WGS84). Otherwise enter the EPSG code of the coordinate columns and the points will be reprojected to WGS84. For a projected CRS, the longitude and latitude fields select the X (easting) and Y (northing) columns.",
+      "importMode": "Import as",
+      "modeCoordinates": "Coordinates",
+      "modeAddresses": "Addresses (geocode)",
+      "addressColumns": "Address columns",
+      "addressColumnsEmptyHint": "Retrieve columns first to select address columns.",
+      "addressColumnsHint": "Select one or more columns to concatenate into the address sent to the geocoder (e.g. street, city, state).",
+      "errorNoAddressColumns": "Select at least one address column.",
+      "errorNoAddressesFound": "No rows had a value in the selected address column(s)."
     },
     "photos": {
       "defaultName": "Photos",
@@ -2743,6 +2751,7 @@
     "summary": "Geocoded {{matched}} of {{total}} row(s); {{failed}} had no match.",
     "failedRows": "Rows with no match: {{rows}}",
     "noMatches": "No rows could be geocoded.",
+    "cancelledNoRows": "Cancelled before any rows were geocoded.",
     "cancelled": "Cancelled. Added {{matched}} matched row(s).",
     "error": "Error: {{message}}",
     "reverseLookingUp": "Looking up address...",

apps/geolibre-desktop/src/i18n/locales/en.json

@@ -10,7 +10,7 @@ The **Add Data** menu is the main way to bring layers into GeoLibre. It groups s
 | --- | --- |
 | **Vector Layer** | Opens the Add Vector panel (backed by `maplibre-gl-vector`). Loads GeoJSON, GeoParquet, FlatGeobuf, zipped Shapefile, GeoPackage, KML/KMZ, GML, and other vector formats from a file or URL. |
 | **Raster Layer** | Opens the Add Raster panel (backed by `maplibre-gl-raster`). Loads GeoTIFF and Cloud-Optimized GeoTIFF (COG) from a file or URL. |
-| **Delimited Text Layer** | Loads CSV/TSV from a file or URL, using longitude and latitude columns to build point features. |
+| **Delimited Text Layer** | Loads CSV/TSV from a file or URL, using longitude and latitude columns to build point features, or by geocoding one or more address columns (see [Geocoding](data-integrations.md#geocoding)). |
 | **GPX Layer** | Loads a GPX file or URL and splits it into separate waypoint, track, and route layers. |
 | **MBTiles Layer** | Loads a local MBTiles tile archive (desktop app). |
 

docs/user-guide/adding-data.md

@@ -56,9 +56,10 @@ GeoLibre can turn addresses into points and points into addresses. Both run thro
 | Tool | Where | What it does |
 | --- | --- | --- |
 | **Geocode Addresses** | Processing menu | Pick a CSV with an address column and geocode each row into a point layer. Each matched row keeps its original columns plus `geocode_lat`, `geocode_lon`, `geocode_display_name`, and `geocode_importance` (a match score). A per-run provider picker lets you switch backend for that batch. |
+| **Delimited Text Layer → Addresses** | Add Data | Geocode a CSV/TSV at import time instead of a separate step: choose "Addresses" as the import mode, pick one or more columns to concatenate into the address (e.g. street, city, state), and each row is geocoded through the project's configured provider. Matched rows become points; rows with no match are kept (not dropped) with `geocode_status: "unmatched"` so they stay visible and fixable in the attribute table. |
 | **Reverse Geocode** | Controls menu | A toggle. While on, click anywhere on the map to look up the address at that point, shown in a popup with a copy button. |
 
-Both send coordinates or addresses to a third-party service, so the first time you enable Reverse Geocode (and whenever you run a batch) your data leaves your device for those requests. Reverse Geocode shows a one-time notice before it is first enabled.
+All three send coordinates or addresses to a third-party service, so the first time you enable Reverse Geocode (and whenever you run a batch, including at CSV import time) your data leaves your device for those requests. Reverse Geocode shows a one-time notice before it is first enabled.
 
 ### Providers
 

docs/user-guide/data-integrations.md

@@ -47,6 +47,10 @@ export const GEOCODE_LAT_KEY = "geocode_lat";
 export const GEOCODE_LON_KEY = "geocode_lon";
 export const GEOCODE_DISPLAY_NAME_KEY = "geocode_display_name";
 export const GEOCODE_SCORE_KEY = "geocode_importance";
+/** Provider id that produced (or failed to produce) a match, when stamped. */
+export const GEOCODE_PROVIDER_KEY = "geocode_provider";
+/** Whether a row matched, when stamped. See {@link GeocodeStatus}. */
+export const GEOCODE_STATUS_KEY = "geocode_status";
 
 /** Identifier of a selectable geocoding backend. */
 export type GeocodingProviderId = "nominatim" | "pelias" | "arcgis" | "mapbox" | "google";
@@ -175,6 +179,9 @@ export interface ReverseGeocodeDisplay {
   parts: Record<string, string>;
 }
 
+/** Whether a row matched during batch geocoding, stamped as {@link GEOCODE_STATUS_KEY}. */
+export type GeocodeStatus = "matched" | "unmatched";
+
 function coerceScore(value: number | string | undefined | null): number | null {
   if (value === undefined || value === null || value === "") return null;
   const num = Number(value);
@@ -265,10 +272,15 @@ function nominatimForwardResultToMatch(result: NominatimForwardResult): GeocodeM
  * against the original columns so an existing `geocode_lat` is not clobbered.
  * Geometry coordinates are `[lon, lat]`. Returns null when the match has no
  * finite coordinates.
+ *
+ * `extra.providerId`, when passed, also stamps `geocode_provider` and
+ * `geocode_status: "matched"` (dropped when omitted, so the existing
+ * `GeocodeDialog` call site keeps its current output unchanged).
  */
 export function geocodeMatchToFeature(
   match: GeocodeMatch,
   originalRow: Record<string, string> = {},
+  extra?: { providerId?: GeocodingProviderId },
 ): Feature<Point> | null {
   if (!Number.isFinite(match.lat) || !Number.isFinite(match.lon)) return null;
 
@@ -279,6 +291,10 @@ export function geocodeMatchToFeature(
     [GEOCODE_DISPLAY_NAME_KEY]: match.displayName ?? "",
     [GEOCODE_SCORE_KEY]: match.score,
   };
+  if (extra?.providerId) {
+    added[GEOCODE_PROVIDER_KEY] = extra.providerId;
+    added[GEOCODE_STATUS_KEY] = "matched" satisfies GeocodeStatus;
+  }
   for (const [key, value] of Object.entries(added)) {
     properties[uniqueKey(key, properties)] = value;
   }
@@ -290,6 +306,30 @@ export function geocodeMatchToFeature(
   };
 }
 
+/**
+ * Build a null-geometry Feature for a CSV row that could not be geocoded, so
+ * it is kept (not silently dropped) alongside the matched point features.
+ * Mirrors the null-geometry shape {@link parseDelimitedTextLayer} already uses
+ * for a non-spatial attribute table. Stamps `geocode_status: "unmatched"` and
+ * `geocode_provider`, de-duplicated against the original columns the same way
+ * {@link geocodeMatchToFeature} does.
+ */
+export function unmatchedGeocodeFeature(
+  originalRow: Record<string, string>,
+  providerId: GeocodingProviderId,
+): Feature<null> {
+  const properties: Record<string, unknown> = { ...originalRow };
+  const added: Record<string, unknown> = {
+    [GEOCODE_STATUS_KEY]: "unmatched" satisfies GeocodeStatus,
+    [GEOCODE_PROVIDER_KEY]: providerId,
+  };
+  for (const [key, value] of Object.entries(added)) {
+    properties[uniqueKey(key, properties)] = value;
+  }
+
+  return { type: "Feature", geometry: null, properties };
+}
+
 /**
  * Convert a Nominatim forward result into a point Feature. Retained as a thin
  * wrapper over {@link geocodeMatchToFeature} for callers and tests that work

packages/core/src/geocoding.ts

@@ -64,6 +64,8 @@ export {
   GEOCODE_LON_KEY,
   GEOCODE_DISPLAY_NAME_KEY,
   GEOCODE_SCORE_KEY,
+  GEOCODE_PROVIDER_KEY,
+  GEOCODE_STATUS_KEY,
   DEFAULT_GEOCODING_PROVIDER_ID,
   GEOCODING_PROVIDERS,
   getGeocoderConfig,
@@ -78,6 +80,7 @@ export {
   buildForwardGeocodeUrl,
   buildReverseGeocodeUrl,
   geocodeMatchToFeature,
+  unmatchedGeocodeFeature,
   nominatimResultToFeature,
   nominatimReverseResultToDisplay,
   csvRowsToGeocodeRequests,
@@ -89,6 +92,7 @@ export {
   type GeocodingProviderId,
   type GeocodingPreferenceInput,
   type GeocodeMatch,
+  type GeocodeStatus,
   type NominatimForwardResult,
   type NominatimReverseResult,
   type GeocodeRequest,

packages/core/src/index.ts

@@ -21,6 +21,7 @@ import {
   resolveGeocoderConfig,
   rowCap,
   shouldThrottle,
+  unmatchedGeocodeFeature,
   type GeocoderConfig,
   type NominatimForwardResult,
 } from "@geolibre/core";
@@ -473,6 +474,42 @@ describe("geocodeMatchToFeature", () => {
   it("returns null for non-finite coordinates", () => {
     assert.equal(geocodeMatchToFeature({ lat: NaN, lon: 0, displayName: "", score: null }), null);
   });
+
+  it("stamps provider and matched status only when extra.providerId is passed", () => {
+    const withoutExtra = geocodeMatchToFeature(
+      { lat: 48.85, lon: 2.35, displayName: "Paris", score: 0.9 },
+      { id: "1" },
+    );
+    assert.ok(withoutExtra);
+    assert.equal(withoutExtra.properties?.geocode_provider, undefined);
+    assert.equal(withoutExtra.properties?.geocode_status, undefined);
+
+    const withExtra = geocodeMatchToFeature(
+      { lat: 48.85, lon: 2.35, displayName: "Paris", score: 0.9 },
+      { id: "1" },
+      { providerId: "nominatim" },
+    );
+    assert.ok(withExtra);
+    assert.equal(withExtra.properties?.geocode_provider, "nominatim");
+    assert.equal(withExtra.properties?.geocode_status, "matched");
+  });
+});
+
+describe("unmatchedGeocodeFeature", () => {
+  it("builds a null-geometry feature flagged unmatched, keeping the original row", () => {
+    const feature = unmatchedGeocodeFeature({ id: "2", address: "nowhere" }, "nominatim");
+    assert.equal(feature.geometry, null);
+    assert.equal(feature.properties?.id, "2");
+    assert.equal(feature.properties?.address, "nowhere");
+    assert.equal(feature.properties?.geocode_status, "unmatched");
+    assert.equal(feature.properties?.geocode_provider, "nominatim");
+  });
+
+  it("de-duplicates against an existing geocode_status column instead of clobbering it", () => {
+    const feature = unmatchedGeocodeFeature({ geocode_status: "original value" }, "mapbox");
+    assert.equal(feature.properties?.geocode_status, "original value");
+    assert.equal(feature.properties?.geocode_status_2, "unmatched");
+  });
 });
 
 describe("setGeocodingFetch", () => {