---
title: "Recherche d'inscriptions"
description: "Cherchez en langage naturel parmi les inscriptions Matchai publiées avec /ask (NLWeb). Paramètres, réponse, portée selon l'hôte, limites et exemples."
last_updated: "2026-10-21"
lang: "fr-CA"
canonical: "https://matchai.co/docs/fr/developers/listing-search"
---

# Recherche d'inscriptions

> Cherchez en langage naturel parmi les inscriptions Matchai publiées avec /ask (NLWeb). Paramètres, réponse, portée selon l'hôte, limites et exemples.

Source: https://matchai.co/docs/fr/developers/listing-search

`/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.

```text
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ête [#search-in-one-request]

```bash
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 :

```json
{
  "_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ête [#request]

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

### GET [#get]

<TypeTable
  type={{
    query: { type: 'string', required: true, description: "La phrase de recherche. Jusqu'à 500 caractères; un texte plus long est coupé. q est accepté comme alias." },
    site: { type: 'string', description: "Un hôte de courtier auquel limiter la recherche, par exemple alice.matchai.co ou le domaine propre d'un courtier. Utilisé seulement sur matchai.co." },
    query_id: { type: 'string', description: "Votre propre identifiant pour la requête : jusqu'à 100 caractères parmi A-Z, a-z, 0-9 et . _ : - . Il est renvoyé tel quel. Sans identifiant, Matchai en génère un." },
    mode: { type: '"list"', description: 'Accepté pour la compatibilité avec NLWeb. La réponse est toujours une liste, peu importe ce que vous envoyez.' },
    streaming: { type: 'boolean', description: 'Accepté, mais ignoré. La réponse est toujours un seul document JSON.' },
  }}
/>

### POST [#post]

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

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

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

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

<TypeTable
  type={{
    query: { type: 'string | { text: string }', required: true, description: 'La phrase de recherche, avec la même limite de 500 caractères. Un q au premier niveau est aussi accepté.' },
    site: { type: 'string', description: 'Identique au paramètre GET.' },
    query_id: { type: 'string', description: 'Identique au paramètre GET.' },
    prefer: { type: 'object', description: 'Accepté pour la compatibilité avec NLWeb. prefer.mode est ignoré, et la réponse est toujours une liste.' },
  }}
/>

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

### Ce que la recherche comprend [#what-the-query-understands]

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.

| Vous écrivez | Filtre appliqué |
|---|---|
| `under 600k`, `max 750,000`, `moins de 750 000 $`, `hasta 400k` | Un prix maximal |
| `over 300k`, `at least 1.2M`, `plus de 500k`, `desde 200k` | Un prix minimal |
| `between 400k and 600k`, `entre 400k et 600k` | Une fourchette de prix |
| `3 bedroom`, `3 br`, `3 chambres`, `3 habitaciones` | Au moins ce nombre de chambres |
| `4½`, `5½` | Le nombre de pièces à la québécoise. Un 4½ compte deux chambres, donc `N½` signifie au moins N − 2 chambres. |
| `2 baths`, `1.5 bathrooms`, `2 sdb` | Au moins ce nombre de salles de bain |
| `for sale`, `à vendre`, `en venta` | Les propriétés à vendre |
| `for rent`, `à louer`, `en alquiler` | Les locations |
| `condo`, `duplex`, `maison`, `chalet`, `terrain`, `townhouse`, `commercial` | Un type de propriété : maison, condo, appartement, maison de ville, plex, terrain, chalet ou commercial |

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éponse [#response]

<TypeTable
  type={{
    _meta: { type: 'object', description: 'response_type vaut toujours answer. version est la version de NLWeb que suit la structure. mode vaut toujours list.' },
    query_id: { type: 'string', description: 'Votre query_id, ou celui que Matchai a généré.' },
    site: { type: 'string', description: "L'hôte qui a répondu, par exemple matchai.co." },
    mode: { type: '"list"', description: 'Toujours list.' },
    query: { type: 'string', description: "La phrase de recherche telle que Matchai l'a lue, après la suppression des espaces superflus et l'application de la limite de 500 caractères." },
    results: { type: 'result[]', description: "Jusqu'à 10 inscriptions correspondantes, la meilleure correspondance d'abord. Un tableau vide signifie qu'aucune inscription ne correspond." },
  }}
/>

Chaque élément de `results` :

<TypeTable
  type={{
    url: { type: 'string', description: "La page de l'inscription. C'est le domaine propre du courtier une fois celui-ci actif." },
    name: { type: 'string', description: "Le titre de l'inscription." },
    site: { type: 'string', description: "L'hôte de la page de l'inscription." },
    score: { type: 'number', description: 'La pertinence et la fraîcheur combinées, de 0 à 1.' },
    description: { type: 'string', description: 'Une ligne avec le prix, le type, les données clés, le lieu et le courtier inscripteur.' },
    schema_object: { type: 'object', description: "Un RealEstateListing de schema.org, avec son Offer et la propriété qu'il décrit. Les valeurs inconnues sont omises, jamais mises à 0." },
  }}
/>

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](https://matchai.co/docs/fr/developers/mcp-server/public-tools) ou lisez la [copie Markdown](https://matchai.co/docs/fr/developers/agent-readable-pages#markdown-copies-of-pages) de l'inscription.

## Quelles inscriptions sont cherchées [#which-listings-are-searched]

`/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.

| Vous appelez | La recherche porte sur |
|---|---|
| `https://matchai.co/ask` | Toutes les inscriptions publiées sur Matchai. Ajoutez `site` pour limiter la recherche à un seul courtier. |
| `https://{name}.matchai.co/ask`, un site Matchai | Seulement les inscriptions publiées sur le site de ce courtier. |
| `https://{domain}/ask`, le domaine propre d'un courtier | La même chose, pour le site que ce domaine sert. |
| `https://{name}.matchai.pro/ask`, une Page Matchai | La requête est redirigée vers `https://matchai.co/ask`, alors elle porte sur tous les courtiers. |

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 CORS [#limits-caching-and-cors]

- **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.

## Erreurs [#errors]

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

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

| Statut | `error` | Signification et marche à suivre |
|---|---|---|
| `400` | `missing_query` | Il n'y a aucune phrase de recherche. Envoyez `?query=` ou un corps JSON avec `query`. |
| `400` | `invalid_json` | Le corps du `POST` n'est pas du JSON valide. |
| `413` | `too_large` | Le corps du `POST` dépasse 16 Ko. Envoyez une phrase plus courte. |
| `404` | `not_found` | L'hôte que vous avez appelé n'a aucune inscription publiée à chercher. |
| `429` | `rate_limited` | Trop de requêtes. Attendez le nombre de secondes indiqué par `Retry-After`. |
| `503` | `unavailable` | La recherche est temporairement indisponible. Réessayez après le nombre de secondes indiqué par `Retry-After`. |

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 exemples [#more-examples]

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

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

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

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

Cherchez depuis votre code avec un `POST` :

<Tabs items={['curl', 'JavaScript']}>
<Tab value="curl">

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

</Tab>
<Tab value="JavaScript">

```js
const response = await fetch('https://matchai.co/ask', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: '4½ à louer sur le Plateau' }),
});

if (response.status === 429) {
  const wait = Number(response.headers.get('Retry-After') ?? 60);
  throw new Error(`Rate limited. Retry in ${wait} seconds.`);
}

const { results } = await response.json();
for (const listing of results) {
  console.log(`${listing.name} - ${listing.description} - ${listing.url}`);
}
```

</Tab>
</Tabs>

<Cards>
  <Card title="Serveur MCP" href="https://matchai.co/docs/fr/developers/mcp-server">
    Offrez la même recherche à un assistant IA, en plus de la consultation d'une inscription ou d'un courtier.
  </Card>
  <Card title="Pages lisibles par l'IA" href="https://matchai.co/docs/fr/developers/agent-readable-pages">
    Lisez tout le site d'un courtier en Markdown au lieu d'y faire une recherche.
  </Card>
</Cards>

## Sitemap

- [Toutes les pages de la documentation Matchai](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/fr/llms.txt)