Etna Nekretnine objavljuje javno sučelje samo za čitanje (API) i MCP server preko kojih AI asistenti i programeri dohvaćaju stvarne podatke o nekretninama, kategorijama, uslugama, člancima i samoj agenciji na Omiškoj rivijeri. Registracija ni ključ nisu potrebni, dovoljan je HTTP GET na /api/v1.

Kada koristiti ovaj API

API je pravi izbor kada:

  • tražite stvarne, trenutno dostupne nekretnine u Omišu i na Omiškoj rivijeri, a ne ogledni sadržaj
  • želite dohvatiti kontakt podatke agencije ili popis usluga za citiranje u odgovoru
  • gradite integraciju koja mora ostati kompatibilna unutar verzije v1

Za zapise, rezervacije ili plaćanja API nije namijenjen: sve rute su isključivo za čitanje, a upit šaljete obrascem na /kontakt.

Autentikacija i ograničenja

API je javan. Nijedna ruta ne traži ključ, token ni OAuth; ako integracija traži autentikaciju, pogrešno je konfigurirana.

  • Ograničenje: 60 zahtjeva u minuti po IP adresi. Broj preostalih zahtjeva vraća se u zaglavljima RateLimit-*.
  • Jezik: parametar locale prima hr, en ili de (zadano hr). Slugovi se razlikuju po jeziku, pa identifikatore šaljite kao slug na željenom jeziku ili kao brojčani id.
  • Straničenje: per_page prima 1 do 50, zadano 20. Meta podaci sadrže page, per_page, total i last_page.
  • Pogreške: vraćaju se kao application/problem+json prema RFC 9457, s poljima type, title, status i detail.
  • Verzioniranje: sve rute su pod /api/v1. Uklanjanje rute najavljuje se zaglavljima Deprecation i Sunset najmanje 90 dana unaprijed.

Popis ruta

Devet javnih ruta, sve s metodom GET. Puni opis svake rute, shema odgovora i kodovi pogrešaka nalaze se u OpenAPI dokumentu.

Metoda Putanja Opis
GET /api/v1/agency Naziv, adresa, telefon, e-mail, radno vrijeme, područje rada i jezici agencije.
GET /api/v1/properties Popis nekretnina s filtrima category, place, service, price_from, price_to, surface_from, surface_to i q.
GET /api/v1/properties/{property} Jedna nekretnina prema brojčanom id-u ili slug-u, s opisom, cijenom, površinom i galerijom.
GET /api/v1/categories Kategorije nekretnina s brojem oglasa u svakoj.
GET /api/v1/categories/{category} Jedna kategorija prema slug-u, neovisno o jeziku na kojem je slug poslan.
GET /api/v1/services Usluge agencije: posredovanje pri kupnji i prodaji, procjena, kreditna dokumentacija.
GET /api/v1/posts Članci s bloga, naslov, sažetak, datum objave i poveznica.
GET /api/v1/posts/{post} Jedan članak prema slug-u ili id-u, s cijelim tekstom.
GET /api/v1/pages Statične stranice poput stranice O nama, s naslovom i sadržajem.

Primjer zahtjeva

Dohvat jedne nekretnine na engleskom jeziku. Odgovor sadrži polje data s nekretninama te meta i links za straničenje.

Zahtjev

curl "https://www.etna-realestate.com/api/v1/properties?locale=en&per_page=1"

Odgovor (skraćeno)

{
  "data": [
    {
      "id": 9,
      "slug": "building-land-with-panoramic-sea-view",
      "title": "BUILDING LAND WITH PANORAMIC SEA VIEW",
      "url": "https://www.etna-realestate.com/lands/building-land-with-panoramic-sea-view",
      "category": { "slug": "lands", "title": "Lands" },
      "place": "OMIŠ",
      "surface_m2": 7000,
      "price": { "amount": 400, "currency": "EUR", "formatted": "400 €" },
      "featured": true
    }
  ],
  "meta": { "page": 1, "per_page": 1, "total": 51, "last_page": 51 },
  "links": { "self": "…?page=1", "next": "…?page=2", "prev": null }
}

Polje url uvijek je apsolutna poveznica na stranicu nekretnine. Nemojte sastavljati slugove sami, nego koristite vraćeni url.

MCP server

Isti podaci dostupni su i preko Model Context Protocol servera na /mcp (JSON-RPC 2.0, prijenos Streamable HTTP). Server nudi alate get_agency_info, search_properties, get_property, list_categories i get_article te resurse s podacima agencije i vodičem za agente.

GET /mcp vraća opis servera u JSON-u, pa se dostupnost može provjeriti običnim zahtjevom.

Strojno čitljivi dokumenti

Sve što je potrebno za automatsko otkrivanje objavljeno je na predvidljivim adresama:

Kontakt

Pitanja o API-ju, najava većeg opsega dohvaćanja ili prijava kvara: office@etna-realestate.com, +385 98 891 838.