ForDevo API Documentation
Přehled
ForDevo API umožňuje přístup k inzertnímu systému pro developery a realitní kanceláře. API poskytuje funkce pro získávání, filtrování a správu inzerátů nemovitostí.
Base URL
https://your-domain.com/apiAutentifikace
Zatím bez autentifikace - doporučuje se implementovat API klíče pro produkci
Rate Limiting
Zatím bez omezení - doporučuje se implementovat pro produkci
Endpointy
1. Získání všech inzerátů
Endpoint: GET /listings/all
Popis: Vrací seznam všech inzerátů seřazených podle data vytvoření (nejnovější první).
Query parametry:
limit(number, optional) - Omezí počet vrácených výsledků (výchozí: 100)
Příklad requestu:
httpGET /api/listings/all?limit=50Response:
json[ { "_id": "507f1f77bcf86cd799439011", "name": "Moderní byt 2+kk", "description": "Krásný světlý byt v centru města", "project": "507f1f77bcf86cd799439012", "building": "507f1f77bcf86cd799439013", "buildingCode": "A1", "buildingName": "Rezidence Central", "buildingDetails": { "_id": "507f1f77bcf86cd799439013", "code": "A1", "name": "Rezidence Central" }, "categories": ["507f1f77bcf86cd799439014", "507f1f77bcf86cd799439015"], "categoryDetails": [ { "_id": "507f1f77bcf86cd799439014", "name": "Byty", "slug": "byty" } ], "mainImageUrl": "https://example.com/image.jpg", "galleryUrls": ["https://example.com/gallery1.jpg"], "price": 4500000, "status": "available", "visibility": "public", "usable_area": 65.5, "floor_area": 70.2, "addons": ["balkon", "sklep"], "rooms": "2+kk", "visualizations": [ { "name": "3D Model", "url": "https://example.com/3d-model" } ], "floor": 3, "location": { "address": "Náměstí Míru 123", "city": "Praha", "coordinates": [14.4378, 50.0755] }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-16T14:20:00Z" }]2. Detail inzerátu
Endpoint: GET /listings/detail
Popis: Vrací detailní informace o konkrétním inzerátu včetně všech souvisejících dat.
Query parametry:
id(string, required) - MongoDB ObjectId inzerátu
Příklad requestu:
httpGET /api/listings/detail?id=507f1f77bcf86cd799439011Response:
json{ "_id": "507f1f77bcf86cd799439011", "name": "Moderní byt 2+kk", "description": "Krásný světlý byt v centru města s výhledem na park", "project": "507f1f77bcf86cd799439012", "building": "507f1f77bcf86cd799439013", "buildingCode": "A1", "buildingName": "Rezidence Central", "buildingDetails": { "_id": "507f1f77bcf86cd799439013", "code": "A1", "name": "Rezidence Central", "address": "Náměstí Míru 123, Praha" }, "categories": ["507f1f77bcf86cd799439014", "507f1f77bcf86cd799439015"], "categoryDetails": [ { "_id": "507f1f77bcf86cd799439014", "name": "Byty", "slug": "byty" }, { "_id": "507f1f77bcf86cd799439015", "name": "2+kk", "slug": "2kk" } ], "mainImageUrl": "https://example.com/main-image.jpg", "galleryUrls": [ "https://example.com/gallery1.jpg", "https://example.com/gallery2.jpg" ], "price": 4500000, "status": "available", "visibility": "public", "usable_area": 65.5, "floor_area": 70.2, "addons": ["balkon", "sklep", "garážové stání"], "rooms": "2+kk", "visualizations": [ { "name": "3D Model", "url": "https://example.com/3d-model", "type": "3d" }, { "name": "Vizualizace obývacího pokoje", "url": "https://example.com/visualization1.jpg", "type": "image" } ], "floor": 3, "features": [ "klimatizace", "podlahové topení", "bezpečnostní dveře" ], "location": { "address": "Náměstí Míru 123", "city": "Praha", "coordinates": [14.4378, 50.0755], "district": "Vinohrady" }, "energyLabel": "B", "itemId": "UNIT-A1-03-12", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-16T14:20:00Z"}3. Filtrované inzeráty podle kategorií (legacy)
Endpoint: GET /listings
Popis: Vrací inzeráty filtrované podle konkrétních kategorií (implementováno pro byty/1kk).
Query parametry: Zatím hard-coded pro "byty" a "1kk" - doporučuje se rozšířit o flexibilní parametry
Příklad requestu:
httpGET /api/listingsResponse:
json[ { "_id": "507f1f77bcf86cd799439011", "name": "Garsonka v centru", "description": "Kompaktní bydlení pro mladé", "categories": ["507f1f77bcf86cd799439014", "507f1f77bcf86cd799439016"], "price": 2800000, "status": "available", "rooms": "1+kk", "usable_area": 28.5, "createdAt": "2024-01-15T10:30:00Z" }]4. Inzeráty podle kategorie (nový)
Endpoint: GET /listings/category
Popis: Vrací inzeráty filtrované podle slug kategorie s kompletními detaily.
Query parametry:
slug(string, required) - Slug kategorie (např. "byty", "domy", "kancelare")
Příklad requestu:
httpGET /api/listings/category?slug=bytyResponse:
json[ { "_id": "507f1f77bcf86cd799439011", "name": "Moderní byt 3+kk", "description": "Prostorný byt s terasou", "project": "507f1f77bcf86cd799439012", "building": "507f1f77bcf86cd799439013", "buildingCode": "B2", "buildingName": "Rezidence Garden", "buildingDetails": { "_id": "507f1f77bcf86cd799439013", "code": "B2", "name": "Rezidence Garden" }, "categories": ["507f1f77bcf86cd799439014"], "categoryDetails": [ { "_id": "507f1f77bcf86cd799439014", "name": "Byty", "slug": "byty" } ], "mainImageUrl": "https://example.com/main-image.jpg", "galleryUrls": ["https://example.com/gallery1.jpg"], "price": 6200000, "status": "available", "visibility": "public", "size": 85.5, "rooms": "3+kk", "floor": 5, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-16T14:20:00Z" }]5. Health check
Endpoint: GET /health
Popis: Kontrola stavu API a databázového připojení.
Příklad requestu:
httpGET /api/healthResponse:
json{ "ok": true}Response při chybě:
json{ "ok": false, "error": "Database connection failed"}Datové modely
Listing (Inzerát)
typescriptinterface Listing { _id: string; // MongoDB ObjectId name: string; // Název inzerátu description: string; // Popis nemovitosti project: string; // ID projektu building: string; // ID budovy buildingCode?: string; // Kód budovy (z join) buildingName?: string; // Název budovy (z join) buildingDetails?: Building; // Detaily budovy categories: string[]; // Pole ID kategorií categoryDetails?: Category[]; // Detaily kategorií mainImageUrl?: string; // URL hlavního obrázku galleryUrls?: string[]; // Pole URL obrázků price: number; // Cena v Kč status: 'available' | 'sold' | 'reserved'; visibility: 'public' | 'private'; // Plocha - různé implementace podle projektu usable_area?: number; // Užitná plocha (m²) - projekt 1 floor_area?: number; // Podlahová plocha (m²) - projekt 1 size?: number; // Celková plocha (m²) - projekt 2 addons?: string[]; // Doplňky (balkon, sklep, atd.) rooms: string; // Dispozice (2+kk, 3+1, atd.) visualizations?: Visualization[]; floor?: number; // Patro features?: string[]; // Vybavení location?: Location; energyLabel?: string; // Energetický štítek itemId?: string; // Interní ID jednotky createdAt: string; // ISO datum vytvoření updatedAt: string; // ISO datum aktualizace}Building (Budova)
typescriptinterface Building { _id: string; code: string; // Kód budovy name: string; // Název budovy address?: string; // Adresa}Category (Kategorie)
typescriptinterface Category { _id: string; name: string; // Název kategorie slug: string; // URL slug}Visualization (Vizualizace)
typescriptinterface Visualization { name: string; // Název vizualizace url: string; // URL souboru type?: string; // Typ (3d, image, video)}Location (Lokace)
typescriptinterface Location { address: string; // Adresa city: string; // Město coordinates?: [number, number]; // [longitude, latitude] district?: string; // Městská část}Chybové kódy
Příklady chybových odpovědí
400 - Chybí parametr
json{ "error": "Missing \"id\" query parameter"}400 - Chybí slug parametr
json{ "error": "Missing \"slug\" query parameter"}400 - Nevalidní formát ID
json{ "error": "Invalid ID format"}404 - Inzerát nenalezen
json{ "error": "Listing not found"}404 - Kategorie nenalezena
json[]Poznámka: Endpoint /api/listings/category vrací prázdné pole místo error zprávy
500 - Serverová chyba
json{ "error": "Database connection failed", "stack": "Error stack trace..."}500 - Health check chyba
json{ "ok": false, "error": "Database connection failed"}Sjednocení API mezi projekty
Rozdíly mezi projekty
Na základě analýzy dvou projektů byly identifikovány tyto rozdíly:
Doporučení pro sjednocení
1. Standardizace datových polí:
typescript// Doporučená struktura pro všechny projektyinterface StandardListing { // Plocha - sjednotit na jeden způsob usable_area: number; // Užitná plocha floor_area?: number; // Podlahová plocha (volitelná) total_area?: number; // Celková plocha (volitelná) // Nebo alternativně pouze size: number; // Hlavní plocha size_type: 'usable' | 'floor' | 'total'; // Typ plochy}2. Sjednotit error handling:
json// Konzistentní formát pro všechny chyby{ "error": "Category not found", "code": "CATEGORY_NOT_FOUND", "status": 404}3. Univerzální kategorie endpoint:
httpGET /api/listings/filter?category=byty&subcategory=1kk&limit=504. Standardní response formát:
json{ "data": [...], "pagination": { "page": 1, "limit": 50, "total": 125, "pages": 3 }, "meta": { "query_time": "23ms", "total_found": 125 }}Plánovaná vylepšení
1. Sjednocené filtrování (rozšíření stávajících)
httpGET /api/listings/filter?category=byty&subcategory=2kk&price_min=3000000&price_max=5000000&location=praha&size_min=502. Pokročilé vyhledávání
httpGET /api/listings/search?q=moderní+byt&location=praha&category=byty3. Autentifikace a authorization
httpAuthorization: Bearer YOUR_API_KEYX-Project-ID: project_abc1234. Pagination pro všechny endpointy
httpGET /api/listings/all?page=2&limit=20GET /api/listings/category?slug=byty&page=1&limit=505. Pokročilé sorting
httpGET /api/listings/all?sort=price&order=desc&sort_secondary=size&order_secondary=asc6. Bulk operace
httpGET /api/listings/bulk?ids=507f1f77bcf86cd799439011,507f1f77bcf86cd7994390127. Realtime notifikace
httpGET /api/listings/subscribe?category=byty&price_max=5000000Typické workflow příklady
1. Načtení inzerátů pro kategorii
javascript// 1. Získat inzeráty podle kategorieconst response = await fetch('/api/listings/category?slug=byty');const apartments = await response.json();// 2. Zobrazit první stránku výsledkůapartments.slice(0, 20).forEach(listing => { console.log(`${listing.name} - ${listing.price} Kč`);});2. Detail nemovitosti s kompletními informacemi
javascript// 1. Získat detail konkrétního inzerátuconst response = await fetch('/api/listings/detail?id=507f1f77bcf86cd799439011');const listing = await response.json();// 2. Zobrazit galerii obrázkůlisting.galleryUrls?.forEach(url => { console.log(`Image: ${url}`);});// 3. Zobrazit vizualizacelisting.visualizations?.forEach(viz => { console.log(`${viz.name}: ${viz.url}`);});3. Filtrování podle ceny a velikosti
javascript// 1. Získat všechny inzerátyconst response = await fetch('/api/listings/all?limit=1000');const allListings = await response.json();// 2. Filtrovat na frontend straně (nebo lépe implementovat v API)const filtered = allListings.filter(listing => { const size = listing.usable_area || listing.size || 0; return listing.price >= 3000000 && listing.price <= 6000000 && size >= 50;});Last updated