Orts-Autovervollständigung

Suchen Sie Länder, Bundesländer und Städte, während der Nutzer tippt

Der Endpunkt /v1/places/autocomplete treibt das Adressfeld eines Checkouts, eines Registrierungsformulars oder eines Versandkostenrechners an. Sie senden, was der Nutzer bisher eingegeben hat, und erhalten nach Relevanz sortierte Vorschläge — jeder bereits mit seiner vollständigen Hierarchie, sodass Sie Madrid, Autonome Gemeinschaft Madrid, Spanien ohne einen zweiten Aufruf anzeigen können.

Er deckt die Ebenen Land, Bundesland und Stadt ab. Er deckt keine Adressen auf Straßenebene und keine Points of Interest wie Geschäfte, Öffnungszeiten oder Bewertungen ab.

Endpunkt

GET https://api.countrydataapi.com/v1/places/autocomplete

Query-Parameter

Wie die Suche trifft

Die Anfrage wird vor der Suche normalisiert, damit der Nutzer nicht gegen seine Tastatur kämpfen muss:

• Unabhängig von Groß-/Kleinschreibung und Akzenten — avila findet Ávila, munchen findet München.
• Unabhängig von Satzzeichen — hospitalet findet L'Hospitalet de Llobregat.
• Jedes Wort trifft — york findet New York, nicht nur Namen, die mit York beginnen.

Die Ergebnisse werden nach Trefferqualität sortiert (exakter Name, dann Namensanfang, dann Anfang eines inneren Wortes), danach von der weiteren zur engeren Verwaltungsebene und zuletzt nach Namenslänge. Das Feld match jedes Vorschlags gibt an, welche Regel gegriffen hat — praktisch zum Hervorheben im Text.

Anfragebeispiel

curl "https://api.countrydataapi.com/v1/places/autocomplete?apikey=ihr-api-schluessel&q=mad&country=ES&limit=5&lang=de"

JavaScript

const API_KEY = 'ihr-api-schluessel';

async function search(query, sessionToken) {
  const params = new URLSearchParams({
    apikey: API_KEY,
    q: query,
    limit: '5',
    lang: 'de',
    sessiontoken: sessionToken,
  });

  const response = await fetch(
    `https://api.countrydataapi.com/v1/places/autocomplete?${params}`
  );
  return response.json();
}

Python

import requests

response = requests.get(
    'https://api.countrydataapi.com/v1/places/autocomplete',
    params={
        'apikey': 'ihr-api-schluessel',
        'q': 'mad',
        'country': 'ES',
        'limit': 5,
        'lang': 'de',
    },
)
data = response.json()

TypeScript-SDK

import { CountryDataApi, Places } from '@countrydataapi/sdk';

const api = new CountryDataApi({ apiKey: 'ihr-api-schluessel' });
const session = Places.createSession();

const { suggestions } = await api.places.autocomplete({
  q: 'mad',
  country: 'ES',
  lang: 'de',
  sessiontoken: session,
});

Antwortformat

{
  "success": true,
  "query": "mad",
  "suggestions": [
    {
      "id": "66c7a6c9e4bda21f4ab1a0f1",
      "type": "city",
      "name": "Madrid",
      "description": "Madrid, Autonome Gemeinschaft Madrid, Spanien",
      "match": "prefix",
      "components": {
        "city": { "id": "66c7a6c9e4bda21f4ab1a0f1", "name": "Madrid" },
        "state": { "id": "66c7a6c9e4bda21f4ab10a22", "name": "Autonome Gemeinschaft Madrid" },
        "country": {
          "id": "66c7a6c9e4bda21f4ab10ef2",
          "name": "Spanien",
          "iso2": "ES",
          "iso3": "ESP",
          "phone_code": "+34",
          "flag": "🇪🇸"
        }
      }
    }
  ],
  "count": 1,
  "session": { "token": "6f9e...", "billed": true, "ttl_seconds": 180 },
  "tokens_used": 1,
  "remaining_tokens": 4871
}

Antwortfelder

Token-Verbrauch: pro Sitzung, nicht pro Tastendruck

Eine Autovervollständigung löst bei jedem Tastendruck eine Anfrage aus. Pro Anfrage abzurechnen würde bedeuten, dass ein einziges Adressfeld 8 bis 10 Token kostet und Ihre Rechnung davon abhängt, wie schnell Ihre Nutzer tippen.

Senden Sie einen sessiontoken — eine beliebige UUID, erzeugt beim Fokussieren des Feldes — und die gesamte Sitzung kostet 1 Token, unabhängig davon, wie viele Anfragen nötig waren:

1. Erzeugen Sie einen Token, wenn das Adressfeld den Fokus erhält.
2. Senden Sie ihn bei jedem /autocomplete-Aufruf. Nur der erste wird berechnet.
3. Senden Sie ihn beim /details-Aufruf für den vom Nutzer gewählten Vorschlag. Dieser Aufruf ist kostenlos und schließt die Sitzung.
4. Erzeugen Sie einen neuen Token für das nächste Adressfeld.

Sitzungen laufen nach 3 Minuten ab. Ohne sessiontoken kostet jede Anfrage 1 Token.

// Eine Sitzung pro Adressfeld
let session = crypto.randomUUID();

input.addEventListener('focus', () => { session = crypto.randomUUID(); });

// ...jeder Tastendruck nutzt `session` weiter, das ganze Feld kostet also 1 Token

Fehlerantwort

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter \"q\" is required and must be at least 2 characters long.",
    "status": 400
  },
  "message": "Parameter \"q\" is required and must be at least 2 characters long."
}

Anders als die älteren Endpunkte gibt /v1/places/* einen echten HTTP-Statuscode (400, 401, 402, 404) zusammen mit einem stabilen error.code zurück. Siehe die Dokumentation der Fehlercodes.

Aufrufe aus dem Browser

/v1/* sendet Access-Control-Allow-Origin: *, Sie können die Autovervollständigung also ohne Proxy direkt aus Ihrem Frontend aufrufen. Bedenken Sie, dass der API-Schlüssel dann für jeden sichtbar ist, der die Entwicklertools öffnet: Verwenden Sie einen Schlüssel mit einem Budget, dessen Offenlegung für Sie vertretbar ist, oder leiten Sie über Ihr eigenes Backend, wenn Ihnen das wichtig ist.

Praktische Hinweise

1. Setzen Sie ein Debounce von etwa 150 ms. Weniger Anfragen, gleiches Gefühl.
2. Fordern Sie 2 bis 3 Zeichen, bevor Sie suchen. Kürzere Anfragen sind nicht hilfreich.
3. Übergeben Sie country, wenn Sie es bereits kennen. Weniger und bessere Vorschläge.
4. Übergeben Sie types=city, wenn das Feld gezielt eine Stadt erfasst.
5. Speichern Sie nichts nutzerbezogen zwischen — aber es steht Ihnen frei, die zurückgegebenen Daten beliebig lange zu speichern und zu cachen. Für ihre Aufbewahrung gibt es keine Einschränkung.

Verwandte Endpunkte

• GET /v1/places/details - Vollständiger Datensatz zu einem Vorschlag
• GET /v1/places/validate - Eine vollständige Adresse validieren
• GET /v1/places/postal-format - Postleitzahlformat pro Land

Vollständige Integrationsanleitung

• Adress-Autovervollständigung von Anfang bis Ende