Listings and SEO

The catalogue reads need no key and return only what the company publishes. Hidden prices are never included.

The reads

Method and path	Returns
`GET /api/v1/listings`	Published listings, filtered, sorted and paginated
`GET /api/v1/listings/map`	Paginated map points using the same filters, without photos or descriptions
`GET /api/v1/listings/{slug}`	One listing, by its English or Arabic slug
`GET /api/v1/areas`	Cities, areas and projects with counts of published listings per type
`GET /api/v1/filters`	Filter options with counts, for the company’s enabled types
`GET /api/v1/team`	Team profiles the company publishes (when it has the team module)
`GET /api/v1/sitemap`	Every published listing’s path in every language, with its last change
`GET /api/v1/services`	The services the company offers, for your forms

Filters on GET /listings: type (sale, lease, holiday_home), area, project, property_type, bedrooms_min, bedrooms_max, guests_min, completion, featured. Sort with sort=featured, newest or sort_order.


curl -s "https://<company host>/api/v1/listings?type=lease&page_size=12"
curl -s "https://<company host>/api/v1/listings/harbour-view-apartment"

Showing a listing in the visitor’s language


const listing = await (await fetch(`https://<company host>/api/v1/listings/${slug}`)).json();
const title = listing.title[locale];   // "en" or "ar": the English text where a language has none
const href = listing.path[locale];     // the page in that language

Map points

GET /listings/map returns lightweight points for listings that have coordinates, with the listing’s location precision (exact or approximate) so a map can draw a pin or a circle, and each point’s first ready photo as cover when it has one. Listings without coordinates are not on the map but are still in GET /listings.

Photos

Each listing carries its photos in position order; a listing card carries the first one as cover. A photo has alt per language, its width and height, and renditions: the ready-made sizes with their addresses. Addresses are stable while the photo is published; a static site may copy them at build time or link to them.

Withdrawn listings

A listing taken off the market is not deleted: GET /listings/{slug} returns its slug and status: "withdrawn" with no content, so a website can answer 410 for the page and keep its address from becoming a 404.

SEO data on every listing

path: the page’s path on the company’s website, per language, built from the pattern the company sets (/en/listings/{slug} and /ar/listings/{slug} by default). Use it for canonical links and hreflang alternates.
structured_data: one schema.org RealEstateListing document per language, ready to print as JSON-LD. It omits the price while the company hides prices.
slug per language, so a page is found whichever language the link was shared in.

The sitemap feed

GET /api/v1/sitemap lists every published listing’s path in every language with its lastmod. Merge it with your static pages into one sitemap. The company’s website profile, in the admin, holds the listing path pattern it expects your site to serve.

Rebuilding a static site

A site built ahead of time (a static site generator) does not need to poll: the company can set a rebuild hook so that publishing a listing triggers one build.