Skip to main content

​
Live Kategorien abrufen

Mit diesem Endpunkt können Sie die vollständige Kategorie-Liste in Echtzeit von der Kleinanzeigen-Plattform abrufen. Die Daten werden nicht gecacht und sind immer aktuell.

​
Endpunkt

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

​
Wichtige Hinweise

  • LIVE = Kein Caching: Kategorien werden in Echtzeit von der Plattform abgerufen
  • Response-Zeit: Bis zu 60 Sekunden (abhängig von der externen API)
  • Immer aktuell: Neue Kategorien sind sofort verfügbar
  • Live-IDs: Die zurückgegebenen IDs sind für den Live Search-Endpunkt gedacht

​
Parameter

Dieser Endpunkt erfordert keine Parameter.

​
Beispielanfrage

const apiKey = "IHR_API_SCHLÜSSEL";
const url =
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/categories";

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

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

​
Beispielantwort

{
  "message": "Categories fetched successfully from live API",
  "success": true,
  "categories": [
    {
      "id": "210",
      "name": "Auto, Rad & Boot",
      "parent_id": "0"
    },
    {
      "id": "216",
      "name": "Autos",
      "parent_id": "210"
    },
    {
      "id": "161",
      "name": "Elektronik",
      "parent_id": "0"
    },
    {
      "id": "173",
      "name": "Audio & HiFi",
      "parent_id": "161"
    }
  ]
}

​
Antwortfelder

Die API liefert die folgenden Felder zurück:

​
Hauptobjekt

FeldTypBeschreibung
messagestringStatusmeldung der Anfrage
successbooleanErfolgsindikator (true/false)
categoriesarrayArray mit allen Kategorien

​
Kategorie-Objekt

FeldTypBeschreibung
idstringEindeutige Live-Kategorie-ID (für categoryId in Live Search)
namestringName der Kategorie (lokalisiert)
parent_idstringID der Elternkategorie ("0" für Top-Level, null für Root)

​
Hierarchie-Struktur

Die Kategorien werden als flaches Array zurückgegeben. Die Hierarchie kann über parent_id rekonstruiert werden: 
const response = await fetch(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/categories",
  { headers: { ads_key: apiKey } }
);

const { categories } = await response.json();

// Top-Level Kategorien (parent_id = "0")
const topLevelCategories = categories.filter((c) => c.parent_id === "0");

// Unterkategorien einer Kategorie finden
function getSubcategories(parentId) {
  return categories.filter((c) => c.parent_id === parentId);
}

const elektronikSubs = getSubcategories("161");
console.log(elektronikSubs);
// [{ id: "173", name: "Audio & HiFi", parent_id: "161" }, ...]

​
Verwendung für Live-Suche

Die erhaltenen Kategorie-IDs können Sie für die Suche im Live Search-Endpunkt verwenden: 
// 1. Kategorien abrufen
const categoriesResponse = await fetch(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/categories",
  { headers: { ads_key: apiKey } }
);
const { categories } = await categoriesResponse.json();

// 2. Gewünschte Kategorie finden
const elektronik = categories.find((c) => c.name === "Elektronik");
console.log(elektronik.id); // "161"

// 3. Mit Kategorie-ID in Live-Suche verwenden
const searchUrl = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/search"
);
searchUrl.searchParams.append("q", "smartphone");
searchUrl.searchParams.append("categoryId", elektronik.id);

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

​
Unterschied zu gecachten Kategorien

Der normale Categories-Endpunkt verwendet lokale, gecachte Daten aus unserer Datenbank:
FeatureLive CategoriesGecachte Categories
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
HierarchieMit parent_idFlat
VerwendungszweckEchtzeit-KategorieabfragenLangzeitanalyse, umfassende Suchen
Wichtig: Die Kategorie-IDs von diesem Live-Endpunkt sind nicht kompatibel mit dem gecachten Search-Endpunkt. Verwenden Sie:

​
Beispiel: Kategoriebaum erstellen

const response = await fetch(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/live/categories",
  { headers: { ads_key: apiKey } }
);

const { categories } = await response.json();

function buildCategoryTree(parentId = "0", level = 0) {
  const children = categories.filter((c) => c.parent_id === parentId);

  children.forEach((category) => {
    const indent = "  ".repeat(level);
    console.log(`${indent}- ${category.name} (ID: ${category.id})`);

    // Rekursiv Unterkategorien anzeigen
    buildCategoryTree(category.id, level + 1);
  });
}

console.log("Kategoriebaum:");
buildCategoryTree();
Ausgabe: 
Kategoriebaum:
- Auto, Rad & Boot (ID: 210)
  - Autos (ID: 216)
  - Motorräder & Motorroller (ID: 305)
- Elektronik (ID: 161)
  - Audio & HiFi (ID: 173)
  - Foto & Camcorder (ID: 174)

​
Fehlerbehandlung

​
404 Not Found

{
  "message": "Categories not found or the service is temporarily unavailable",
  "success": false
}

​
504 Gateway Timeout

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

​
Best Practices

  1. Caching implementieren: Da sich Kategorien selten ändern, können Sie die Antwort clientseitig cachen
  2. Fehlerbehandlung: Implementieren Sie Retry-Logik für Timeouts
  3. Hierarchie nutzen: Verwenden Sie parent_id für bessere UX (verschachtelte Menüs)
  4. Live-IDs speichern: Speichern Sie die IDs für spätere Live-Suchen
  5. Timeout einplanen: Response kann bis zu 60 Sekunden dauern