Geocoding

// The live search box on the Geocoding page: maplibre-gl-geocoder on a
// MapLibre map, searching OpenStreetMap through Photon. The page loads this
// module only when the map scrolls into view.
import MaplibreGeocoder from "@maplibre/maplibre-gl-geocoder";
import "@maplibre/maplibre-gl-geocoder/dist/maplibre-gl-geocoder.css";
import type { FitBoundsOptions, FlyToOptions } from "maplibre-gl";
import { maplibregl } from "./maplibre";
import { photonGeocoderApi } from "./photon";

// The plugin hands these to fitBounds for results with an area and to flyTo
// for points, so they may use either one's options. Without the cap, a
// building-sized result would zoom in to about 20.
const flyTo: FlyToOptions & FitBoundsOptions = { maxZoom: 16 };

export function mountGeocoder(container: HTMLElement): void {
  const map = new maplibregl.Map({
    container,
    style: "https://tiles.openfreemap.org/styles/liberty",
    center: [10, 30],
    zoom: 1.4,
    cooperativeGestures: true,
    attributionControl: {
      compact: true,
      customAttribution: 'Search: <a href="https://photon.komoot.io">Photon</a> by komoot',
    },
  });

  map.addControl(
    new MaplibreGeocoder(photonGeocoderApi, {
      maplibregl,
      placeholder: "Search a place, like Kyoto",
      showResultsWhileTyping: true,
      minLength: 3,
      debounceSearch: 300,
      flyTo,
    }),
    "top-left",
  );
}

The Photon adapter turns Photon's results into the plugin's format:

// maplibre-gl-geocoder backed by Photon (https://photon.komoot.io), komoot's
// open-source geocoder for OpenStreetMap data. Its public instance allows use
// "as long as the number of requests stay in a reasonable limit" and needs no
// key; the map must credit OpenStreetMap, which the basemap already does.
import type {
  CarmenGeojsonFeature,
  MaplibreGeocoderApi,
  MaplibreGeocoderApiConfig,
  MaplibreGeocoderFeatureResults,
} from "@maplibre/maplibre-gl-geocoder";

const PHOTON = "https://photon.komoot.io";
// The public instance answers HTTP 400 for any other language.
const LANGUAGES = ["en", "de", "fr"];

interface PhotonProperties {
  osm_type?: string;
  osm_id?: number;
  osm_value?: string;
  type?: string;
  name?: string;
  street?: string;
  housenumber?: string;
  postcode?: string;
  city?: string;
  state?: string;
  country?: string;
  extent?: [number, number, number, number]; // [west, north, east, south]
}

interface PhotonFeature {
  geometry: { type: "Point"; coordinates: [number, number] };
  properties: PhotonProperties;
}

// Photon's extent is [west, north, east, south]; Carmen's bbox is [west, south, east, north].
function toBbox([x1, y1, x2, y2]: [number, number, number, number]): [
  number,
  number,
  number,
  number,
] {
  return [Math.min(x1, x2), Math.min(y1, y2), Math.max(x1, x2), Math.max(y1, y2)];
}

function toCarmen(feature: PhotonFeature): CarmenGeojsonFeature {
  const p = feature.properties;
  const street = [p.street, p.housenumber].filter(Boolean).join(" ");
  const text = p.name || street || p.city || p.state || p.country || "";
  // "Station", "City": tells apart places that share a name.
  const kind = p.osm_value && p.osm_value !== "yes" ? p.osm_value.replaceAll("_", " ") : "";
  const label = kind.charAt(0).toUpperCase() + kind.slice(1);
  const parts = [
    text,
    label,
    street,
    [p.postcode, p.city].filter(Boolean).join(" "),
    p.state,
    p.country,
  ];
  return {
    type: "Feature",
    id: `${p.osm_type}${p.osm_id}`,
    geometry: feature.geometry,
    properties: { ...p },
    text,
    place_name: [...new Set(parts.filter(Boolean))].join(", "),
    place_type: [p.type || "place"],
    center: feature.geometry.coordinates,
    ...(p.extent && { bbox: toBbox(p.extent) }),
  };
}

async function photon(
  path: string,
  params: URLSearchParams,
): Promise<MaplibreGeocoderFeatureResults> {
  const response = await fetch(`${PHOTON}${path}?${params}`);
  if (!response.ok) throw new Error(`Photon ${path}: HTTP ${response.status}`);
  const json = (await response.json()) as { features: PhotonFeature[] };
  return { type: "FeatureCollection", features: json.features.map(toCarmen) };
}

// The plugin's types say comma-separated strings, but it passes arrays at runtime.
const list = (value: string | string[] | undefined): string[] =>
  (Array.isArray(value) ? value : (value?.split(",") ?? []))
    .map((item) => item.trim())
    .filter(Boolean);

function withLanguage(params: URLSearchParams, config: MaplibreGeocoderApiConfig) {
  const code = list(config.language)[0]?.slice(0, 2).toLowerCase();
  if (code && LANGUAGES.includes(code)) params.set("lang", code);
  return params;
}

export const photonGeocoderApi: MaplibreGeocoderApi = {
  forwardGeocode(config) {
    const params = new URLSearchParams({
      q: String(config.query),
      limit: String(config.limit ?? 5),
    });
    if (config.proximity) {
      params.set("lon", String(config.proximity[0]));
      params.set("lat", String(config.proximity[1]));
    }
    if (config.bbox) params.set("bbox", config.bbox.join(","));
    for (const country of list(config.countries)) params.append("countrycode", country);
    return photon("/api/", withLanguage(params, config));
  },
  reverseGeocode(config) {
    const [lon, lat] = config.query as number[];
    const params = new URLSearchParams({ lon: String(lon), lat: String(lat), limit: "1" });
    return photon("/reverse", withLanguage(params, config));
  },
};