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/api

Autentifikace

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=50

Response:

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=507f1f77bcf86cd799439011

Response:

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/listings

Response:

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=byty

Response:

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/health

Response:

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=50

4. 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=50

2. Pokročilé vyhledávání

httpGET /api/listings/search?q=moderní+byt&location=praha&category=byty

3. Autentifikace a authorization

httpAuthorization: Bearer YOUR_API_KEYX-Project-ID: project_abc123

4. Pagination pro všechny endpointy

httpGET /api/listings/all?page=2&limit=20GET /api/listings/category?slug=byty&page=1&limit=50

5. Pokročilé sorting

httpGET /api/listings/all?sort=price&order=desc&sort_secondary=size&order_secondary=asc

6. Bulk operace

httpGET /api/listings/bulk?ids=507f1f77bcf86cd799439011,507f1f77bcf86cd799439012

7. Realtime notifikace

httpGET /api/listings/subscribe?category=byty&price_max=5000000

---

Typické 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;});