🏠 ImmoScout24 API

Portal: api.immobilienscout24.de
Auth: OAuth 2.0 (Three-Legged / Two-Legged / Personal Access Token)
Status: 🟢 Ready

---

Übersicht

ImmoScout24 ist das größte Immobilienportal Deutschlands. Die API ermöglicht: - Inserate erstellen, aktualisieren, löschen - Exposé-Daten abrufen - Kontakte und Leads verwalten - Statistiken und Reports

---

Authentifizierung

OAuth 2.0 Options

Typ	Beschreibung	Use Case
Three-Legged	User-Consent erforderlich	Makler-Portal
Two-Legged	Server-to-Server	Automatisierung
Personal Access Token	Statischer Token	Entwicklung

// Two-Legged OAuth
const token = await getOAuthToken({
  clientId: process.env.IMMOSCOUT_CLIENT_ID,
  clientSecret: process.env.IMMOSCOUT_CLIENT_SECRET,
  grantType: 'client_credentials'
});

---

Endpunkte

Real Estate (Objekte)

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/immoscout/realestate	Alle Objekte abrufen	15 min
GET	/api/immoscout/realestate/:id	Einzelnes Objekt	15 min
POST	/api/immoscout/realestate	Objekt erstellen	-
PUT	/api/immoscout/realestate/:id	Objekt aktualisieren	-
DELETE	/api/immoscout/realestate/:id	Objekt löschen	-

Attachments (Bilder & Dokumente)

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/immoscout/realestate/:id/attachments	Alle Anhänge	30 min
POST	/api/immoscout/realestate/:id/attachments	Anhang hochladen	-
PUT	/api/immoscout/realestate/:id/attachments/:aid	Anhang aktualisieren	-
DELETE	/api/immoscout/realestate/:id/attachments/:aid	Anhang löschen	-
PUT	/api/immoscout/realestate/:id/attachments/order	Reihenfolge ändern	-

Publishing (Veröffentlichung)

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/immoscout/publish/:id/channels	Publikationskanäle	60 min
POST	/api/immoscout/publish/:id	Objekt veröffentlichen	-
DELETE	/api/immoscout/publish/:id	Veröffentlichung löschen	-

Contacts (Kontakte)

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/immoscout/contacts	Alle Kontakte	30 min
GET	/api/immoscout/contacts/:id	Einzelner Kontakt	30 min
POST	/api/immoscout/contacts	Kontakt erstellen	-
PUT	/api/immoscout/contacts/:id	Kontakt aktualisieren	-
DELETE	/api/immoscout/contacts/:id	Kontakt löschen	-

Expose (Öffentliche Daten)

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/immoscout/expose/:id	Exposé abrufen	5 min
GET	/api/immoscout/expose/:id/video	Video-URL	30 min
POST	/api/immoscout/expose/:id/contact	Kontaktanfrage senden	-

Geo Services

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/immoscout/geo/autocomplete	Geo Auto-Complete	24h
GET	/api/immoscout/geo/hierarchy	Geo Hierarchie	24h

Reports

Methode	Endpunkt	Beschreibung	Cache TTL
GET	/api/immoscout/reports/daily	Täglicher Report	1h
GET	/api/immoscout/reports/statistics	Statistiken	1h

---

Request-Beispiel

// POST /api/immoscout/realestate
const response = await fetch('/api/immoscout/realestate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    type: 'APARTMENT_RENT',
    title: 'Moderne 3-Zimmer-Wohnung in Top-Lage',
    address: {
      street: 'Musterstraße',
      houseNumber: '1',
      postcode: '80331',
      city: 'München',
      quarter: 'Altstadt-Lehel'
    },
    livingSpace: 85.5,
    numberOfRooms: 3,
    floor: 2,
    numberOfFloors: 5,
    price: {
      baseRent: 1500,
      additionalCosts: 200,
      heatingCosts: 100,
      currency: 'EUR'
    },
    features: ['BALCONY', 'ELEVATOR', 'BUILT_IN_KITCHEN'],
    energyCertificate: {
      type: 'CONSUMPTION',
      value: 85,
      validUntil: '2030-12-31'
    }
  })
});

// Response
{
  "id": "123456789",
  "scoutId": "IS24-123456789",
  "status": "ACTIVE",
  "createdAt": "2024-12-30T12:00:00Z",
  "publishedAt": null,
  "cached": false
}

---

TypeScript Types

interface ImmoScoutRealEstate {
  id: string;
  scoutId: string;
  type: 'APARTMENT_RENT' | 'APARTMENT_BUY' | 'HOUSE_RENT' | 'HOUSE_BUY' | 'PLOT' | 'OFFICE';
  title: string;
  description: string;
  address: ImmoScoutAddress;
  livingSpace: number;
  plotArea?: number;
  numberOfRooms: number;
  floor?: number;
  price: ImmoScoutPrice;
  features: string[];
  energyCertificate?: ImmoScoutEnergyCertificate;
  status: 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'ARCHIVED';
  createdAt: string;
  updatedAt: string;
}

interface ImmoScoutAddress {
  street: string;
  houseNumber: string;
  postcode: string;
  city: string;
  quarter?: string;
  geoCoordinates?: { latitude: number; longitude: number };
}

interface ImmoScoutPrice {
  baseRent?: number;
  purchasePrice?: number;
  additionalCosts?: number;
  heatingCosts?: number;
  currency: 'EUR';
  pricePerSqm?: number;
}

interface ImmoScoutAttachment {
  id: string;
  type: 'PICTURE' | 'FLOOR_PLAN' | 'VIDEO' | 'DOCUMENT';
  title: string;
  url: string;
  order: number;
}

---

Rate Limits

Limit	Wert
Requests/Minute	100
Requests/Tag	10.000
Burst	20

---

Sandbox

Für Entwicklung steht eine Sandbox zur Verfügung: - URL: https://sandbox.immobilienscout24.de/api/v1 - Postman Collection: api.immobilienscout24.de/api-docs/postman

---

Dokumentation basiert auf: api.immobilienscout24.de