Listing search

/ask searches published listings from a plain sentence such as "3 bedroom condo in Laval under 600k". It follows the NLWeb protocol, so NLWeb clients can call it without custom code. It is public and read-only, and it needs no account or API key.

https://matchai.co/ask

It returns listings in the order a person would want them: best match first, by relevance to the request and by how recently the listing was updated. No broker can pay to change the order or to be included.

Search in one requestCopy link to this section

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

An abridged answer. This search matched one listing, and the score is an example value:

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

The names, addresses and photo host in these examples are made up.

RequestCopy link to this section

Send the search as a GET with query-string parameters, or as a POST with a JSON body.

GETCopy link to this section

POSTCopy link to this section

Send Content-Type: application/json. The body can be up to 16 KB.

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

The query can also be an object, as in NLWeb:

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

Query-string parameters fill in anything the body leaves out.

What the query understandsCopy link to this section

The search reads your sentence with a small, predictable parser. It does not call a language model, so the same sentence always gives the same filters. It understands English, French and Spanish.

Amounts can be written as 600k, 1.2M, 600 000, $750,000 or 2 million. A small bare number with no unit and no dollar sign, such as over 2, is not read as a price. If the sentence asks for both sale and rent, or for neither, the search does not filter on it.

Everything else becomes a keyword. The search keeps up to 6 keywords, drops words shorter than 3 letters and common filler words, and ignores accents, so montreal finds Montréal. Keywords are matched against the title, the place names, the property type and the description. A match in a place name counts most, then the title, then the property type, then the description.

Searches return listings that are available now. Sold and rented listings are not returned.

ResponseCopy link to this section

Each item in results:

A successful answer carries Link: </llms.txt>; rel="describedby", </openapi.json>; rel="service-desc". For photos, highlights and the full description of one listing, use the MCP server's tools or read the listing's Markdown copy.

Which listings are searchedCopy link to this section

/ask answers for the host you call, so asking a broker's own site searches that broker, and asking matchai.co searches everyone.

Notes:

• On a Matchai Site or a broker's own domain, site is ignored: the host decides the scope.
• On matchai.co, site takes a broker's site host. A value that matches no published site is ignored, and the search covers everyone. It does not return an empty list.
• A Matchai Page has no search of its own. The redirect is a 307, which keeps the method and the body. To search one professional's listings, ask their Matchai Site, or call matchai.co with their site as site. From browser code, call matchai.co/ask directly, because a browser cannot follow a redirect on a cross-origin preflight.
• A host with no published site answers 404.

Limits, caching and CORSCopy link to this section

• Rate limit: 60 requests per minute for each calling address, across GET and POST. Above it, the answer is 429 with Retry-After: 60.
• Results: at most 10 per request. There is no paging, so narrow the sentence to reach other listings.
• Caching: a GET without a query_id can be cached for up to a minute (Cache-Control: public, max-age=60). Everything else is sent with no-store. A new listing appears in results within about a minute.
• CORS: open to every origin for GET, POST and OPTIONS, so browser code can call it. OPTIONS answers 204, and preflight answers can be cached for 24 hours.

ErrorsCopy link to this section

Errors are JSON with a stable error code and a message you can show to a person.

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

An empty results array is a successful answer: nothing published matched. Try a wider area, a higher budget or fewer requirements.

More examplesCopy link to this section

Search one broker's listings by calling their site. Replace alice with a real site name:

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

Limit a search on matchai.co to one broker:

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

Search from code with a 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" }'