StopFinder-Request

Freitextsuche nach Haltestellen, Adressen oder POIs. Verifiziert Benutzer­eingaben und liefert strukturierte Trefferkandidaten — typischer Einstieg in jeden Workflow, der mit einer ID weiterarbeitet (DM, Trip, LineStop …).

Endpoint

• Pfad: XML_STOPFINDER_REQUEST
• Methode: GET

Obligatorische Parameter

Point-Input mit Suffix _sf:

Parameter	Werte	Beschreibung
name_sf	Suchbegriff, ID oder Koordinate	Eingabetext (frei), ID (z. B. de:05911:5494) oder Koordinate
type_sf	any | coord	any für Text/ID, coord für Koordinateneingabe

Optionale Parameter — Such­optimierung

Parameter	Werte	Beschreibung
anyMaxSizeHitList	Ganzzahl	Maximale Trefferliste; über diesen Wert hinaus wird nach Qualität reduziert
anyResSort_<usage>	ResultSorter-ID	Benutzerdefinierte Sortierung (Config-seitig im EFALocationServer)
anySigWhenPerfectNoOtherMatches	1	Nur den perfekten Treffer zurückgeben, sonst unscharfe Liste
locationInfoActive	1	Hausnummer-Auflösung für verifizierte Straßen aktivieren
useHouseNumberList_<usage>	1	Liste möglicher Hausnummern zurückgeben
useLocalityMainStop	1	Einen Ort auf seine Haupt­haltestelle abbilden statt umliegende zu suchen
doNotSearchForStops_<usage>	1	Nach Koordinaten-Verifikation nicht nach nahegelegenen Halten suchen (für Nicht-ÖPNV-Routing)
prMinQu	0–100	Mindestqualität, unter der Treffer verworfen werden

Optionale Parameter — Suchkriterien

Parameter	Werte	Beschreibung
anyObjFilter_<usage>	Bitmaske	Objekttyp-Filter — siehe Objekttypen
anyOmc_<usage>	Gemeindeschlüssel	Suche auf eine Gemeinde beschränken
regionID_<usage>	Regions-ID	Suche auf eine Region beschränken (Config-abhängig)
tryFurtherAnyWithoutLoc	1	Fallback: ohne Gemeinde-Filter nachziehen, wenn keine Treffer

Optionale Parameter — Qualität & Ranking

Parameter	Werte	Beschreibung
coord	<x>:<y>:<CoordFormat>	Bezugspunkt für rMethod=DISTANCEFROMCENTER
objPrefAl	Bitmaske	Typen-Präferenz — immer bevorzugen
objPrefAm	Bitmaske	Typen-Präferenz — unter den besten Treffern bevorzugen
prefStModeAm	Bitmaske über MOT-IDs	Unter den besten Halten jene mit bestimmten Verkehrsmitteln bevorzugen
regPrefAl	Regions-ID	Region immer bevorzugen
regPrefAm	Regions-ID	Region unter den besten Treffern bevorzugen
relInf	0–100 (%)	Gewicht der Relevanz im Quality-Score
rMethod	DISTANCEFROMCENTER | BESTCOVER | PREFIXCOUNT | PREFIXRATIO	Ranking-Verfahren

Siehe auch gemeinsame Parameter.

Beispiel-Requests

Textsuche in einer Gemeinde, nur Halte und POIs, mit Ranking nach Trefferpräfix:

GET /XML_STOPFINDER_REQUEST
    ?outputFormat=JSON
    &type_sf=any
    &name_sf=Essen%20Hbf
    &anyObjFilter_sf=34
    &anyOmc_sf=05113
    &rMethod=PREFIXRATIO
    &anyMaxSizeHitList=20

Umkreis­suche um eine Koordinate, bevorzugt Halte mit S-/U-/Straßenbahn:

GET /XML_STOPFINDER_REQUEST
    ?outputFormat=JSON
    &type_sf=coord
    &name_sf=7.0128:51.4513:WGS84[dd.ddddd]
    &rMethod=DISTANCEFROMCENTER
    &coord=7.0128:51.4513:WGS84[dd.ddddd]
    &prefStModeAm=30
    &anyMaxSizeHitList=10

(prefStModeAm=30 = Bits 1|2|3|4 → S-Bahn, U-Bahn, Stadtbahn, Straßenbahn.)

Antwort (Beispiel)

{
  "locations": [
    {
      "id": "de:05113:9009",
      "name": "Essen Hbf",
      "type": "stop",
      "isBest": true,
      "matchQuality": 950,
      "coord": { "lat": 51.4513, "lon": 7.0128 },
      "assignedStops": [
        { "id": "de:05113:9009:1", "name": "Gleis 1" }
      ]
    }
  ]
}

• isBest — Server-seitig beste Übereinstimmung.
• matchQuality — numerische Güte.
• assignedStops[] — umliegende Halte (nur wenn Point-Input sie anfordert).

JavaScript-Beispiele

Browser — Live-Suche mit Debounce

const base = 'https://server:port/virtuellesVerzeichnis/XML_STOPFINDER_REQUEST'

async function searchStops(query, { signal } = {}) {
  const usp = new URLSearchParams({
    outputFormat: 'JSON',
    type_sf: 'any',
    name_sf: query,
    anyObjFilter_sf: '34',
    rMethod: 'PREFIXRATIO',
    anyMaxSizeHitList: '10'
  })
  const res = await fetch(`${base}?${usp}`, { signal })
  if (!res.ok) throw new Error('HTTP ' + res.status)
  return res.json()
}

function debounce(fn, ms = 250) {
  let t, ctrl
  return (...args) => {
    clearTimeout(t)
    if (ctrl) ctrl.abort()
    ctrl = new AbortController()
    t = setTimeout(() => fn(...args, { signal: ctrl.signal }), ms)
  }
}

Node — verifizierte ID extrahieren

export async function resolveToId(query: string): Promise<string | null> {
  const usp = new URLSearchParams({
    outputFormat: 'JSON',
    type_sf: 'any',
    name_sf: query,
    anySigWhenPerfectNoOtherMatches: '1'
  })
  const res = await fetch(`${base}?${usp}`)
  const data = await res.json() as { locations: { id: string; isBest: boolean }[] }
  return data.locations.find(l => l.isBest)?.id ?? null
}

Umkreis + MOT-Präferenz

async function findStopsNear(lat, lon) {
  const coord = `${lon}:${lat}:WGS84[dd.ddddd]`
  const usp = new URLSearchParams({
    outputFormat: 'JSON',
    type_sf: 'coord',
    name_sf: coord,
    coord,
    rMethod: 'DISTANCEFROMCENTER',
    prefStModeAm: '30',
    anyMaxSizeHitList: '5'
  })
  const res = await fetch(`${base}?${usp}`)
  return res.json()
}

Hinweise

• Eine verifizierte id aus locations[].id lässt sich unverändert in Folge-Requests (z. B. DM, Trip) als name_<usage> verwenden.
• Bei freier Texteingabe immer debouncen (200–300 ms) und laufende Requests via AbortController abbrechen.
• matchQuality ist deployment-spezifisch skaliert; nicht mit Prozentwerten vergleichen.