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 read-only and requires an admin-issued token. Sign in and request access, describing your integration. Suelo admins review requests, issue tokens to specific users, and deliver them directly. Users cannot issue or revoke tokens themselves. Tokens expire after 90 days by default; an admin can choose 1–365 days and revoke access at any time.

Send the token with every data request:

curl -H "Authorization: Bearer <token>" https://suelo.casa/api/v1/listings

Missing, invalid, expired or revoked tokens return 401. Browser sessions and query-string tokens are not accepted. CORS permits the Authorization header. The OpenAPI description, catalog and health endpoint remain public. See auth.md for authentication details.

Please send a descriptive User-Agent. Data responses are private and are not cached, so token revocation takes effect on the next request.

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.