Claro AI · Use cases

Score every match with your own model

For AI agent builders scoring premises with a proprietary model. Pull every match with its raw data, matched sentences and location figures with source and vintage, and score them with your own model.

#What is the problem?

Your agent has its own site-scoring model and must not be steered by a built-in fit verdict. It needs every match, every raw figure with its unit and vintage, the sentence each fact rests on, and a clear way to tell unknown from zero.

#How does it work?

1. Call search_premises (tool; REST POST /v1/claro/search, operation) with the brief or criteria as data, limit 200, check: false (the read-through runs only for pages of up to 50) and insights: true for per-criterion counts over every match.
2. Page with next_cursor sent as cursor. The order is fixed for the search's 24 hours, so pages never repeat or skip a premises; page gives the total ranked and matching the exact count.
3. For each result read its data, the met / not met / not_stated verdict per criterion with its sentence, the coordinates (exact, approximate when snapped to a ~500 m cell, or absent), and with location access the location block: the footfall index split by weekday and weekend, time of day and local, commuter and tourist shares; residents within a 10-minute walk and drive, by age band; households per net income quintile; spending power; nearby places.
4. Keep location_sources with each figure: unit, source and vintage. On 15 October 2026 the vintages are Footfall estimates 2024 and MB Research sociodemographics 2024 (Targomo) and places release 2026-09-23.1.
5. Feed your model the raw figures; treat null as unknown, never 0, and not_stated as a third state, never false. Ignore the fit verdict or keep it as one feature.
6. For finalists call get_premises (tool; GET /v1/claro/premises/{id}) with insights, segments for your competitor kinds and assessment: it adds fact_sources, timeline, energy, status, up to 8 thumbnails and a site_assessment written from that premises' own figures only.

POST https://platform.casafari.com/mcp/claro
Authorization: Bearer $CASAFARI_API_KEY
Content-Type: application/json

{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_premises", "arguments": {"brief": "burger restaurant, corner unit 120-250 m², smoke outlet, busy street, Madrid, rent under 8,000 a month", "limit": 200, "check": false, "insights": true}}}

#What do you get?

Every match with exact counts (matching, all_criteria_stated), the criteria as understood, a search_id for refine_search (tool), opaque pm_ ids that are the same over REST and MCP, and the figures your model needs with their provenance.

#What are the limits?

200 results a page; check is forced off above 50 and on later pages; a search is kept 24 hours. Location criteria and figures need location data access on the account, and a refused criterion is named in not_applied. A 429 rate_limited means wait and retry; quota_reached means stop until the reset. Over MCP a refusal is a tool error with Claro's body. What you may display follows the content terms.

#Related use cases

• Load every matching premises into your CRM nightly
• Location figures for any point in Spain
• Keyword search from a form with no model
• Compare a shortlist for a committee dossier
• Claro AI FAQ