Recherche d'inscriptions

/ask cherche parmi les inscriptions publiées à partir d'une simple phrase, comme « condo 3 chambres à Laval moins de 600 000 $ ». Il suit le protocole NLWeb, alors les clients NLWeb peuvent l'appeler sans code sur mesure. Il est public et en lecture seule, et il ne demande ni compte ni clé d'API.

https://matchai.co/ask

Il renvoie les inscriptions dans l'ordre qu'une personne voudrait : la meilleure correspondance d'abord, selon la pertinence pour la requête et la date de la dernière mise à jour de l'inscription. Aucun courtier ne peut payer pour changer l'ordre ou pour y figurer.

Chercher en une seule requêteCopier le lien de cette section

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

Une réponse abrégée. Cette recherche a trouvé une inscription, et la valeur de score est un exemple :

{
  "_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" }
        }
      }
    }
  ]
}

Les noms, les adresses et l'hôte des photos de ces exemples sont fictifs.

RequêteCopier le lien de cette section

Envoyez la recherche en GET avec des paramètres dans la chaîne de requête, ou en POST avec un corps JSON.

GETCopier le lien de cette section

POSTCopier le lien de cette section

Envoyez Content-Type: application/json. Le corps peut atteindre 16 Ko.

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

La valeur de query peut aussi être un objet, comme dans NLWeb :

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

Les paramètres de la chaîne de requête complètent ce que le corps ne précise pas.

Ce que la recherche comprendCopier le lien de cette section

La recherche lit votre phrase avec un petit analyseur prévisible. Elle n'appelle aucun modèle de langage, alors la même phrase donne toujours les mêmes filtres. Elle comprend l'anglais, le français et l'espagnol.

Les montants peuvent s'écrire 600k, 1.2M, 600 000, $750,000 ou 2 million. Un petit nombre seul, sans unité ni signe de dollar, comme over 2, n'est pas lu comme un prix. Si la phrase demande à la fois la vente et la location, ou ni l'une ni l'autre, la recherche ne filtre pas sur ce critère.

Tout le reste devient un mot-clé. La recherche garde jusqu'à 6 mots-clés, retire les mots de moins de 3 lettres et les mots vides courants, et ignore les accents, alors montreal trouve Montréal. Les mots-clés sont comparés au titre, aux noms de lieux, au type de propriété et à la description. Une correspondance dans un nom de lieu compte le plus, puis le titre, puis le type de propriété, puis la description.

Les recherches renvoient les inscriptions disponibles en ce moment. Les inscriptions vendues et louées ne sont pas renvoyées.

RéponseCopier le lien de cette section

Chaque élément de results :

Une réponse réussie porte l'en-tête Link: </llms.txt>; rel="describedby", </openapi.json>; rel="service-desc". Pour les photos, les points forts et la description complète d'une inscription, utilisez les outils du serveur MCP ou lisez la copie Markdown de l'inscription.

Quelles inscriptions sont cherchéesCopier le lien de cette section

/ask répond pour l'hôte que vous appelez : interroger le site d'un courtier cherche parmi les inscriptions de ce courtier, et interroger matchai.co cherche parmi celles de tout le monde.

Remarques :

• Sur un site Matchai ou sur le domaine propre d'un courtier, site est ignoré : c'est l'hôte qui détermine la portée.
• Sur matchai.co, site prend l'hôte du site d'un courtier. Une valeur qui ne correspond à aucun site publié est ignorée, et la recherche couvre tout le monde. Elle ne renvoie pas de liste vide.
• Une Page Matchai n'a pas de recherche qui lui est propre. La redirection est un 307, qui conserve la méthode et le corps. Pour chercher parmi les inscriptions d'un seul professionnel, interrogez son site Matchai, ou appelez matchai.co avec son site comme site. Depuis du code exécuté dans un navigateur, appelez directement matchai.co/ask, car un navigateur ne peut pas suivre une redirection lors d'une requête de pré-vérification multi-origines.
• Un hôte sans site publié répond 404.

Limites, mise en cache et CORSCopier le lien de cette section

• Limite de débit : 60 requêtes par minute pour chaque adresse appelante, GET et POST confondus. Au-delà, la réponse est 429 avec Retry-After: 60.
• Résultats : au plus 10 par requête. Il n'y a pas de pagination, alors précisez la phrase pour atteindre d'autres inscriptions.
• Mise en cache : un GET sans query_id peut être mis en cache jusqu'à une minute (Cache-Control: public, max-age=60). Tout le reste est envoyé avec no-store. Une nouvelle inscription apparaît dans les résultats en une minute environ.
• CORS : ouvert à toutes les origines pour GET, POST et OPTIONS, alors du code exécuté dans un navigateur peut l'appeler. OPTIONS répond 204, et les réponses aux requêtes de pré-vérification peuvent être mises en cache pendant 24 heures.

ErreursCopier le lien de cette section

Les erreurs sont en JSON, avec un code error stable et un message que vous pouvez montrer à une personne.

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

Un tableau results vide est une réponse réussie : aucune inscription publiée ne correspond. Essayez un secteur plus large, un budget plus élevé ou moins d'exigences.

Autres exemplesCopier le lien de cette section

Cherchez parmi les inscriptions d'un courtier en appelant son site. Remplacez alice par un vrai nom de site :

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

Limitez une recherche sur matchai.co à un seul courtier :

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

Cherchez depuis votre code avec 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" }'