API REST

Solo lectura, en JSON, abierta a llamadas desde el navegador. Los nombres de los campos son estables: si algo cambia de forma incompatible, será en una nueva versión.

Dirección base

URL

https://www.deveras.app/api/v1

Acceso y claves

No necesitas clave para empezar. Con una clave el límite sube y puedes ver tu consumo. Envíala en el encabezado Authorization: Bearer … o en x-api-key.

curl

curl -H "Authorization: Bearer $API_KEY" \
  "https://www.deveras.app/api/v1/listings?city=playa-del-carmen"

Tu clave es secreta: úsala desde tu servidor, nunca en código que llegue al navegador. Si se filtra, revócala y crea otra.

Gestionar mis claves

Límites y caché

Sin clave: 60 solicitudes por minuto por dirección IP.
Con clave: 600 solicitudes por minuto por clave.
Si te pasas, respondemos 429 con el encabezado Retry-After (segundos de espera). Con clave, cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.
Las respuestas se pueden guardar en caché 60 segundos (Cache-Control). Los anuncios cambian poco: guarda las respuestas y ahorra solicitudes.

Forma de las respuestas

Toda respuesta correcta trae data (el resultado) y attribution (la mención que debes mostrar). Las listas añaden pagination, con enlaces a la página anterior y siguiente, también en el encabezado Link.

JSON

{
  "data": [
    {
      "id": "k7m2x9p",
      "url": "https://www.deveras.app/en/p/bright-two-bedroom-near-the-beach-k7m2x9p",
      "title": "Bright two-bedroom near the beach",
      "language": "en",
      "type": "apartment",
      "operation": "rent",
      "terms": [
        "long",
        "mid"
      ],
      "price": {
        "amount": 1200,
        "currency": "USD",
        "amount_mxn": 21960,
        "period": "month"
      },
      "sale": null,
      "bedrooms": 2,
      "bathrooms": 1.5,
      "area_m2": 78,
      "land_m2": null,
      "furnished": true,
      "pets_allowed": false,
      "amenities": [
        "pool",
        "ac",
        "wifi"
      ],
      "location": {
        "city": {
          "slug": "playa-del-carmen",
          "name": "Playa del Carmen"
        },
        "zone": {
          "slug": "centro",
          "name": "Centro"
        },
        "coordinates": {
          "lat": 20.627,
          "lng": -87.074,
          "precision": "approximate"
        }
      },
      "photos": [
        {
          "url": "https://www.deveras.app/media/public/listings/k7m2x9p/1.jpg",
          "width": 1600,
          "height": 1200,
          "alt": "Living room",
          "room": "living"
        }
      ],
      "advertiser": {
        "handle": "ana-lopez",
        "name": "Ana López",
        "role": "owner",
        "agency_name": null,
        "avatar_url": null,
        "trust_score": 82,
        "reviews": {
          "count": 4,
          "average": 4.75
        },
        "verifications": [
          {
            "kind": "email",
            "verified_at": "2026-01-05T10:00:00.000Z"
          },
          {
            "kind": "identity",
            "verified_at": "2026-03-02T10:00:00.000Z"
          }
        ],
        "url": "https://www.deveras.app/en/u/ana-lopez"
      },
      "verifications": [
        {
          "kind": "ownership",
          "verified_at": "2026-04-01T10:00:00.000Z"
        }
      ],
      "shares_commission": false,
      "demo": false,
      "published_at": "2026-06-10T15:00:00.000Z",
      "availability_confirmed_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 24,
    "total": 1,
    "pages": 1,
    "links": {
      "self": "https://www.deveras.app/api/v1/listings?city=playa-del-carmen&beds=2&max=25000",
      "first": "https://www.deveras.app/api/v1/listings?city=playa-del-carmen&beds=2&max=25000",
      "last": "https://www.deveras.app/api/v1/listings?city=playa-del-carmen&beds=2&max=25000",
      "prev": null,
      "next": null
    }
  },
  "attribution": {
    "text": "Listings from Deveras",
    "url": "https://www.deveras.app/en",
    "license_url": "https://www.deveras.app/en/developers/license",
    "notice": "Free to reuse, including commercially, as long as you show this mention visibly and link each listing to its `url`. Do not remove verification context or the demo flag, and do not publish contact details."
  }
}

Lo que conviene saber de los campos

url: La página del anuncio en Deveras. Es el enlace obligatorio en cualquier reutilización.
price: amount va en la moneda del anuncio (currency); amount_mxn es el mismo precio en pesos. Los filtros min y max y el orden por precio usan pesos.
sale: Solo en venta (operation: sale, price.period: total): preventa, entrega, tipo de título, mantenimiento y precio por m². En renta vale null.
location.coordinates: precision vale exact o approximate. Si es aproximada, el punto está desplazado a propósito: dibuja una zona, no un pin. Puede ser null.
verifications: Lista de pruebas comprobadas por la plataforma, con su tipo y su fecha. En el anuncio hablan del inmueble; en advertiser, de la persona. Una lista vacía significa «sin verificar».
demo: true en los datos de demostración, que no son anuncios reales. No aparecen salvo que pidas demo=1.
locale: Con locale=es, en o fr eliges el idioma de títulos, descripciones y enlaces. Si no hay traducción, recibes el texto original (language te dice cuál).

Lo que nunca devolvemos

Dirección exacta, teléfono, WhatsApp, correo electrónico, documentos de identidad, identificadores internos y anuncios sin publicar. Tampoco los perfiles de inquilinos. Si un texto libre contiene un teléfono o un correo, lo ocultamos.

Rutas

Buscar anuncios

GET/api/v1/listings

Anuncios publicados, del más reciente al más antiguo, con los mismos filtros que el buscador del sitio. En renta por defecto; en venta con operation=sale.

operationstring — opcional — rent · sale — por defecto: rent: rent (por defecto) o sale. Una búsqueda trae una u otra, nunca las dos.
citystring — opcional: Ciudad (identificador de /places). Sin ella, se busca en todas.
zonestring — opcional: Zona dentro de la ciudad. Requiere city.
typestring — opcional — apartment · house · studio · room · villa · commercial · land: Tipo de inmueble.
bedsinteger — opcional: Número mínimo de recámaras.
bathsinteger — opcional: Número mínimo de baños.
mininteger — opcional: Precio mínimo en pesos (MXN): renta, o precio total en venta.
maxinteger — opcional: Precio máximo en pesos (MXN): renta, o precio total en venta.
furnishedboolean — opcional: 1 para ver solo amueblados.
petsboolean — opcional: 1 para ver solo los que aceptan mascotas. Solo en renta.
termstring — opcional — long · mid · short: Plazo: long (12 meses o más), mid (1 a 11 meses) o short (por noche o semana). Solo en renta.
amenitiesstring[] — opcional — pool · gym · ac · parking · rooftop · security · washer · elevator · cowork · balcony · garden · kitchen · wifi · tv · beach_walk · generator · cistern · storage · bbq · jacuzzi: Amenidades que el anuncio debe tener todas, separadas por comas.
verifiedboolean — opcional: 1 para ver solo anunciantes con identidad verificada.
qstring — opcional: Texto libre, buscado en el título y la descripción.
advertiserstring — opcional: Solo los anuncios de este perfil.
sortstring — opcional — recent · price_asc · price_desc — por defecto: recent: Orden: recent, price_asc o price_desc.
pageinteger — opcional — por defecto: 1: Número de página, desde 1.
per_pageinteger — opcional — por defecto: 24: Anuncios por página.
demoboolean — opcional — por defecto: 0: 1 para incluir datos de demostración (van marcados con demo: true).
localestring — opcional — es · en · fr — por defecto: es: Idioma de textos y enlaces: es, en o fr.

curl

curl "https://www.deveras.app/api/v1/listings?city=playa-del-carmen&beds=2&max=25000&furnished=1"

JavaScript

const response = await fetch("https://www.deveras.app/api/v1/listings?city=playa-del-carmen&beds=2&max=25000");
const { data, pagination, attribution } = await response.json();

for (const listing of data) {
  // listing.url is the page of the listing: always link to it.
  console.log(listing.title, listing.price.amount, listing.price.currency, listing.url);
}

// Show attribution.text, linked to attribution.url, wherever you display the listings.
console.log(attribution.text, attribution.url, pagination.total);

Leer un anuncio

GET/api/v1/listings/{shortId}

El anuncio completo: descripción, todas las fotos, condiciones, servicios incluidos, distancias y verificaciones.

shortIdstring: Identificador del anuncio (campo id).
demoboolean — opcional — por defecto: 0: 1 para incluir datos de demostración (van marcados con demo: true).
localestring — opcional — es · en · fr — por defecto: es: Idioma de textos y enlaces: es, en o fr.

curl

curl "https://www.deveras.app/api/v1/listings/k7m2x9p?locale=en"

Ciudades y zonas

GET/api/v1/places

Las ciudades y sus zonas, con los identificadores que usan los filtros city y zone y el número de anuncios en renta (listing_count) y en venta (sale_count).

demoboolean — opcional — por defecto: 0: 1 para incluir datos de demostración (van marcados con demo: true).
localestring — opcional — es · en · fr — por defecto: es: Idioma de textos y enlaces: es, en o fr.

curl

curl "https://www.deveras.app/api/v1/places"

Perfil público de un anunciante

GET/api/v1/profiles/{handle}

Nombre, rol, puntuación de confianza, reseñas y pruebas verificadas de un propietario o agente.

handlestring: Identificador del perfil (campo advertiser.handle).
demoboolean — opcional — por defecto: 0: 1 para incluir datos de demostración (van marcados con demo: true).
localestring — opcional — es · en · fr — por defecto: es: Idioma de textos y enlaces: es, en o fr.

curl

curl "https://www.deveras.app/api/v1/profiles/ana-lopez"

Errores

Los errores usan el código HTTP habitual y siempre la misma forma. Guíate por code, que es estable; message es para ti.

JSON

{
  "error": {
    "code": "invalid_parameter",
    "message": "One or more parameters are invalid.",
    "status": 400,
    "details": [
      {
        "param": "beds",
        "message": "Invalid input: expected number, received string"
      }
    ],
    "docs_url": "https://www.deveras.app/en/developers/api"
  }
}

invalid_parameterHTTP 400: Un parámetro falta, sobra o tiene un valor no válido. details dice cuál.
invalid_api_keyHTTP 401: La clave no existe, está revocada o está mal escrita.
not_foundHTTP 404: La ruta no existe.
listing_not_foundHTTP 404: No hay ningún anuncio publicado con ese identificador.
profile_not_foundHTTP 404: No hay ningún perfil público de anunciante con ese identificador.
place_not_foundHTTP 404: La ciudad o la zona no existe. Consulta /places.
advertiser_not_foundHTTP 404: El perfil indicado en advertiser no existe.
method_not_allowedHTTP 405: La API es de solo lectura: usa GET.
rate_limitedHTTP 429: Demasiadas solicitudes. Espera lo que indica Retry-After.
internal_errorHTTP 500: Algo falló de nuestro lado. Vuelve a intentarlo.

Documento OpenAPI

La descripción completa de la API en formato OpenAPI 3.1 se genera a partir de las mismas definiciones que usa el servidor: siempre está al día. Úsala para generar un cliente o importarla en tu herramienta favorita.

Abrir openapi.json