Suelo Public API

Read-only access to every publicly listed property on suelo.casa: houses, apartments, land, townhouses and multi-family buildings across Venezuela, for sale and for rent.

The API is anonymous, read-only and CORS-open. There is no key to request and no OAuth flow to complete, because every response contains exactly what an anonymous visitor already sees on the website. See auth.md for the long answer.

Please send a descriptive User-Agent. Responses are edge-cached for five minutes with a one-hour stale window, so polling faster than that returns the same bytes.

Search listings

GET /api/v1/listings

Every parameter is optional. With none, you get the whole live inventory, newest first, 24 per page.

Parameter Values Notes
operation sale, rent Omit for both.
propertyType house, apartment, land, townhouse, multi_family Repeatable, or comma-separated.
place a place slug path, e.g. miranda/chacao See Places below.
bbox south,west,north,east WGS84 degrees. Narrows place when both are sent.
priceMin, priceMax integers In the listing's own currency.
bedsMin, bathsMin, parking integers Minimums.
areaMin, areaMax integers Built area in m².
yearMin, yearMax integers Year built.
condition new, good, fair, needs_renovation
furnished furnished, semi_furnished, unfurnished
feature pool, generator, water_tank, gym, terrace, balcony Repeatable; all must match.
sort newest, price_asc, price_desc, featured Default newest.
page integer ≥ 1 1-based.
limit 1–100 Default 24.

Example:

GET /api/v1/listings?operation=sale&propertyType=apartment&place=miranda/chacao&priceMax=150000&sort=price_asc

The response carries three keys:

  • listings — the page of results.
  • pagination — page, limit, total (all matches, not just this page), totalPages, and a ready-made nextPageUrl that is null on the last page.
  • place — the resolved place, echoed back so you can confirm what the slug matched.

One listing

GET /api/v1/listings/{listingId}

404 covers both an id that never existed and a listing that is no longer publicly visible. The API does not distinguish the two.

Places

GET /api/v1/places                  # the 24 states
GET /api/v1/places?parent=miranda   # that state's municipios and neighborhoods

Place slugs are the same ones the crawlable landing pages use, so /api/v1/listings?place=miranda/chacao and /ve/venta/apartamentos/miranda/chacao describe the same set. Each entry carries a path to pass back as place and a pageUrl for the human page.

Do not guess slugs: an unknown place is a 400, never an empty result set, so a typo can never be mistaken for "no inventory here".

What a listing means

  • price.amount is the asking price for a sale and the monthly rent for a rental. It is what the lister published, not an appraisal and not a sale price.
  • address carries locality only — neighborhood, city, municipality, state, country, and a one-line locality string. There is no street field: the website does not print one on a search card either.
  • location is the exact point, or null when the lister chose to withhold it. An approximate area pin is never returned dressed up as an address.
  • underInvestigation: true means a reported data problem is being checked. Cite such a listing with that caveat, or leave it out.
  • source names the originating system of a syndicated listing. Attribute it.
  • url is the canonical page. Link people there rather than reproducing the listing wholesale.

Aggregate market data

Do not compute a market average from a page of search results — it is a filtered, sorted, paginated sample. Suelo publishes monthly asking-price reports at /datos, with the method behind them at /datos/metodologia.

Errors

Errors are RFC 9457 problem details with Content-Type: application/problem+json:

{
  "type": "about:blank",
  "title": "Invalid query",
  "status": 400,
  "detail": "One or more query parameters were rejected.",
  "errors": ["place: unknown place path \"mirandaa\""]
}

Markdown

Every HTML page on suelo.casa, this one included, answers Accept: text/markdown with a markdown rendering and an x-markdown-tokens estimate. HTML stays the default for browsers.

Esta página en español

This page is also published in Spanish at /docs/api.

Terms

Use of the API is covered by the terms of use. Attribute Suelo and link back to the listing you are describing. Questions: hola@suelo.casa.