Skip to main content

​
Live Orte suchen

Mit diesem Endpunkt können Sie nach Orten in Echtzeit auf der Kleinanzeigen-Plattform suchen und Location-IDs mit geografischen Informationen abrufen. Die Daten werden nicht gecacht und sind immer aktuell.

​
Endpunkt

GET https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations

​
Wichtige Hinweise

  • LIVE = Kein Caching: Standorte werden in Echtzeit von der Plattform abgerufen
  • Response-Zeit: Bis zu 60 Sekunden (abhängig von der externen API)
  • Suchbegriff erforderlich: Der q Parameter ist REQUIRED (vollständige Standortliste sehr groß)
  • Live-IDs: Die zurückgegebenen IDs sind für den Live Search-Endpunkt gedacht

​
Parameter

ParameterTypRequiredBeschreibungStandard
qstringJaSuchbegriff für Standort (z.B. “Berlin”)-
latitudefloatNeinBreitengrad für Standortsuche-
longitudefloatNeinLängengrad für Standortsuche-
limitintegerNeinMax. Anzahl Ergebnisse (max 500)100

​
Beispielanfrage

​
Suche nach Name

const apiKey = "IHR_API_SCHLÜSSEL";
const url = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations"
);

url.searchParams.append("q", "Berlin");
url.searchParams.append("limit", 20);

const response = await fetch(url, {
  headers: {
    ads_key: apiKey,
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);

​
Suche nach Koordinaten

const apiKey = "IHR_API_SCHLÜSSEL";
const url = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations"
);

url.searchParams.append("q", "nearby");
url.searchParams.append("latitude", "52.520008");
url.searchParams.append("longitude", "13.404954");
url.searchParams.append("limit", 50);

const response = await fetch(url, {
  headers: {
    ads_key: apiKey,
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);

​
Beispielantwort

{
  "message": "Locations fetched successfully from live API",
  "success": true,
  "data": {
    "meta": {
      "query": "Berlin",
      "limit": 100,
      "total": 25,
      "source": "live"
    },
    "locations": [
      {
        "id": "3331",
        "city": "Berlin",
        "state": "Berlin",
        "zip": null,
        "latitude": "52.520008",
        "longitude": "13.404954"
      },
      {
        "id": "3332",
        "city": "Berlin-Mitte",
        "state": "Berlin",
        "zip": null,
        "latitude": "52.532614",
        "longitude": "13.3777035"
      }
    ]
  }
}

​
Antwortfelder

Die API liefert die folgenden Felder zurück:

​
Hauptobjekt

FeldTypBeschreibung
messagestringStatusmeldung der Anfrage
successbooleanErfolgsindikator (true/false)
dataobjectEnthält die Suchergebnisse

​
Meta-Objekt

FeldTypBeschreibung
querystringDer verwendete Suchbegriff
limitnumberMax. Anzahl Ergebnisse
totalnumberAnzahl zurückgegebener Standorte
sourcestringImmer "live" für Live-Endpoints

​
Location-Objekt

FeldTypBeschreibung
idstringEindeutige Live-Standort-ID (für locationId in Live Search)
citystringStadt/Stadtteil Name
statestringBundesland
zipstringPostleitzahl (meist null in Standort-Hierarchie)
latitudestringBreitengrad
longitudestringLängengrad

​
Verwendung für Live-Umkreissuche

Die erhaltenen Location-IDs können Sie für die Umkreissuche im Live Search-Endpunkt verwenden: 
// 1. Live-Standort suchen
const locationResponse = await fetch(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations?q=München",
  { headers: { ads_key: apiKey } }
);
const locations = await locationResponse.json();

// 2. Location-ID extrahieren
const locationId = locations.data.locations[0].id;
console.log(`München Location-ID: ${locationId}`);

// 3. Live-Umkreissuche durchführen
const searchUrl = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/search"
);
searchUrl.searchParams.append("q", "fahrrad");
searchUrl.searchParams.append("locationId", locationId);
searchUrl.searchParams.append("distance", "25"); // 25km Umkreis

const searchResponse = await fetch(searchUrl, {
  headers: { ads_key: apiKey },
});

const searchData = await searchResponse.json();
console.log(`${searchData.data.meta.total} Anzeigen gefunden`);

​
Unterschied zu gecachten Locations

Der normale Locations-Endpunkt verwendet lokale, gecachte Daten aus unserer Datenbank:
FeatureLive LocationsGecachte Locations
DatenquelleExterne APIInterne Datenbank
CachingNeinJa (regelmäßig aktualisiert)
Verfügbarkeit~100% (Live-Daten)~98% (umfangreicherer Datenbestand)
Response-ZeitBis zu 60 Sekunden< 1 Sekunde
ID-FormatLive-IDs (string)Lokale IDs (number)
VerwendungLive SearchGecachte Search
KoordinatenJaJa
VerwendungszweckEchtzeit-StandortabfragenLangzeitanalyse, umfassende Suchen
Wichtig: Die Location-IDs von diesem Live-Endpunkt sind nicht kompatibel mit dem gecachten Search-Endpunkt. Verwenden Sie:

​
Beispiel: Mehrere Städte gleichzeitig suchen

const apiKey = "IHR_API_SCHLÜSSEL";
const cities = ["Berlin", "München", "Hamburg", "Köln"];

async function getLocationIds(cityName) {
  const url = new URL(
    "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations"
  );
  url.searchParams.append("q", cityName);
  url.searchParams.append("limit", 1);

  const response = await fetch(url, {
    headers: { ads_key: apiKey },
  });

  const data = await response.json();
  return {
    city: cityName,
    id: data.data.locations[0]?.id,
    coords: {
      lat: data.data.locations[0]?.latitude,
      lng: data.data.locations[0]?.longitude,
    },
  };
}

// Alle Städte nacheinander abrufen (wegen Rate Limit)
const locationData = [];
for (const city of cities) {
  const data = await getLocationIds(city);
  locationData.push(data);
  console.log(`${city}: ID ${data.id}`);

  // Rate Limit: 1 Request pro 5 Sekunden
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

console.log(locationData);

​
Beispiel: Umkreissuche mit Koordinaten

// Nutzer-Position (z.B. vom Browser Geolocation API)
const userLat = 52.520008;
const userLng = 13.404954;

// 1. Nächstgelegenen Standort finden
const locationResponse = await fetch(
  `https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations?q=nearby&latitude=${userLat}&longitude=${userLng}&limit=1`,
  { headers: { ads_key: apiKey } }
);
const { data } = await locationResponse.json();
const nearestLocation = data.locations[0];

console.log(`Nächster Standort: ${nearestLocation.city}`);

// 2. In diesem Umkreis suchen
const searchUrl = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/search"
);
searchUrl.searchParams.append("q", "sofa");
searchUrl.searchParams.append("locationId", nearestLocation.id);
searchUrl.searchParams.append("distance", "10"); // 10km Umkreis

const searchResponse = await fetch(searchUrl, {
  headers: { ads_key: apiKey },
});

​
Fehlerbehandlung

​
400 Bad Request

{
  "message": "Query parameter 'q' is required for location search",
  "success": false
}

​
404 Not Found

{
  "message": "No locations found matching your search",
  "success": false
}

​
504 Gateway Timeout

{
  "message": "Request timeout - the locations service took too long to respond",
  "success": false
}

​
Best Practices

  1. Suchbegriff immer angeben: Der q Parameter ist erforderlich
  2. Rate Limiting beachten: Max. 1 Request pro 5 Sekunden
  3. Caching implementieren: Speichern Sie häufig verwendete Location-IDs clientseitig
  4. Fehlerbehandlung: Implementieren Sie Retry-Logik für Timeouts
  5. Koordinaten nutzen: Für Umkreissuche vom aktuellen Standort
  6. Timeout einplanen: Response kann bis zu 60 Sekunden dauern
  7. Live-IDs speichern: Speichern Sie die IDs für spätere Live-Suchen

​
Vollständiges Workflow-Beispiel

const apiKey = "IHR_API_SCHLÜSSEL";

async function searchWithLocation() {
  try {
    // 1. Standort suchen
    console.log("Suche nach Standort 'Berlin'...");
    const locationUrl = new URL(
      "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations"
    );
    locationUrl.searchParams.append("q", "Berlin");

    const locationResponse = await fetch(locationUrl, {
      headers: { ads_key: apiKey },
    });

    if (!locationResponse.ok) {
      throw new Error("Location search failed");
    }

    const { data: locationData } = await locationResponse.json();
    const berlin = locationData.locations[0];
    console.log(`✓ Berlin gefunden (ID: ${berlin.id})`);

    // 2. Rate Limit respektieren
    console.log("Warte 5 Sekunden (Rate Limit)...");
    await new Promise((resolve) => setTimeout(resolve, 5000));

    // 3. Live-Suche durchführen
    console.log("Suche nach Anzeigen...");
    const searchUrl = new URL(
      "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/search"
    );
    searchUrl.searchParams.append("q", "laptop");
    searchUrl.searchParams.append("locationId", berlin.id);
    searchUrl.searchParams.append("distance", "15");
    searchUrl.searchParams.append("minPrice", "30000"); // 300€

    const searchResponse = await fetch(searchUrl, {
      headers: { ads_key: apiKey },
    });

    if (!searchResponse.ok) {
      throw new Error("Search failed");
    }

    const { data: searchData } = await searchResponse.json();
    console.log(`✓ ${searchData.meta.total} Anzeigen gefunden`);

    // Erste 5 Anzeigen ausgeben
    searchData.ads.slice(0, 5).forEach((ad, i) => {
      console.log(`\n${i + 1}. ${ad.title}`);
      console.log(`   Preis: ${(parseInt(ad.price) / 100).toFixed(2)}€`);
      console.log(`   Ort: ${ad.location.state}`);
    });
  } catch (error) {
    console.error("Fehler:", error.message);
  }
}

searchWithLocation();