Country Data API

Ortsdetails

Alles, was Sie brauchen, sobald der Nutzer einen Vorschlag auswählt

Der Endpunkt /v1/places/details nimmt die id eines Autovervollständigungs-Vorschlags entgegen und liefert den vollständigen Datensatz: die gesamte Hierarchie, das Postleitzahlformat des Landes und die Daten, die ein Formular üblicherweise als Nächstes braucht — Telefonvorwahl, Währung, Zeitzonen.

Endpunkt

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

Query-Parameter

Parameter Typ Erforderlich Beschreibung
apikey string Ja Ihr API-Authentifizierungsschlüssel
id string Ja Die von /v1/places/autocomplete zurückgegebene id
type string Ja country, state oder city — der type des Vorschlags
lang string Nein Sprache der zurückgegebenen Namen. Standard: en
sessiontoken string Nein Der in der Autovervollständigung verwendete Sitzungstoken. Macht diesen Aufruf kostenlos

Anfragebeispiel

curl "https://api.countrydataapi.com/v1/places/details?apikey=ihr-api-schluessel&id=66c7a6c9e4bda21f4ab1a0f1&type=city&lang=de"

JavaScript

async function getDetails(suggestion, sessionToken) {
  const params = new URLSearchParams({
    apikey: 'ihr-api-schluessel',
    id: suggestion.id,
    type: suggestion.type,
    lang: 'de',
    sessiontoken: sessionToken,
  });

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

TypeScript-SDK

const { place } = await api.places.details({
  id: suggestion.id,
  type: suggestion.type,
  sessiontoken: session,
});

place.components.country?.phone_code; // "+34"
place.postal.regex;                   // "^\\d{5}$"

Antwortformat

{
  "success": true,
  "place": {
    "id": "66c7a6c9e4bda21f4ab1a0f1",
    "type": "city",
    "name": "Madrid",
    "description": "Madrid, Autonome Gemeinschaft Madrid, Spanien",
    "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": "🇪🇸"
      }
    },
    "postal": {
      "format": "#####",
      "regex": "^\\d{5}$",
      "example": "12345"
    },
    "location": null,
    "country_info": {
      "currencies": [{ "code": "EUR", "name": "Euro", "symbol": "€" }],
      "languages": ["Spanisch"],
      "timezones": ["UTC+01:00"],
      "continent": "EU",
      "region": "Europe"
    }
  },
  "tokens_used": 0,
  "remaining_tokens": 4871
}

Antwortfelder

Feld Typ Beschreibung
place.components object Vollständige Hierarchie: city, state, country
place.postal.format string Vorlage: # ist eine Ziffer, @ ist ein Buchstabe
place.postal.regex string Offizielles Postleitzahlmuster des Landes
place.postal.example string Beispielwert, aus format erzeugt und gegen regex geprüft
place.location object Koordinaten — siehe Hinweis unten
place.country_info object Währungen, Sprachen, Zeitzonen, Kontinent und Region

Zu location

location ist nur bei type=country gefüllt und enthält dort den Mittelpunkt des Landes sowie "precision": "country".

Für Bundesländer und Städte ist es null. Der Datenbestand ist administrativ und enthält keine Koordinaten je Stadt; den Landesmittelpunkt als Stadt auszugeben wäre schlechter, als gar nichts zurückzugeben. Wenn Sie Koordinaten auf Stadtebene oder Geokodierung brauchen, ist dieser Endpunkt nicht das richtige Werkzeug.

Token-Verbrauch

  • 0 Token, wenn sessiontoken zu einer offenen Autovervollständigungs-Sitzung gehört. Die Sitzung wurde bereits beim ersten Tastendruck berechnet, und dieser Aufruf schließt sie.
  • 1 Token in allen anderen Fällen.

Ein vollständiges Adressfeld — beliebig viele Tastendrücke plus die abschließende Detailabfrage — kostet damit einen einzigen Token.

Fehlerantwort

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No city found with id \"abc\".",
    "status": 404
  },
  "message": "No city found with id \"abc\"."
}

Verwandte Endpunkte