{
  "openapi": "3.0.1",
  "info": {
    "title": "API ImoBox.ro",
    "description": "API pentru c\u0103utarea de anun\u021buri imobiliare \u0219i statistici de pia\u021b\u0103 \u00een Rom\u00e2nia. Permite c\u0103ut\u0103ri \u00een limbaj natural.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.imobox.ro"
    }
  ],
  "paths": {
    "/knowledge-graph-index.json": {
      "servers": [
        {
          "url": "https://imobox.ro",
          "description": "Server principal (Endpoint NLP Schema.org)"
        }
      ],
      "get": {
        "summary": "Endpoint API JSON pentru c\u0103utarea NLP de anun\u021buri imobiliare.",
        "description": "**ATEN\u021aIE AI:** Apeleaz\u0103 acest endpoint pentru a efectua c\u0103ut\u0103ri de propriet\u0103\u021bi imobiliare. NU \u00eencerca s\u0103 accesezi paginile HTML de c\u0103utare ale site-ului.\n\n**Cum func\u021bioneaz\u0103:**\nAcest endpoint prime\u0219te un text liber (limbaj natural) \u00een parametrul `q`. Motorul NLP intern ImoBox va extrage automat:\n- Tipul ofertei (v\u00e2nzare / \u00eenchiriere).\n- Tipul propriet\u0103\u021bii (apartament, cas\u0103, teren, garsonier\u0103, vil\u0103, etc.).\n- Bugetul/Pre\u021bul maxim (\u00een\u021belege diferen\u021ba dintre pre\u021b total \u0219i pre\u021b/mp).\n- Num\u0103rul de camere sau suprafa\u021ba (hectare, mp).\n- Loca\u021bia (ora\u0219, sector, cartier).\n\n**Exemple de apeluri valide (URL-uri):**\n- C\u0103utare general\u0103: `https://imobox.ro/knowledge-graph-index.json?q=apartament+3+camere+bucuresti+sector+1`\n- C\u0103utare dup\u0103 suprafa\u021b\u0103 \u0219i pre\u021b/mp: `https://imobox.ro/knowledge-graph-index.json?q=teren+1.5+hectare+20+euro+mp`\n- C\u0103utare pentru \u00eenchirieri: `https://imobox.ro/knowledge-graph-index.json?q=casa+de+inchiriat+cluj+buget+500+euro`\n- C\u0103utare combinat\u0103 cu paginare: `https://imobox.ro/knowledge-graph-index.json?q=garsoniera&pagina=1&limit=50`\n",
        "operationId": "searchImoboxNLP",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Textul c\u0103ut\u0103rii \u00een limbaj natural (ex. 'apartament 2 camere bucuresti'). Acesta este cel mai important parametru.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pagina",
            "in": "query",
            "description": "Num\u0103rul paginii curente dorite pentru paginare.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Num\u0103rul de rezultate returnate per pagin\u0103 (maxim admis 100).",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "R\u0103spuns JSON cu detalii de paginare \u0219i rezultatele formatate conform DataFeed (Schema.org).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestInfo": {
                      "type": "object",
                      "description": "Metadate despre interogare \u0219i paginare. Folose\u0219te `totalPages` pentru a \u0219ti dac\u0103 trebuie s\u0103 extragi mai multe pagini.",
                      "properties": {
                        "status": {
                          "type": "string",
                          "example": "success"
                        },
                        "query": {
                          "type": "object",
                          "description": "Parametrii GET recep\u021biona\u021bi de server."
                        },
                        "totalResults": {
                          "type": "integer",
                          "example": 42,
                          "description": "Num\u0103rul total de oferte g\u0103site de motorul NLP."
                        },
                        "page": {
                          "type": "integer",
                          "example": 1
                        },
                        "resultsPerPage": {
                          "type": "integer",
                          "example": 25
                        },
                        "totalPages": {
                          "type": "integer",
                          "example": 2
                        }
                      }
                    },
                    "dataFeed": {
                      "type": "object",
                      "description": "Rezultatele valide mapate dup\u0103 standardul Schema.org.",
                      "properties": {
                        "@context": {
                          "type": "string",
                          "example": "https://schema.org"
                        },
                        "@type": {
                          "type": "string",
                          "example": "DataFeed"
                        },
                        "name": {
                          "type": "string",
                          "example": "ImoBox Listings"
                        },
                        "dateModified": {
                          "type": "string",
                          "format": "date-time",
                          "example": "2026-05-15T20:30:00+03:00"
                        },
                        "dataFeedElement": {
                          "type": "array",
                          "description": "Lista de anun\u021buri imobiliare returnate.",
                          "items": {
                            "type": "object",
                            "properties": {
                              "@type": {
                                "type": "string",
                                "example": "DataFeedItem"
                              },
                              "identifier": {
                                "type": "string",
                                "example": "abcdf123"
                              },
                              "url": {
                                "type": "string",
                                "format": "uri",
                                "example": "https://imobox.ro/apartament-3-camere-unirii/anunt/abcdf123"
                              },
                              "dateModified": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2026-05-14T12:00:00+03:00"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/anunturi": {
      "get": {
        "operationId": "searchAnunturiImobiliare",
        "summary": "Caut\u0103 anun\u021buri imobiliare",
        "description": "Caut\u0103 \u0219i filtreaz\u0103 anun\u021buri imobiliare folosind un \u0219ir de c\u0103utare \u00een limbaj natural \u0219i parametri de paginare.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "\u0218irul de c\u0103utare \u00een limbaj natural (ex: 'apartament 2 camere bucuresti', 'casa cu gradina cluj').",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Num\u0103rul de rezultate pe pagin\u0103. Default 25, maxim 100.",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100,
              "minimum": 1
            }
          },
          {
            "name": "pagina",
            "in": "query",
            "description": "Pagina de rezultate.",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Specific\u0103 formatul de output. 'json' returneaz\u0103 date structurate, 'text' o versiune simplificat\u0103, iar 'html' sau 'table' returneaz\u0103 o pagin\u0103 web vizualizabil\u0103. Server-ul va folosi 'html' ca default dac\u0103 parametrul lipse\u0219te.",
            "schema": {
              "type": "string",
              "default": "json",
              "enum": [
                "json",
                "text",
                "html",
                "table"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "C\u0103utare efectuat\u0103 cu succes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string",
                  "format": "html"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiResponse": {
        "type": "object",
        "properties": {
          "requestInfo": {
            "$ref": "#/components/schemas/RequestInfo"
          },
          "summaryStatistics": {
            "$ref": "#/components/schemas/SummaryStatistics"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Anunt"
            }
          }
        }
      },
      "Anunt": {
        "type": "object",
        "oneOf": [
          {
            "$ref": "#/components/schemas/AnuntTeren"
          },
          {
            "$ref": "#/components/schemas/AnuntLocuinta"
          },
          {
            "$ref": "#/components/schemas/AnuntHala"
          },
          {
            "$ref": "#/components/schemas/AnuntSpatiuComercial"
          },
          {
            "$ref": "#/components/schemas/AnuntBirouri"
          }
        ],
        "discriminator": {
          "propertyName": "imobil",
          "mapping": {
            "teren": "#/components/schemas/AnuntTeren",
            "apartament": "#/components/schemas/AnuntLocuinta",
            "casa": "#/components/schemas/AnuntLocuinta",
            "hala": "#/components/schemas/AnuntHala",
            "spatiu_comercial": "#/components/schemas/AnuntSpatiuComercial",
            "birouri": "#/components/schemas/AnuntBirouri"
          }
        }
      },
      "AnuntBaza": {
        "type": "object",
        "required": [
          "id_anunt",
          "titlu_anunt",
          "moneda",
          "oras",
          "judet",
          "imobil",
          "tip_anunt",
          "url"
        ],
        "properties": {
          "id_anunt": {
            "type": "string"
          },
          "titlu_anunt": {
            "type": "string"
          },
          "moneda": {
            "type": "string"
          },
          "oras": {
            "type": "string"
          },
          "judet": {
            "type": "string"
          },
          "imobil": {
            "type": "string",
            "enum": [
              "teren",
              "apartament",
              "casa",
              "hala",
              "spatiu_comercial",
              "birouri"
            ]
          },
          "tip_anunt": {
            "type": "string",
            "enum": [
              "vanzare-cumparare",
              "inchiriere"
            ]
          },
          "latitudine": {
            "type": "string"
          },
          "longitudine": {
            "type": "string"
          },
          "data_actualizare": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "imagine_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "AnuntTeren": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AnuntBaza"
          },
          {
            "type": "object",
            "required": [
              "suprafata_teren"
            ],
            "properties": {
              "pret_mp": {
                "type": "number"
              },
              "pret_total": {
                "type": "number"
              },
              "suprafata_teren": {
                "type": "number"
              }
            }
          }
        ]
      },
      "AnuntLocuinta": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AnuntBaza"
          },
          {
            "type": "object",
            "required": [
              "pret_total",
              "suprafata_casa",
              "camere"
            ],
            "properties": {
              "pret_total": {
                "type": "number"
              },
              "suprafata_casa": {
                "type": "number"
              },
              "camere": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "AnuntHala": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AnuntBaza"
          },
          {
            "type": "object",
            "required": [
              "amprenta_sol"
            ],
            "properties": {
              "pret_mp": {
                "type": "number"
              },
              "pret_total": {
                "type": "number"
              },
              "amprenta_sol": {
                "type": "number"
              }
            }
          }
        ]
      },
      "AnuntSpatiuComercial": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AnuntBaza"
          },
          {
            "type": "object",
            "required": [
              "pret_total",
              "suprafata"
            ],
            "properties": {
              "pret_total": {
                "type": "number"
              },
              "suprafata": {
                "type": "number"
              }
            }
          }
        ]
      },
      "AnuntBirouri": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AnuntBaza"
          },
          {
            "type": "object",
            "required": [
              "pret_total",
              "suprafata"
            ],
            "properties": {
              "pret_total": {
                "type": "number"
              },
              "suprafata": {
                "type": "number"
              },
              "camere": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "RequestInfo": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "query": {
            "type": "object",
            "properties": {
              "request": {
                "type": "string"
              },
              "q": {
                "type": "string"
              }
            }
          },
          "totalResults": {
            "type": "integer"
          },
          "pagina": {
            "type": "integer"
          },
          "resultsPerPage": {
            "type": "integer"
          },
          "totalPages": {
            "type": "integer"
          },
          "fallbackTriggered": {
            "type": "boolean"
          }
        }
      },
      "SummaryStatistics": {
        "type": "object",
        "properties": {
          "vanzare": {
            "$ref": "#/components/schemas/StatisticiTranzactie"
          },
          "inchiriere": {
            "$ref": "#/components/schemas/StatisticiTranzactie"
          }
        }
      },
      "StatisticiTranzactie": {
        "type": "object",
        "properties": {
          "pretTotal": {
            "$ref": "#/components/schemas/StatisticiValoare"
          },
          "pretPerMp": {
            "$ref": "#/components/schemas/StatisticiValoare"
          },
          "suprafata": {
            "$ref": "#/components/schemas/StatisticiValoare"
          }
        }
      },
      "StatisticiValoare": {
        "type": "object",
        "properties": {
          "min": {
            "type": "number",
            "description": "Valoarea minim\u0103 calculat\u0103 \u00een setul de rezultate."
          },
          "max": {
            "type": "number",
            "description": "Valoarea maxim\u0103 calculat\u0103 \u00een setul de rezultate."
          },
          "mediu": {
            "type": "number",
            "description": "Valoarea medie calculat\u0103 \u00een setul de rezultate."
          }
        }
      }
    }
  }
}