# Documentație: https://imobox.ro/knowledge-graph-index/ (Motor Căutare AI și DataFeed HTML)

Acest endpoint returnează o listă de anunțuri imobiliare formatată într-o structură HTML5 semantică pură, optimizată special pentru a fi parcursă extrem de eficient de către modelele mari de limbaj (LLMs - Gemini, ChatGPT, Claude etc.) și agenți AI. 

Feed-ul este structurat pentru a asigura o densitate maximă a informației utile, eliminând elementele de design (fără CSS sau Javascript client-side) pentru a reduce consumul de tokeni la procesare. De asemenea, integrează **motorul complet de procesare a limbajului natural (NLP)** al platformei ImoBox, permițând interogări textuale complexe.

## Cum funcționează:
1. **Analiza NLP avansată (Interogare liberă)**: Căutarea înțelege automat intențiile de tranzacție (vânzare/închiriere), tipul proprietății, intervalele de preț, numărul de camere sau suprafețele direct din textul interogării.
2. **Structură Semantică HTML5**: Datele sunt organizate folosind tag-uri semantice structurate (`<article>`, `<dl>`, `<dt>`, `<dd>`, `<ul>`, `<li>`), permițând AI-ului să coreleze precis atributele proprietăților.
3. **Paginare integrată**: Permite parcurgerea seturilor consecutive de rezultate.

---

## Interfață de Interogare și URL-uri (Friendly URLs)

Interogările către acest endpoint se realizează prin URL-uri prietenoase (Friendly URLs), care pot fi accesate direct de asistenții AI externi:

### 1. Index General
- **URL:** `https://imobox.ro/knowledge-graph-index/`
- **Descriere:** Returnează prima pagină cu anunțuri generale.

### 2. Paginare pe Index
- **URL:** `https://imobox.ro/knowledge-graph-index/page/{numar_pagina}/`
- **Exemplu:** `https://imobox.ro/knowledge-graph-index/page/2/`

### 3. Căutare în Limbaj Natural (NLP)
- **URL:** `https://imobox.ro/knowledge-graph-index/query/{interogare_cu_plus}/`
- **Exemplu:** `https://imobox.ro/knowledge-graph-index/query/apartament+2+camere/`

### 4. Căutare NLP cu Paginare
- **URL:** `https://imobox.ro/knowledge-graph-index/query/{interogare_cu_plus}/page/{numar_pagina}/`
- **Exemplu:** `https://imobox.ro/knowledge-graph-index/query/apartament+2+camere/page/2/`

---

## Parametrii NLP recunoscuți în interogare (`query`)
Motorul de căutare analizează textul liber transmis în URL și extrage automat:
- **Tipul proprietății:** *casă, vilă, apartament, garsonieră, teren* etc.
- **Tipul tranzacției:** identifică dacă se dorește *vânzare* sau *închiriere*.
- **Localizarea:** recunoaște localități, zone specifice sau sectoare (ex: *sector 1*).
- **Camere:** convertit automat din text sau cifre (ex: *trei camere*, *3 camere*).
- **Bugete:** recunoaște limitele financiare specificate (ex: *buget 100000 euro*).
- **Suprafețe:** procesează intervale sau suprafețe specifice (ex: *1.5 hectare*, *între 500 și 1000 mp*).

### Exemple de interogări complexe:
- [https://imobox.ro/knowledge-graph-index/query/casa+ieftina+sector+1/](https://imobox.ro/knowledge-graph-index/query/casa+ieftina+sector+1/)
- [https://imobox.ro/knowledge-graph-index/query/teren+1.5+hectare+20+euro+mp/](https://imobox.ro/knowledge-graph-index/query/teren+1.5+hectare+20+euro+mp/)
- [https://imobox.ro/knowledge-graph-index/query/apartament+trei+camere+buget+120000+euro/](https://imobox.ro/knowledge-graph-index/query/apartament+trei+camere+buget+120000+euro/)
- [https://imobox.ro/knowledge-graph-index/query/garsoniera+de+inchiriat+unirii/](https://imobox.ro/knowledge-graph-index/query/garsoniera+de+inchiriat+unirii/)
- [https://imobox.ro/knowledge-graph-index/query/teren+intre+500+si+1000+mp+buget+30000+euro/](https://imobox.ro/knowledge-graph-index/query/teren+intre+500+si+1000+mp+buget+30000+euro/)

---

## Structură Răspuns (Exemplu Renderizat HTML)

Răspunsul primit de la server este un document HTML semantic curat. Mai jos este un exemplu reprezentativ de cod HTML primit ca răspuns pentru o interogare:

```html
<!DOCTYPE html>
<html lang="ro">
<head>
    <meta charset="UTF-8">
    <title>Knowledge Graph - Imobox Listings</title>
</head>
<body>
    <header>
        <h1>ImoBox Listings - AI DataFeed</h1>
        <section id="metadata">
            <h2>Request Info</h2>
            <dl>
                <dt>Status</dt>
                <dd>success</dd>
                
                <dt>Total Results</dt>
                <dd>3</dd>
                
                <dt>Page</dt>
                <dd>1 of 1</dd>
                
                <dt>Results Per Page</dt>
                <dd>25</dd>

                <dt>Query</dt>
                <dd>
                    <ul>
                        <li><strong>q:</strong> "apartament trei camere buget 120000 euro"</li>
                    </ul>
                </dd>
            </dl>
        </section>
    </header>

    <main>
        <section id="listings">
            <h2>Real Estate Listings</h2>
            
            <article id="listing-EX1234567890ABCDEF1234567890ABCDEF123456">
                <h3>Apartament 2 camere luminos - Zonă Centrală (Exemplu)</h3>
                <dl>
                    <dt>Identifier</dt>
                    <dd>EX1234567890ABCDEF1234567890ABCDEF123456</dd>
                    
                    <dt>Listing URL</dt>
                    <dd><a href="https://imobox.ro/apartament-exemplu-2-camere-zona-centrala/anunt/EX1234567890ABCDEF1234567890ABCDEF123456">https://imobox.ro/apartament-exemplu-2-camere-zona-centrala/anunt/EX1234567890ABCDEF1234567890ABCDEF123456</a></dd>
                    
                    <dt>JSON Data URL</dt>
                    <dd><a href="https://imobox.ro/apartament-exemplu-2-camere-zona-centrala/anunt/EX1234567890ABCDEF1234567890ABCDEF123456/knowledge-graph.json">https://imobox.ro/apartament-exemplu-2-camere-zona-centrala/anunt/EX1234567890ABCDEF1234567890ABCDEF123456/knowledge-graph.json</a></dd>
                    
                    <dt>Property ID (RDF URI)</dt>
                    <dd><a href="https://imobox.ro/apartament-exemplu-2-camere-zona-centrala/anunt/EX1234567890ABCDEF1234567890ABCDEF123456#imobil">https://imobox.ro/apartament-exemplu-2-camere-zona-centrala/anunt/EX1234567890ABCDEF1234567890ABCDEF123456#imobil</a></dd>

                    <dt>Last Modified</dt>
                    <dd><time datetime="2026-05-20T10:00:00+03:00">2026-05-20T10:00:00+03:00</time></dd>
                    
                    <dt>Description</dt>
                    <dd>Apartament de Vanzare in Bucuresti, Sector 1</dd>
                    
                    <dt>Total Price</dt>
                    <dd>85000 EUR</dd>
                    
                    <dt>Location</dt>
                    <dd>Bucuresti, Sector 1</dd>
                </dl>

                <h4>Property Details</h4>
                <ul>
                    <li><strong>propertyType:</strong> Apartament</li>
                    <li><strong>transactionType:</strong> Vanzare</li>
                    <li><strong>Rooms:</strong> 2</li>
                    <li><strong>Floor Size:</strong> 55 MTK</li>
                </ul>
            </article>
            <hr>
            
            <article id="listing-EX9876543210FEDCBA9876543210FEDCBA987654">
                <h3>Teren pentru construcție casă - Acces utilități (Exemplu)</h3>
                <dl>
                    <dt>Identifier</dt>
                    <dd>EX9876543210FEDCBA9876543210FEDCBA987654</dd>
                    
                    <dt>Listing URL</dt>
                    <dd><a href="https://imobox.ro/teren-constructie-casa-exemplu/anunt/EX9876543210FEDCBA9876543210FEDCBA987654">https://imobox.ro/teren-constructie-casa-exemplu/anunt/EX9876543210FEDCBA9876543210FEDCBA987654</a></dd>
                    
                    <dt>JSON Data URL</dt>
                    <dd><a href="https://imobox.ro/teren-constructie-casa-exemplu/anunt/EX9876543210FEDCBA9876543210FEDCBA987654/knowledge-graph.json">https://imobox.ro/teren-constructie-casa-exemplu/anunt/EX9876543210FEDCBA9876543210FEDCBA987654/knowledge-graph.json</a></dd>
                    
                    <dt>Property ID (RDF URI)</dt>
                    <dd><a href="https://imobox.ro/teren-constructie-casa-exemplu/anunt/EX9876543210FEDCBA9876543210FEDCBA987654#imobil">https://imobox.ro/teren-constructie-casa-exemplu/anunt/EX9876543210FEDCBA9876543210FEDCBA987654#imobil</a></dd>

                    <dt>Last Modified</dt>
                    <dd><time datetime="2026-05-21T11:30:00+03:00">2026-05-21T11:30:00+03:00</time></dd>
                    
                    <dt>Description</dt>
                    <dd>Teren de Vanzare in Ilfov, Otopeni</dd>
                    
                    <dt>Total Price</dt>
                    <dd>50000 EUR</dd>
                    
                    <dt>Unit Price</dt>
                    <dd>100 EUR / MTK</dd>
                    
                    <dt>Location</dt>
                    <dd>Otopeni, Ilfov</dd>
                </dl>

                <h4>Property Details</h4>
                <ul>
                    <li><strong>propertyType:</strong> Teren</li>
                    <li><strong>transactionType:</strong> Vanzare</li>
                    <li><strong>lotSize:</strong> 500 MTK</li>
                </ul>
            </article>
            <hr>

            <article id="listing-EX55555555555555555555555555555555555555">
                <h3>Casă de închiriat 3 camere cu curte proprie (Exemplu)</h3>
                <dl>
                    <dt>Identifier</dt>
                    <dd>EX55555555555555555555555555555555555555</dd>
                    
                    <dt>Listing URL</dt>
                    <dd><a href="https://imobox.ro/casa-de-inchiriat-3-camere-curte-proprie-exemplu/anunt/EX55555555555555555555555555555555555555">https://imobox.ro/casa-de-inchiriat-3-camere-curte-proprie-exemplu/anunt/EX55555555555555555555555555555555555555</a></dd>
                    
                    <dt>JSON Data URL</dt>
                    <dd><a href="https://imobox.ro/casa-de-inchiriat-3-camere-curte-proprie-exemplu/anunt/EX55555555555555555555555555555555555555/knowledge-graph.json">https://imobox.ro/casa-de-inchiriat-3-camere-curte-proprie-exemplu/anunt/EX55555555555555555555555555555555555555/knowledge-graph.json</a></dd>
                    
                    <dt>Property ID (RDF URI)</dt>
                    <dd><a href="https://imobox.ro/casa-de-inchiriat-3-camere-curte-proprie-exemplu/anunt/EX55555555555555555555555555555555555555#imobil">https://imobox.ro/casa-de-inchiriat-3-camere-curte-proprie-exemplu/anunt/EX55555555555555555555555555555555555555#imobil</a></dd>

                    <dt>Last Modified</dt>
                    <dd><time datetime="2026-05-22T09:15:00+03:00">2026-05-22T09:15:00+03:00</time></dd>
                    
                    <dt>Description</dt>
                    <dd>Casa de Inchiriere in Brasov, Brasov</dd>
                    
                    <dt>Total Price</dt>
                    <dd>750 EUR</dd>
                    
                    <dt>Location</dt>
                    <dd>Brasov, Brasov</dd>
                </dl>

                <h4>Property Details</h4>
                <ul>
                    <li><strong>propertyType:</strong> Casa</li>
                    <li><strong>transactionType:</strong> Inchiriere</li>
                    <li><strong>lotSize:</strong> 300 MTK</li>
                    <li><strong>Rooms:</strong> 3</li>
                    <li><strong>Floor Size:</strong> 110 MTK</li>
                </ul>
            </article>
            <hr>
        </section>
    </main>
</body>
</html>
```