Drop-in-Tools

Place-Widget (JS), Map-Widget (JS) und PHP-Client als One-Line-Setup für eigene Seiten.

🧩 Place-Widget (JavaScript)

Verwandelt jedes <input>-Feld mit dem Attribut data-geoapi-place in ein Autosuggest-Feld mit Tastatur-Navigation, Hidden-Field-Pflege und Auto-Fill.

↓ geoapi-widget.js herunterladen Quelle ansehen

Schnellstart

<form method="post" action="speichern.php">
  <input type="text" name="ort" data-geoapi-place placeholder="Ort eingeben">
  <button type="submit">Speichern</button>
</form>

<script src="https://geoapi.world/dist/geoapi-widget.js"></script>

Im Server-PHP stehen anschließend zur Verfügung:

$_POST["ort"] — der angezeigte Text
$_POST["ort_geonameid"] — die GeoNames-ID
$_POST["ort_timezone"] — die IANA-Zeitzone

data-Attribute

Attribut	Default	Bedeutung
Pflicht
`data-geoapi-place`	—	Markiert das Feld als Autosuggest.
Hidden-Feld-Namen — Default jeweils `{inputname}_{key}`
`data-geoapi-id`	`{name}_geonameid`	Hidden-Field-Name für die geonameid.
`data-geoapi-tz`	`{name}_timezone`	Hidden-Field-Name für die Zeitzone.
`data-geoapi-lat`	—	Hidden-Field für Breitengrad.
`data-geoapi-lon`	—	Hidden-Field für Längengrad.
`data-geoapi-country`	—	Hidden-Field für ISO-Ländercode.
Format der Anzeige
`data-geoapi-format-list`	name + Land + Untertitel	Template für die Vorschlagsliste mit `{key}`-Platzhaltern.
`data-geoapi-format-input`	name + Land	Was nach Auswahl im Eingabefeld steht.
Verhalten
`data-geoapi-limit`	`8`	Maximale Vorschläge in der Liste (1–30).
`data-geoapi-min`	`2`	Mindestlänge des Suchbegriffs.
`data-geoapi-base`	(geraten)	Alternative API-Base-URL.
`data-geoapi-debug`	aus	Zeigt eine Debug-Box unter dem Input.

Auto-Fill in beliebige Elemente

Mit data-geoapi-fill="key" auf einem beliebigen Element wird dieses nach jeder Auswahl automatisch gefüllt:

<input type="text" name="ort" data-geoapi-place>

<p>Land:        <span data-geoapi-fill="country_code"></span></p>
<p>Zeitzone:    <span data-geoapi-fill="timezone"></span></p>
<p>Einwohner:   <span data-geoapi-fill="population"></span></p>
<p>Koordinaten: <span data-geoapi-fill="lat"></span>, <span data-geoapi-fill="lon"></span></p>

JavaScript-Events

Vier Events bubbeln bis document:

Event	Wann	`detail`
`geoapi:fetch-start`	vor jedem API-Call	`{ url, query }`
`geoapi:fetch-end`	nach Antwort	`{ url, response, results }` oder `{ url, error }`
`geoapi:select`	beim Klick/Enter auf einen Vorschlag	Treffer-Objekt
`geoapi:clear`	wenn der Nutzer das Feld verändert	—

document.querySelector("[data-geoapi-place]")
  .addEventListener("geoapi:select", (e) => {
    const ort = e.detail;
    console.log("Gewählt:", ort.name);
    // map.setView([ort.lat, ort.lon], 13);
  });

→ Alle Widget-Anpassungen live ausprobieren

🧩 Map-Widget (JavaScript)

Interaktive OpenStreetMap-Karte mit Klick-Reverse-Geocoding. Lädt Leaflet 1.9 automatisch nach.

↓ geoapi-map.js herunterladen Quelle ansehen

Schnellstart

<div data-geoapi-map style="height: 500px"></div>
<script src="https://geoapi.world/dist/geoapi-map.js"></script>

Klick auf die Karte → Marker → Popup mit Stadt-Name + Zeitzone + Distanz. Mit Hidden-Feldern (siehe Attribute) kommen die Werte beim Form-Submit als $_POST beim Server an — analog zum Place-Widget.

Wichtigste data-Attribute

Attribut	Default	Bedeutung
`data-geoapi-map`	—	Pflicht — markiert das Element als Karte.
`data-geoapi-center`	`50,10`	Initial-Zentrum als `"lat,lon"`.
`data-geoapi-zoom`	`4`	Initial-Zoomlevel (0 = Welt, 19 = Hausnummer).
`data-geoapi-mode`	`city`	`city` oder `exact`.
`data-geoapi-marker`	`single`	`single` oder `double` (Klick-Marker + zweiter Marker am Treffer + Distanz-Linie).
`data-geoapi-tiles`	OSM	Alternative Tile-Server-URL — siehe Tile-Tabelle weiter unten.
`data-geoapi-name`	—	Präfix für automatisch angelegte Hidden-Felder.

Auto-Fill funktioniert genauso wie beim Place-Widget: data-geoapi-fill="key" auf beliebige Elemente.

JavaScript-Events

Event	Wann	`detail`
`geoapi:map-click`	direkt nach jedem Klick auf die Karte	`{ lat, lon }`
`geoapi:fetch-start`	vor dem API-Call	`{ url, lat, lon, mode }`
`geoapi:fetch-end`	nach Antwort	`{ url, response, hit }`
`geoapi:map-result`	nach erfolgreichem Reverse-Geocoding	Treffer + `{ clickedLat, clickedLon }`

document.querySelector("[data-geoapi-map]")
  .addEventListener("geoapi:map-result", (e) => {
    const ort = e.detail;
    document.getElementById("name").textContent = ort.name;
    document.getElementById("timezone").textContent = ort.timezone;
  });

Frei nutzbare Tile-Server

OpenStreetMap (Default), CartoDB Positron, Voyager & Dark Matter, OpenTopoMap, Esri Imagery, CyclOSM. Jeder Anbieter hat eigene Lizenz-Bedingungen — bei produktivem Traffic eigenen Tile-Server (siehe switch2osm) oder kostenpflichtigen Anbieter (Mapbox, MapTiler, Stadia) nutzen.

<div data-geoapi-map
     data-geoapi-tiles="https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png"
     data-geoapi-attribution="Karte: &copy; OpenTopoMap (CC-BY-SA)"
     data-geoapi-max-zoom="17"
     style="height: 500px"></div>

→ Alle Map-Anpassungen live ausprobieren

🧩 PHP-Client

Single-File-Klasse für eigenes Server-PHP, mit optionalem Datei-Cache. Erfordert PHP 8.1+.

↓ GeoApiClient.php herunterladen Quelle ansehen

Schnellstart

<?php
require __DIR__ . "/GeoApiClient.php";

$api = new GeoApiClient();

// Suche
$treffer = $api->search("Münch", limit: 5);

// Reverse-Geocoding
$ort = $api->lookupCity(48.137, 11.575);
$ort = $api->lookupExact(48.137, 11.575);  // ohne Städte-Präferenz

Konstruktor mit Cache

$api = new GeoApiClient(
    baseUrl:         "https://geoapi.world",
    timeoutSeconds:  5,
    userAgent:       "MeineApp/1.0",
    cacheDir:        __DIR__ . "/cache",
    cacheTtlSeconds: 900,   // 15 Min
);

Fehlerbehandlung

Bei HTTP- oder Parsing-Fehlern wirft der Client GeoApiException:

try {
    $ort = $api->lookupCity($lat, $lon);
    if ($ort === null) {
        echo "Keine Stadt gefunden in der Nähe.";
    } else {
        echo "Stadt: " . $ort["name"];
    }
} catch (GeoApiException $e) {
    error_log("geoAPI-Fehler: " . $e->getMessage());
}