Skip to main content

​
Live Suche

Mit diesem Endpunkt können Sie in Echtzeit nach Kleinanzeigen suchen. Die Daten werden nicht gecacht und direkt von der Kleinanzeigen-Plattform abgerufen.

​
Endpunkt

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

​
Wichtige Hinweise

  • LIVE = Kein Caching: Alle Daten werden in Echtzeit abgerufen
  • Response-Zeit: 2-120 Sekunden (abhängig von der externen API)
  • Rate Limiting: Strenger als bei gecachten Endpoints
  • Empfehlung: Max. 1 Request pro 5 Sekunden

​
Parameter

ParameterTypBeschreibungStandard
qstringSuchbegriff-
pageintegerSeitennummer (0-indexed)0
sizeintegerErgebnisse pro Seite10
categoryIdstringKategorie-ID (von Live Categories)-
locationIdstringStandort-ID (von Live Locations)-
distancestringRadius in km vom Standort-
minPriceintegerMindestpreis in Euro-
maxPriceintegerHöchstpreis in Euro-
pictureRequiredbooleanNur Anzeigen mit Bildern-
buyNowOnlybooleanNur “Direkt kaufen” Anzeigen-
shippablebooleanVersand verfügbar-
posterTypestringInserent: PRIVATE oder COMMERCIAL-

​
Limits nach Plan

Die maximale Anzahl der Ergebnisse (size) hängt von Ihrem API-Plan ab:
PlanMax. Ergebnisse
Free10
Basic15
Pro20
Enterprise/Developer30

​
Beispielanfrage

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

url.searchParams.append("q", "iphone");
url.searchParams.append("categoryId", "161"); // Elektronik
url.searchParams.append("locationId", "3331"); // Berlin
url.searchParams.append("distance", "20");
url.searchParams.append("minPrice", "500"); // 500€
url.searchParams.append("maxPrice", "1000"); // 1000€
url.searchParams.append("size", "10");

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

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

​
Beispielantwort

{
  "message": "Data fetched successfully from live API",
  "success": true,
  "data": {
    "meta": {
      "query": "iphone",
      "sort": null,
      "limit": 10,
      "page": 0,
      "total": 59618328,
      "max_page": 5961833,
      "api_key_role": "free",
      "source": "live"
    },
    "ads": [
      {
        "adid": "3227334640",
        "title": "iPhone 14 Pro 128GB",
        "description": "Sehr gut erhaltenes iPhone 14 Pro in Space Black. Keine Kratzer, mit Originalverpackung.",
        "price": "89900",
        "shipping": "0",
        "images": [
          "https://img.kleinanzeigen.de/api/v1/prod-ads/images/30/30fd30a5-ab75-45f0-98db-a2d67daa21f9?rule=$_1.AUTO",
          "https://img.kleinanzeigen.de/api/v1/prod-ads/images/21/217b04e9-8267-4faf-86b7-e7ba2ad4da3d?rule=$_1.AUTO"
        ],
        "views": "0",
        "upload_date": "2025-10-26T01:24:31.000+0200",
        "seller": {
          "type": "PRIVATE"
        },
        "location": {
          "state": "Berlin",
          "zip": "10115",
          "geocoding": ""
        },
        "metadata": {
          "details": "elektronik.condition:like_new|elektronik.brand:apple",
          "details_text": "Zustand: Sehr Gut | Marke: Apple",
          "categories": "161"
        }
      }
    ]
  },
  "request_id": "7f2a9e8d-4b3c-5d6e-8f9a-0b1c2d3e4f5g"
}

​
Antwortfelder

Die API liefert die folgenden Felder zurück:

​
Hauptobjekt

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

​
Meta-Objekt

FeldTypBeschreibung
querystringDer verwendete Suchbegriff
sortstringDie verwendete Sortierung
limitnumberAnzahl Ergebnisse pro Seite
pagenumberAktuelle Seitennummer
totalnumberGesamtanzahl gefundener Anzeigen
max_pagenumberMaximale Seitenzahl
api_key_rolestringIhr API-Plan (free, basic, pro, enterprise_developer)
sourcestringImmer "live" für Live-Endpoints

​
Ad-Objekt

FeldTypBeschreibung
adidstringEindeutige Anzeigen-ID
titlestringTitel der Anzeige
descriptionstringBeschreibung (HTML-Tags entfernt)
pricestringPreis in Euro
shippingstringVersandkosten (nicht verfügbar in Search, immer “0”)
imagesarrayArray von Bild-URLs (large Auflösung)
viewsstringAnzahl Aufrufe (nicht verfügbar in Search, immer “0”)
upload_datestringErstellungsdatum der Anzeige
seller.typestringInserent-Typ (PRIVATE oder COMMERCIAL)
location.statestringBundesland/Stadt
location.zipstringPostleitzahl
location.geocodingstringGeocoding (nicht verfügbar, immer leer)
metadata.detailsstringAttribute als Key-Value String
metadata.details_textstringAttribute als lesbarer Text
metadata.categoriesstringKategorie-ID

​
Verwendung mit Live-IDs

Die categoryId und locationId Parameter verwenden Live-IDs, die Sie über die entsprechenden Live-Endpoints abrufen müssen: 
// 1. Live-Kategorie-ID abrufen
const categoriesResponse = await fetch(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/categories",
  { headers: { ads_key: apiKey } }
);
const categories = await categoriesResponse.json();
const electronicsId = categories.categories.find(
  (c) => c.name === "Elektronik"
).id;

// 2. Live-Standort-ID abrufen
const locationsResponse = await fetch(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/locations?q=Berlin",
  { headers: { ads_key: apiKey } }
);
const locations = await locationsResponse.json();
const berlinId = locations.data.locations[0].id;

// 3. Live-Suche durchführen
const searchUrl = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/search"
);
searchUrl.searchParams.append("q", "iphone");
searchUrl.searchParams.append("categoryId", electronicsId);
searchUrl.searchParams.append("locationId", berlinId);
searchUrl.searchParams.append("distance", "25");

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

​
Unterschied zu gecachten Endpoints

Der normale Search-Endpunkt verwendet lokale, gecachte Daten aus unserer Datenbank:
FeatureLive SearchGecachte Search
DatenquelleExterne API (Echtzeit)Interne Datenbank
CachingNeinJa (regelmäßig aktualisiert)
Verfügbarkeit~100% (Live-Daten)~98% (umfangreicherer Datenbestand)
Response-Zeit2-120 Sekunden< 1 Sekunde
IDsLive-IDs (von Live-Endpoints)Lokale IDs
DatenumfangAktuelle AnzeigenMehr Daten inkl. Verkäuferdetails
VerwendungszweckEchtzeit-AbfragenLangzeitanalyse, umfassende Suchen
Wichtig: Die location_id und category Parameter im gecachten Search-Endpunkt verwenden lokale IDs von den Endpoints /categories und /locations. Diese sind nicht kompatibel mit den Live-IDs.

​
Fehlerbehandlung

​
400 Bad Request

{
  "message": "Requested size exceeds maximum allowed (10) for your plan",
  "success": false
}

​
404 Not Found

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

​
429 Too Many Requests

{
  "message": "Rate limit exceeded on live search service. Please try again later",
  "success": false
}

​
504 Gateway Timeout

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

​
Best Practices

  1. Rate Limiting beachten: Max. 1 Request pro 5 Sekunden
  2. Timeouts einplanen: Response kann bis zu 2 Minuten dauern
  3. Fehlerbehandlung: Implementieren Sie Retry-Logik für Timeouts
  4. IDs vorher abrufen: Holen Sie Live-IDs von Categories und Locations bevor Sie suchen
  5. Paginierung: Nutzen Sie page Parameter für große Ergebnismengen