Búsqueda de anuncios

/ask busca anuncios publicados a partir de una frase sencilla, como "3 bedroom condo in Laval under 600k". Sigue el protocolo NLWeb, así que los clientes NLWeb pueden llamarlo sin código personalizado. Es público y de solo lectura, y no necesita cuenta ni clave de API.

https://matchai.co/ask

Devuelve los anuncios en el orden en que una persona los querría: primero la mejor coincidencia, según la relevancia para la solicitud y la fecha de la última actualización del anuncio. Ningún corredor puede pagar para cambiar el orden ni para aparecer.

Buscar en una sola solicitudCopiar el enlace de esta sección

curl "https://matchai.co/ask?query=3+bedroom+condo+in+Laval+under+600k"

Una respuesta abreviada. Esta búsqueda encontró un anuncio, y el score es un valor de ejemplo:

{
  "_meta": { "response_type": "answer", "version": "0.55", "mode": "list" },
  "query_id": "6f1d2c1e-3b0a-4a54-9f2e-0c7b8a5d9e41",
  "site": "matchai.co",
  "mode": "list",
  "query": "3 bedroom condo in Laval under 600k",
  "results": [
    {
      "url": "https://alice.matchai.co/bright-condo-montmorency",
      "name": "Bright 3-bedroom condo near Montmorency metro",
      "site": "alice.matchai.co",
      "score": 0.872,
      "description": "$585,000, condo for sale · 3 bedrooms · 1.5 bathrooms · 1,120 sq ft · Montmorency, Laval, Québec · Listed by Alice Tremblay (Agence Exemple)",
      "schema_object": {
        "@context": "https://schema.org",
        "@type": "RealEstateListing",
        "url": "https://alice.matchai.co/bright-condo-montmorency",
        "name": "Bright 3-bedroom condo near Montmorency metro",
        "image": "https://media.example.com/listings/bright-condo-montmorency/cover.jpg",
        "dateModified": "2026-10-12T14:03:22.000Z",
        "offers": {
          "@type": "Offer",
          "price": 585000,
          "priceCurrency": "CAD",
          "availability": "https://schema.org/InStock",
          "businessFunction": "http://purl.org/goodrelations/v1#Sell",
          "url": "https://alice.matchai.co/bright-condo-montmorency",
          "offeredBy": {
            "@type": "RealEstateAgent",
            "name": "Alice Tremblay",
            "worksFor": { "@type": "Organization", "name": "Agence Exemple" }
          }
        },
        "about": {
          "@type": "Apartment",
          "numberOfBedrooms": 3,
          "numberOfBathroomsTotal": 1.5,
          "floorSize": { "@type": "QuantitativeValue", "value": 1120, "unitCode": "FTK" },
          "address": { "@type": "PostalAddress", "addressLocality": "Laval", "addressRegion": "Québec" }
        }
      }
    }
  ]
}

Los nombres, las direcciones y el host de las fotos de estos ejemplos son ficticios.

SolicitudCopiar el enlace de esta sección

Envía la búsqueda como un GET con parámetros en la cadena de consulta, o como un POST con un cuerpo JSON.

GETCopiar el enlace de esta sección

POSTCopiar el enlace de esta sección

Envía Content-Type: application/json. El cuerpo puede tener hasta 16 KB.

{ "query": "4½ à louer sur le Plateau" }

La consulta también puede ser un objeto, como en NLWeb:

{ "query": { "text": "condo near the metro in Montréal" }, "prefer": { "mode": "list" } }

Los parámetros de la cadena de consulta completan todo lo que el cuerpo omita.

Lo que entiende la consultaCopiar el enlace de esta sección

La búsqueda lee tu frase con un analizador pequeño y predecible. No llama a un modelo de lenguaje, así que la misma frase siempre produce los mismos filtros. Entiende inglés, francés y español.

Los montos pueden escribirse como 600k, 1.2M, 600 000, $750,000 o 2 million. Un número pequeño sin unidad y sin signo de dólar, como over 2, no se interpreta como precio. Si la frase pide venta y alquiler a la vez, o ninguno de los dos, la búsqueda no filtra por ese criterio.

Todo lo demás se convierte en palabra clave. La búsqueda conserva hasta 6 palabras clave, descarta las palabras de menos de 3 letras y las palabras de relleno comunes, e ignora los acentos, así que montreal encuentra Montréal. Las palabras clave se comparan con el título, los nombres de lugares, el tipo de propiedad y la descripción. Una coincidencia en un nombre de lugar es la que más cuenta; le siguen el título, el tipo de propiedad y, por último, la descripción.

Las búsquedas devuelven los anuncios disponibles en este momento. Los anuncios vendidos y alquilados no se devuelven.

RespuestaCopiar el enlace de esta sección

Cada elemento de results:

Una respuesta exitosa incluye Link: </llms.txt>; rel="describedby", </openapi.json>; rel="service-desc". Para las fotos, los puntos destacados y la descripción completa de un anuncio, usa las herramientas del servidor MCP o lee la copia en Markdown del anuncio.

Qué anuncios se buscanCopiar el enlace de esta sección

/ask responde para el host al que llamas: si consultas el sitio propio de un corredor, busca en los anuncios de ese corredor, y si consultas matchai.co, busca en los de todos.

Notas:

• En un sitio de Matchai o en el dominio propio de un corredor, site se ignora: el host determina el alcance.
• En matchai.co, site recibe el host del sitio de un corredor. Un valor que no coincide con ningún sitio publicado se ignora, y la búsqueda abarca a todos. No devuelve una lista vacía.
• Una Página Matchai no tiene búsqueda propia. La redirección es un 307, que conserva el método y el cuerpo. Para buscar en los anuncios de un profesional, consulta su sitio de Matchai, o llama a matchai.co con su sitio como site. Desde código de navegador, llama directamente a matchai.co/ask, porque un navegador no puede seguir una redirección en una solicitud preflight de origen cruzado.
• Un host sin sitio publicado responde 404.

Límites, caché y CORSCopiar el enlace de esta sección

• Límite de solicitudes: 60 solicitudes por minuto por cada dirección de origen, sumando GET y POST. Por encima de ese límite, la respuesta es 429 con Retry-After: 60.
• Resultados: como máximo 10 por solicitud. No hay paginación, así que acota la frase para llegar a otros anuncios.
• Caché: un GET sin query_id puede almacenarse en caché hasta un minuto (Cache-Control: public, max-age=60). Todo lo demás se envía con no-store. Un anuncio nuevo aparece en los resultados en aproximadamente un minuto.
• CORS: abierto a todos los orígenes para GET, POST y OPTIONS, así que el código de navegador puede llamarlo. OPTIONS responde 204, y las respuestas preflight pueden almacenarse en caché durante 24 horas.

ErroresCopiar el enlace de esta sección

Los errores son JSON con un código error estable y un message que puedes mostrarle a una persona.

{ "error": "rate_limited", "message": "Too many requests. Try again in a minute." }

Un array results vacío es una respuesta exitosa: nada de lo publicado coincidió. Prueba con una zona más amplia, un presupuesto más alto o menos requisitos.

Más ejemplosCopiar el enlace de esta sección

Busca en los anuncios de un corredor llamando a su sitio. Reemplaza alice por el nombre de un sitio real:

curl "https://alice.matchai.co/ask?query=condo+under+500k"

Limita una búsqueda en matchai.co a un corredor:

curl "https://matchai.co/ask?query=house+for+sale&site=alice.matchai.co"

Busca desde código con un POST:

curl -X POST https://matchai.co/ask \
  -H "Content-Type: application/json" \
  -d '{ "query": "4½ à louer sur le Plateau", "query_id": "rent-plateau-1" }'