Mit der Ortssuche von Maps findest du Adressen, Straßen, Postleitzahlen und Orte zu einem Suchbegriff. Das eignet sich zum Beispiel für eine Adress-Autovervollständigung im Bestellformular oder um Eingaben deiner Kunden zu vereinheitlichen. Du bekommst bis zu zehn Treffer mit Koordinaten und sauber aufgeteilten Adressbestandteilen.
Die Anfrage
Die Suche ist ein GET an https://api.flowdata.one/v1/maps/search. Pflicht ist nur der Suchbegriff q.
curl "https://api.flowdata.one/v1/maps/search?q=Alexanderplatz%201%20Berlin&limit=5&country=DE&language=de" \
-H "Authorization: Bearer fd_DEIN_SCHLUESSEL"
Diese Parameter kannst du mitgeben:
| Parameter | Bedeutung |
|---|---|
q |
Suchbegriff, Pflicht, höchstens 256 Zeichen. URL-kodiert, also Leerzeichen als %20. |
limit |
Anzahl der Treffer von 1 bis 10. Standard ist 10. |
country |
Zweistelliger Ländercode wie DE, AT oder CH. Beschränkt die Suche auf dieses Land. |
language |
Sprache der Namen. Standard ist de. |
proximity |
Ein Punkt als Längengrad,Breitengrad, zum Beispiel 13.4050,52.5200. Treffer in der Nähe werden bevorzugt. |
types |
Schränkt die Art der Treffer ein, zum Beispiel address, street, postcode oder place. Mehrere Werte trennst du mit Komma. |
Für eine Autovervollständigung reichen meist q, limit=5 und country=DE.
Die Antwort
{
"success": true,
"addresses": [
{
"lat": 52.521918,
"lng": 13.413215,
"full_address": "Alexanderplatz 1, 10178 Berlin, Deutschland",
"address_name": "Alexanderplatz 1",
"address_number": "1",
"street_name": "Alexanderplatz",
"postcode_name": "10178",
"locality_name": "Mitte",
"place_name": "Berlin",
"region_name": "Berlin",
"region_code": "BE",
"country_name": "Deutschland",
"country_code": "DE"
}
],
"attribution": "NOTICE: © 2026 ... This response and the information it contains may not be retained."
}
Das Beispiel ist gekürzt, meist enthält addresses mehrere Treffer. Jeder Treffer hat diese Felder:
- lat, lng: Breiten- und Längengrad.
- full_address: die vollständige, lesbare Adresse für die Anzeige.
- address_name: Straße mit Hausnummer.
- street_name, address_number: Straße und Hausnummer getrennt.
- postcode_name: Postleitzahl.
- locality_name: Ortsteil, falls bekannt.
- place_name: Stadt oder Gemeinde.
- region_name, region_code: Bundesland und Kürzel.
- country_name, country_code: Land und zweistelliger Ländercode.
Felder, die es für einen Treffer nicht gibt, sind null. Eine Postleitzahl als Treffer hat zum Beispiel keine Straße.
In welcher Reihenfolge kommen die Treffer?
Maps sortiert die Treffer nach Vollständigkeit. Zuerst kommen vollständige Adressen mit Straße, Hausnummer, Postleitzahl, Ort und Land. Danach folgen Straßen ohne Hausnummer, dann Postleitzahlen mit Ort, dann reine Orte und am Ende Treffer, bei denen nur das Land feststeht. Für ein Adressformular ist der erste Treffer damit meist der passendste.
Gibt es keinen Treffer, bekommst du trotzdem "success": true, aber eine leere Liste in addresses.
Was bedeutet der attribution-Text?
Jede erfolgreiche Antwort enthält im Feld attribution einen Nutzungshinweis. Er besagt, dass die Daten den Nutzungsbedingungen unterliegen und die Antwort nicht dauerhaft gespeichert werden darf. Zeig die Treffer also direkt an oder übernimm die Adresse, die deine Kundin auswählt, in ihre Bestellung. Eine eigene Adressdatenbank aus den Suchergebnissen aufzubauen, ist nicht erlaubt.
Wenn etwas nicht klappt
Fehlt q oder ist ein Parameter ungültig, antwortet Maps mit HTTP 422. Unter details steht, welches Feld das Problem ist:
{"success":false,"error":"Invalid parameters","details":{"q":["Das Feld q ist erforderlich."]}}
Weitere typische Stolpersteine wie vertauschte Koordinaten erklärt Maps findet nichts oder die falsche Stelle: Was kann ich tun?.
Was kostet eine Suche?
Die Ortssuche wird je 1.000 erfolgreiche Anfragen berechnet. Eine Suche zählt nur, wenn sie mindestens einen Treffer liefert. Eine Suche mit leerer Liste und alle Fehler sind kostenlos. Antworten aus dem Zwischenspeicher zählen wie jede andere erfolgreiche Antwort.
Die Beträge stehen auf der Preisseite, die für dein Team gültigen Preise im Dashboard unter Abrechnung. Reicht dein Guthaben nicht, antwortet die API mit HTTP 402. Mehr dazu in FlowData-Preise verstehen.
Gut zu wissen
- Wie viele Anfragen deine Integration stellt und wie viele davon fehlschlagen, siehst du im Dashboard unter Bereiche › Maps, darunter folgt das Protokoll mit jeder einzelnen Anfrage.
- Brauchst du nur die Koordinaten zu einer bekannten Adresse, ist Geocoding der direktere Weg, siehe Wie wandle ich eine Adresse in Koordinaten um und umgekehrt?.
- Schick die Suche von deinem Server aus. Für eine Autovervollständigung im Browser baust du dir einen kleinen eigenen Endpunkt, der die Eingabe an Maps weiterreicht, damit der Schlüssel nicht im Browser landet.
- Die vollständige Referenz steht in der API-Dokumentation.