Skip to main content

Inserate suchen

Mit diesem Endpunkt können Sie Inserate anhand verschiedener Parameter durchsuchen.

Endpunkt

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

Parameter

ParameterTypBeschreibungStandard
querystringSuchbegriff für Anzeigentitel und -beschreibungen.*
excludestringEine kommaseparierte Liste von Schlüsselwörtern, die aus den Suchergebnissen ausgeschlossen werden sollen. Inserate, die eines der angegebenen Schlüsselwörter im Titel oder in der Beschreibung enthalten, werden herausgefiltert.-
limitnumberAnzahl der zurückzugebenden Ergebnisse pro Seite. Der Maximalwert hängt von Ihrem API-Plan ab.5
pagenumberDie Seitennummer für die Paginierung.1
sortstringSortierreihenfolge der Ergebnisse. Mögliche Werte: newest, oldest, price_asc, price_desc, relevance."newest"
categorystring / string[]Eine einzelne Kategorie-ID oder eine kommaseparierte Liste von Kategorie-IDs zum Filtern. Verfügbare IDs können über den Kategorien-Endpunkt abgerufen werden.-
location_idnumberDie ID eines Ortes, in dessen Nähe gesucht werden soll. IDs können über den Orte-Endpunkt abgerufen werden. Muss mit radius verwendet werden.-
radiusnumberDer Suchradius in Kilometern (km) um eine location_id.-
upload_date_fromnumberDer Beginn des Datumsbereichs (Unix-Zeitstempel) zum Filtern von Anzeigen nach ihrem Hochladedatum.-
upload_date_tonumberDas Ende des Datumsbereichs (Unix-Zeitstempel) zum Filtern von Anzeigen nach ihrem Hochladedatum.-

Rollenbasierte Suchlimits

Der Maximalwert für den limit-Parameter wird durch die Rolle Ihres API-Schlüssels bestimmt:
  • Free: 10
  • Basic: 50
  • Pro: 100
  • Enterprise: 250
Wenn ein angeforderter limit den Maximalwert für Ihre Rolle überschreitet, wird er automatisch auf den zulässigen Wert begrenzt.

Beispielanfrage

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

url.searchParams.append("query", "iphone 16 pro");
url.searchParams.append("exclude", "case,reparatur");
url.searchParams.append("limit", "50");
url.searchParams.append("page", "2");
url.searchParams.append("sort", "price_asc");
url.searchParams.append("category", "123,456");
url.searchParams.append("location_id", "789");
url.searchParams.append("radius", "10");
url.searchParams.append("upload_date_from", "1672531200");

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",
  "success": true,
  "data": {
    "meta": {
      "query": "iphone 16 pro",
      "exclude": "case,reparatur",
      "sort": "price_asc",
      "limit": 50,
      "page": 2,
      "total": 1523,
      "max_page": 31,
      "api_key_role": "pro",
      "upload_date_from": "2023-01-01T00:00:00.000Z"
    },
    "ads": [
      {
        "adid": "3032850243",
        "title": "iPhone 16 Pro 128 GB Neu",
        "description": "Biete hier mein iPhone 16 Pro 128GB Neu nur ausgepackt siehe Bilder 0 Akku Zyklen am 17.03 .25 aktiviert.\nFestpreis",
        "price": 870,
        "shipping": true,
        "images": [
          "https://img.kleinanzeigen.de/api/v1/prod-ads/images/af/afd62862-258f-4843-82e3-0862f2f73cce?rule=$_59.AUTO",
          "https://img.kleinanzeigen.de/api/v1/prod-ads/images/c0/c0d9ff44-02c6-432b-a94f-95c5598a3468?rule=$_59.AUTO",
          "https://img.kleinanzeigen.de/api/v1/prod-ads/images/f6/f609ec08-a55c-459b-b19e-7b080564f312?rule=$_59.AUTO"
        ],
        "views": "0",
        "upload_date": "2025-03-19T00:00:00.000Z",
        "scrape_time": "2025-03-18T23:18:22.000Z",
        "seller": {
          "id": 12355856,
          "name": "N.E",
          "type": "Privater Nutzer",
          "since": 1352419200,
          "badges": ["10", "12", "16"],
          "badges_text": [
            "Sehr freundlich",
            "OK Zufriedenheit",
            "Sehr zuverlässig"
          ]
        },
        "location": {
          "id": 1173,
          "city": "Main",
          "state": "Frankfurt",
          "zip": "60486",
          "geocoding": [50.1130657, 8.6252221]
        },
        "metadata": {
          "details": [
            {
              "d": 72946,
              "v": 81107
            },
            {
              "d": 72947,
              "v": 81063
            },
            {
              "d": 72949,
              "v": 81117
            },
            {
              "d": 72954,
              "v": 81144
            }
          ],
          "details_text": "Art:Apple | Zustand:Neu | Farbe:Schwarz | Gerät & Zubehör:Gerät",
          "categories": ["49", "110", "175"],
          "categories_text": [
            "Elektronik",
            "Handy & Telefon",
            "Kleinanzeigen Frankfurt am Main"
          ]
        }
      }
    ]
  },
  "request_id": "8c4b1560-86cb-4cf5-b928-254745aed250"
}

Antwortfelder

Die API liefert die folgenden Felder zurück:

Hauptobjekt

FeldBeschreibung
messageStatusmeldung der Anfrage
successErfolgsindikator (true/false)
dataEnthält die Suchergebnisse
request_idEindeutige ID dieser Anfrage (nützlich für Support)

Data-Objekt

FeldBeschreibung
metaMetainformationen zur Suchanfrage
adsArray mit den gefundenen Inseraten

Meta-Objekt (meta)

FeldTypBeschreibung
querystringDie verwendete Suchanfrage.
excludestringDie verwendeten Ausschluss-Schlüsselwörter, falls angegeben.
sortstringDie verwendete Sortiermethode.
limitnumberDie Anzahl der pro Seite angeforderten Ergebnisse.
pagenumberDie aktuelle Seitennummer.
totalnumberDie Gesamtzahl der gefundenen Anzeigen, die der Anfrage entsprechen.
max_pagenumberDie Gesamtzahl der verfügbaren Seiten für die aktuelle Anfrage und das Limit.
api_key_rolestringDie Rolle Ihres API-Schlüssels (free, basic, pro, enterprise).
upload_date_fromstringDer Startdatumsfilter (im ISO 8601-Format), falls angegeben.
upload_date_tostringDer Enddatumsfilter (im ISO 8601-Format), falls angegeben.

Inserat-Objekt

FeldBeschreibung
adidEindeutige ID des Inserats
titleTitel des Inserats
descriptionBeschreibung des Inserats
pricePreis in Euro
shippingGibt an, ob Versand möglich ist
imagesArray mit URLs zu Bildern des Inserats
viewsAnzahl der Aufrufe
upload_dateDatum, an dem das Inserat erstellt wurde
scrape_timeZeitpunkt, zu dem das Inserat zuletzt gescrapt wurde
sellerInformationen zum Verkäufer
locationStandortinformationen
metadataZusätzliche Informationen zum Inserat

Umkreissuche

Die API unterstützt eine geografische Umkreissuche. Dafür müssen Sie zuerst über den Orte-Endpunkt eine Location-ID ermitteln und diese dann mit einem Radius verwenden.

Beispiel: Umkreissuche

// 1. Schritt: Ort suchen
const locationUrl = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/locations"
);
locationUrl.searchParams.append("query", "München");

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

const locationData = await locationResponse.json();
const locationId = locationData.data.locations[0].id;

// 2. Schritt: Umkreissuche durchführen
const searchUrl = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/search"
);
searchUrl.searchParams.append("query", "fahrrad");
searchUrl.searchParams.append("location_id", locationId);
searchUrl.searchParams.append("radius", 30); // 30km Umkreis

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

const searchData = await searchResponse.json();
console.log(searchData);

Kombinierte Suche

Sie können die Umkreissuche mit allen anderen Suchparametern kombinieren:
const url = new URL(
  "https://api.kleinanzeigen-agent.de/ads/v1/kleinanzeigen/search"
);

// Alle Parameter kombinieren
url.searchParams.append("query", "iPhone");
url.searchParams.append("category", "110"); // Handy & Telefon
url.searchParams.append("location_id", 2031); // Berlin Mitte
url.searchParams.append("radius", 25); // 25km Umkreis
url.searchParams.append("sort", "newest");
url.searchParams.append("limit", 20);

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