Claro AI · Use cases

Score every premises with your own agent

For AI agent builders who score premises with their own model. Pull every match with its raw figures, matched sentences and location_sources, treat null and not_stated as unknown, and score with your own model.

#Why not rely on the built-in fit verdict?

Your team has its own site model. Claro's fit verdict, read from the advertisement text, is one input; the raw figures, the sentence each criterion rests on and the location figures with their unit, source and vintage are what your model scores. Nothing is inferred: a criterion is met, not met or not_stated, and a footfall or population figure is null when unknown, never 0.

#How does it work, step by step?

1. Call search_premises (POST /v1/claro/search, REST) with a brief in plain words, criteria as data, or both (criteria override the brief). Send "check": false, limit set to 200 and insights set to true for per-criterion counts over every match.
2. Walk every page: send next_cursor as cursor within the search's 24 hours; the order is fixed, so pages never repeat or skip a premises.
3. For each result read the criteria with their three states and sentences, the coordinates (exact, approximate when snapped to the centre of 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 by age band; households per net income quintile; spending power; nearby places. Read location_sources for each figure's unit, source and vintage.
4. For finalists call get_premises (GET /v1/claro/premises/{id}, REST) for fact_sources, timeline (first and current asking price per live operation, price cuts, history), energy and status.
5. Score with null and not_stated as unknown, and put the shortlist through compare_premises.

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

{"jsonrpc": "2.0", "id": "search", "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?

Exact counts (matching, all_criteria_stated, the number with some criteria not stated), the criteria as understood, a search_id for refine_search, and every match with its data, its state per criterion with the sentence, an excerpt, the first 4 Casafari thumbnails, agency_links, and location figures with location_sources. Ids are the same opaque pm_ tokens over REST and MCP.

#What are the limits?

The platform's units and plan limits come first (limits); behind them Claro's per-account limits on calls a minute and a day and max_results (up to 200 a page) answer 429 with rate_limited or quota_reached. Location criteria and figures need location data access on the account; a refused criterion is named in not_applied. Searches are kept 24 hours. The MCP is stateless: carry search_id and next_cursor as tool arguments. What you show follows the content terms.

#Related use cases

• Load every match into a CRM or warehouse nightly
• Get location figures for any point in Spain
• Keyword search from a simple form, no model
• Compare a shortlist for the committee dossier
• Claro AI FAQ